Mcp Memory Graph

MCP Memory Graph

[npm version] [npm downloads] [License: PolyForm Noncommercial] [Node] [CI] [MCP server] [Built for Claude Code] [Local-first · $0/token]

A memory server for Claude Code and any other MCP client. It gives your AI assistant a permanent, searchable memory that lives in one SQLite file on your machine. Store a decision today, ask about it next month, and the answer comes back. Everything runs locally: the embedding model, the search index, the knowledge graph. No cloud account, no API key, no per-token cost.

License: source-available and free for noncommercial use (PolyForm Noncommercial 1.0.0): personal projects, hobby, study, research, charity, education, and government. Commercial use requires a paid license (COMMERCIAL.md).

Who it's for: developers who want Claude (or Cursor, Codex, any MCP client) to remember decisions across sessions. Solo builders and hobbyists use it free. Teams share a knowledge base over git. And anyone who wants to replace a cloud memory service (mem0, Zep, Letta, Supermemory) with something that runs entirely on their own machine.

What it looks like

Run npx mcp-memory-graph serve and you get a local web dashboard for browsing and searching your memory outside Claude.

[The dashboard: memory counts, breakdowns by scope, department, and type, and the most recent memories]

Search works by meaning, not keywords. The query below ("how do we handle payments") finds the Stripe, GDPR, and Postgres notes even though none of them contains that phrase — each result carries a confidence score and a match-type badge:

[Semantic search results with confidence and match-type badges]

Browse and sort the whole store in one table — scope, type, tags, quality score, and how often each memory has been read:

[Sortable table of all stored memories]

How it compares

mem0, Zep, Letta, and Supermemory are the usual names for AI memory, and several of them have open-source cores. This one is built around a different default: nothing leaves your machine and there's no infrastructure to run.

The trade-off is honest: a single-process SQLite server tops out in the low hundreds of thousands of vectors (see Limitations), and a hosted service will scale past that without you thinking about it. If you're a solo developer or a small team who wants memory that's private, free, and zero-ops, that ceiling is rarely the thing you hit first.

Why this exists

AI assistants forget everything between sessions. Your decisions, your patterns, the bug you fixed last Tuesday: all gone when the conversation ends. This server fixes that.

• Knowledge stored today is searchable tomorrow, next week, next year.
• Search works by meaning, not just keywords. "contract notice period" finds "90-day renewal clause".
• It improves itself. It tracks what gets used, scores quality, extracts learnings from your sessions, and cleans itself up on a schedule.
• It stays private. Local embeddings, no cloud APIs, no telemetry. The one exception is the optional Stop hook, which sends your session transcript to your own locally installed Claude Code (claude -p) for learning extraction. You can turn that off with review_on_stop: false.
• It works for any kind of knowledge. Engineers store architecture decisions, lawyers store contract patterns, accountants store audit procedures.

Quick start (about 5 minutes)

You need Node.js 20 or newer and Claude Code installed.

1. Get the server. From npm (easiest):

npm install -g mcp-memory-graph

Or from source:

git clone https://github.com/YonasValentin/mcp-memory-graph.gitcd mcp-memory-graphnpm installnpm run build

2. Register the server with Claude Code (optional — init in step 3 does this for you at user scope):

# npm install:claude mcp add memory-server -- npx -y mcp-memory-graph
# from source:claude mcp add memory-server node /path/to/mcp-memory-graph/dist/index.js

3. Install the hooks (recommended):

npx mcp-memory-graph init

This is the one command that wires everything up: it registers the MCP server (user scope), installs the auto-capture/recall hooks and the usage skill, writes config, and schedules a nightly cleanup. Answer the prompts, or pass --yes to accept the defaults. (Skip the auto-registration with --no-register if you manage claude mcp yourself.)

4. Try it. Open a Claude Code session and say:

Remember this: we use Postgres for the main app database. Decided 2026-06-01,because we need JSONB and full-text search in one place.

Then, in a later session:

What database did we decide to use, and why?

Claude searches its memory and answers with the stored decision. That's the whole loop.

5. Verify the install. Ask Claude:

What memory tools do you have available?

It should list all 51 tools (45 memory_*, 3 vault_*, 3 core_memory_*).

The first time a memory tool runs, the embedding model (about 30 MB) downloads from HuggingFace and is cached at ~/.cache/huggingface/. Every start after that is instant.

To undo everything: npx mcp-memory-graph uninstall.

Upgrading

npm install -g mcp-memory-graph@latest   # or just let `npx -y mcp-memory-graph` pull itnpx mcp-memory-graph init                # re-run to refresh on-disk hooks + the nightly schedule

Upgrading the package updates the code that runs each session (hooks, tools, the server), so server-side fixes apply the next time a tool runs — nothing else needed for those.

But files that init wrote earlier are not rewritten by a package upgrade: the Claude Code hook registrations in settings.json and the macOS launchd plist at ~/Library/LaunchAgents/com.mcp-memory.consolidate.plist. If you installed before 2.6.3, that plist used a bare node that launchd (whose minimal PATH excludes nvm) could not run — so the nightly consolidation silently never fired. Re-run npx mcp-memory-graph init once after upgrading to regenerate it with an absolute node path and an output log. Verify it then runs:

launchctl start com.mcp-memory.consolidatecat ~/.mcp-memory/consolidation.log      # should show a "Consolidation complete" report

