mcp-memory-graph

# MCP Memory Graph

[![npm version](https://img.shields.io/npm/v/mcp-memory-graph?logo=npm&color=cb3837)](https://www.npmjs.com/package/mcp-memory-graph)
[![npm downloads](https://img.shields.io/npm/dm/mcp-memory-graph?color=cb3837)](https://www.npmjs.com/package/mcp-memory-graph)
[![License: PolyForm Noncommercial](https://img.shields.io/badge/license-PolyForm%20Noncommercial-1f6feb.svg)](./LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)](./package.json)
[![CI](https://github.com/YonasValentin/mcp-memory-graph/actions/workflows/ci.yml/badge.svg)](https://github.com/YonasValentin/mcp-memory-graph/actions/workflows/ci.yml)
[![MCP server](https://img.shields.io/badge/MCP-server-111111)](https://modelcontextprotocol.io/)
[![Built for Claude Code](https://img.shields.io/badge/built%20for-Claude%20Code-d97757)](https://docs.anthropic.com/en/docs/claude-code)
[![Local-first · $0/token](https://img.shields.io/badge/local--first-%240%2Ftoken-2ea043)](#why-this-exists)

A memory server for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and any other [MCP](https://modelcontextprotocol.io/) 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](./LICENSE)): personal projects, hobby, study, research, charity, education, and government. Commercial use requires a paid license ([COMMERCIAL.md](./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](docs/assets/dashboard.png)

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](docs/assets/search.png)

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](docs/assets/browse.png)

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

| | MCP Memory Graph | Typical hosted memory service |
|---|---|---|
| Where it runs | One SQLite file on your machine | A managed cloud service (some also self-host) |
| Embeddings | Local model in Node (MiniLM), no API key | Usually a cloud embedding API |
| Cost per token | $0 — nothing is metered | Usage-based, or a server you operate |
| Extra infrastructure | None | Often Postgres/pgvector, Redis, or a Python service |
| Claude Code integration | First-class: hooks auto-capture and recall | Manual wiring |
| Benchmarks | Committed corpus + runner, reproducible locally | Mostly self-reported |

The trade-off is honest: a single-process SQLite server tops out in the low hundreds of thousands of vectors (see [Limitations](#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):

```bash
npm install -g mcp-memory-graph
```

Or from source:

```bash
git clone https://github.com/YonasValentin/mcp-memory-graph.git
cd mcp-memory-graph
npm install
npm run build
```

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

```bash
# 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):**

```bash
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 50 tools (44 `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

```bash
npm install -g mcp-memory-graph@latest   # or just let `npx -y mcp-memory-graph` pull it
npx 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:

```bash
launchctl start com.mcp-memory.consolidate
cat ~/.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

| | precision@1 | precision@3 | MRR | search p95 |
|---|---|---|---|---|
| Hybrid (RRF) | 0.563 | 0.750 | 0.704 | ~4 ms |
| **+ cross-encoder rerank** (MCP default) | **0.813** | **0.875** | **0.867** | ~230 ms |

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

### Scale

With the real embedder and a file-backed SQLite database, retrieval