codemem

codemem

Persistent memory for OpenCode and Claude Code. codemem captures what you work on across sessions, retrieves relevant context using hybrid search, and injects relevant context automatically in OpenCode.

• Local-first — everything lives in SQLite on your machine
• Hybrid retrieval — FTS5 BM25 lexical search + sqlite-vec semantic search, merged and re-ranked
• Automatic injection — the OpenCode plugin injects context into every prompt, no manual steps
• Claude Code plugin support — install from the codemem marketplace source
• Built-in viewer — browse memories, sessions, and observer output in a local web UI
• Peer-to-peer sync — replicate memories across machines without a central service

Light	Dark

Quick start

Prerequisites: Node.js 22+ and npm (or pnpm)

OpenCode

1. Install the OpenCode plugin and MCP config:

npx -y codemem setup --opencode-only

2. Restart OpenCode.

The OpenCode plugin manages backend execution automatically — no separate global install is required.

3. Verify:

# Works on fresh installs (no global codemem needed)
npx -y codemem stats
npx -y codemem db raw-events-status

That's it. The plugin captures activity, builds memories, and injects context from here on.

If you want codemem available directly on your PATH for manual commands, install the CLI globally:

npm install -g codemem

OpenCode plugin and CLI are now split intentionally:

• @codemem/opencode-plugin — OpenCode plugin package
• codemem — CLI and MCP commands

Claude Code (marketplace install)

1. Install codemem's Claude MCP config:

npx -y codemem setup --claude-only

2. In Claude Code, add the codemem marketplace source and install the plugin:

/plugin marketplace add kunickiaj/codemem
/plugin install codemem

The Claude plugin starts MCP with the TS CLI (codemem mcp).

Claude hook ingestion is HTTP enqueue-first (POST /api/claude-hooks) and falls back to direct local DB enqueue via codemem claude-hook-ingest when the local server path is unavailable.

Claude hook events share the same raw-event queue pipeline used by OpenCode. UserPromptSubmit runs capture ingest in the background and injects memory context via Claude additionalContext using local pack generation by default, with optional HTTP /api/pack fallback.

Migrating from opencode-mem? See docs/rename-migration.md.

How it works

Adapters hook into runtime event systems (OpenCode plugin and Claude hooks). They capture tool calls and conversation messages, flush them through an observer pipeline that produces typed memories, and surface retrieval context for future prompts.

sequenceDiagram
participant OC as OpenCode
participant PL as codemem plugin
participant ST as MemoryStore
participant DB as SQLite

OC->>PL: tool.execute.after events
OC->>PL: experimental.chat.system.transform
PL->>ST: build_memory_pack with shaped query
ST->>DB: FTS5 BM25 lexical search
ST->>DB: sqlite vec semantic search
ST->>ST: merge rerank and section assembly
ST-->>PL: pack text
PL->>OC: inject codemem context

Retrieval combines two strategies: keyword search via SQLite FTS5 with BM25 scoring and semantic similarity via sqlite-vec embeddings. In the pack-building path, results from both are merged, deduplicated, and re-ranked using recency and memory-kind boosts.

Injection happens automatically. The plugin builds a query from the current session context (first prompt, latest prompt, project, recently modified files), calls build_memory_pack, and appends the result to the system prompt via experimental.chat.system.transform.

Memories are typed — bugfix, feature, refactor, change, discovery, decision, exploration — with structured fields like facts, concepts, files_read, and files_modified that improve retrieval relevance. Low-signal events are filtered at multiple layers before persistence.

For architecture details, see docs/architecture.md.

CLI