remem: Local-first memory for Claude Code and OpenAI Codex

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

Language: English | 简体中文

remem automatically captures, distills, searches, and injects engineering memory across Claude Code and OpenAI Codex CLI sessions. Decisions, bug-fix rationale, project patterns, and preferences stay available through hooks, MCP, CLI, and a localhost REST API.

A new Claude Code session recalls the earlier root cause, commit, and open TODO with memory citations and no re-explaining.

What remem gives you

• Automatic session capture and background LLM distillation.
• Project-scoped recall across Claude Code and Codex using one local store.
• Searchable decisions, bug fixes, architecture notes, preferences, and raw session evidence.
• Source attribution, staleness labels, suppression, review queues, and injection audits.
• SQLite with SQLCipher encryption by default for fresh installs.
• MCP, CLI, and authenticated localhost REST access from one Rust runtime.

remem prioritizes memory quality. Automatic capture is the primary path; manual save_memory calls supplement it when a decision needs to be recorded immediately.

Install in five minutes

Homebrew

brew install majiayu000/tap/remem
"$(brew --prefix remem)/bin/remem" install --target codex

Use --target claude for Claude Code. --target all configures every known host, including Cursor where its v1 renderer is supported.

Standalone installer

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

npm or Cargo

npm install -g @remem-ai/remem
# or
cargo install remem-ai --bin remem

remem install --target codex

GitHub Releases: prebuilt binaries for macOS and Linux on x64/arm64, with published checksums. Use one canonical remem executable on PATH; remem doctor warns when hooks and terminals resolve different copies.

For channel-specific upgrades, platform boundaries, PATH drift, and manual install notes, read the installation and upgrade guide. The broader documentation guide links plugin and operational material.

Verify the installation

Restart the selected coding agent, then run:

remem doctor
remem status
remem search "last decision"

A healthy Claude Code or Codex installation injects relevant project memory at SessionStart and queues durable session distillation at Stop. Codex also uses UserPromptSubmit to capture each prompt and surface compact optional memory candidates. remem doctor checks the schema, encryption key, database, hooks, MCP registration, worker, and common install-path drift.

Repository contributors can verify duplicate SessionStart suppression with the isolated executable smoke fixture.

For a focused, read-only view of current-memory truth:

remem doctor truth --cwd .

Host support

Cursor's v1 installer registers MCP only. The verified observe and summarize runtime commands exist, but remem install --target cursor does not install automatic capture hooks or SessionStart injection.

The repository also includes a Codex plugin wrapper. See plugins/remem/README.md for local plugin runtime and explicit hook activation instructions.

Why use remem alongside built-in memory

Built-in MEMORY.md, CLAUDE.md, and agent instruction files are ideal for a small set of stable facts that should always be visible. remem covers the engineering history that is too large, dynamic, or evidence-heavy to maintain by hand.

Use both. Keep concise rules in native files and let remem retain the long tail of decisions, failures, evidence, and changing project state.

The broader ecosystem comparison lives in the dated memory-tool survey.

How it works

Claude Code / Codex hooks
          |
          v
append-only captured_events ledger
          |
          v
coalesced background extraction and session rollup
          |
          v
governed candidates -> curated memories + workstreams + raw archive
          |
          v
FTS, entity, temporal, vector, graph, and optional local rerank retrieval
          |
          v
budgeted, source-attributed SessionStart context

Hooks return quickly after durable capture or queueing. Background workers perform extraction, candidate governance, compression, retrieval enrichment, and lifecycle cleanup. MCP, CLI, REST, and SessionStart share the same local store and governance model, but apply surface-specific eligibility policies. Explicit search is an inspection and recovery surface, so it may return labeled legacy_unverified memories; default SessionStart and CurrentTruth exclude those rows and record the reason.

Generated memory is treated as untrusted until it passes source-support, secret, instruction-pattern, scope, and lifecycle checks. Unsafe content is dropped or routed to review with a diagnosable reason.

For module ownership and current data flow, read docs/ARCHITECTURE.md.

The experimental MCP context_bundle tool exposes the versioned, budgeted compiler to explicit callers. The experimental remem context-plan command prints a request-specific retrieval plan. These opt-in interfaces are tracked by the Context Bundle and retrieval-router contracts.

The default Codex integration stays low-noise: SessionStart provides stable context, UserPromptSubmit provides a compact candidate index, and Stop queues background summarization. Prompt candidates contain IDs, titles, state, retrieval reason, estimated read cost, and a detail lookup hint, but no memory bodies. They are optional leads that Codex may ignore, open, or search beyond. The first prompt may also receive up to two continuity anchors so a prompt such as continue does not depend on lexical overlap. Existing hybrid RRF ranks memory candidates; no final confidence threshold decides relevance for the model.

Everyday workflows

Recall and inspect

remem search "database encryption"
remem search "deployment decision" --branch main --explain
remem show <memory-id>
remem why <memory-id>
remem current <state-key>

remem search keeps the terminal clean: per-query [INFO] [search-perf] diagnostics are written to the log file, not stderr, in normal use. Set REMEM_DEBUG=1 to mirror them to stderr while debugging.

Agents can use MCP search for compact results, then get_observations for selected details. Use raw recall only when curated memory misses exact transcript evidence:

remem raw search "exact phrase" --since 2026-06-01 --json

List complete host-bound sessions before reading an exact transcript:

remem raw sessions --latest 20 --json
remem raw messages --host codex-cli --source-root local \
  --project "/path/to/project" --session-id SESSION_ID --json
remem ingest-sessions --root codex-cli:archive=/path/to/sessions --json