remem-mcp
Your coding agent stops repeating the same mistakes.
Local-first memory that survives context compaction. Learns from every error, injects fixes before the next attempt, and syncs to your git repo so your whole team shares it.
No API key. No cloud. No database server. Just a SQLite file.
Install
Auto-detects ZCode, Claude Code, Cursor, Devin, Codex. Registers MCP server + hooks.
Quick start
- Restart your agent (quit and reopen)
- Ask: "what do you remember?"
- If agent recalls past context = memory working
In your agent, you can say:
- "index the code in src" → CodeGraph indexes symbols
- "find who calls function X" → caller analysis
- "what do you remember?" → recall past context
What happens automatically
| When | What |
|---|
| Session start | Past errors, decisions, and persona injected into agent context |
| Each prompt | Matching memory injected into agent context |
| Failed commands | Auto-captured as error memories |
| Context compaction | Memory re-injected after compaction |
| Session end | Worker auto-extracts facts, consolidates summaries, updates persona |
You don't run any commands. The agent calls recall() before answering and capture() after work — the skill tells it to.
How it works
AI Agent (ZCode / Claude Code / Devin / Cursor / Codex)
│
├── MCP tools ──▶ recall, capture, codegraph_*, wiki_*, feedback
│
└── Hooks ──▶ SessionStart, UserPromptSubmit,
PostToolUse, PostCompaction, SessionEnd
│
▼
SQLite (memory.db)
L0 captures → L1 atoms → L2 scenarios → L3 persona
(raw) (facts) (summaries) (preferences)
CodeGraph: symbols + calls + imports (tree-sitter, 9 languages)
Memory links: Hebbian co-retrieval (frequently co-retrieved = stronger)
No LLM API key needed — rule-based extraction + keyword grouping.
CodeGraph
Structural code indexing via tree-sitter. The agent uses codegraph_search instead of grep to find symbols.
npx remem-mcp index --path src
npx remem-mcp search-code --query "parseTar"
npx remem-mcp callers <id>
npx remem-mcp impact <id>
9 languages: TS/JS/Python/Go/Rust/Java/C/C++/C#. 6-strategy call resolution (import-map → same-module → unique-name → suffix → fuzzy). Stdlib calls filtered out.
| Repo | Files | Symbols | Calls | Time |
|---|
| remem-mcp | 79 | 301 | 6,456 | 3s |
| AZR Go | 455 | 3,417 | 41,603 | 111s |
| Orca TS | 3,000 | 7,632 | 78,981 | 705s |
Why it's different
| remem-mcp | Mem0 | Claude MEMORY.md | Mneme |
|---|
| Survives compaction | Yes | Yes — cloud | No — 200-line cap | Yes |
| Learns from errors | Yes — auto | No | No | No |
| Search | Hybrid BM25 + vector + entities | Vector only | No | Vector + graph |
| Memory links | Hebbian co-retrieval | No | No | Graph |
| Decay/forget | Yes | No | No | No |
| CodeGraph | Yes — 6-strategy call resolution | No | No | No |
| Token offload | Yes — Mermaid canvas | No | No | No |
| Setup | 1 command | API key + cloud | Built-in | Build from source |
| Cost | Free | $19–249/mo | Free | Free |
Useful commands
npx remem-mcp status
npx remem-mcp viewer
npx remem-mcp errors
npx remem-mcp recent [N]
npx remem-mcp help all
Configuration
All settings have defaults. Config file is optional: ~/.config/remem-mcp/config.json.
| Setting | Env var | Default |
|---|
| DB path | REMEM_DB_PATH | ~/.local/share/remem-mcp/memory.db |
| Cross-project memory | REMEM_GLOBAL_SESSION_KEY | (unset) |
| Unified flow (F1+F2+F3) | REMEM_FLOW | (unset, set to full) |
| Suppress hook feedback | REMEM_QUIET | (unset, set to 1) |
Global memory policy — set REMEM_GLOBAL_SESSION_KEY to read cross-project memory automatically. Captures stay project-local unless the user explicitly asks to save globally; then use session_key: "global". Do not auto-classify ordinary captures into global.
Team sharing — npx remem-mcp sync-export writes .remem-mcp/memory-export.jsonl. Commit it to git. Team members get the same memory on git pull.
Per-repo capture exclusions — Drop a .remem.toml in any project root:
[capture]
ignore_paths = ["node_modules", "dist", ".git", "*.min.js"]
Benchmark
| Benchmark | remem-mcp | Mem0 | Without memory |
|---|
| AMB (L1/L2/L3) | 100/100/100 | — | — |
| LoCoMo (long conversation QA) | 95 | 92.5 | — |
| PersonaMem (personalization) | 100 | — | 48 |
| LongMemEval (ICLR 2025) | 96 | 94.4 | — |
bash scripts/bench-all.sh --quick
Architecture
See ARCHITECTURE.md for full system diagrams, schema, and performance details.
Credits
Core based on TencentDB Agent Memory (MIT, Tencent 2026). CodeGraph call resolution adapted from Codebase-Memory (arXiv:2603.27277). Recall boost adapted from ai-memory by Akita On Rails. Contextual retrieval from Anthropic (2024).
License
MIT. See LICENSE.