Remem

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.*

DeepSeek Harness

The optional DSH adapter injects project context and captures live prompts, assistant text, and tools using the existing CLI. It targets published DSH 0.2.0-rc.2; the npm adapter is not yet published. Build the DSH-enabled remem 0.7.0 source before installing the adapter. Assistant-only claims remain available for review and cannot auto-promote without independent supporting evidence. Snapshot updates and removals respect the published DSH session invariant; remem preparation failures retain uncommitted prompts for an explicit retry, while cancellation leaves durable capture available to flush. Recovery across unload lasts until the in-flight remem callback exits; while loaded, agent/error also recovers later preparation failures. Host prepareCall runs after agent/request returns: after unload, failure can lose claimed input, while success still commits once without remem capture. Reload does not recover lost input or import events committed while unloaded. Oversized prompts, assistant messages, turn summaries and tool observations retain bounded evidence with explicit omissions before core redaction. Arbitrary DSH tool names retain their provenance but are external evidence; their names alone never authorize automatic promotion.

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

Codex installation, detection, doctor, uninstall, transcript scanning and default native-memory import all honor CODEX_HOME; the default is ~/.codex. Set it to an absolute directory before running these commands to select another Codex profile. Empty or relative overrides fail visibly before installation writes. Unrelated profile files stay untouched.

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. Its diagnostics do not create the data directory or write or rotate log files; findings and stderr warnings remain visible, and existing log health is inspected.

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 .

Why wasn't something remembered?

Use one read-only report to follow capture, extraction, review, current validity, and the latest recorded context run:

remem doctor memory "original phrase" --cwd .

remem doctor memory --host codex-cli --source-root local \ --project PROJECT_KEY --session-id SESSION_ID --json

Copy the exact selector from remem raw sessions --json. Use --injection-run-id RUN_ID to inspect a specific destination context emission. The source session and destination context run are distinct. Each evidence source is bounded at 20 rows; omitted evidence is marked. Terminal output shows retained source/status counts and three samples per source; --json includes all retained evidence. A missing match or per-item audit is unknown, not proof that capture failed or a guessed drop reason. Query discovery combines raw search with literal stored-text matches; try an original phrase or the exact session when a paraphrase finds no evidence. See the diagnosis contract.

Remem helps an Agent continue work; Refine helps people inspect and reuse knowledge; agent-sessions parses native source formats. Refine consumes Remem's existing session references, content fingerprints and commit/session links instead of collecting another transcript copy.

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.

Claude Code auto memory already saves notes automatically. The distinction is the memory surface and its evidence, retrieval, and lifecycle controls, rather than automatic persistence alone.

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.

Malformed generated extraction responses retry with the existing bounded backoff while keeping the same source evidence. Invalid stored evidence still requires repair; exhausted model attempts preserve raw capture and replay ranges for inspection instead of accepting incomplete output.

Observation extraction and session rollup split large backlogs into bounded event chunks. Each model call budgets system instructions, prompt formatting, and evidence together; completion advances only through the processed chunk. Raw evidence remains available when per-event prompt content is clipped. Exact recovery retains the original range and resumes verified successful chunks under the explicitly selected profile and one overall timeout. Already-existing linked successors resume from their own original bounds and checkpoints; a completed primary task does not hide a failed successor. Archived exact recovery claims the existing family atomically, suppresses new follow-up work, and archives unfinished members again if the attempt fails.

Workers persist fair queue and stage/project claim order, so continuing capture in a busy project leaves room for downstream extraction and durable jobs across once-worker restarts. The existing once-worker admission budget still applies.

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. Complete, user-supported security prohibitions, research activities and explicitly analytical quotations can enter human review in English or Chinese; they never auto-promote. Secret values, harmful instructions and unsupported external te