remem-mcp — Local-first MCP Memory + CodeGraph + Wiki
LocalAbout remem-mcp — Local-first MCP Memory + CodeGraph + Wiki
remem-mcp gives coding agents local SQLite memory, code indexing, and a wiki, capturing errors and decisions for retrieval across sessions. It needs no cloud or database server, and memory can be shared with a team through Git.
Key features
- 01Persistent memory in local SQLite
- 02Automatic error capture and context injection
- 03tree-sitter-based code indexing
- 04Symbol search and caller analysis
- 05Memory retrieval, consolidation, and decay
- 06Share memory through Git exports
Use cases
- 01Recall earlier decisions after context compaction
- 02Retrieve past errors before retrying
- 03Find callers and assess code impact
- 04Sync memory with a team through Git
MCP support
As an MCP server, remem-mcp exposes recall, capture, CodeGraph, Wiki, and feedback tools to clients. Hooks also inject and save memory during sessions.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
48Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| mode | enum | No | The search mode.hybrid | keyword | vector |
| type | enum | No | Filter results by memory type. Use 'decision' to skip checkpoints/tasks, 'error' for past failures, etc.conversation | decision | learning | task | error | atom |
| limit | integer | No | The maximum number of results. |
| query | string | Yes | A natural language query. The tool uses this text for the BM25 search and the vector search. |
| format | enum | No | The response format. Use 'json' for structured data (e.g. benchmarks). Defaults to 'text'.text | json |
| offset | integer | No | The pagination offset. Use this to get the next page of results. |
| task_id | string | No | The task ID. Use this to isolate memory by a specific task. Link captures to a task for finer isolation. |
| team_id | string | No | The team ID. Use this to isolate memory by team. When set, all queries filter by this value. |
| user_id | string | No | The user ID. Use this to isolate memory by user within a team. When set with team_id, queries filter by both. |
| agent_id | string | No | The agent ID. Use this to isolate memory by agent role within a team. Defaults to the detected agent. |
| max_tokens | integer | No | The maximum number of tokens in the response. If the result exceeds this value, the tool truncates the text. |
| session_key | string | No | The session key. The default is hash(cwd). Use this to recall memory from a different project. |
Details
From the project READMEremem-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
npx remem-mcp setup
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 # index a directory
npx remem-mcp search-code --query "parseTar" # find symbols
npx remem-mcp callers <id> # who calls this?
npx remem-mcp impact <id> # blast radius
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 # health + hooks + DB + CodeGraph
npx remem-mcp viewer # web UI at localhost:7331
npx remem-mcp errors # error dashboard
npx remem-mcp recent [N] # recent captures
npx remem-mcp help all # full list of 40+ subcommands
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 # AMB only (~2 min)
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.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.