Remem Memory
majiayu000/remem
Memória persistente automática para Claude Code e Codex
Ver no GitHubMCP server em Rust que captura e injeta automaticamente contexto de projeto (decisões, padrões, preferências) entre sessões do Claude Code e Codex. Elimina a necessidade de re-explicar o projeto a cada nova sessão, mantendo continuidade e histórico de decisões.
Instalação
npx convez-ai majiayu000/remem1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter contexto de decisões arquiteturais entre sessões
- Preservar preferências de código e padrões de projeto
- Rastrear histórico de bugs e suas soluções
- Garantir continuidade em trabalhos de longa duração
Veredito

Solução robusta e bem-implementada que resolve um problema real em workflows de IA: a amnésia de contexto entre sessões. Integração nativa via MCP e instalação simplificada tornam sua adoção prática, especialmente para projetos complexos que exigem continuidade.
README
A tradução para o português deste README ainda está na fila.
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 Claude Code and Codex sessions: decisions, patterns, preferences, and learnings. Stop re-explaining your project every new session.

The Problem
- Session amnesia: every new Claude Code or Codex 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
| 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 |
Install
# Option 1: Homebrew
brew install majiayu000/tap/remem
# Option 2: Quick install (prebuilt GitHub Release binary, then auto-configures hooks)
curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh
# Pin a specific release or install into a custom bin directory
REMEM_VERSION=v0.5.42 curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh
REMEM_INSTALL_DIR=/usr/local/bin curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh
REMEM_NO_CONFIG=1 curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | sh
# Option 3: 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
# Option 4: Cargo
cargo install remem-ai --bin remem
# Option 5: 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
# If you used Cargo or source install, 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.
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
For Codex-only setup:
remem install --target codex
remem doctor
remem status
remem install --target codex configures Codex in three ways:
- Enables Codex hooks with
[features].hooks = truein~/.codex/config.toml - Registers
rememas an MCP server in~/.codex/config.toml - Writes Codex hook commands to
~/.codex/hooks.json - Creates or updates
~/.remem/config.tomlmemory-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;
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 @majiayu000/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, <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 (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. Use the golden retrieval eval for deterministic gating; LoCoMo remains useful only for manual, informational comparison because the methodology is disputed.
| Config | Overall | Single-hop | Multi-hop | Temporal | Open-domain | Ingest | Model |
|---|---|---|---|---|---|---|---|
| v1 (fair) | 56.8% | 67.1% | 39.0% | 53.9% | 28.1% | per-turn | gpt-5.4 |
| v2 (optimized) | 62.7% | 72.3% | 61.3% | 40.5% | 56.2% | session_summary | gpt-5.4 |
Internal Eval (1777 real memories)
| Metric | Value |
|---|---|
| MRR | 0.858 |
| Hit Rate@5 | 1.000 |
| Dedup rate | 1.0% |
| Project leak | 0% |
| Self-retrieval | 100% |
Local QA Eval
python3 eval/local/run_local_eval.py --db ~/.remem/remem.db --n 20
| Metric | Score |
|---|---|
| Overall | 85.0% |
| Decision | 77.8% |
| Discovery | 87.5% |
| Preference | 100% |
| Source in top-20 | 90.0% |
Requires explicit --db plus .env with OPENAI_API_KEY (optional OPENAI_BASE_URL, OPENAI_MODEL).
Sandboxed E2E Eval
remem eval-e2e
remem eval-e2e --json
Runs a deterministic coding-agent memory corpus through the real local REST API
boundary (POST /api/v1/memories, then GET /api/v1/search) with a temporary
REMEM_DATA_DIR. The default run removes the sandbox directory afterward, so it
does not touch ~/.remem or other real memory data. Use --keep-data-dir when
you need to inspect the generated database.
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 APIcodex_log: exact token counts parsed from the currentcodex exec --jsonturn.completed.usageeventtext_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.
Memory AI Configuration
Memory AI execution is configured in ~/.remem/config.toml (override path with
REMEM_CONFIG). Hooks pass only --host; the config maps each host to one
profile used by summarize, flush/extract, compress, and dream.
remem config path
remem config show
remem config set memory_ai.profiles.codex.model gpt-5.2
For normal model switching, prefer the higher-level remem model commands:
remem model current
remem model list
remem model use cheap
remem model use balanced --dry-run
remem model use gpt-5.2 --reasoning medium
remem model use haiku --host claude-code
remem model test
remem model test --live
remem model rollback
remem model test only validates the selected config unless --live is set.
remem model use saves a rollback backup before writing the config. Built-in
presets are Codex-focused; use explicit model names for Claude Code profiles.
Default Codex profile:
[memory_ai.hosts."codex-cli"]
memory_profile = "codex"
context_gate = "strict"
context_color = true
capture_adapter = "codex-cli"
[memory_ai.profiles.codex]
executor = "codex-cli"
model = "gpt-5.2"
path = "codex"
Commands
remem install
remem uninstall
remem doctor
remem search "query"
remem search "query" --branch main --type decision --multi-hop --offset 10
remem search "query" --json
remem show <id>
remem show <id> --json
remem eval
remem eval-e2e --json
remem eval-local
remem backfill-entities
remem encrypt
remem api --port 5567
remem status
remem status --json
remem config show
remem config set memory_ai.profiles.codex.model gpt-5.2
remem model current
remem model list
remem model use balanced --dry-run
remem model use gpt-5.2 --reasoning medium
remem model use haiku --host claude-code
remem model test [--live]
remem model rollback
remem usage --days 14 --weeks 8
remem pending list-failed
remem pending list-failed --json
remem pending retry-failed --dry-run
remem pending purge-failed --dry-run --older-than-days 7
remem govern --action stale --dry-run --json <id>
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 --dry-run --json
remem cleanup
remem dream [--project X] [--profile NAME] [--dry-run]
remem install --target codex
remem mcp
remem sync-memory --cwd .
Scriptable JSON output
These commands emit one JSON object and no human text on stdout when --json
is set:
| Command | Stable top-level fields |
|---|---|
remem status --json | version, database, totals, capture_pipeline, pending_observations, jobs, worker_daemon, today, top_projects |
remem cleanup --dry-run --json | dry_run, retention_days, plan, applied |
remem search ... --json | query, project, memory_type, limit, offset, branch, include_stale, multi_hop_requested, explain_requested, count, has_more, next_offset, results, raw_hits, multi_hop, explain_details |
remem show <id> --json | found, id, memory |
remem pending list-failed --json | project, limit, count, failed |
remem govern ... --json | dry_run, action, reason, affected |
REST API
remem api --port 5567
TOKEN=$(cat ~/.remem/.api-token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/status
Library users who build the router directly should call
remem::api::ensure_api_token() before remem::api::build_router(...).
| Endpoint | Method | Description |
|---|---|---|
/api/v1/search?query=&project=&type=&limit=&offset=&branch=&multi_hop= | GET | Search memories |
/api/v1/memory?id= | GET | Get one memory |
/api/v1/memories | POST | Save memory |
/api/v1/status | GET | System status |
Security
- SQLCipher encryption at rest (
remem encrypt) - Data directory permissions (
0700) - Key file permissions (
0600) - REST API binds localhost only (
127.0.0.1) and requiresAuthorization: Bearer $(cat ~/.remem/.api-token) - API token file permissions (
0600)
Architecture Docs
See docs/ARCHITECTURE.md for full internals and data flow.
Uninstall
remem uninstall
rm -rf ~/.remem
License
MIT