To clear conflict noise that accumulated while the job wasn't running: npx mcp-memory-graph consolidate.

How it works, in plain terms

When you store a memory, the server turns the text into a vector (a list of 384 numbers that captures its meaning) using a small model that runs inside Node.js. It also indexes the text for keyword search. Both live in one SQLite file, by default at ~/.mcp-memory/memory.db.

When you search, the server runs both kinds of search at once, merges the rankings, and returns the best matches with a confidence label. A second model can then re-sort the top results for better precision (this is the reranker, on by default for MCP clients, and it costs about 200 ms).

On top of that sits a knowledge graph: memories link to entities and to each other, so the server can answer questions that need more than one hop, like "what does the payment service depend on?". A nightly "dream cycle" deduplicates, re-scores, prunes, and reports gaps.

The benchmarks, and how to read them

Every number below was produced locally: real embedding model, real production handlers, no network. You can rerun all of them on your own machine.

A quick primer if benchmarks are new to you. A gold set is a list of questions where the right answer is known in advance. Precision@1 asks: was the top result the right one? Recall@5 asks: was the right answer anywhere in the top 5? MRR (mean reciprocal rank) rewards putting the right answer near the top. The reranker is a second model that re-sorts the top 50 results; it is slower but noticeably more accurate.

Local gold set

Reproduce with npm run bench. Full methodology, the gold set itself, and every miss are printed and documented in docs/BENCHMARKS.md.

Scale

With the real embedder and a file-backed SQLite database, retrieval p95 is 9.1 ms at 10,000 vectors and 30 ms at 50,000. The rerank pass adds a roughly constant 200 ms on top. Most memory products publish self-reported, cloud-hosted numbers; these are measured locally and reproducible from a committed corpus and runner.

Public benchmarks

Four public memory benchmarks, run untuned (stock MiniLM embedder, production handlers, zero benchmark-specific tweaks), matching or beating MemPalace on all four:

Run them yourself: npm run bench:longmemeval, bench:locomo, bench:convomem, bench:membench. The honest notes (where the reranker helps and where it hurts, the dedup floor on MemBench, gold-set size caveats) are in docs/BENCHMARKS.md.

Features

Core

• 51 MCP tools: CRUD and retrieval, a confidence-tagged knowledge graph, a self-correcting write gate, signed provenance and verification, an event bus with SSRF-guarded webhooks, change propagation and advisor surfaces, resumable session state, expertise profiles, memory tiers, Obsidian vault round-tripping, and GDPR-grade forget and history. Full list below.
• Hybrid search: vector similarity (meaning) plus keyword matching (exact terms), merged with Reciprocal Rank Fusion. rerank: true adds the cross-encoder pass. use_graph: true blends in HippoRAG Personalized PageRank multi-hop scores. as_of: <timestamp> searches the graph as it stood at a past moment.
• Local embeddings: Transformers.js running all-MiniLM-L6-v2 (384 dimensions) inside Node.js. No Python, no cloud API, no GPU.
• SQLite storage: one file, using better-sqlite3 with two extensions: sqlite-vec for vector nearest-neighbor search, FTS5 for keyword search with BM25 ranking.
• Structure-aware chunking: text splits on paragraphs, markdown on headings (heading context preserved in each chunk), code on function and class boundaries, legal on sentences.
• Scopes: organize memories into global, project, user, team, department.
• Version history: every update saves the previous version. Full audit trail of who changed what, when.
• Temporal decay: optional time-based scoring that favors recent memories (exponential or linear).
• Confidence scoring: every result carries a 0 to 1 confidence and a plain label (high, medium, low).
• Expiration: time-sensitive memories can carry an expiry date and drop out of search automatically.

Self-improvement

