Memory

Memory helps omp continue work without making you restate durable facts such as repository conventions, architectural decisions, and review preferences. It is separate from compaction: compaction shortens one session, while memory can affect future sessions.

Memory is off by default. If you want it, open /settings, select the Memory tab, and choose one backend. Start with mnemopi for searchable memory stored on this machine, local for automatic project summaries, hindsight when you already operate a Hindsight service, or sharpshooter when you want project decisions (architecture, product, style) captured automatically with almost no prompting.

Choose a backendCopy Anchor Link

The smallest persistent setup from a shell is:

# Pick exactly one
omp config set memory.backend local
omp config set memory.backend mnemopi
omp config set memory.backend hindsight
omp config set memory.backend sharpshooter

# Confirm the effective setting
omp config get memory.backend

/settings writes the global config and switches the active backend when you save it. Shell or YAML changes apply to new omp processes. For one repository only, put the same keys in <repo>/.omp/config.yml; project settings override the global file. See Settings for paths and precedence.

Privacy, scope, and defaultsCopy Anchor Link

Enabling memory changes what persists and, depending on the backend, what may cross a network boundary.

• Off means no memory processing. It does not disable ordinary session persistence. Memory commands also do not erase files under ~/.omp/agent/sessions/; manage those separately through Sessions.
• Local stores generated artifacts locally, under ~/.omp/agent/memories/<encoded-project>/ by default. Its extraction and consolidation passes use your configured model roles, so past session text can still be sent to that model provider. Generated outputs are filtered for common token and secret patterns, but do not intentionally ask omp to remember secrets.
• Mnemopi stores its SQLite banks locally, under ~/.omp/agent/memories/mnemopi/ by default. Local embeddings may download and run an embedding model. Its default llmMode: smol uses your configured online tiny / smol model for LLM-backed extraction; use llmMode: none when you want no LLM-backed memory processing.
• Hindsight stores durable memory on the configured server. With autoRetain: true (the default), omp sends user and assistant text every three user turns and at session boundaries. It omits tool calls, tool results, and thinking blocks. Recall and synthesis queries also go to that server.
• Turning a backend off does not delete its store. This makes switching reversible, but you must clear or delete data separately when removal is the goal.

Choose scope before accumulating sensitive data:

Use memory in conversationCopy Anchor Link

With Mnemopi or Hindsight enabled, use ordinary prompts. You do not need to know how omp performs the memory operation.

Remember that this repository uses pnpm and Node 22.

Before changing authentication, recall why we rejected session cookies.

What durable preferences have you learned about how I review pull requests?

Mnemopi can also edit, forget, or invalidate an editable memory:

Forget the memory that says releases happen on Fridays; that policy was retired.

Update the stored release convention to say that releases happen after CI is green.

Ask omp to show the candidate memory before changing it when the description could match more than one entry. Mnemopi's extracted fact-table rows are read-only; the prompt should identify an editable memory, or you can clear the scoped bank when complete removal is required. Hindsight does not expose individual record editing through omp; use the Hindsight service's UI for record-level review or deletion.

The local backend works differently. It automatically summarizes eligible persisted sessions and injects a static Memory Guidance block at startup. A request such as “remember this” is not a guaranteed individual write. Its best use is allowing recurring project knowledge to emerge from completed work.

Recalled or summarized memory is background context, not an instruction. Current prompts and current repository state take precedence when they conflict with it.

What you can inspect and controlCopy Anchor Link

Run these slash commands in a session:

/memory reset is an alias for clear; /memory rebuild is an alias for enqueue.

What enqueue and clear meanCopy Anchor Link

Review local generated filesCopy Anchor Link

The local backend keeps readable generated artifacts below ~/.omp/agent/memories/<encoded-project>/:

• memory_summary.md — compact guidance shown by /memory view and injected at startup
• MEMORY.md — the longer consolidated project memory
• learned.md — explicitly captured lessons when optional auto-learn is enabled
• skills/ — generated procedural playbooks

These are generated files, not the source session history. Editing them is not a durable workflow because later consolidation can replace them. Clear stale output and enqueue a rebuild instead.

Manage Hindsight mental modelsCopy Anchor Link

Hindsight mental models are curated summaries such as user preferences, project conventions, and project decisions. They are enabled and automatically seeded by default. In the interactive TUI, use:

Mental-model commands are TUI-only and require an active Hindsight backend. They are not Mnemopi controls.

Configure the local backendCopy Anchor Link

Minimal global YAML in ~/.omp/agent/config.yml:

memory:
  backend: local

The pipeline starts in the background when omp starts. It skips subagents and sessions that were not persisted. By default, it ignores sessions still active within the last 12 hours and sessions older than 30 days, so a newly enabled backend may initially show an empty payload. Per-session extraction uses the default model role; consolidation uses smol with fallbacks.

Optional autolearn.enabled: true lets omp capture explicit lessons into learned.md; it is experimental and off by default. autolearn.autoContinue is also false by default and controls whether omp runs a private capture turn after stopping.

Configure MnemopiCopy Anchor Link

The defaults are enough for a project-isolated local bank:

memory:
  backend: mnemopi

A privacy-oriented FTS-only setup that avoids LLM-backed extraction is:

memory:
  backend: mnemopi
mnemopi:
  scoping: per-project
  noEmbeddings: true
  llmMode: none

Storage, scope, and automationCopy Anchor Link

Retrieval, embeddings, and LLM processingCopy Anchor Link

Configure HindsightCopy Anchor Link

Run a reachable Hindsight server first. The built-in URL is http://localhost:8888, so a local unauthenticated server needs only:

memory:
  backend: hindsight

For Hindsight Cloud or an authenticated deployment:

memory:
  backend: hindsight
hindsight:
  apiUrl: https://api.hindsight.vectorize.io
  scoping: per-project

Keep the token outside the file when possible:

export HINDSIGHT_API_TOKEN='replace-me'
omp

HINDSIGHT_* environment variables override matching hindsight.* settings. See Environment variables for the override names and parsing rules.

Connection, banks, and retentionCopy Anchor Link

Recall, mental models, and timeoutsCopy Anchor Link

Configure SharpshooterCopy Anchor Link

Sharpshooter is the friction-gated project-decision memory backend: per-prompt async extraction emits decision deltas into a per-session queue, and a shared consolidation pass (default every 5 minutes) applies queued deltas per project into three markdown decision files. Only decisions that show friction persist — a regression, repeated corrections, or a rule that is subtle to get right from the code alone. Ordinary facts and task state do not persist here.

memory:
  backend: sharpshooter

What gets storedCopy Anchor Link

Each file has a 120-line ceiling enforced at consolidation. Banks live under <agentDir>/memories/sharpshooter/<project>/ with queue/<sessionId>/ deltas and a state.json for consolidation bookkeeping. Use /memory stats and /memory diagnose output for the last consolidation result and error.

SettingsCopy Anchor Link

Decision categories a delta may claim are architecture_decision, product_decision, style_decision, constraint, rejected_approach and correction. Each delta carries the exact triggering user-prompt substring as evidence.

TroubleshootingCopy Anchor Link

RelatedCopy Anchor Link

Source: omp.sh — MIT, Stencil Labs. Initially imported on 2026-10-03; updates via automatic sync.