Concepts
OpenMem is a memory interface for coding agents: a stable API and operator surface over pluggable memory providers.
What’s coding-agent memory?
Section titled “What’s coding-agent memory?”Coding agents forget between sessions. A memory system stores durable facts, decisions, and project context so the next turn (or agent) can recall them without re-deriving everything from the repo.
In practice that means:
- Write — retain notes, session transcripts, indexed sources
- Read — search, recall, or synthesize an answer from stored memories
- Scope — keep personal notes, vaults, and per-repo banks from colliding
- Operate — run a backend locally (or point at one), keep secrets off the wire you did not choose
Full use of memory needs a memory system: an API (or library) plus storage, extraction, and usually an admin or ops path. Hindsight, mem0, Cognee, and in-house stores are examples. Each has its own API, deploy story, and agent wiring.
What’s OpenMem?
Section titled “What’s OpenMem?”OpenMem is not a memory engine. It is the layer that sits between coding agents and whichever engine you run:
| Layer | Role |
|---|---|
| Agents | Claude Code, Codex, Cursor Agent, OpenCode — call stable memory_* tools and share one skill |
| OpenMem | Wizard, Compose, indexer, unified MCP, session hooks, import/export formats |
| Memory provider | The selected memory system; owns storage, semantics, and its native API. See Provider status. |
One active provider at a time. openmem switch rewires the stack; it does not pretend to migrate your data. Portability is explicit through the format layer (PMM today).
Why an interface layer?
Section titled “Why an interface layer?”Without a shared front door, every agent and indexer hard-codes one vendor’s SDK or HTTP shape. Switching providers means rewriting hooks, MCP entries, and indexing. Trying a second system means a second install path.
Standardizing the agent and ops surface means:
- Keep using your current memory product
- Try another provider without rewriting agent prompts and MCP tool names
- Share indexer, wizard, and install plumbing across backends
- Grow a community of providers behind one contract
OpenMem owns machine plumbing. Providers own memory quality.
Core pieces
Section titled “Core pieces”Providers
Section titled “Providers”A memory provider is the selected memory system, such as Hindsight, mem0, or Cognee. OpenMem’s adapter under providers/<id>/ maps its manifest, Compose fragment, wizard hooks, and indexer sink to that provider’s API.
Ship a provider as providers/<id>/ (manifest + hooks + compose). Status (supported / experimental / planned) comes from the manifest. See Provider status and Pluggable memory providers.
Only one provider is active (MEMORY_PROVIDER). Switching updates Compose, the indexer sink, and unified MCP to use it.
Evaluation API (memory_*)
Section titled “Evaluation API (memory_*)”Agents do not call Hindsight or mem0 tool names by default. They call a stable tool set on the openmem MCP server:
| Tool | Intent |
|---|---|
memory_add |
Store a durable record |
memory_search / memory_recall |
Retrieve |
memory_reflect / memory_consolidate |
Synthesize (provider-dependent) |
memory_forget |
Delete (scoped; confirm before bulk) |
memory_export / memory_import |
Portability (PMM) |
memory_provider_status / memory_project_scope |
Ops / bank resolution |
The facade (cli/mcp/memory-facade.mjs) maps each call onto the active provider’s HTTP API. Native provider MCP (install-mcp --provider-only) remains available when you want vendor tools.
Context and banks
Section titled “Context and banks”Bank (or provider-equivalent user_id / dataset) is the scope key for a write or read. Default MCP scope is openmem-mcp. Project work should pass the resolved project bank so session noise does not land in the default.
Resolution order: longest matching index.yml bank prefix → ~/.config/personal-memory/coding-agent.json mapPathToBank → legacy Hindsight mapping → coding-agent::<repo-directory-name>. Details: Coding-agent scopes.
Formats
Section titled “Formats”Import/export goes through a format layer, not a provider-specific dump. PMM (Personal Memory Manifest) is the first format; more formats plug into the same orchestrator. See Portable memory (PMM).
Session hooks and skill
Section titled “Session hooks and skill”OpenMem installs one skill and session hooks (SessionStart / prompt / Stop) so agents recall and retain without remembering a vendor SDK. Optional: upstream Hindsight plugin via --hindsight-plugin.
Indexer
Section titled “Indexer”A shared indexer watches git repos, Obsidian vaults, notes trees, and feed caches, then writes through the active provider’s sink. Sources are provider-agnostic; only the sink changes with MEMORY_PROVIDER.
What OpenMem is not
Section titled “What OpenMem is not”- A replacement for Hindsight, mem0, or Cognee product UIs
- A guarantee that memories move losslessly between backends (export/import is explicit)
- A multi-provider fan-out in one process (one active provider; switch to change)
| Doc | Use when |
|---|---|
| Quickstart | First install |
| MCP setup | Unified memory_* MCP, native mem0/Cognee, NotebookLM |
| Portable memory (PMM) | Export/import between providers |
| Architecture | Runtime data paths |
| Provider status | Which backends ship |
| mem0 · Hindsight · Cognee | Provider operator guides |