Remem

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

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

Language: English | [简体中文](README.zh-CN.md)

remem is 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.

[](https://github.com/majiayu000/remem/actions/workflows/ci.yml) [](https://github.com/majiayu000/remem/releases/latest) [](https://crates.io/crates/remem-ai) [](https://www.npmjs.com/package/@remem-ai/remem) [](LICENSE)

What You Get

• Claude Code, OpenAI Codex, and Codex CLI remember project decisions across sessions.
• 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.
• Current-memory contracts expose staleness, temporal/as-of truth, citation

usage, and injection audit state instead of treating recall as a black box.

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

Install

For Codex CLI:

brew install majiayu000/tap/remem
remem install --target codex
remem doctor

For Claude Code:

brew install majiayu000/tap/remem
remem install --target claude
remem doctor

If you do not use Homebrew:

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

Success Check

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"

remem install --target codex creates or updates:

• ~/.remem/.key and the encrypted ~/.remem/remem.db
• ~/.remem/config.toml memory-AI profiles
• Codex MCP registration in ~/.codex/config.toml
• Codex SessionStart/Stop hooks in ~/.codex/hooks.json

For a Codex-only setup, remem doctor reports Schema, Key format, Database, and the Codex Hooks/MCP rows as ok. If Claude Code config directories already exist, Claude rows can warn until you also run remem install --target claude or remem install --target all. If it warns about multiple remem binaries, follow the printed install-path fix so hooks keep using the intended binary.

Install With Your Coding Agent

Paste this into Claude Code or Codex CLI:

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

Why remem if Claude Code and Codex already have memory?

Built-in memory is useful for concise preferences and stable project guidance.

remem is for engineering memory that needs to be searchable, auditable, project-scoped, and recoverable:

• Search past decisions, bug fixes, and rationale with remem search
• Inspect why a memory was injected with remem why
• Keep memory local with SQLite and SQLCipher
• Use MCP and REST APIs from coding agents and local tools
• Track usage and background memory cost
• Avoid hand-maintaining large MEMORY.md or CLAUDE.md files

How remem Solves Session Amnesia

| Without remem | With remem | |---|---| | "We use FTS5 trigram tokenizer..." (every session) | Injected automatically from memory | | "Do not use expect() in non-test code" (again) | Preference surfaced before you ask | | "Last session we decided to..." (reconstruct manually) | Decision history with rationale | | Bug context lost after session ends | Root cause + fix preserved |

Other Install Channels

# Quick install options
curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | env REMEM_NO_CONFIG=1 REMEM_VERSION=vX.Y.Z sh
~/.local/bin/remem install --target codex

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

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

# npm wrapper
npm install -g @remem-ai/remem
remem install --target codex

# Cargo
cargo install remem-ai --bin remem
remem install --target codex

# Manual GitHub Release download
curl -LO https://github.com/majiayu000/remem/releases/latest/download/remem-darwin-arm64.tar.gz
tar xzf remem-darwin-arm64.tar.gz
mv remem ~/.local/bin/
codesign -s - -f ~/.local/bin/remem  # required on macOS ARM
remem install --target codex

# Build from source
git clone https://github.com/majiayu000/remem.git
cd remem
cargo build --release
cp target/release/remem ~/.local/bin/
codesign -s - -f ~/.local/bin/remem  # required on macOS ARM
remem install --target codex

Use one canonical remem command on PATH. Standalone and source installs should normally live at ~/.local/bin/remem; Windows standalone installs should use %USERPROFILE%\.local\bin\remem.exe. If you install through a package manager such as Homebrew or Cargo, update through that same channel and avoid keeping a second manual copy earlier or later on PATH. remem doctor and remem install --dry-run warn when multiple remem executables are visible.

Updating an Existing Install

When you replace the binary manually, rerun remem install so existing Claude Code and Codex hook commands pick up the current host-aware settings:

cargo build --release
cp target/release/remem ~/.local/bin/
codesign -s - -f ~/.local/bin/remem  # required on macOS ARM
remem install --target all

Verify the installed hooks include host-specific context commands:

jq -r '.hooks.SessionStart[]?.hooks[]?.command' ~/.claude/settings.json
jq -r '.hooks.SessionStart[]?.hooks[]?.command' ~/.codex/hooks.json

Expected commands are host-only; model, executor, and context policy live in ~/.remem/config.toml:

/Users/you/.local/bin/remem context --host claude-code
/Users/you/.local/bin/remem context --host codex-cli

Use With Codex

remem install --target codex configures Codex in four ways:

• Enables Codex hooks with [features].hooks = true in ~/.codex/config.toml
• Registers remem as an MCP server in ~/.codex/config.toml
• Writes Codex hook commands to ~/.codex/hooks.json
• Creates or updates ~/.remem/config.toml memory-AI profiles

After restarting Codex, remem automatically injects relevant project memory at session start and summarizes the session at stop. Codex can also call the MCP tools exposed by remem mcp, including search, get_observations, save_memory, workstreams, and timeline.

The default Codex integration is intentionally low-noise: it uses SessionStart for context injection and Stop for background summarization. Codex uses strict duplicate-injection gating via [memory_ai.hosts."codex-cli"].context_gate = "strict", so a mid-chat SessionStart repeat stays silent after the first injection for the same session. It does not install high-frequency Bash observation by default.

Codex Plugin

This repository includes a local Codex plugin wrapper in plugins/remem. The plugin exposes remem mcp and a Remem skill while keeping hook activation explicit. The complete product direction is documented in [docs/spec-codex-plugin-complete-design.md](docs/spec-codex-plugin-complete-design.md); the current plugin is the local development foundation, not the final self-contained plugin experience. To try it from a local checkout:

codex plugin marketplace add .
codex plugin add remem@remem-local

After installing the plugin, start a new Codex thread. To enable automatic SessionStart context injection and Stop summarization, run:

cargo build --release
node plugins/remem/scripts/activate-codex.js --dry-run
node plugins/remem/scripts/activate-codex.js

Distribution Channels

Currently published:

• Homebrew: brew install majiayu000/tap/remem
• GitHub Releases: prebuilt binaries for macOS and Linux on x64/arm64
• crates.io: cargo install remem-ai --bin remem
• npm: npm install -g @remem-ai/remem
• Source build: cargo build --release

Good next channels:

• apt/yum packages: useful later, after the binary install path and service

story are stable across Linux distributions

How It Works

remem uses host-specific hook strategies:

Claude Code workflow
        |
        |- SessionStart      -> Inject memories + preferences
        |- UserPromptSubmit  -> Register session, flush stale queues
        |- PostToolUse       -> Capture tool operations (queued,  Summarize in background (~6ms return)

Codex workflow
        |
        |- SessionStart      -> Inject memories + preferences
        '- Stop              -> Summarize in background with Codex CLI

Codex does not install a high-frequency PostToolUse(Bash) observe hook by default. Shell-heavy sessions must use the coalesced capture pipeline before per-command capture is enabled again; otherwise Bash output can create an unbounded backlog. Existing legacy hooks are also ignored unless REMEM_ENABLE_CODEX_BASH_OBSERVE=1 is set explicitly.

The capture pipeline starts with an append-only ledger: captured_events stores raw hook/session evidence, event_blobs keeps large payloads out of prompt-sized rows, and extraction_tasks coalesces work by host/project/session instead of creating one LLM job per tool call. Curated memory remains the promoted output of this pipeline, not the raw event itself.

Remem vs Built-in MEMORY.md

Built-in memory files are enough when the context is small, stable, and worth editing by hand: project rules, setup notes, and a short list of durable preferences. Keep using them for facts that should be obvious at first glance.

Remem is meant for the parts that should not depend on manual upkeep:

• Automatic capture and recall: hooks summarize sessions into a SQLite

memory store, while remem search, remem show, timeline, and MCP get_observations retrieve details on demand.

• A bridge to native memory: remem sync-memory --cwd . writes a compact

remem_sessions.md entry for Claude Code native memory when that directory exists, with a MEMORY.md pointer and a size guard. Full detail stays in the database and is fetched with remem search.

• A human-editable mirror: `remem export --markdown --output

./remem-memory --project "$PWD" writes one .md file per curated memory to an empty directory. After editing those files, remem import markdown --source ./remem-memory` updates existing rows and rebuilds search, entity, embedding, and current-state indexes. Export refuses non-empty directories to avoid overwriting manual edits.

• Failure-loop learning: raw transcripts that contain both concrete

build/test failure evidence and an explicit "stop and challenge the hypothesis" style lesson feed an idempotent failure lesson before summary cooldown, duplicate, or skip exits.

• Governance and auditability: remem why , `remem govern --action

stale --dry-run --json , remem status --json, and remem usage --days 14 --weeks 8` show why a memory is visible, what would change, store health, and memory-AI token/cost accounting.

• Current-memory accountability: staleness labels, temporal facts,

source-anchor checks, injection item audit rows, and citation/usage events show why a memory is current, stale, dropped, abstained, cited, or ignored.

• User-context governance: remem user ..., remem memory suppress ...,

profile export, and non-retention policy checks keep personalized recall explicit instead of silently blending every user fact into every project.

• Deterministic checks before claims: local gates include

cargo test -q context::claude_memory --lib, cargo test -q eval::golden --lib, cargo test -q eval::governance --lib, and remem eval-e2e --json.

Do not read this as a published claim that remem beats a carefully maintained MEMORY.md on coding tasks. The flagship no-memory / remem / curated-file A/B is still a separate benchmark requirement; until it is published, the honest claim is capability coverage and reproducible local checks.

Search Architecture

remem uses 4-channel Reciprocal Rank Fusion (RRF) inspired by Hindsight:

Query: "database encryption"
        |
   +----+------------------------------------+
   |          4 parallel channels            |
   +-----------------------------------------+
   | 1. FTS5 (BM25)   trigram + OR           |
   | 2. Entity Index  1600+ entities         |
   | 3. Temporal      "yesterday"/"last week" |
   | 4. LIKE fallback short tokens           |
   +-------------+---------------------------+
                 |
        RRF score = sum(1 / (60 + rank_i))
                 |
             Top-K merged results

Enhancements:

• Entity graph expansion (2-hop multi-hop retrieval)
• Project-scoped entity search (no cross-project leakage)
• CJK segmentation support
• Chinese-English synonym expansion
• Title-weighted BM25 (bm25(fts, 10.0, 1.0))
• Content-hash deduplication via topic_key
• Multi-step retrieval guidance in MCP tool descriptions

Benchmark Snapshot

Public Artifact Suite (Directional Only)

The checked-in eval/public artifacts now separate memory-system capability evidence from coding-agent outcome evidence. Reproduce the public verifier with:

cargo run -- bench verify --root eval/public --json-out /tmp/remem-bench-verify.json
cargo run -- bench report --root eval/public --json-out eval/public/reports/baseline.json --markdown-out eval/public/reports/baseline.md

The current directional report verifies 4 manifests, 4 reports, 25 run artifacts, and 125 artifact files. It includes:

• remem-code-memory: 8 memory QA runs covering temporal/as-of answers, stale

decision avoidance, conflicts, workstream continuity, prior bug root cause, architecture constraints, file/source anchors, and user-context relevance.

• adversarial-policy: 15 non-retention cases covering secrets, credentials,

payment data, unsupported assistant claims, unapproved external sources, roleplay, negation, same-name repos, branch divergence, stale file anchors, and unresolved conflicts.

• issue385-smoke: one committed coding-agent smoke run artifact with

memory-contract fields for remem runs. The full issue385-v1 fixture pack is referenced for dry-run reproduction, but it is not yet part of the verified public outcome report.

The report is intentionally labeled directional_only_no_public_claim. README and release wording must stay directional and avoid broad outcome or coding-task outcome claims until the public claim gate in [docs/release-lifecycle.md](docs/release-lifecycle.md) passes.

Isolated Coding-Agent Baseline (Internal, Not A Public Claim)

eval/coding-bench/reports/baseline.json contains an isolated 5-task, 3-runs-per-condition baseline generated with codex-cli 0.142.1 and gpt-5.5: no_memory resolved 2/15, remem resolved 15/15, and curated_file resolved 15/15. This is useful engineering evidence, but it predates the public 16-task v1 fixture pack and must be regenerated before it supports stronger product claims.

LoCoMo (Informational Only)

Full LoCoMo benchmark (10 conversations, 1540 QA pairs after adversarial skip):

This snapshot is a historical footnote and is not a CI or release gate. Us

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: majiayu000
• Source: majiayu000/remem
• License: MIT
• Homepage: https://majiayu000.github.io/remem/

Install and usage instructions live in the source repository linked above.