Settings and memory files
How oklm agent is configured: the settings files and
their order, every setting, the usage counts, the debug log and the
telemetry export, and the memory files (OKLM.md,
AGENTS.md...) that become the project instructions. Part of
the agent harness (harness.md); the
environment variables are in build.md.
Status: implemented.
Settings files
Highest first: managed (/etc/oklm/managed-settings.json,
%ProgramData%\oklm\managed-settings.json, or
$OKLM_MANAGED_SETTINGS), command-line rules,
.oklm/settings.local.json,
.oklm/settings.json, the user's
($XDG_CONFIG_HOME/oklm/settings.json,
~/.config/oklm/, %APPDATA%\oklm\), then
answers given for the rest of a session. When an OKLM file is absent,
the spec's .agent/settings.local.json,
.agent/settings.json and
~/.agent/settings.json are read in its place (never
written). oklm_perms_save_rule() adds a rule to
.oklm/settings.local.json,
oklm_perms_save_rule_to() to the project's or the user's
file (created if needed; the file's other members are kept as they were
written, a rule already listed is not added twice): the terminal's
"always" answers go to the local file.
{
"permissions": {
"allow": ["Bash(make:*)", "Bash(git log:*)", "Edit(./src/**)"],
"ask": ["Bash(git push:*)"],
"deny": ["Read(./secrets/**)", "Bash(rm -rf:*)", "WebFetch(domain:example.net)"],
"defaultMode": "acceptEdits",
"additionalDirectories": ["../shared"]
}
}The highest file that sets defaultMode sets the mode.
Managed settings may also hold
"disableBypassPermissionsMode": "disable" and
"allowManagedPermissionRulesOnly": true (allow rules of the
other sources are then ignored). A malformed rule or file is an error,
not a silently dropped rule.
oklm permissions [--project DIR] [--mode MODE] <Tool> <argument>
prints how the settings decide a call (exit status 0 allow, 3 ask, 4
deny):
$ oklm permissions Bash "git status && rm -rf /"
deny: Bash(rm -rf:*) (project settings), a command matches a deny rule
Settings
include/oklm/harness/settings.h,
src/harness/settings.c. The other keys of the same files,
merged by priority: managed (nothing overrides it), the command line,
environment variables, the local file, the project's, the user's. A
scalar takes the highest source's value, objects merge key by key,
arrays are joined (highest source first, each item once);
oklm_settings_get() says which source a value comes
from.
| Key | Type | Used by |
|---|---|---|
model |
string | the model file when -m is not given (or the remote
model's name with an endpoint) |
smallModel |
string | a small model loaded beside the main one for the asides — the titles
and the compaction summaries; it answers in its own context, leaving the
main model's cache untouched. A sub-agent whose definition sets
model: small runs on it too. OKLM_SMALL_MODEL
sets it. Its turns are written by its file's chat template; a file that
carries none gets the catalogue's format for it, else the one
--chat-template names (inference.md) |
baseUrl |
string | an OpenAI-compatible endpoint used when neither -m nor
--url is given |
outputStyle |
string | the output style when --output-style is not given |
bashTimeout |
integer, ms | Bash's default timeout |
maxToolOutputChars |
integer | bytes of a tool's output kept for the model; a longer foreground
result is spilled whole to .oklm/tool-output/ with its path
in the cut |
maxRetries |
integer >= 0 | with --url, how often a turn is sent again after a
transient failure (no connection, a time-out, 408, 409, 429, 5xx) before
it fails: waits of 1, 2, 4 s... within 30 s, or the server's
Retry-After; never once part of the answer has arrived
(default 4, OKLM_MAX_RETRIES) |
maxReasoningTokens |
integer >= 0 | for an in-process thinking model, a cap on a turn's reasoning: once
that many tokens have been spent inside the <think>
block, the block is closed so the answer follows (0: no cap, the
default, OKLM_MAX_REASONING_TOKENS). A
think hard, think harder,
think deeply or ultrathink in the user's
message lifts the cap for that one turn |
commandClassifier |
boolean | with a smallModel set, the small model rates each Bash
command for prompt-injection or exfiltration risk before it runs; a
flagged command asks the user even when a rule allows it (default off,
OKLM_COMMAND_CLASSIFIER). It fails open: no small model, or
an unclear answer, leaves the command to the usual rules and
dangerous-pattern list |
env |
object of strings | the environment of commands |
sandbox |
object: enabled, network,
allowedDomains, deniedDomains |
the sandbox when --no-sandbox /
--allow-network are not given; without the network, the
domains its commands may still reach through the proxy (§ Sandbox) |
permissions |
object | the rules and modes above |
memory |
object | the memory files |
autoCompact |
boolean | compaction by itself near the window's end (default true) |
autoContinue |
boolean | an answer the token limit or the context cut is gone on with by
itself (default true); false: with /continue |
continueMax |
integer | the pieces an answer is continued with in a row at most (default 8).
oklm chat reads and writes autoCompact,
autoContinue and continueMax too (inference.md) |
compactThreshold |
number, 0 to 1 | the share of the window, less the reply's reserve, where it starts
(default by the model's size: 0.60 under 2 billion parameters, 0.75
under 8 billion, 0.85 above or when the size is unknown, as with
--url) |
contextWindow |
integer, tokens | the model's window with --url (default: the context an
oklm serve tells with GET /api/context, 32768
for another server); the in-process context's length when
-c is not given (default 32768, within the model's training
length), compaction then counting against the context itself |
theme |
string | dark, light, colorblind,
none (§ Terminal
UI) |
statusLine |
object: command |
a command whose first line is the status line, the session as JSON on its input |
preferredNotifChannel |
string | terminal_bell, iterm2,
system, notifications_disabled |
editorMode |
string | emacs (the default) or vi /
vim for vi line-editing keys |
skillOverrides |
object of strings | a skill's visibility: on, menu-only,
model-only, off (§ Slash commands) |
skills |
object: listBudget |
tokens the system prompt's list of skills takes at most (2000); the rest are found with ToolSearch |
toolSearch |
object: topK, model,
minScore, mode |
tool selection by retrieval: topK the entries retrieved
for each message (0, off; --tool-rag K overrides),
minScore the cosine a deferred tool needs to be given
(0.62), model the embedding model (a path, a file name
looked for as the models are, none for BM25 alone;
bge-small-en-v1.5-q8_0.gguf by default), mode
the ranking (hybrid, the default: dense and BM25 fused;
dense: the cosine alone; bm25: BM25 alone, the
cosine still computed for minScore) (§ Deferred
tools) |
rag |
object: enabled, memory,
inject, model, queryPrefix,
include, exclude, index,
maxBytes |
retrieval: enabled the project's documentation indexed
by the agent and searched by the Retrieve tool
(--rag-project), memory earlier sessions
searched too (--rag-memory), inject
off, always or route for passages
given with each message (--rag-inject), model
the embedding model (hash: the hash encoder;
bge-small-en-v1.5-q8_0.gguf by default),
include / exclude the files' globs (a string
or an array; the documentation by default), index the index
file, maxBytes the size cap (200 MB) (§ Agentic retrieval) |
deferredTools |
array of tool names | tools whose definitions stay out of the prompt until ToolSearch
loads them (default ["ProcessList", "PowerShell", "LSP"];
[] defers none) |
processes |
object: maxConcurrent, defaultGraceMs,
logRetentionDays, logRotateMB,
autoBackgroundOnTimeout, autoReapOrphans,
keepOnExit |
background jobs (§ Background jobs) |
events |
object: wakeOnEvents,
maxWakeupsPerHour |
background events waking the agent (§ Background jobs) |
lsp |
object: servers by language (command,
extensions), enabled,
diagnosticsWaitMs |
language servers (§ Language servers) |
git |
object: coAuthorTrailer,
protectedBranches, worktree
(copy, symlink, setup) |
the commit trailer, branches a push to asks about, what a new worktree gets (§ Git) |
commands |
object: maxStack, legacyDirs |
prompt commands stacked at most (6); legacyDirs false
leaves the single-file command directories unread
(.oklm/commands, .agent/commands, the user's
commands; default true), the skill directories and the
plugins' commands still read |
review |
object: defaultLevel |
the level /code-review (/review) takes
when its arguments name none: low, medium,
high, max or ultra (the skill's
own default is medium) |
goal |
object: maxIterations |
turns /goal starts toward its condition before it stops
(10; maxTurns, its older name, is read when it is
unset) |
loop |
object: defaultPrompt |
what /loop sends without a prompt when the project has
no .oklm/loop.md (default: a maintenance round) |
schedule |
object: backend |
how /schedule schedules: cron (the
default, the only one written); systemd,
launchd and taskscheduler are recognised and
refused by /schedule with a message, any other value is
left out with a warning |
reasoning |
object: keepInHistory |
with a server (--url), whether earlier turns' reasoning
is sent back as reasoning_content on their assistant
messages: true always, false never; unset, as
the template variables say (clear_thinking false, GLM-4.7's
preserved thinking, or preserve_thinking true). The
in-process model always keeps it, its template deciding what it renders.
/config changes it at once |
ui |
object: viewMode, promptColor |
the view a session starts in: classic (or
default; the reasoning folded), full (shown as
written, as --thinking show, which wins),
fullscreen (the full-screen UI of /tui on a
terminal, else the full view, said); the prompt's color:
red, green, yellow,
blue, magenta, cyan or
default (/color changes it for the
session) |
agents |
object: maxDepth, waitForBackground |
how deep agents start agents (1: sub-agents start none); the
commands a Bash call does not run while background agents run, waiting
for their reports first (["git commit", "git push"];
[] none; § Sub-agents) |
cleanupPeriodDays |
integer, days | sessions not written to for longer are removed at start (default 30); 0 writes no transcript |
hooks |
object of events | commands run on the agent's events (§ Hooks) |
pricing |
object: model name prefixes or default, each
input, output, cachedInput
(dollars per million tokens) |
the cost in /usage and the JSON results (§ Usage, debug log, telemetry) |
telemetry |
object: enabled, otlpEndpoint |
the OpenTelemetry export (§ Usage, debug log, telemetry) |
feedback |
object: bundleDir |
where /bug writes its bundles |
smallModel, includeCoAuthoredBy,
mcpServers, enabledPlugins |
checked, kept | the milestones that read them |
A value of the wrong type is left out with a warning (printed at
start, and by /config); a malformed file is left out whole;
unknown keys are kept. The members of commands,
review, goal, loop,
schedule, ui and reasoning above
are checked one by one: a member of the wrong type or value is left out
with a warning naming the accepted values, the object's other members
kept, and /doctor fix removes it. Some settings are also
read from the environment (OKLM_MODEL for
model, ...: the list is in build.md, with every other variable the
agent reads); the endpoint's key comes from --api-key, else
OKLM_API_KEY, else OPENAI_API_KEY. Nothing is
sent anywhere unless the OpenTelemetry export is turned on (§ Usage, debug log, telemetry).
oklm_settings_edit(path, key, op, json) changes one key
of a file (set, unset, add to or remove from an array; key
or object.key), written atomically, the file's other
members kept byte for byte.
In the REPL:
/configlists every setting in force with its source (key = value (source)), then the warnings;/config get KEY;/config set [--local|--project|--user] KEY VALUE(VALUE as JSON when it is, else a string; the local file by default) and/config unset [scope] KEYwrite the file and read the settings again:outputStyle,bashTimeout,maxToolOutputCharsandenvapply at once, the others at the next start. Rules go through/permissions./permissionslists the mode, the added directories and the rules by list with their source;/permissions allow|ask|deny [--local|--project|--user|--session] RULEadds a rule (saved, or for the session),/permissions remove [scope] RULEremoves it.
Usage, debug log, telemetry
include/oklm/harness/telemetry.h,
src/harness/telemetry.c. A recorder sees every stream event
before the session's own callback: tokens (input, cached, output), model
turns timed from the request or the last tool result, tool calls timed
by their ids, failures counted, and the cost by the pricing
table (the model's longest name prefix, else default).
/usage shows the time in the model and the tools and the
cost; a headless result has total_cost_usd.
- Debug log:
--debug,OKLM_DEBUG=1, or/debugfrom then on, appends to$XDG_STATE_HOME/oklm/logs/SESSION.log(~/.local/state/oklm/...), named for the session's commands inOKLM_DEBUG_LOG(the debug skill reads it when OKLM itself is at fault): a line an event with the seconds since the start: requests (their length), model turns (tokens, seconds), tool calls (arguments cut to 300 characters, API keys, tokens andpassword=values of the usual shapes masked), results (status, size, seconds), turn ends, compactions./statusnames it. - Export: only with
OKLM_ENABLE_TELEMETRY=1ortelemetry.enabled, and an endpoint (OTEL_EXPORTER_OTLP_ENDPOINTortelemetry.otlpEndpoint, headers fromOTEL_EXPORTER_OTLP_HEADERS): after each request, OTLP/HTTP JSON log records (oklm.model_turn,oklm.tool_result,oklm.compact: names, statuses, sizes, tokens, durations, never arguments or results) to/v1/logs, and cumulative sums (oklm.tokensby type,oklm.cost.usd,oklm.tool.calls) to/v1/metrics, posted by a thread of its own; the session's end waits three seconds at most for the last. Those two paths are the collector's, appended to the endpoint's address: the agent posts to them, and neitheroklm servenor a listening agent answers them (server.md lists the routes OKLM answers). /bug [report],/feedback [report]: after choosing how much goes in (the report and diagnostics, the last 20 messages, or the whole conversation and the debug log), a bundle in$XDG_STATE_HOME/oklm/feedback/STAMP-bug(orfeedback.bundleDir):report.md(the report, version, platform, model, session, mode, totals,/doctor's findings),transcript.jsonl,debug.log, secrets masked. Nothing is sent. Headless runs write the report alone.
Memory files
include/oklm/harness/memory.h,
src/harness/memory.c. Instructions the agent follows in a
project, by scope, lowest priority first (later files win where they
disagree):
| Scope | Where | Shared |
|---|---|---|
| managed | /etc/oklm/ (%ProgramData%\oklm\, macOS
/Library/Application Support/OKLM/), or the file
$OKLM_MANAGED_MEMORY |
every user, read-only |
| user | $XDG_CONFIG_HOME/oklm/ or ~/.config/oklm/,
else ~/.agent/ |
the user, every project |
| project | each directory from the repository's root (the nearest
.git, else the file system's root) down to the project
directory |
the team (committed) |
| local | the local names in the same directories | the user alone (a # note puts the file in
.gitignore) |
| sub-directory | the files of directories below the project, when a tool first reaches them | the team |
In each place the names are AGENTS.md (what
/init writes), OKLM.md, AGENT.md,
CLAUDE.md (setting memory.fileNames), each
also under .oklm/ and .agent/; the local name
is .local.md for .md
(AGENTS.local.md). A file met twice (a symbolic link, the
same content under two names) is read once.
Imports. @path at a line's start or
after a blank, outside code spans and fenced blocks, naming a path (a
/, a . or a leading ~;
me@host and @alice are left alone), becomes
the file's content in <file path="..."> ...
</file>, relative to the importing file, nested up to
5 deep. A missing file, a cycle, or a file outside the project and the
home directory stays as written and is listed as a warning (at start, in
/memory); each file is cut at 40000 bytes and all of them
at memory.maxTokens (20000) tokens, with a notice.
In the prompt, after the environment:
# Project instructions
These instructions override your default behavior: follow them exactly. Later files take precedence over earlier ones where they differ.
Contents of /home/me/.config/oklm/AGENTS.md (user instructions, applies to all projects):
...
Contents of /repo/AGENTS.md (project instructions, checked into the codebase):
...
A sub-directory's file comes as a reminder the first time a file tool
(Read, Write, Edit, MultiEdit, NotebookEdit, Glob, Grep) reaches a path
under it: "Instructions for packages/web/ (from
packages/web/AGENTS.md) ...", once per session; the directories are kept
(oklm_memory_loaded_dirs()) to be told again after a
compaction. A memory file that changes on disk, appears or goes is read
again before the next turn (oklm_agent_refresh_memory()):
the prompt is assembled again and a reminder names the files.
Commands (oklm agent):
/init: the agent lists the files, reads the README, the build files and a few sources, and writesAGENTS.md(build, test and lint commands, architecture, conventions, gotchas), or improves the existing file with edits; writes toAGENTS.mdthen ask with their diff whatever the mode.#note: the model rewrites the note as one bullet (oklm_agent_ask_once(): a turn that leaves the conversation as it was), then the user picks the project's file, the local one, the user's, or none./memorylists the files (imports under their importer, scope, size, tokens) and the warnings;/memory Nopens file N in$VISUALor$EDITOR./contextshows the tokens of the system prompt, of its memory files and of the conversation (estimated at 4 bytes a token).
Settings: a memory object in the
settings files (read as the permissions are): enabled,
fileNames, maxTokens,
lazySubdirs; --no-memory turns the files
off.
On Qwen3-4B, with a project whose AGENTS.md says "always
use pnpm, never npm" and the task "Install the project's dependencies,
then run its tests" (npm and pnpm both allowed), the model ran
pnpm install and pnpm test; pnpm being absent
from the sandbox, it then tried npm install -g pnpm (to get
pnpm, against the letter of the rule) and downloads the dangerous list
refused. /init on a small C project (Makefile, sources, a
test) listed the files, read the README and the Makefile, wrote
AGENTS.md (asked, with its diff), read the sources and the
test, and improved it with an edit: commands, flags and layout all taken
from the files. With a first wording that did not spell out the steps,
the same model globbed for build files without reading them and wrote a
file of guesses (CMake, a CI that does not exist): the instructions now
say to read each file before writing about it.