remem

remem: Local-first Coding Agent Memory for Claude Code and OpenAI Codex

Stop re-explaining your project every new coding-agent session.

rememis a single Rust binary that automatically captures, distills, searches, and injects project memory across Claude Code, OpenAI Codex, and Codex CLI sessions. It keeps decisions, bug-fix rationale, project patterns, and preferences available through hooks, MCP, CLI, and REST without requiring an external database.

Real Claude Code session on a demo repo: a brand-new session recalls last week's root cause, commit, and open TODO — with memory citations, zero re-explaining.

- Claude Code, OpenAI Codex, and Codex CLI remember project decisions across sessions.
- Cursor has a v1 integration:remem install --target cursorregisters the remem MCP server (macOS/Linux), and the runtime commands for tool-event capture (remem observe --host cursor, GH-823) and Stop transcript summarization (remem summarize --host cursor, GH-825) are merged. The v1 install surface does not register Cursor hook entries yet, so automatic Cursor memory capture is not enabled, and session-init injection is not supported on Cursor. See the[Cursor capability matrix.
- Bug-fix rationale, preferences, and project patterns are searchable.
- Memory stays local by default with SQLite and SQLCipher.
- Hooks, MCP tools, CLI commands, and a localhost REST API use the same store.
- The experimental MCPcontext_bundletool compiles a versioned, budgeted, source-attributed SessionStart context bundle with a complete selection/drop audit, including redacted poisoning-gate drops and canonical memory, session, and preference preselection reasons. Poisoned session/workstream text is rejected before it can steer implicit retrieval. High-risk requests return only user-authored trusted memories and abstain when none survive. It requiresschema_version: 1; its foreground query embeddings are local-only, ambient reranking is disabled, retrieval weights are fixed to the bundle v1 policy instead of ambient overrides, and the effective local embedding provider/model/dimensions are fingerprinted intoplan_hash. The shape is intentionally not yet a stable API commitment.
- Bundle-backed SessionStart emissions persist a payload-free, hash-verified audit linked to the existing per-item injection rows. The durable record contains plan/policy/schema versions, selection and token-budget aggregates, degraded/truncation state, and canonical audit reason metadata. Delta-mode previews rewind to the last complete item boundary, then records are resealed to the identities and token estimate actually emitted, including when gate state persistence fails after preview construction; no record stores memory titles, memory bodies, or rendered hook output.
- Current-memory contracts expose staleness, temporal/as-of truth, citation usage, and injection audit state instead of treating recall as a black box.
- Active memories without sufficient provenance, confidence, validity, or mutable-state identity are classified as legacy_unverified. They remain recoverable through labeled search/detail, but are excluded from CurrentTruth and default SessionStart context with stable audit reasons.
- User-context controls keep personal claims, profile summaries, suppression feedback, and Markdown export explicit and reviewable.
- One Rust binary; no hosted database or separate memory service.

Then configure hooks and MCP for your installed coding agents:

REMEM_INSTALL_BINARY="$(brew --prefix remem)/bin/remem" remem install --target codex # or: REMEM_INSTALL_BINARY="$(brew --prefix remem)/bin/remem" remem install --target claude # or: REMEM_INSTALL_BINARY="$(brew --prefix remem)/bin/remem" remem install --target all

curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | env REMEM_NO_CONFIG=1 sh ~/.local/bin/remem install --target codex # or: ~/.local/bin/remem install --target claude # or: ~/.local/bin/remem install --target all

remem installcan auto-detect existing Claude Code, Codex CLI, and Cursor config directories. On first-time setups, use--target codex,--target claude, or--target allso remem can create the selected config files.

--target cursor(macOS/Linux) manages only the user-level~/.cursor/hooks.jsonand~/.cursor/mcp.json: it registers the remem MCP server, strictly validates both files, and preserves foreign entries semantically for the validated snapshot (coordinated updates use staged apply with compensating rollback, not a cross-file atomic transaction, and edits landing between the final comparison and the rename can still be lost). Install contract v1 registers no Cursor hook entries — automatic Cursor memory is not enabled — andsession-initis not supported on Cursor.--target autoincludes Cursor only when a Cursor config is detected on macOS/Linux; Windows is skipped with a diagnostic because no hook command renderer is approved there, and--repairdoes not cover Cursor. Before downgrading remem, runremem uninstall --target cursorwith the current version first.

Capabilities below reflect the merged runtime, not planned work:

Runremem doctorwhen you want to verify or troubleshoot the integration. If Claude Code reports a Hook Integrity Warning or doctor shows incomplete Claude hooks, run:

Repair mode restores only user-level Claude hooks in~/.claude/settings.json. It preserves third-party hooks, does not write.claude.jsonMCP settings, and does not initialize the runtime store or API token.

Whatremem installconfigures, and what a new Codex session receives at SessionStart. The demo uses a temp HOME and temp database; no private memories are shown.

Start a new Claude Code or Codex CLI session after installation. remem should inject relevant project memory at session start and summarize durable memory after the session stops. Then run:

remem status remem search "last decision"

For a focused, read-only view of the CurrentTruth projection, run:

remem doctor truth --cwd . remem doctor truth --cwd . --branch main --as-of-epoch 1735689600 --json

The diagnostic summarizes current results, surfaced conflicts and abstentions, supersedes links, non-current or dangling claim references, and the explicit stored-status to lifecycle mapping. It does not print claim text and never migrates or writes the database.--projectaccepts an exact stored project key; otherwise--cwd(or the current directory) is normalized to the project key.--subjectaccepts an exact memory topic key, a bare user-claim key, or its explicittype:keyform. Warnings exit with status 1, including in quiet mode. The selector also scopes lifecycle counts; object kinds without a matching subject identity are omitted from a subject-focused report. When--as-of-epochis omitted, the report samples one effective epoch, returns it asas_of_epoch, and uses it for every projection and diagnostic query in the same read snapshot. Every explicit historical cutoff is reported as unreconstructable and exits with a warning until versioned lifecycle history can prove in-place status changes.

For Codex CLI,remem installcreates or updates:

- ~/.remem/.keyand the encrypted~/.remem/remem.db
- ~/.remem/config.tomlmemory-AI profiles
- Codex MCP registration in~/.codex/config.toml
- Codex SessionStart/Stop hooks in~/.codex/hooks.json

For a Codex-only setup,remem doctorreports Schema, Key format, Database, and the Codex Hooks/MCP rows as ok. If Claude Code config directories already exist but were not auto-detected during installation, runremem install --target claudeorremem install --target all. If doctor warns about multipleremembinaries, follow the printed install-path fix so hooks keep using the intended binary.

Paste this into Claude Code or Codex CLI:

Install remem for this repository. Use the official README. Configure it for this agent, runremem doctor, verify that session memory is working, and summarize what was installed.