Semantic Memory MCP

Persistent, semantic memory for AI coding agents — a single Python file, entirely local.

semantic-memory-mcp is a self-hosted Model Context Protocol server that gives AI coding agents a durable, searchable memory across sessions. It is built as one Python file, stores everything in a single local SQLite database, and needs no cloud service and no API key.

What it is

• Cross-session memory: notes survive between sessions; the agent searches its own memory at the start of every task instead of relying on the user to re-explain context.
• Hybrid retrieval: keyword full-text search (SQLite FTS5) and semantic vector search (sqlite-vec) are combined through Reciprocal Rank Fusion — a note can be found by exact wording or by meaning.
• Multilingual embeddings: quantized ONNX model (Xenova/multilingual-e5-small, ~113 MB) runs locally on CPU. English and German work equally well; no OpenAI key required.
• Trivially auditable: the whole server is a single readable file (memory_server.py, ~1,100 lines). There is no hidden state beyond the SQLite file.

Tools

Why

AI coding agents forget everything between sessions. File-based memory (markdown indexes that get reloaded) is keyword-based: it has no semantic recall and no ranking — a note saved as "embedding model comparison" will not be found when the agent later asks "which embedding did we test?".

This server was built as a working reference implementation and measured, not assumed — see Evaluation.

Evaluation

Retrieval quality was tracked throughout development. Recall@5 — the share of queries where the correct note is among the top 5 hits — rose from 68.4 % to 89.2 % across successive, individually measured optimization steps (chunking, embedding model choice, query rewriting, and more). The full measurement series with a 22-study comparison table is documented here:

The Memory Server in the Lab

Working across parallel sessions

You can run several agent sessions at the same time — they all share one memory. Instead of a single "where did I stop?" slot that parallel sessions would overwrite, each session ends its work with a short checkpoint note in the memory (topic, what was done, what is open, next step), with the writing agent and model recorded in the source field. Asking any window "Where did we stop on X?" then finds the answer — even if the work happened in a different window. The convention is part of the agent rules (memory-mcp-knowledge.md, R17).

Installation

Prerequisites: Linux, Python 3.11+ with venv, ~500 MB free disk space (virtual environment plus embedding model). The server is written for Linux, but not limited to it: since everything is one Python file, any AI assistant can read the script and adapt the installation for Windows or macOS.

git clone https://github.com/Michael-Logies/semantic-memory-mcp.git
cd semantic-memory-mcp
bash setup.sh      # creates the venv, installs dependencies, downloads the model
bash verify.sh     # checks the installation, writes a report

The embedding model is downloaded automatically from Hugging Face (huggingface_hub, no account needed).

Alternative: pip install from GitHub — no clone needed; the package ships a semantic-memory-mcp command, and the embedding model (~113 MB) downloads automatically on first start:

python3 -m venv ~/.venv-memory
~/.venv-memory/bin/pip install git+https://github.com/Michael-Logies/semantic-memory-mcp.git

Then register the server in your AI agent's MCP configuration (example for Qwen Code, ~/.qwen/settings.json):

{
  "mcpServers": {
    "memory": {
      "command": "/home/<user>/.venv-memory/bin/python3",
      "args": ["/path/to/semantic-memory-mcp/memory_server.py"],
      "transport": "stdio"
    }
  }
}

If your client has an mcp add command, registration is a one-liner once the venv exists (with the pip installation, use the packaged ~/.venv-memory/bin/semantic-memory-mcp as the single command instead of python3 …/memory_server.py):

# Qwen Code (note: no `--` separator)
qwen mcp add memory ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py

# Claude Code
claude mcp add memory -- ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py

# Codex CLI
codex mcp add memory -- ~/.venv-memory/bin/python3 /path/to/semantic-memory-mcp/memory_server.py

The Qwen Code and Claude Code commands were verified against the locally installed CLIs. The Codex line was not tested by us — its syntax was adopted from the documentation of other projects, since we only use Qwen Code ourselves.

See mcp-config.json for a template. usage-notes.md contains practical guidance for working with an agent that has persistent memory (context management, what to store, tagging, parallel sessions); the German version ships as nutzungshinweise.md.

Documentation for your AI agent

Two documents ship with this repository, written for the agent rather than the human (both CC0-licensed):

• memory-mcp-knowledge.md — the rules and learning protocol for operating the memory server in daily agent work: when to read, when to write, what to store, and how to tag it.
• zotero-mcp-agent-knowledge.md — hard-won knowledge about connecting Zotero with AI agents via MCP servers: tool comparison (zotero-mcp-server, Zoteus, pyzotero, CLI access), benchmarks, and best practices. Since 31 August 2026, Zoteus is the sole Zotero MCP server in the reference setup; the older ChromaDB-based material is kept as background, not as a recommendation.

The bigger picture

This server is the memory layer of a reproducible AI workstation for students — a complete setup guide (research, learning, literature work on a Linux machine) documented step by step here:

• AI Workstation for Students: Research, Learning, and More (English)
• KI-Arbeitsplatz fürs Studium: Recherche, Lernen und mehr (German)

Memory comes in two layers in that setup: this server stores the working memory of day-to-day collaboration with the agent, while scholarly literature lives in a Zotero research database made searchable by meaning through a second MCP server (Zoteus). How the two fit together is described on the project pages:

• Cross-Session Memory for AI Agents (English)
• Cross-Session-Memory für KI-Agenten (German)

Status and maintenance

The server has been in daily production use since August 2026 as the memory of a working AI workstation. It is developed and maintained by Michael Logies in close collaboration with AI coding agents — see the project pages above for how it was built and evaluated. The server is provided as-is: bug reports are welcome and handled on a best-effort basis, but there is no formal support.

License

MIT — see LICENSE.