Remem Memory

Automatic memory for Claude Code and Codex.

Language: English | 简体中文

remem is a single Rust binary that automatically captures, distills, and injects project context across sessions: decisions, patterns, preferences, and learnings. Stop re-explaining your project every new session.

The Problem

• Session amnesia: every new Claude Code session starts from zero.
• Lost context: bug-fix rationale and design decisions disappear after the session ends.
• Preference fatigue: the same preferences must be repeated every session.
• No continuity: long-running work is hard to resume with confidence.

How remem Solves This

Install

# Option 1: Quick install (prebuilt binary)
curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh

# Option 2: Cargo
cargo install remem-ai --bin remem

# Option 3: 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

# Configure detected Claude Code/Codex hooks + MCP
remem install

# Optional: target one host explicitly
remem install --target codex    # auto | claude | codex | all
remem install --dry-run         # preview config changes

Restart your AI coding tool after installation.

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, <1ms)
        '- Stop              -> 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.

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

LoCoMo

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

Internal Eval (1777 real memories)

Local QA Eval

python3 eval/local/run_local_eval.py --n 20

Requires .env with OPENAI_API_KEY (optional OPENAI_BASE_URL, OPENAI_MODEL).

Token Usage And Cost Reporting

remem records an AI usage ledger for its own background extraction, summary,
compression, and promotion calls. The CLI can report daily and weekly token
usage and estimated cost:

remem usage --days 14 --weeks 8
remem usage --project /path/to/project --days 30 --weeks 12

The report includes calls, input tokens, cache tokens, output tokens, reasoning
tokens, total tokens, estimated USD cost, and a precision note. Usage rows are
tagged by source:

• anthropic_usage: provider-reported usage from the Anthropic Messages API
• codex_log: exact token counts parsed from the current codex exec --json
turn.completed.usage event
• text_estimate: fallback estimate from prompt/response text length

Cost is an estimate, not an invoice. Historical rows may be text estimates or
may have been repriced from older rows that did not store the exact model.
Codex summarization defaults to gpt-5.2; set REMEM_CODEX_MODEL=auto to let
Codex choose its own default, or set any explicit Codex model name.

Commands

remem install
remem uninstall
remem doctor
remem search "query"
remem search "query" --branch main --type decision --multi-hop --offset 10
remem show <id>
remem eval
remem eval-local
remem backfill-entities
remem encrypt
remem api --port 5567
remem status
remem usage --days 14 --weeks 8
remem pending list-failed
remem pending retry-failed --dry-run
remem pending purge-failed --dry-run --older-than-days 7
remem review list
remem review approve <id>
remem review discard <id>
remem review edit <id> --text "updated memory"
remem preferences list
remem preferences add "text"
remem preferences remove 42
remem context --cwd .
remem cleanup
remem dream [--project X] [--dry-run]
remem install --target codex
remem mcp
remem sync-memory --cwd .

REST API

remem api --port 5567

Security

• SQLCipher encryption at rest (remem encrypt)
• Data directory permissions (0700)
• Key file permissions (0600)
• API binds localhost only (127.0.0.1)

Architecture Docs

See docs/ARCHITECTURE.md for full internals and data flow.

Uninstall

remem uninstall
rm -rf ~/.remem

License

MIT