• Access tracking: every search, get, and related-memory call records which memories were touched.
• Quality scoring: automatic importance_score and confidence_score on every memory, from access frequency, recency, and content signals.
• Learning extraction: at session end, a headless claude -p reviews the transcript and stores zero to five curated learnings. (This replaces the older type: "agent" Stop hook, which is silently broken on macOS; see anthropics/claude-code#39184.)
• Dream cycle: scheduled or on-demand deduplication, re-scoring, pruning, expiry enforcement, and knowledge-gap detection.
• Gap detection: searches that return nothing are logged, so you can see what knowledge is missing.

Claude Code hooks

Five opt-in hooks, installed by init:

The Stop hook detaches in about 30 ms and reviews in the background for 10 to 60 seconds. It needs the claude CLI on $PATH (or $CLAUDE_BIN), authenticated. Turn it off with review_on_stop: false in ~/.mcp-memory/config.json.

Metadata on every memory

scope and namespace group content within one database. A shared-database MCP_API_NAMESPACE pin gives supported per-namespace multi-tenant isolation (schema v14); a separate database file per tenant is the strongest boundary. See docs/MULTI-TENANCY.md.

Knowledge graph and bi-temporal model

• Bi-temporal validity: every memory carries valid-time (valid_from, valid_to) alongside transaction-time. Updates invalidate rather than delete: the prior fact gets a valid_to stamp instead of being overwritten, so history is never lost. Reads default to currently valid rows but accept as_of: <timestamp> for point-in-time recall. memory_history returns one memory's full timeline.
• Confidence-tagged links: memories connect via wikilink, co-occurrence, and similarity edges, each with a confidence weight. memory_graph traverses entities and relationships up to 3 hops. memory_extract_entities stores LLM-extracted entities and relationships.
• HippoRAG multi-hop: use_graph: true on search runs Personalized PageRank over the entity and link graph for associative retrieval.
• Token-budgeted answers: memory_query answers a question with a tight subgraph. It seeds from hybrid search, walks the graph up to max_hops while avoiding hubs, and returns a token-budgeted context string instead of flooding the window.
• Communities: memory_communities finds densely connected entity clusters, for "what are the main themes in here?" questions.

Self-correcting writes

• Write gate: stores route through an ADD, UPDATE, DELETE, or NOOP decision (on_conflict), so new facts reconcile with existing ones instead of piling up duplicates.
• Contradiction detection: a cross-encoder NLI model flags when an incoming memory contradicts something already stored.
• Forgetting curve: memories carry a stability signal, so rarely reinforced knowledge slowly sinks in ranking, the way human memory fades.

Agent-OS memory

• Core memory block: a small, bounded, always-in-context note per (scope, namespace) that the agent maintains itself (core_memory_get, core_memory_append, core_memory_replace). Appends that would overflow are refused, which forces deliberate compaction.
• Tiers: memory_tiers reports a MemGPT-style hot / recall / archival distribution and lists the hot working set.
• Reflection: memory_reflect gathers the most reflection-worthy memories and, in store mode, persists synthesized insights linked back to their sources.

Obsidian vault

• Bidirectional sync: vault_sync reads a vault in. memory_export_vault writes memories out as .md files with YAML frontmatter that round-trips losslessly for every authored field (id, scope, namespace, tags, access_level, importance, timestamps). Two derived scores are not in the frontmatter and reset on re-import: confidence_score (to 0.6) and stability (to 1.0). Use memory_export (JSON) for a byte-perfect backup. One metadata key is reserved: metadata._vault holds internal sync bookkeeping and never appears in tool output or exported files.
• JSON Canvas: memory_canvas exports the graph as a JSON Canvas 1.0 .canvas file that opens as a spatial board in Obsidian.
• Read-only wiki: serve exposes /publish/:namespace (index, page, search, graph) as a read-only wiki. It is deliberately not behind bearer auth, but is hard-scoped to published access levels (MCP_PUBLISH_ACCESS_LEVELS, default public).
• Session notes and templates: memory_session_note appends to one "daily note" per session. memory_template returns structured note scaffolds per document type.

Team and solo sharing (git)

• memory init wizard: interactive setup (or --yes for defaults) that writes ~/.mcp-memory/config.json (or project-scoped config) plus the Claude Code wiring.
• Committable graph artifact: memory export-graph writes a deterministic memory-graph.json you can commit and share. memory git-setup installs a .gitattributes entry and the memory-union merge driver so parallel commits merge instead of conflict.
• Attribution: set MCP_AGENT_ID (or pass agent_id per store) and memory_attribution reports how many valid memories each agent wrote.

Trust and governance

• Questions to ask: memory_questions surfaces what the graph is well placed to find: ambiguous links to confirm, frequently mentioned but under-documented entities, orphaned and stale memories.
• GDPR-grade forget: memory_forget soft-deletes by default (a tombstone via valid_to, recoverable, still visible via as_of). With hard: true it returns a portability export first, then permanently erases. memory_delete is unchanged.
• Output sanitization: every tool result passes through one chokepoint that strips ANSI and VT escapes, control characters, and zero-width or BiDi Trojan-Source spoofing before it leaves the server. Stored content stays raw at rest.
• Hot reload: config changes apply without a restart.

Web dashboard

The server ships a browser dashboard for viewing and managing memories outside Claude. It runs on the same Express server as the MCP HTTP transport, so there is no separate process.

Six pages:

• Dashboard: memory counts, content size, breakdowns by scope, department, and type, plus the 10 most recently updated memories.
• Search: hybrid search with confidence and match-type badges, and instant fuzzy suggestions as you type.
• Browse: sortable, paginated table of all memories with scope filtering and quality indicators.
• Memory detail: full content, metadata, version history, related memories, inline edit and delete.
• Knowledge graph: D3 force-directed view. Nodes sized by importance, colored by scope. Zoom, pan, drag, double-click to navigate.
• Tools: a console for the full tool surface. It lists every tool the server advertises, renders a form from each schema, and runs it over the authenticated MCP endpoint. Destructive tools ask for confirmation first.

Tech: React 19, Vite, Tailwind CSS v4, shadcn/ui, Fuse.js, D3, Recharts.

Run it:

# Development (hot reload)npm run build && npm run serve   # Terminal 1: server on :3100npm run dev:web                   # Terminal 2: Vite on :5173 (proxies /api to :3100)
# Production (single process)npm run build:all                 # Builds server + frontendnpm run serve                     # http://localhost:3100 serves both API and UI

Docker: the image includes the built frontend. After docker compose up, the dashboard is at http://<host>:3200 alongside the MCP endpoint. Team members can browse the shared store from any browser, no Claude Code required.

REST API (16 endpoints)

The REST surface is for reading and managing. Creating memories goes through MCP (memory_store over POST /mcp); there is deliberately no POST /api/memories.

The first nine are what the dashboard uses. All REST endpoints call the same handlers as the MCP tools; no business logic is duplicated.

Self-improvement in detail

The server tracks how knowledge is used, scores quality, learns from sessions, and consolidates itself over time.

The learning loop

 ┌──────────────────────────────────────────────────────────┐ │                    SESSION                                │ │  Claude searches → access_count++ on matched memories     │ │  Claude stores   → new memory with initial scores         │ │  Zero results    → knowledge gap recorded                 │ └─────────────┬────────────────────────────────────────────┘               │               ▼ ┌──────────────────────────────────────────────────────────┐ │            SESSION END (Stop command hook)                │ │  Hook spawns detached `claude -p` headless review         │ │  --allowedTools restricts to memory_store only            │ │  Claude judges → 0-5 curated entries via memory_store     │ │  Deduplicates against existing memories                   │ └─────────────┬────────────────────────────────────────────┘               │               ▼ ┌──────────────────────────────────────────────────────────┐ │              DREAM CYCLE (nightly or manual)              │ │  1. Score    : Recalculate importance from access data    │ │  2. Expire   : Enforce expiration dates                   │ │  3. Prune    : Remove low-quality, never-accessed items   │ │  4. Dedup    : Merge near-duplicate memories              │ │  5. Gaps     : Surface zero-result search patterns        │ └──────────────────────────────────────────────────────────┘

Quality scoring

Every memory gets an importance_score between 0 and 1:

importance = 0.3 * current_score + 0.4 * normalized_access_frequency + 0.3 * recency_factor

Recency factor:

Memories that are never accessed gradually lose importance. Auto-extracted memories start lower and get pruned if they never prove useful.

Note on access reinforcement. The formula above is the periodic recompute run by the consolidate Score stage. Each read (memory_get, memory_search, memory_related) also applies a small immediate boost (importance_score += 0.03, capped at 1.0), and search uses importance as a mild rank multiplier (1 + importance * 0.5). A memory read 20 or more times approaches the ceiling from reads alone, and consolidate re-baselines it on the next run. This popularity weighting is intentional. If you want a fixed value that reads don't drift, set an explicit importance_score on memory_store or memory_update.

Knowledge gap detection

When a search returns nothing, the query is logged. The dream cycle's gap stage surfaces these, so you can see what's missing from the store.

Installation reference

Prerequisites

• Node.js 20+, for any client.
• An MCP client. Claude Code is the first-class experience; the automatic capture and recall hooks are Claude-Code-only. Other MCP clients (Codex, Cursor, and the rest) get all 51 tools but drive them manually. See "Other MCP clients" below.
• For the Stop hook only: the claude binary on $PATH (or $CLAUDE_BIN), authenticated without prompting. Optional; disable with review_on_stop: false.

What init does

npx mcp-memory-graph init                  # user scope: hooks apply to all projectsnpx mcp-memory-graph init --scope project  # this project only

User scope writes hooks to ~/.claude/settings.json, so they fire in every Claude Code session. Project scope writes hooks to .claude/settings.json in the current directory and creates .mcp.json for automatic server discovery; collaborators who clone the project get the memory server registered automatically.

Init does seven things:

1. Verifies the hook scripts exist in dist/hooks/.
2. Registers the five hooks in settings.json.
3. Creates the config file with sensible defaults: ~/.mcp-memory/config.json (user scope) or <project>/.mcp-memory/config.json (project scope; the generated .mcp.json pins it via MCP_MEMORY_CONFIG_PATH).
4. Writes memory usage instructions to .claude/CLAUDE.md (project scope) or prints a snippet (user scope).
5. Registers the MCP server with Claude Code — user scope runs claude mcp add -s user memory-server -- npx -y mcp-memory-graph for you (idempotent; best-effort — warns with the manual command if the claude CLI isn't on PATH; skip with --no-register). Project scope is registered via the committable .mcp.json instead. This makes step 2 of the Quick Start optional.
6. Installs the mcp-memory-graph usage skill into ~/.claude/skills/ so Claude Code has inline guidance for all 51 tools, gotchas, and workflows. Skip with --no-skill.
7. Sets up the nightly consolidation schedule (macOS: launchd, loaded immediately so it runs without a relogin; Linux: prints a cron suggestion; skipped for project scope).

Under a non-interactive shell (agent/CI) the wizard is bypassed: defaults are applied and a report is printed showing what was set and how to change each value. Passing --yes applies the defaults silently (no report).

Key flags: --scope user|project, --schedule HH:MM[,HH:MM] (nightly consolidation time, default 03:00), --vault <path> (enable Obsidian vault round-trip), --no-review-on-stop (disable the end-of-session learning review), --no-skill (skip skill install), --no-register (skip the user-scope claude mcp add), --remote <url> (team server mode).

npx mcp-memory-graph uninstall reverses everything init did: removes hooks, the nightly schedule, the CLAUDE.md block, and the installed skill.

Unattended setup (CI, provisioning, agents)

Every step is scriptable. There is no interactive-only path:

git clone https://github.com/YonasValentin/mcp-memory-graph.gitcd mcp-memory-graphnpm install && npm run buildnpx mcp-memory-graph init --scope project --yes   # local: hooks + .mcp.json, no prompts# or point at a shared self-hosted server instead:# npx mcp-memory-graph init --remote https://memory.example.com --token-env MEMORY_MCP_TOKEN

Other MCP clients (Codex, Cursor, and more)

Claude Code gets the hooks; everyone else gets the same 51 tools, driven manually. The server is a standard MCP server, so any client works. A line in the client's rules file makes usage near-automatic.

Register the server. Example for Codex, in ~/.codex/config.toml (global) or .codex/config.toml (project, trusted only):

[mcp_servers.memory-graph]command = "node"args = ["/abs/path/to/mcp-memory-graph/dist/index.js"]tool_timeout_sec = 180   # the first call downloads the ~30 MB model once; the 60s default can be tight
[mcp_servers.memory-graph.env]MCP_MEMORY_DB_PATH = "/abs/path/to/.mcp-memory/memory.db"
# or a shared self-hosted server over HTTP (see Self-hosting below):# url = "https://memory.example.com/mcp"# bearer_token_env_var = "MEMORY_MCP_TOKEN"

Or codex mcp add memory-graph -- node /abs/path/to/mcp-memory-graph/dist/index.js. Cursor, Windsurf, and other clients use their own MCP config format, but the server command (node .../dist/index.js) and the HTTP option are the same.

Then nudge the agent in its instructions file (Codex: AGENTS.md; Cursor: project rules):

Before answering questions about architecture, decisions, patterns, or past fixes, call memory_search on the memory-graph server first; store new decisions, patterns, and fixes with memory_store.

Self-hosting and sharing a memory base

The server runs three ways, from a single-user cache to a knowledge base shared across many machines. All three are local-first: nothing leaves the machines you choose to run it on.

1. Local (single user), the default

npx mcp-memory-graph init registers a local stdio server plus the hooks. Memory lives in one SQLite file on your machine. Nothing else to run. Right choice for solo use.

2. Shared server (multiple machines or a group)

Run one server that many clients connect to over HTTP. Everyone shares the same memory base, live.

Start the server (pick one):

# From source: build the server (and the dashboard, if you want it) firstnpm run build:allMCP_AUTH_TOKEN=$(openssl rand -hex 32) MCP_BIND=0.0.0.0 npm run serve# MCP at /mcp, REST at /api, dashboard at /, all on :3100
# Or with Docker (frontend included; publishes host port 3200 by default)MCP_AUTH_TOKEN=$(openssl rand -hex 32) docker compose up -d

Set MCP_AUTH_TOKEN whenever the server is reachable beyond loopback. It is a shared bearer token, one secret for all clients. The server refuses to start unauthenticated on a non-loopback bind unless you set MCP_AUTH_OPTIONAL=1. Terminate TLS at a reverse proxy or tunnel for anything off-host.

Connect a client, one command per machine:

npx mcp-memory-graph init --remote https://memory.example.com --token-env MEMORY_MCP_TOKENexport MEMORY_MCP_TOKEN=<the server token>     # in your shell or .env

For Claude Code this writes a project .mcp.json pointing at the shared server. The token is stored as an env-var reference ("Authorization": "Bearer ${MEMORY_MCP_TOKEN}"), so the committed .mcp.json never contains the secret. Non-Claude clients point at the same server through their own MCP config.

In remote mode the local capture and recall hooks are not installed. The memory lives on the server, not in a local file the hooks could read. The agent uses memory_search and memory_store directly (the CLAUDE.md guidance is still written).

3. Git vault (async, version-controlled sharing)

Prefer your knowledge base in git, reviewed through pull requests, with no server to run? Export memories to plain Markdown and share the folder as a git repo:

npx mcp-memory-graph vault-init                    # make the vault a git repo (union merge driver + rebuild hook)git add -A && git commit -m "memory snapshot" && git push# collaborators, once after cloning:#   npx mcp-memory-graph vault-init                # registers the union merge driver + post-merge hook in THEIR clone# collaborators, thereafter: git pull && npx mcp-memory-graph rebuild

Each collaborator must run vault-init once in their own clone. The merge driver and post-merge rebuild hook live in local git config (.git/), not in the repo. A fresh clone without vault-init will hit raw conflict markers in .memory/graph.json on its first concurrent pull. Re-running vault-init is idempotent and does not clobber the committed sidecar.

Two recovery notes for team vaults:

• After a merge you resolved by hand (the post-merge hook only fires on clean merges), memory rebuild can refuse with VaultIntegrityError because .memory/manifest.json is stale. Delete that file and re-run rebuild; it is derived state and regenerates.
• Hand-edited a .md while your database has newer state? Import first (vault_sync or rebuild), then export (memory sync). A full export from a stale database overwrites vault files, including your hand edit.

Security notes

• MCP_AUTH_TOKEN is a single shared secret, fine for a trusted group; rotate it by restarting the server with a new value. For per-key RBAC (one server, N keys, each pinned to a namespace set and an access-level ceiling) use memory keys create|list|revoke (schema v16). The legacy shared token still works and is checked first. See docs/MULTI-TENANCY.md.
• Never commit a token. The --remote default keeps it in an env var by design.
• Bind to 127.0.0.1 (the default) unless you front the server with a proxy that terminates TLS; then set MCP_BIND=0.0.0.0.

Building an org-wide AI brain? One server, a key per employee, an org chart the AI can traverse (people, teams, SOPs, and tools as typed graph nodes), with enforced who-sees-what. The recipe, built on existing primitives, is in docs/ENTERPRISE-BRAIN.md.

Configuration

Environment variables

The full env reference (auth, rate limits, webhooks, vault, publish) is in docs/ENV.md.

Custom database location

claude mcp add memory-server --env MCP_MEMORY_DB_PATH=/path/to/project/.memory.db node /path/to/dist/index.js

Alternative embedding models

# Swap the embedding model (same 384 dimensions; drop-in for the existing index# AFTER a re-embed; see the warning below)claude mcp add memory-server \  --env MCP_MEMORY_MODEL=Xenova/bge-small-en-v1.5 \  --env MCP_MEMORY_DIMENSIONS=384 \  node /path/to/dist/index.js

Model identity is recorded and enforced. The database remembers which embedding model built it (schema_meta.embedding_model). Starting the server with a different MCP_MEMORY_MODEL fails loudly instead of silently degrading every search (same dimension does not mean same vector space). To switch models: set the new model and run memory rebuild (re-embeds from the vault), or export and re-import.

Configuration file

The config file controls self-improvement behavior, hook settings, and per-project overrides. Resolution order: MCP_MEMORY_CONFIG_PATH env, then <cwd>/.mcp-memory/config.json (project-scope init writes this), then ~/.mcp-memory/config.json. Created by npx mcp-memory-graph init, or write it by hand:

{  "defaults": {    "scope": "project",    "namespace": "auto"  },  "projects": [    {      "path": "~/Documents/MyApp",      "namespace": "my-app",      "watch": ["README.md", "docs/**/*.md"]    }  ],  "consolidation": {    "similarity_threshold": 0.85,    "prune_after_days": 30,    "min_importance_to_keep": 0.1,    "max_operations": 100,    "schedule": [      { "hour": 11, "minute": 30 },      { "hour": 16, "minute": 0 }    ]  },  "hooks": {    "extract_on_compact": false,    "extract_on_session_end": false,    "track_searches": true,    "review_on_stop": true  },  "extraction": {    "categories": ["decision", "pattern", "error_fix", "convention"],    "min_confidence": 0.4  }}

CLI commands

Tools reference

1. memory_store

Store a new memory. The vector embedding is generated automatically.

¹ When omitted, a loaded config file's defaults.scope and defaults.namespace ("auto" = project directory name) apply first; the hardcoded fallback is global with no namespace.

Example prompt:

Store this memory with department=legal and tags=["compliance","gdpr"]:"All customer data processing agreements must include a GDPR Article 28 addendum effective January 2025."

2. memory_search

Hybrid vector plus keyword search across stored memories.

How it works:

1. Your query is embedded and compared against all stored vectors (semantic similarity).
2. Your keywords are matched against memory text via FTS5 (exact matching).
3. Both result lists merge using Reciprocal Rank Fusion.
4. Optional temporal decay favors recent memories.
5. Results get a confidence score and label.
6. The access is recorded for quality scoring.

Example prompts:

Search memories for "contract renewal notice requirements" in the legal department
Search memories for "authentication" with search_mode=keyword
Search memories for "deployment patterns" with temporal_decay={type:"exponential", half_life_days:60}

Each result includes the memory content and metadata, the combined RRF score, a normalized confidence (0-1), a confidence_level label (high at 0.7 and above, medium at 0.4 and above, low below that), and a match_type (hybrid, vector, or keyword).

The default detail_level: "summary" projection returns confidence_level but omits the numeric confidence and the full content, to save tokens. Pass detail_level: "full" when you need them.

3. memory_get

Retrieve a specific memory by ID. For ingested documents, optionally include all child chunks.

4. memory_update

Update an existing memory. If content changes, the embedding regenerates automatically. The previous version is saved to history.

5. memory_delete

Delete memories by ID or by filter. At least one of id or filter is required.

6. memory_list

Browse memories with filtering, pagination, and sorting.

7. memory_ingest

Ingest a full document: it is chunked by content type, each chunk is embedded, and everything is stored with parent-child relationships. Use this for large documents.

Chunking by content type:

8. memory_related

Find memories semantically related to a given one. Uses vector similarity, so it finds connections keyword search misses.

9. memory_versions

View a memory's version history. Every update creates a version record.

10. memory_stats

Usage statistics about stored memories.

Returns totals for memories, documents, and chunks, breakdowns by scope, department, and type, storage size, and the expired count.

11. memory_export

Export current memory content as JSON for portability or migration. This is not a full backup: it serializes only currently live, top-level memories. It omits edit history, the knowledge graph, condense-undo originals, ingested child chunks, and soft-forgotten rows. For disaster recovery, copy the SQLite file (cp ~/.mcp-memory/memory.db ..., see the RUNBOOK); embeddings recompute deterministically on import.

Max 1000 records per export.

12. memory_import

Import memories from JSON. Each item is embedded and stored.

13. vault_sync

Scan an Obsidian vault, parse the markdown, embed and store. See Obsidian Vault Integration below.

14. vault_status

Sync status for a vault: files synced, pending, changed, and the last sync time.

15. vault_search

Hybrid search scoped to one vault's memories.

By default this searches the namespace named after the vault's folder name. Memories exported from another namespace keep their original namespace in frontmatter. If a search over a freshly synced vault returns nothing, pass an explicit namespace (and/or scope) override.

16. memory_consolidate

The dream cycle: deduplicate, score, prune, expire, and detect knowledge gaps.

Five stages run in order: Score (recalculate importance), Expire (enforce expires_at), Prune (drop low-quality when enabled), Dedup (merge near-duplicates), Gaps (surface zero-result searches). Returns a report with counts per stage.

Example prompts:

Run a dream cycle consolidation with dry_run=true to preview what would change
Consolidate memories in namespace=my-project with similarity_threshold=0.9
Run consolidation with prune_low_quality=true to clean up unused memories

17. memory_extract_learnings

Mine a session transcript for decisions, patterns, error fixes, and conventions using heuristic pattern matching. No external LLM needed.

Extraction looks for decision language ("we decided", "the fix was"), pattern language ("always use", "never do"), error fixes ("the problem was", "solved by"), and conventions ("our convention is", "standard practice"). Each hit is deduplicated against existing memories and stored with a lower initial confidence.

18-42. Graph, Agent-OS, vault round-trip, and governance tools

Parameters for the remaining tools are validated by Zod schemas in src/schemas/; each registration's full description lives in src/server.ts.

43-50. Active infrastructure and typed shapes

Architecture

System overview

Claude Code ──stdio──> MCP Memory Graph                            │                    ┌───────┴───────┐                    │               │              Transformers.js   SQLite DB              (embeddings)    (~/.mcp-memory/memory.db)                                    │                       ┌────────────┼────────────┐                       │            │            │                   memories    memories_fts  memories_vec                   (data +     (FTS5 index)  (vec0 index)                    scores)                       │              ┌────────┼────────┐              │        │        │        memory_    memory_    ingest_        versions   access_    source_                   log        tracking

Claude Code Hooks (opt-in)    │    ├── SessionStart ──> memory_stats (status check)    ├── PostToolUse ───> search-log.jsonl (hit/miss tracking)    ├── PreCompact ────> learning extraction (disabled by default)    └── Stop ──────────> spawn detached `claude -p` headless review                              │                              └─> --allowedTools mcp__memory-server__memory_store                                  Claude reviews transcript → memory_store calls
Nightly Schedule (opt-in)    └── 3:00 AM ───────> memory_consolidate (dream cycle)

How hybrid search works

Query: "contract renewal notice"         │    ┌────┴────┐    │         │ Embed     Tokenize    │         │    ▼         ▼ sqlite-vec  FTS5 (semantic)  (keyword)    │         │    │  rank   │  rank    │  1: A   │  1: A    │  2: C   │  2: B    │  3: B   │  3: D    │         │    └────┬────┘         │   Reciprocal Rank Fusion   RRF(d) = Σ 1/(60 + rank)         │         ▼   [A: 0.033, B: 0.026, C: 0.016, D: 0.016]         │   Temporal Decay (optional)         │   Confidence Scoring         │   Access Tracking (record hit)         │         ▼   Final ranked results

Database schema

The SQLite database is at schema version 18, with automatic forward migration from any earlier version. The core tables:

• memories: all memory data, TEXT primary key (UUIDs), parent-child support for document chunks, plus access_count, last_accessed_at, importance_score, and confidence_score.
• memories_fts: FTS5 virtual table for keyword search with BM25 ranking, synced with the memories table.
• memories_vec: vec0 virtual table for vector search. 384-dimension float32 embeddings with scope and namespace metadata for pre-filtering.
• memory_versions: version history for every change.
• memory_access_log: every search, get, and related-memory access, with timestamps and query context.
• ingest_source_tracking: ingested files, for change detection on re-ingestion.

Later schema versions add the knowledge-graph tables (entities, links, conflicts, communities), webhooks, session state, and the RBAC api_keys table. Every mutation keeps the three core tables in sync atomically inside a SQLite transaction; the repository.ts layer enforces this, and nothing else touches the tables directly.

Project layout

src/├── index.ts        # Entry point (stdio transport)├── server.ts       # All 51 tool registrations├── config/         # Config file loading + validation├── db/             # Connection, schema, migrations, repository (three-table sync)├── embeddings/     # Embedding providers (Transformers.js, registry, Ollama)├── search/         # Hybrid search, reranker, temporal decay, scoring├── chunking/       # Per-content-type chunking strategies├── graph/          # Entities, links, PageRank, communities├── vault/          # Obsidian round-trip, write-through, bookkeeping├── tools/          # One handler per MCP tool├── api/            # REST routes + security middleware├── events/         # Webhook bus (SSRF guard, HMAC, retry)├── cli/            # init, serve, vault, backup, keys, migrate, ...├── hooks/          # Claude Code lifecycle hooks└── schemas/        # Zod schemas for every tool input

Use cases by department

Engineering:

Store memory: "We chose event sourcing over CRUD for the order service becausewe need full audit trail and the ability to replay events for debugging.ADR-042, decided 2026-03-15."department=engineering, document_type=decision, tags=["architecture","event-sourcing"]

Legal:

Ingest this contract template with content_type=legal, department=legal,document_type=contract, tags=["template","nda","standard"]

Finance:

Store memory: "Q4 2025 revenue recognition policy change: SaaS contractsover 12 months now recognized ratably per ASC 606 guidance."department=finance, document_type=policy, tags=["revenue-recognition","asc-606"]

HR:

Ingest the employee handbook with department=hr, content_type=text,document_type=policy, tags=["handbook","onboarding"]

Sales:

Store memory: "When prospect objects on price vs CompetitorX, lead withour 99.9% uptime SLA and dedicated support. This converted 3 deals in Q1."department=sales, document_type=pattern, tags=["objection-handling","pricing","competitorx"]

Obsidian Vault Integration

Point the server at a vault folder and every markdown file becomes a searchable memory, with frontmatter, tags, and wiki-links extracted. No Obsidian app needed; it reads the files straight from disk.

What gets extracted:

Usage examples:

Sync my Obsidian vault at ~/Documents/my-vault
Check vault sync status for ~/Documents/my-vault
Search my vault for "meeting action items about hiring"
Sync vault but only the notes/ and projects/ folders:  vault_sync with include_patterns=["notes/**", "projects/**"]
Force re-sync everything (ignore modification times):  vault_sync with force=true

vault_sync parameters:

How sync works: it scans the vault recursively for .md files (skipping .obsidian/, .trash/, .git/), compares modification times against the last sync, extracts frontmatter, wiki-links, and tags from new or changed files, embeds, and stores. Deleted files have their memories removed. Files larger than the chunk size are split with markdown-aware chunking. A second sync of an unchanged vault takes under a millisecond.

Security and privacy

• No network calls after the one-time model download (cached locally).
• No telemetry, no analytics, no tracking.
• Hooks are opt-in. They are only installed when you run npx mcp-memory-graph init.
• The nightly schedule is opt-in too, and removed by npx mcp-memory-graph uninstall.
• Everything is one SQLite file: easy to back up, move, or delete.
• access_level metadata (public, internal, confidential, restricted) for organizational awareness.
• Data never leaves your machine.

Backup:

# WAL-safe online snapshot with retentionnpx mcp-memory-graph backup
# Or a simple file copycp ~/.mcp-memory/memory.db ~/.mcp-memory/memory.db.backup

Reset:

# Delete the database to start freshrm ~/.mcp-memory/memory.db

Nightly consolidation

When installed via npx mcp-memory-graph init, a nightly job runs all five dream-cycle stages plus access-log rotation (entries older than 90 days are dropped).

On macOS, a launchd plist is created at ~/Library/LaunchAgents/com.mcp-memory.consolidate.plist, scheduled for 3:00 AM. On Linux, init prints a cron suggestion:

# Add to crontab -e0 3 * * * /usr/local/bin/npx mcp-memory-graph consolidate

Run it manually any time:

npx mcp-memory-graph consolidate

Limitations

• Scale ceiling. Vector search is an exact scan: 9.1 ms p95 at 10K vectors, about 30 ms at 50K, and it degrades linearly from there. Comfortable into the low hundreds of thousands; past that you want a dedicated ANN index, which this server does not have yet.
• English-optimized. The default MiniLM model is English-only in practice; cross-language matching is weak. A multilingual model can be configured via MCP_MEMORY_MODEL (with a rebuild), but the shipped benchmarks only validate the default.
• First-call cold start. Three to five seconds on first use while the embedding model loads. Cached after that.
• Heuristic extraction. memory_extract_learnings uses pattern matching, not an LLM. It catches common phrasings and misses subtle ones. (The Stop hook's claude -p review is the LLM-quality path.)
• One process. RBAC keys and revocation live in the server process. For horizontal scale you shard tenants across processes or give each tenant their own database file.

Roadmap

What's actually next, in rough order:

• Multilingual embeddings, opt-in. Ship a multilingual ONNX model option (the embedder registry and the model-identity guard already exist, so a swap is safe and loud).
• Office document ingestion. PDF, DOCX, XLSX, and friends as an ingest mode, with local extraction only.
• Vault file watcher. Auto-rebuild on .md changes instead of manual rebuild.
• as_of content reconstruction. Point-in-time queries currently reconstruct validity (which facts were live); reconstructing the content of edited memories at that instant is the remaining half.
• ANN index for corpora past a few hundred thousand vectors.
• Windows test suite port. The server runs on Windows, but the test suite carries POSIX path assumptions; the Windows CI leg is non-blocking until that's done.

Tech stack

License

Source-available, not open source. Licensed under the PolyForm Noncommercial License 1.0.0: free for any noncommercial purpose (personal projects, hobby, study, research, charitable, educational, public-research, and government use). Commercial use requires a paid license; see COMMERCIAL.md.

If you're unsure whether your use counts as commercial, check the safe harbors in the license or just ask: [email protected].

Keywords

MCP memory server · Model Context Protocol · Claude Code memory · persistent AI memory · LLM long-term memory · AI agent memory · local-first memory · $0/token memory · hybrid vector + keyword search · semantic search · knowledge graph · bi-temporal memory · HippoRAG / Personalized PageRank · cross-encoder reranking · RAG memory · SQLite vector database · sqlite-vec · FTS5 / BM25 · local embeddings (all-MiniLM-L6-v2, Transformers.js) · Obsidian vault sync · JSON Canvas · GDPR forget · signed provenance · self-hosted memory.

Also searched as: a self-hosted, privacy-first alternative to mem0, Zep, Letta, Cognee, and Supermemory · long-term memory for Claude / Cursor / Codex · an Obsidian-backed knowledge base for AI agents · a local knowledge-graph memory that never leaves your machine.