Codemem

CI codecov Release

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

Quick start

Prerequisites: Node.js 24+ 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. Experimental Codex hook ingestion follows the same shared raw-event pipeline through POST /api/codex-hooks, codemem codex-hook-ingest, and a Codex-specific fallback spool.

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.

Codex (early beta)

Codex support is early beta — functional and dogfooded, but not yet promoted to a stable support tier. It installs through Codex's own plugin marketplace; there is no codemem setup step.

1. Add the codemem marketplace and install the plugin:

codex plugin marketplace add https://github.com/kunickiaj/codemem.git
codex plugin add codemem@codemem

2. Restart Codex.

The Codex plugin bundles its MCP config (codemem mcp) and hooks. Hooks call codemem from your PATH and fall back to npx -y codemem@<version>, so a global install is optional (installing codemem globally reduces hook latency). Validated targets are Codex CLI 0.135+ and current Desktop builds.

Codex hook ingestion shares the same raw-event pipeline as Claude and OpenCode: HTTP enqueue-first (POST /api/codex-hooks), then codemem codex-hook-ingest direct enqueue, with a Codex-specific spool fallback. UserPromptSubmit runs capture ingest in the background and injects memory context via additionalContext; disable injection with CODEMEM_INJECT_CONTEXT=0. See docs/plugin-reference.md for details and troubleshooting.

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, exactly deduplicated, and re-ranked using recency and memory-kind boosts. Near-related memories stay fully rendered by default; use compact rendering or CODEMEM_PACK_COMPRESSION=ids only when you intentionally want ID-based expansion via memory_get_observations.

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

Run codemem --help for the full list. Legacy top-level aliases (export-memories, import-memories, show, forget, remember) still work but are hidden from help.

Pack rendering defaults to self-contained context. For token-constrained experiments, codemem pack <context> --compact renders an index plus top details. Near-related compression is controlled by --compression-mode off|compact|ids (or CODEMEM_PACK_COMPRESSION); MCP memory_pack exposes the same setting as compression_mode. Use ids only when the agent can follow up with memory_get_observations.

MCP tools

To give the LLM direct access to memory tools (search, timeline, pack, remember, forget):

codemem setup --opencode-only

This updates your OpenCode config to install the plugin and register the MCP server. Restart OpenCode to activate.

The standalone codemem-mcp-ts binary runs the same stdio server used by codemem mcp. Viewer autostart is on by default for both invocation paths; set CODEMEM_VIEWER=0 or CODEMEM_VIEWER_AUTO=0 to disable.

For local HTTP transport testing, run codemem mcp http. It listens on 127.0.0.1:38889 by default and exposes Streamable HTTP at POST /mcp; use --host, --port, and --db-path to override those values. OAuth discovery metadata and Dynamic Client Registration are available at /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource/mcp, and /register; set --public-url or CODEMEM_MCP_HTTP_PUBLIC_URL to the externally reachable /mcp URL so advertised endpoints use the public origin. /authorize redirects through a configured upstream OIDC provider before issuing public-client authorization codes, /token supports PKCE S256 exchange, and /oauth/revoke revokes access tokens. When a public URL or OIDC configuration is present, POST /mcp requires a valid bearer token; local-only HTTP mode remains unauthenticated for development and still applies loopback Host/Origin checks. Non-loopback binds are rejected unless you explicitly pass --unsafe-public or set CODEMEM_MCP_HTTP_UNSAFE_PUBLIC=1.

Configuration

Config resolution precedence for runtime commands is:

1. explicit CODEMEM_CONFIG
2. workspace-scoped config derived from CODEMEM_RUNTIME_ROOT or CODEMEM_WORKSPACE_ID
3. legacy global config at ~/.config/codemem/config.json{c}

Environment variables still override file values once a config file has been selected.

Common overrides:

Viewer note:

• The plugin manages one explicit viewer target per runtime. If you run multiple viewers, give each one its own DB/runtime folder instead of sharing viewer.pid state next to the same SQLite file.

The viewer includes a grouped Settings modal (Connection, Processing, Device Sync) with shell-agnostic labels and an advanced-controls toggle for technical fields.

• Settings show effective values (configured or default) and only persist changed fields on save.
• The viewer HTTP service is intended for localhost-only use. It does not currently provide a general-purpose auth/session layer for safe public exposure.

Observer runtime/auth:

• Runtime options: api_http and claude_sidecar.
• api_http defaults to gpt-5.1-codex-mini (OpenAI path) unless you set observer_model.
• Anthropic direct API calls accept Anthropic model IDs/aliases. codemem maps the common Claude shorthand claude-4.5-haiku to Anthropic's direct API alias claude-haiku-4-5; you can also set a pinned snapshot like claude-haiku-4-5-20251001 explicitly.
• claude_sidecar defaults to claude-4.5-haiku; if the selected observer_model is unsupported by Claude CLI, codemem retries once with Claude's CLI default model.
• claude_sidecar command is configurable with claude_command (CODEMEM_CLAUDE_COMMAND) as a JSON argv array.
  • Config file example: "claude_command": ["wrapper", "claude", "--"]
  • Env var example: CODEMEM_CLAUDE_COMMAND='["wrapper","claude","--"]'
• Auth sources: auto, env, file, command, none.
• observer_auth_command must be a JSON string array (argv), not a space-separated string.
  • Config file example: "observer_auth_command": ["iap-auth", "--audience", "example"]
  • Env var example: CODEMEM_OBSERVER_AUTH_COMMAND='["iap-auth","--audience","example"]'
• Header templates support ${auth.token}, ${auth.type}, and ${auth.source} (for example Authorization: Bearer ${auth.token}).
• Queue cadence is configurable with raw_events_sweeper_interval_s (seconds) in Settings/config.

Export and import

Share project knowledge with teammates or back up memories across machines.

# Export current project
codemem memory export project.json

# Import on another machine (idempotent, safe to re-run)
codemem memory import project.json --remap-project ~/workspace/myproject

See codemem memory export --help and codemem memory import --help for full options. Legacy top-level aliases still work but are hidden from help.

Peer-to-peer sync

Replicate memories across devices without a central server.

codemem sync enable        # generate device keys
codemem sync pair          # generate pairing payload
codemem sync start         # start the viewer-backed sync runtime
codemem sync once          # run one immediate sync pass

The viewer now includes actor management for mapping multiple peers to one logical person, plus owned-memory visibility controls so project-filtered memories share by default while Only me stays a per-memory local override.

Project filters, peer-to-actor assignment, visibility controls, and config keys are documented in docs/user-guide.md.

For cross-network setups where peer addresses change frequently or mDNS does not cross VPN/network boundaries, codemem also supports optional coordinator-backed discovery with a self-hosted coordinator. The preferred deployment path is the built-in codemem coordinator service; see docs/coordinator-discovery.md.

Semantic recall

Embeddings are stored in sqlite-vec and written automatically when memories are created. Use codemem embed to backfill existing memories. If sqlite-vec cannot load, keyword search still works.

Alternative install methods

pnpm install
pnpm build
pnpm run codemem --help

npx -y codemem stats

Documentation

• Architecture — data flow, retrieval, observer pipeline, design tradeoffs
• Coordinator-backed discovery — self-hosted cross-network peer discovery
• User guide — viewer usage, sync setup, troubleshooting
• Plugin reference — plugin behavior, env vars, stream reliability
• Migration guide — migrating from opencode-mem
• Contributing — development setup, tests, linting, releases