Environment variables and files
Where everything lives: config precedence, the environment variables Okami reads, and what shows up in the .okami/ directory when you use the agent.
Configuration precedence
| file | role · versioned? |
|---|---|
| okami.yaml | base config (providers, memory, contracts) · ✅ yes |
| okami.local.yaml | local overrides (deep-merge over base; wins) · ❌ no |
| .env | PROJECT secrets · ❌ no |
| ~/.okami/.env | GLOBAL secrets (any workspace, 0600) · ❌ no |
| okami.policy.yaml | authored conformance posture · ✅ yes |
Secrets take precedence: real environment > project .env > global .env. okami config set <UPPERCASE_KEY> writes to the global .env by default (--project uses the project's).
Environment variables
params OKAMI_API_TOKEN secret Bearer for the HTTP API (okami serve) — fail-closed, without it the API won't boot. MIMO_API_KEY secret Key for the MiMo provider (the one API-key provider in the default posture). <PROVIDER>_API_KEY secret Referenced by api_key_env (e.g. GITHUB_TOKEN in an MCP header). PAPERCLIP_API_URL / _API_KEY secret Paperclip connection — injected per-run on the heartbeat; don't fill in by hand. PAPERCLIP_RUN_ID / _AGENT_ID / … string Paperclip run metadata (reference/tests). EDITOR string Editor used by okami config edit (else nano/notepad).
The .okami/ directory (per workspace/agent)
| path | what it is |
|---|---|
| events.jsonl | append-only turn timeline (redacted, with trace_id) |
| audit.jsonl | every tool + approval decision |
| sessions/<chat>.jsonl | append-only transcript (one line per turn) |
| checkpoints/journal.jsonl | write journal (lock + HMAC) for rollback |
| memory.db | sqlite-fts5 memory (+ vectors) |
| taste.json | design-taste attractors/repulsors |
| persona_signals.json | observed signals to evolve VOICE/PERSONA |
| tuning.json | per-model stats (capability auto-tune) |
| quarantine/ | downloaded skills awaiting the scan |
| gateway.pid · gateway.log | PID and log of the background gateway |
| cron.json | scheduled jobs |
| chat_history | the REPL's line history |