OKLMdocumentation v1.0.3
On this page

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:

  • /config lists 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] KEY write the file and read the settings again: outputStyle, bashTimeout, maxToolOutputChars and env apply at once, the others at the next start. Rules go through /permissions.
  • /permissions lists the mode, the added directories and the rules by list with their source; /permissions allow|ask|deny [--local|--project|--user|--session] RULE adds a rule (saved, or for the session), /permissions remove [scope] RULE removes 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 /debug from then on, appends to $XDG_STATE_HOME/oklm/logs/SESSION.log (~/.local/state/oklm/...), named for the session's commands in OKLM_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 and password= values of the usual shapes masked), results (status, size, seconds), turn ends, compactions. /status names it.
  • Export: only with OKLM_ENABLE_TELEMETRY=1 or telemetry.enabled, and an endpoint (OTEL_EXPORTER_OTLP_ENDPOINT or telemetry.otlpEndpoint, headers from OTEL_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.tokens by 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 neither oklm serve nor 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 (or feedback.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 writes AGENTS.md (build, test and lint commands, architecture, conventions, gotchas), or improves the existing file with edits; writes to AGENTS.md then 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.
  • /memory lists the files (imports under their importer, scope, size, tokens) and the warnings; /memory N opens file N in $VISUAL or $EDITOR.
  • /context shows 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.