remem-mcp
The server is a local-first, SQLite-backed memory layer for coding agents. It lets agents recall past context, capture decisions/errors/learnings, and share memory across sessions and teams.
Memory retrieval:
recall,search,related,explain_recall— hybrid keyword/vector search with filters, pagination, and scoring explanations.Memory capture:
capture,adr,handoff,session_end,session_checkpoint— store facts, decisions, session summaries, and structured handoffs.Memory maintenance:
update,forget,consolidate,resolve,supersede,correct,confirm,feedback— edit, delete, merge, resolve conflicts, and rank memory quality.Persona & scenarios:
persona_update,scenario_create— build L3 user preferences and L2 consolidated summaries from L1 atoms.CodeGraph:
codegraph_index/search/callers/callees/impact/list/detect_changes/stats— index code symbols, find callers/callees, assess impact, and detect changed-symbol blast radius.Wiki:
wiki_ingest/search/get/outdated— ingest markdown docs and search/read wiki pages with links and backlinks.Knowledge assets:
knowledge_create/get/list/delete— register wiki or code-graph assets for teams.Skills:
skill_create/get/list/search/archive— create reusable SOPs and inject them on matching triggers.Session tools:
session_start,session_end,session_checkpoint— manage session context across compactions or multi-turn work.Health & stats:
health,stats,correction_kpis— diagnose DB health, view memory breakdown, and track correction effectiveness.Token offload:
canvas_get,ref_read— view a compact Mermaid task canvas and drill into raw node outputs.
Allows syncing the agent's memory to a Git repository for team sharing, by exporting memory to a JSONL file and auto-importing on startup.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@remem-mcp Before you start, remember what we learned from past build errors."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
npx remem-mcp setupAuto-detects ZCode, Claude Code, Cursor, Devin, Codex. Registers MCP server + hooks.
Related MCP server: local-agent-context
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 radius9 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+ subcommandsConfiguration
All settings have defaults. Config file is optional: ~/.config/remem-mcp/config.json.
Setting | Env var | Default |
DB path |
|
|
Cross-project memory |
| (unset) |
Unified flow (F1+F2+F3) |
| (unset, set to |
Suppress hook feedback |
| (unset, set to |
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.
Available Tools
48 toolsadrA
Record an Architecture Decision Record (ADR). Use this tool when you make a technical decision that future agents should know about. The ADR is stored as a structured capture and can be recalled by any agent working on the same project.
Inputs: title (required), context (required), decision (required), tags, +7 more.
canvas_getA
Get the Mermaid task canvas for the current session. The canvas is a symbolic graph of tool calls and state transitions — it replaces verbose tool logs in your context with a compact Mermaid diagram. Use this to see the task structure without re-reading full tool outputs. Requires REMEM_OFFLOAD_ENABLED=true and pipeline=mermaid.
Inputs: format, session_key.
captureA
Store a decision, a learning, or a task outcome to memory. Call this tool after you complete a non-trivial task, make a decision, or fix a bug with a known root cause. You can capture a single text string, or a list of role-based conversation messages. Captures are project-local by default. Write to global memory ONLY when the user explicitly asks to remember something across projects/globally; then pass session_key="global".
Inputs: tags, type, atoms, format, +13 more.
codegraph_calleesA
Find all callees of a symbol — what does this function call? Returns the called functions with file paths and line numbers. Requires the symbol ID from codegraph_search.
Inputs: symbol_id (required), limit.
codegraph_callersA
Find all callers of a symbol — who calls this function? Returns the calling functions with file paths and line numbers. Requires the symbol ID from codegraph_search.
Inputs: symbol_id (required), limit.
codegraph_detect_changesA
Detect uncommitted git changes and map them to affected symbols with blast radius. Runs git diff --name-only to find changed files, finds symbols in those files, then traces callers to determine impact. Returns affected symbols + risk classification.
Inputs: repo_path (required), team_id, max_depth.
codegraph_entry_pointsA
Find entry points in the codebase — main functions, HTTP handlers, CLI commands, event handlers. An entry point is called by external infrastructure (HTTP server, CLI framework, event loop) rather than by other code. Inspired by codegraph-ai's find_entry_points.
Inputs: repo_path (required), limit, team_id.
codegraph_impactA
Perform impact analysis: if I change this symbol, what else might be affected? Traverses the call graph upward (callers of callers) to find all potentially impacted code. Requires the symbol ID from codegraph_search.
Inputs: symbol_id (required), max_depth.
codegraph_indexA
Index a file or directory into the code graph. Extracts symbols (functions, classes, methods), call relationships, and imports. Supports TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, C#. Note: codegraph_search auto-indexes on first use, so you only need this for explicit re-indexing or custom paths.
Inputs: path (required), team_id, max_files, repo_path.
codegraph_listA
List all symbols in a file or directory. Returns symbols sorted by line number. Use this to get an overview of what a file contains.
Inputs: file_path (required), kind, limit, team_id.
codegraph_searchA
Search for code symbols by name. Returns matching functions, classes, methods, etc. with file paths and line numbers. Use this INSTEAD of grep when looking for function/class/method definitions. If the codebase hasn't been indexed yet, this starts background indexing and asks you to retry in a few seconds — non-blocking, so you can continue working while indexing runs.
Inputs: query (required), kind, path, limit, +2 more.
codegraph_statsA
Return indexed CodeGraph statistics: total symbols, calls, resolved calls, imports, and file counts. Optionally scoped to a repo_path. Use this to check indexing coverage before searching.
Inputs: team_id, repo_path.
confirmA
Confirm that a memory is accurate. Increments the Bayesian confirmation count, raising its confidence score in future searches. Use when a recalled memory proved helpful and correct.
Inputs: capture_id (required).
consolidateA
Find and merge duplicate or near-duplicate memories. Use this when you suspect redundant captures (e.g. same decision captured twice). Returns groups of similar captures. Set confirm=true to merge them. Use batch_size to limit how many captures are processed in one call (cost control).
Inputs: confirm, threshold, batch_size, session_key.
correctA
Mark a memory as inaccurate or outdated. Increments the Bayesian correction count, lowering its confidence score in future searches. Use when a recalled memory was wrong, misleading, or superseded by newer information.
Inputs: capture_id (required), reason.
correction_kpisA
Get correction learning metrics: total corrections, average precision, heed rate, noise candidates (precision < 0.3), and high-signal candidates (precision >= 0.8). Use this to evaluate memory quality and identify unhelpful corrections to prune.
Inputs: no named parameters.
explain_recallA
Explain WHY a memory was recalled for a given query. Shows the BM25 score, vector score, RRF fused score, rank, and matching keywords for each result. Use this to debug unexpected recall results or to understand the retrieval pipeline. If you provide a capture_id, the tool explains why that specific capture was or was not retrieved.
Inputs: query (required), mode, limit, task_id, +5 more.
feedbackA
Record a quality signal for a recalled memory. Call this AFTER using a recall result: use 'helpful' if the memory answered your question, 'not_helpful' if it was irrelevant, 'stale' if the information is outdated, or 'wrong' if it is incorrect. This creates a feedback flywheel — useful memories rise, unhelpful ones fade. Do not call this for memories you have not actually used.
Inputs: signal (required), capture_id (required), reason.
forgetB
Delete specific memory entries. Use this tool only when the user requests a deletion. Do not auto-forget.
Inputs: id, filter, format, reason, +2 more.
handoffA
Write a structured handoff packet for the next agent session. Call this tool at the end of a session, or before you switch to a different agent. The next agent calls recall to load this packet and continue without re-reading files. This saves 60-85% of tokens compared to re-discovering context.
Inputs: task (required), status (required), progress (required), files, +7 more.
healthA
Diagnose memory server health: DB integrity, index status, capture count, schema version, embedding model.
Inputs: no named parameters.
knowledge_createA
Register a knowledge asset (wiki or code-graph) for the team. The asset metadata is stored locally. The actual content is processed by an external knowledge service.
Inputs: name (required), type (required), team_id (required), branch, +3 more.
knowledge_deleteB
Delete one or more knowledge assets by ID.
Inputs: knowledge_ids (required).
knowledge_getA
Get a single knowledge asset by ID.
Inputs: knowledge_id (required).
knowledge_listB
List knowledge assets for a team. Optionally filter by type.
Inputs: team_id (required), type.
persona_updateA
Update the L3 persona profile for this user/team. Call this when you notice a user preference or pattern (e.g., 'prefers concise output', 'works in Vietnamese', 'uses AZR project'). Persona is injected at SessionStart — every session gets it automatically in ~50 tokens. No LLM needed — you write the trait/value yourself.
Inputs: trait (required), value (required), task_id, team_id, +2 more.
recallA
Retrieve relevant past memory. Call this tool before you answer the user. Use it when the user references past work or when the task needs project context. Automatically searches both project memory and global cross-project memory (rules, learnings) when REMEM_GLOBAL_SESSION_KEY is configured.
Inputs: query (required), mode, type, limit, +8 more.
record_outcomeA
Record whether a correction was heeded (agent followed the advice) or recurred (same error happened again). This tracks correction effectiveness over time. Call after applying a correction to a recalled memory.
Inputs: outcome (required), capture_id (required).
ref_readA
Read the raw tool output for a specific canvas node by node_id. Use this to drill down from the Mermaid canvas to the full output when you need details. Requires REMEM_OFFLOAD_ENABLED=true and pipeline=mermaid.
Inputs: node_id (required).
resolveA
Resolve a conflict between two captures. Mark one as the winner and the other as stale. Call this tool when capture reports a conflict between two memories.
Inputs: loser (required), winner (required), reason.
scenario_createA
Consolidate multiple L1 atoms into an L2 scenario summary. Call this when you have 5+ atoms about the same topic — it creates a high-signal summary that recall injects in ~100 tokens instead of 5+ individual atoms. No LLM needed — you write the summary yourself based on the atoms you've seen.
Inputs: summary (required), atom_ids (required), task_id, team_id, +4 more.
searchA
Search memory by keyword or by semantic similarity. Use this tool when recall is too broad and you need specific facts. Automatically searches both project and global cross-project memory when REMEM_GLOBAL_SESSION_KEY is configured.
Inputs: query (required), mode, limit, format, +3 more.
session_checkpointA
Create a checkpoint of the current session state. Returns a checkpoint ID that can be used to resume later. Stores recent captures as a named snapshot.
Inputs: name (required), summary.
session_endA
Close a session and optionally capture a summary. Call this at the end of a conversation to record what was accomplished.
Inputs: tags, summary.
session_startA
Open a session and return recent context. Call this at the start of a multi-turn conversation to get a summary of recent captures and correction alignment metrics. Returns both project-specific and global cross-project memory when configured.
Inputs: session_key, context_query.
skill_archiveA
Archive a skill — forces it to always be injected into recall, even when the query doesn't strongly match. Use this for critical SOPs that must always be available.
Inputs: id (required).
skill_createA
Create a reusable skill (SOP) from a successful task or conversation. Skills are injected into recall when matching trigger conditions are met. Use this after completing a non-trivial task to capture the workflow for reuse.
Inputs: name (required), content (required), steps, task_id, +7 more.
skill_getA
Get a single skill by ID, including its full content and version.
Inputs: skill_id (required).
skill_listA
List skills bound to a team. Optionally filter by agent.
Inputs: team_id (required), agent_id.
skill_searchA
Search skills by keyword. Returns matching skills with descriptions.
Inputs: query (required), team_id (required), agent_id (required), topK.
statsA
Query memory statistics: total captures, breakdown by type, top tags, session count, date range, and database size. Use this to understand memory health and coverage. No arguments needed — returns a summary.
Inputs: session_key.
supersedeA
Mark an old memory as superseded by a newer one. The old memory's superseded_by field is set, and it will be filtered out of search results (unless explicitly requested). Use when a fact has changed (e.g. 'database is MySQL' → 'database is PostgreSQL').
Inputs: new_id (required), old_id (required).
updateA
Update an existing memory entry. Use this when a capture needs corrections (wrong info, missing tags, needs rewording). Preserves the original ID and created_at.
Inputs: id (required), tags, type, content, +1 more.
wiki_getA
Get a wiki page by ID, including its links and backlinks. Use this to read a specific page and see what it links to and what links to it.
Inputs: page_id (required).
wiki_ingestA
Ingest markdown documentation files into the wiki. Parses frontmatter, headings, [[wikilinks]], and text links to build a structured page graph. Supports .md and .markdown files.
Inputs: path (required), team_id, max_files, repo_path.
wiki_outdatedA
Find wiki pages whose source file has changed since the last ingest. Returns pages that need re-ingesting because the source markdown was modified or deleted.
Inputs: repo_path (required), team_id.
wiki_searchA
Search wiki pages by content. Returns matching pages with title, file path, and a snippet. Use this to find documentation relevant to a topic.
Inputs: query (required), limit, team_id.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Most tools target distinct actions and resources, but the large number of memory-management tools (confirm, correct, supersede, resolve, feedback, record_outcome, consolidate) have overlapping conceptual boundaries that could cause an agent to pick the wrong one. The recall/search/related trio is also somewhat redundant, though each has a clear retrieval purpose.
Naming uses a rough prefix-based pattern for knowledge, codegraph, wiki, and skill tools, but mixes bare verbs (capture, recall, forget, resolve) with noun_verb pairs (knowledge_get, skill_list) and stacked prefixes (codegraph_detect_changes). The convention is readable but not consistent across the toolset.
48 tools is a very large surface for a single MCP server. While the breadth covers multiple domains (memory, knowledge, codegraph, wiki, skills, sessions, corrections), the sheer count makes the set unwieldy and likely to overwhelm agents when selecting the right tool.
The tool surface is remarkably comprehensive: full CRUD for memories and knowledge assets, multiple retrieval modes, graph traversal, impact analysis, wiki ingestion, skill lifecycle, session management, correction tracking, and diagnostics. Obvious gaps are minor (e.g., no skill_update, no wiki_delete), but agents can complete virtually any workflow in the stated domain.
Maintenance
Related MCP Connectors
Cloud-hosted MCP server for durable AI memory
An MCP server that gives your AI access to the source code and docs of all public github repos
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Hosted MCP server and Agent Skills for specs, engineering threads, and project memory.
Related MCP Servers
- AlicenseAqualityCmaintenanceLocal-first MCP server that gives any AI coding agent per-project memory, workflow intelligence, and always-on, lossless token & context optimization.3731 npm6MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that gives AI coding agents persistent memory and context across sessions.4 npmMIT
- AlicenseAqualityDmaintenanceA local-first MCP server that gives AI coding assistants persistent, structured, human-readable memory for a software project by storing project knowledge as Markdown files in the project's .dev-context-memory/ folder.71MIT
- AlicenseNot gradedqualityCmaintenancePersistent memory MCP server that remembers decisions and context across coding sessions, automatically logging and surfacing relevant knowledge as you work.12 npmMIT