codemem

The code is still there. The reasoning usually isn’t.

codemem is persistent coding memory across sessions, machines, and teammates for OpenCode, Claude Code, and Codex. It captures decisions, dead ends, and repository-specific traps, then automatically brings relevant context into later prompts.

• Automatic context injection — relevant memories reach the agent without asking it to search; unchanged memories already in OpenCode context are not repeated
• Optional sync and sharing — peer-to-peer sync carries selected project memory across machines; share project knowledge with a teammate or Team when it helps
• Local-first storage — memories live in SQLite on your machine; observer processing uses your configured model provider and can incur costs or consume plan usage
• Hybrid retrieval — FTS5 BM25 lexical search + sqlite-vec semantic search, merged and re-ranked
• Automatic injection for OpenCode 1 and 2 — the plugin injects context into every prompt, no manual steps; the OpenCode 2 integration is beta
• Claude Code plugin support — install from the codemem marketplace source
• Multi-agent — OpenCode, Claude Code, Codex, and pi share one project-scoped store
• Built-in viewer — browse memories, sessions, and observer output in a local web UI
• Remote MCP access — advanced single-user self-hosting can expose an OAuth-protected Streamable HTTP MCP endpoint to configured remote clients; keep the localhost viewer private (guide)

Synthetic project memories, not real session data. Explore the Feed, Facts, and Projects walkthrough to see how to inspect what was captured.

Quick start

Prerequisites: Node.js 24.15+ and npm (or pnpm). Native database support covers macOS x64/arm64, Linux x64/arm64 (glibc 2.34+ or musl), and Windows x64. 32-bit targets, including Linux armv7, are not supported.

Linux: set ONNXRUNTIME_NODE_INSTALL=skip in your shell and the environment that launches OpenCode, Claude Code, or Codex before the first package install. This avoids downloading the unused ONNX Runtime GPU provider while keeping CPU inference. Setup-managed npx launchers cannot set it themselves.

OpenCode

Codemem requires OpenCode 1.18.29 or newer. One installed @codemem/opencode-plugin package serves both host generations: OpenCode 1 calls its server() entrypoint and OpenCode 2 calls its setup() entrypoint. OpenCode 2 support is validated against the exact stable @opencode/cli@2.0.12 and @opencode/plugin@2.0.12 releases; Codemem labels its OpenCode 2 integration beta until it has shipped through a full release cycle.

On OpenCode 2 the plugin captures user and assistant messages, terminal usage, tool results, and session lifecycle events, and exposes the same mem-status, mem-recent, and mem-stats tools. Automatic recall runs through session.context: the latest user-message ID is required, and a missing or blank ID skips recall safely. Each identified turn performs one fresh retrieval; retries and tool continuations replay retained context byte-for-byte. Compaction, title, and generate hooks stay isolated. Both the default message surface and legacy CODEMEM_INJECT_SURFACE=system surface work. See OpenCode host support, troubleshooting, and rollback.

1. Install the OpenCode plugin and MCP config:

npx -y codemem setup --opencode-only

2. Restart OpenCode.

npx uses a downloaded or cached package to configure the OpenCode host; it does not create a durable codemem CLI installation. The configured plugin manages backend execution independently on both hosts, so no global install is required for automatic capture and context injection.

Setup writes the singular plugin key on purpose. OpenCode 1 requires that key, and OpenCode 2 translates it into its native plugins configuration, so one config entry works on both hosts. Keep one Codemem entry; if OpenCode loads Codemem twice for one project, the first registration wins and later copies skip their hooks with a warning.

3. Verify:

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

That's it. On either host, the plugin captures activity, builds memories, and injects relevant context from here on.

Try a fresh-session recall

After completing a task, check that its decision appears in the local viewer at http://localhost:38888. Start a new OpenCode session in the same project and ask about that decision without supplying the answer. For example, if your task involved a database migration:

What decision did we make about the database migration, and why?

Verify the answer against the stored decision and the original task evidence. If capture is still pending or recall is empty, inspect the local state:

npx -y codemem status
npx -y codemem db raw-events-status

Observer access and external-model costs

The observer is the model that turns captured activity into memories. Choose an OpenCode account, an API key, or a local Claude/Codex session in Settings. Explicit connections never fall back to another account; existing automatic setups keep their current rules until you change them. Local storage does not mean local-only processing: captured context is sent to the configured model, and calls can incur charges or consume plan usage. See configuration for options.

Installation, upgrades, and runtime details

codemem keeps one minimum Node.js version across published packages and workspace tooling.

If you want codemem on your PATH for manual commands and semantic retrieval, install the CLI globally. The CLI installs its matching embedding runtime by default:

# Linux: skip the unused ONNX Runtime GPU