Skip to main content
Glama

remem-mcp

npm version GitHub stars License: MIT Benchmark

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.


Related MCP server: local-agent-context

Quick start

  1. Restart your agent (quit and reopen)

  2. Ask: "what do you remember?"

  3. 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.

Available Tools

48 tools
adrA

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_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.

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.

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 48 tools

    Disambiguation4/5

    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 Consistency3/5

    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.

    Tool Count2/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers