memory MCP server
Commit Oct 22, 2026Provides persistent semantic memory for Claude using a local HNSW vector index and an on-device ONNX embedding model.
Also known as abho7/mcp-memory-server
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 22, 2026
- License
- MIT
What is memory MCP?
memory provides persistent semantic memory for Claude using a local HNSW vector index and an on-device ONNX embedding model.
Summary generated from the project's README
About memory MCP server
Giving Claude a long-term memory that persists across different chat sessions is what this server enables. It allows Claude Desktop and Claude Code users to store information, such as project decisions or personal preferences, and recall them later using semantic search. Because it uses a local HNSW vector index and an on-device ONNX embedding model, your data stays on your machine without making network calls to external embedding APIs or hosted databases.
Developers interact with the server through four specific tools: store_memory, search_memory, list_memories, and delete_memory. The system manages its own storage in a local directory, using a MiniLM model to create embeddings. While the first run downloads the necessary model weights, all subsequent operations are fully offline. This setup is ideal for developers who need a private, local way to provide context to their AI assistants without sacrificing privacy or relying on cloud-based vector stores.
What you can do with it
- 1Recall project decisionsAsk the AI to remember why a specific technology was chosen for a project so it can explain the reasoning in future sessions.
- 2Store personal preferencesInstruct the AI to remember how you prefer to receive feedback or code reviews to maintain consistency in its output.
- 3Maintain technical environment detailsSave specific requirements for running tests or deploying code to ensure the AI provides accurate setup instructions later.
- 4Organize information with tagsRetrieve a specific list of stored items by filtering them through assigned categories.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
MCP_MEMORY_TEST_REAL_MODEL
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableabho7/mcp-memory-server is public and reachablegithub.com/abho7/mcp-memory-server ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-22github.com/abho7/mcp-memory-server ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmcp-memory-hnsw
Persistent semantic memory for Claude Code and Claude Desktop, backed by a from-scratch HNSW vector index and a local embedding model. Nothing leaves the machine: no embedding API, no hosted vector database, no network calls after the model is cached once.
Claude gets four tools — store_memory, search_memory, list_memories,
delete_memory — and memories written in one session are recallable in
every later one.
How it fits together
Claude Code / Desktop
│ MCP over stdio
┌───────▼─────────────────────────────────────┐
│ mcp_memory/server.py four MCP tools │
│ mcp_memory/store.py persistence, tags │
│ mcp_memory/embedder.py MiniLM via ONNX │
└───────┬─────────────────────────────────────┘
│ imports, never modifies
┌───────▼─────────────────────────────────────┐
│ hnsw-engine/ VectorDB + HNSWIndex │
│ (github.com/abho7/vectordb-hnsw) │
└─────────────────────────────────────────────┘
│
~/.claude/memory-hnsw/
memories.json source of truth: text, tags, ids
index.npz graph snapshot + vectors
hnsw-engine/ is a plain checkout, treated as a read-only dependency. Two
things it does not provide — persistence and enumeration — are supplied by
store.py from the outside, so the engine can be git pulled without
merge conflicts.
Setup
Requires Python 3.10+.
git clone https://github.com/abho7/vectordb-hnsw.git ./hnsw-engine
pip install -r requirements.txt
pytest # 66 tests
Then register the server with Claude Code (-s user makes it available in
every project, not just this one):
claude mcp add memory-hnsw -s user -- /absolute/path/to/python /absolute/path/to/mcp-memory-server/run_server.py
Point it at run_server.py rather than -m mcp_memory.server: the CLI's
own option parser claims the -m and rejects the command. The launcher
also puts the package on sys.path itself, so the server does not depend
on the client's working directory. Check it came up with claude mcp list.
For Claude Desktop, add it to claude_desktop_config.json (on Windows,
%APPDATA%\Claude\; on macOS, ~/Library/Application Support/Claude/):
{
"mcpServers": {
"memory-hnsw": {
"command": "/absolute/path/to/python",
"args": ["/absolute/path/to/mcp-memory-server/run_server.py"]
}
}
}
Use an absolute path to the Python executable in both cases. Desktop and
Claude Code do not inherit your shell's PATH, and a bare python that
resolves in your terminal is the most common reason a server shows up
dead. On Windows, escape backslashes in the JSON (C:\\Users\\...).
Newly added servers are picked up at startup, so restart Claude Code or Claude Desktop before the tools appear.
Copy SKILL.md into .claude/skills/memory-hnsw/SKILL.md (project) or
~/.claude/skills/memory-hnsw/SKILL.md (global) so Claude knows when to
reach for the tools rather than only what they do.
The first store_memory call downloads ~90MB of MiniLM weights to
~/.cache/mcp-memory-hnsw/. Every run after that is fully offline.
Configuration
| Variable | Default | Purpose |
|---|---|---|
MCP_MEMORY_DIR |
~/.claude/memory-hnsw |
where memories are stored |
MCP_MEMORY_MODEL_DIR |
~/.cache/mcp-memory-hnsw/all-MiniLM-L6-v2 |
model weight cache |
MCP_MEMORY_ENGINE_DIR |
./hnsw-engine |
path to the engine checkout |
MCP_MEMORY_EAGER_LOAD |
unset | 1 loads the model at startup instead of on first use |
Demo: recall across two sessions
Two separate OS processes sharing nothing but a directory on disk — which is what two Claude sessions are. This is real captured output.
Session 1 writes and exits:
$ python scripts/demo_two_sessions.py write --reset
=== SESSION 1 (process A) ===
Opened store at C:\path\to\mcp-memory-server\.demo-memory in 0.00s (0 existing)
stored 685814f899be [decision, db] We picked Postgres over MySQL because we need JSONB indexing
stored eb48e4499d68 [ops] The staging deploy key rotates on the first of every month
stored 6f1dbc3c81bf [preference] Ali prefers code review comments to be specific and short
stored 4ba2f6b59477 [testing] Integration tests live in tests/integration and need Docker running
4 memories written to disk.
Session 1 now exits. Nothing stays in RAM.
Session 2 is a brand new process:
$ python scripts/demo_two_sessions.py read
=== SESSION 2 (process B, started fresh) ===
Loaded 4 memories in 0.13s (restored from snapshot)
query: "which database did we choose and why"
-> [0.393] We picked Postgres over MySQL because we need JSONB indexing
query: "how should I write review feedback"
-> [0.375] Ali prefers code review comments to be specific and short
query: "what do I need installed to run the slower tests"
-> [0.378] Integration tests live in tests/integration and need Docker running
Tag filter (list_memories tag='ops'):
eb48e4499d68 The staging deploy key rotates on the first of every month
None of those queries share meaningful wording with the text they matched — "which database did we choose" against "We picked Postgres over MySQL", "run the slower tests" against "Integration tests ... need Docker". That is the point of embedding rather than grepping.
In Claude, the same exchange looks like:
Session 1 — "Remember that we went with Postgres over MySQL for JSONB indexing." →
store_memory→ Stored memory 685814f899be with tags [decision, db].Session 2, next day — "Remind me which database we settled on?" →
search_memory("which database did we settle on")→ We picked Postgres over MySQL because we need JSONB indexing
Design notes
Persistence, given an engine that has none. hnsw-engine's
ARCHITECTURE.md lists in-memory-only as a known limitation: every restart
rebuilds from scratch. Rebuilding is not viable at MCP startup — the engine's
published build cost is 5.1s for 500 vectors at dim=32, and MiniLM's 384
dimensions make each distance computation over ten times more expensive.
So the store snapshots the built graph to index.npz and restores it directly.
Measured on this machine with 200 memories:
| time | |
|---|---|
| load from snapshot | 0.08s |
| load by rebuilding | 4.38s |
| warm query | 5ms |
| first query (includes model load) | 0.48s |
The graph's bytes are the engine's to define, not this store's. It asks for
them with VectorDB.snapshot_arrays(), writes them into index.npz beside
its own fingerprint, and hands them back to VectorDB.restore_snapshot().
This used to encode the adjacency here and assign back into the engine's
attributes, which meant a layout change upstream was a silent break here
rather than a loud failure there.
That still leaves a snapshot that can go stale, so it stays guarded:
memories.json is the source of truth, the snapshot carries a fingerprint of
exactly which entries it should contain, and the engine version-stamps its own
arrays and validates them before adopting them. Any mismatch — stale snapshot,
corrupt file, a snapshot written by an older layout — falls back to rebuilding
from the stored text. The worst case is a slow startup, never a wrong or lost
memory. Both paths are tested, including that they return identical search
results and that an old-format snapshot rebuilds instead of being half-read.
Rebuilding is also the compaction pass. The engine soft-deletes: a deleted node stays in the graph and is filtered out of results, so the index only ever grows. Its docs list compaction as future work. A rebuild here drops tombstones, so deleting a lot and forcing one rebuild reclaims the space.
IDs are never recycled. Re-inserting an id the engine has soft-deleted
leaves the old vector live in the graph under that same id, which surfaces
as a duplicate hit carrying stale text. (The engine's own
test_reinsert_after_delete_succeeds passes because it only asks for k=1.)
Every store_memory mints a fresh id, so the situation never arises.
ONNX instead of PyTorch. Same all-MiniLM-L6-v2 weights and the same
mean-pool-then-normalize computation sentence-transformers performs, run
under onnxruntime: ~90MB installed against ~2.5GB, and a cold start well
under a second. Embeddings are unit length, so the engine's cosine distance
is exactly 1 - similarity.
Similarity scores read low. MiniLM puts genuine paraphrase matches
around 0.3–0.5, not 0.9. Rank matters; the absolute number does not.
SKILL.md tells Claude to read them relatively.
Tests
pytest # 66 tests, no model needed
MCP_MEMORY_TEST_REAL_MODEL=1 pytest # + 3 against real MiniLM weights
Most tests use a deterministic hashing embedder rather than the neural model: fast, offline, and it makes ranking assertions exact instead of dependent on what a neural net happens to think.
| File | Covers |
|---|---|
test_store.py |
CRUD, tags, snapshot round-trip, all three rebuild-fallback triggers, compaction, id recycling, graph-structure fidelity, both load paths agreeing |
test_tools.py |
each of the four tools, MCP registration and schemas, dispatch through server.call_tool, cross-session recall through the tools |
test_embedder.py |
mean-pooling under the attention mask, padding invariance, unit length; real-model tests are opt-in |
The engine's own 28 tests still run from hnsw-engine/ (cd hnsw-engine && pytest) and are unaffected — nothing in that directory was modified.
Limitations
- No update tool. Superseding a memory is store-then-delete.
- Tag filtering happens after search, not inside it, so
list_memoriesfilters by tag butsearch_memoryranks on text alone. - Single writer. Two servers pointed at one data directory will clobber each other's writes; each write rewrites both files atomically, but there is no cross-process lock.
- Plaintext on disk.
memories.jsonis human-readable and unencrypted. Don't store secrets in it. - Everything in RAM while running. Fine for thousands of memories at 384 dimensions; this is not a billion-scale store.
memory MCP questions
Is my data sent to any external APIs?
No, everything stays on your machine. There are no embedding APIs, no hosted vector databases, and no network calls after the model is cached once.
How does the server handle memory persistence?
The server snapshots the built HNSW graph to an index file and restores it directly to avoid rebuilding the index from scratch on every startup.
What happens if the snapshot file becomes corrupt or stale?
The server is designed to be resilient; if it detects a mismatch or corruption, it automatically falls back to rebuilding the index from the stored text.
Does the server require an internet connection to function?
After the initial download of the MiniLM weights, the server operates fully offline.