Memory

Memory is durable: facts and conventions from past sessions feed forward into new ones. It sits next to but separate from compaction, which keeps a single session inside the context window.

When each fires

Compaction

Compaction is the orthogonal in-session mechanism: it summarizes older messages on the active branch when the window fills up, leaving the file on disk untouched. See Compaction for triggers, the /compact command, the non-compaction retry path, and the compaction.* settings.

Memory backends

The backend is selected via memory.backend:

Local backend

Past sessions for the current project are summarized into a compact memory document and injected into the system prompt as a Memory Guidance block at session start. The block is heuristic context the agent is told to verify against current repo state before acting. Memory is isolated per project (working directory) and stored under ~/.omp/agent/memories/.

Manage local memory from the TUI:

The agent can also pull deeper context on demand by reading the memory:// URLs with the read tool:

# Show the static guidance block injected into the system prompt
omp -p 'read memory://root'
 
# Show the full long-term memory document for this project
omp -p 'read memory://root/MEMORY.md'
 
# Show a generated skill playbook
omp -p 'read memory://root/skills/<name>/SKILL.md'

Hindsight backend

Opt-in remote backend backed by Hindsight (Cloud or self-hosted). Instead of a static injected summary, Hindsight surfaces three tools to the agent: retain stores a durable fact, recall searches prior memories, and reflect synthesises an answer across many memories. On the first turn of every session, an auto-recall fires against the configured bank so prior context lands before the model speaks.

Each session aliases a bank; subagents reuse the parent’s bank so retains and recalls converge on the same place. hindsight.scoping chooses how banks are partitioned:

Setting up Hindsight

Four hindsight.* keys in ~/.omp/agent/config.yml are enough to connect:

# Public Hindsight Cloud
memory:
  backend: hindsight
hindsight:
  apiUrl: https://api.hindsight.vectorize.io
  apiToken: hs_live_REPLACE_ME
  bankId: my-team-bank # optional; defaults to a bank derived from `omp`
  scoping: per-project-tagged # global | per-project | per-project-tagged

# Self-hosted (default apiUrl is http://localhost:8888)
memory:
  backend: hindsight
hindsight:
  apiUrl: http://hindsight.internal:8888
  apiToken: REPLACE_ME
  bankId: null # per-project bucket allocated on first use
  scoping: per-project

Use per-project-tagged when you want global facts and project-scoped facts to live in one bank and merge on recall. Switch to per-project when projects must not see each other’s memories (e.g. client work under NDA) and accept that recall will no longer pull in cross-cutting preferences. Reserve global for single-developer setups with one mental project.

Mental models

Long-running curated summaries (user preferences, project conventions, architectural decisions) seeded once per bank and refreshed after consolidations. The active set is spliced into the system prompt as a <mental_models> block. Manage them from the TUI with /memory mm:

The local /memory view|clear|enqueue commands still apply with the Hindsight backend — they manage the project’s local artifacts, not the remote bank. /memory mm is TUI-only; in ACP / headless mode use the Hindsight HTTP API directly to maintain models.

Privacy and storage

Where do session transcripts live? Under ~/.omp/agent/sessions/<encoded-cwd>/, one JSONL file per session. Local-only by default; nothing leaves the machine unless you run /share, /export to a network path, or launch with --mode rpc to pipe session events out to an ACP client.

Where does memory live? With the local backend, under ~/.omp/agent/memories/<encoded-cwd>/MEMORY.md, plus a SQLite job/state database in the agent directory. With the hindsight backend, the durable store is the external bank you point hindsight.apiUrl at — self-hosted or Hindsight Cloud — and only the local config and an aliased bank id sit on your machine.

What gets uploaded to Hindsight? Explicit retain payloads, recall / reflect queries, and — with hindsight.autoRetain on (the default) — a transcript of the session’s user and assistant text turns, retained every few turns. The retained transcript drops tool calls, tool results, and thinking blocks, and strips injected <memories> / <mental_models> blocks, so curated memory never re-feeds the bank as conversation noise. Disable hindsight.autoRetain if only explicit retain calls should leave the machine.

Audit at any time with omp -p 'read memory://root' for the injected payload and omp -p 'read memory://root/MEMORY.md' for the long-term document.

Recipes

Rebuild local memory after a major refactor

You renamed half the modules and the “Memory Guidance” block is now full of stale file paths. Wipe the project’s memory and enqueue a fresh consolidation:

/memory clear
/memory enqueue

Seed mental models on a fresh Hindsight bank

/memory mm seed
/memory mm list

The models start empty and fill in as retain calls stream in. Force an early refresh once you have a few real retains in the bank with /memory mm refresh project-conventions.

Switch from local to Hindsight without losing context

1. /memory clear — otherwise the local Memory Guidance lingers as a static system-prompt block alongside the new Hindsight tools.

2. Set memory.backend: hindsight plus the four hindsight.* keys in ~/.omp/agent/config.yml.

3. Restart the agent. Auto-recall fires on the first turn against the new (empty) bank; subsequent retain calls populate it from real work.

4. Optional: /memory mm seed to drop the built-in mental-model scaffolding into the bank.

See Sessions for resume and branch mechanics, Slash commands for the full command inventory, and CLI reference for headless flags.