LLMemory MCP server

LLMemory

Self-hosted memory for AI assistants, stored as a knowledge graph you can edit.

An assistant reads and writes typed entities and relationships over MCP. An embedded property graph (LadybugDB) is the system of record, and Qdrant adds hybrid dense and sparse retrieval. No second LLM sits on the write path. The assistant supplies the structure, the server validates it and stores it.

Why it exists

Version 1 (LightRAG + GraphML) let a local model extract relationships and merged them into the graph. A bad edge could not be fixed on its own, and small local models would not hold a type vocabulary, so the graph filled with generic, mistyped nodes. LLMemory is a ground-up rework built around two rules:

1. Relationships are first-class records with their own ids, so any one of them can be edited, re-typed, or removed.
2. The model in the loop is the one already talking to you. The server never asks a second model to guess structure.

What it does

• Editable graph. Entities and relationships are separate by construction. A connection is never stored as a node. This is enforced four ways: disjoint entities and relationships arrays in the API, a predicate-blocklist validator, a closed type vocabulary, and separate NODE and REL tables in the graph store.
• Hybrid retrieval. Dense vectors (Ollama, nomic-embed-text, 768d) and sparse vectors in Qdrant, fused with graph expansion and a lexical fallback. Reads return in under a second and call no LLM.
• Journal-first writes. Every write is appended to a journal and drained by a background embedding worker. A reconcile script compares the graph against the vector store.
• 24 MCP tools for writing, reading, merging, history, communities, property templates, and a category and tag vocabulary registry. See the table below.
• Siloing. Reads can be scoped to categories, and per-identity permissions can be enforced server-side. Both fail closed.
• Auth. GitHub OAuth with an allowlist. An empty allowlist denies everyone.
• Web UI served at /ui for browsing and editing the graph.
• Small-hardware friendly. Designed to a 4 GB VRAM ceiling, and the test suite needs no GPU.

Architecture

Assistant ──MCP──▶ FastMCP server ──validate──▶ LadybugDB (graph, system of record)
                         │                               ▲
                         └─append─▶ journal/outbox ─▶ embedding worker ─▶ Qdrant (dense + sparse)
                                                          (Ollama, nomic-embed-text 768d)
Reads: hybrid retriever over Qdrant + the graph, sub-second, no LLM.

Layer	Choice	Why
Graph (system of record)	LadybugDB, the maintained fork of the archived Kùzu	Embedded, Cypher, first-class editable nodes and edges
Vectors	Qdrant	Hybrid dense and sparse, payload filtering
Embeddings	Ollama nomic-embed-text (768d)	Fits a 4 GB VRAM ceiling
MCP	FastMCP (Python)	Mounted at /

LadybugDB replaced Kùzu in production on 2026-09-30 after Kùzu was archived upstream. The decision and the cutover are recorded in decisions.md (D027). Some code names (kuzu_store, KUZU_DB_PATH) keep the old name for lineage.

MCP tools

Group	Tools
Write	remember, update_entity, update_relationship, link, unlink, forget, merge, set_visibility
Read	search_memory, get_entity, get_relationships, browse, find_similar, get_entity_history, memory_stats
Communities	refresh_communities
Property templates	create_property_template, update_property_template, get_property_template, list_property_templates
Vocabulary	list_terms, register_term, vocabulary_report, apply_vocabulary

Quickstart

Requires Python 3.12+, uv, and Docker for the full stack.

uv sync                      # create the env and install dependencies
cp .env.example .env         # set endpoints and auth; every option is commented
docker compose up -d         # qdrant, ollama, mcp-server (cloudflared if you set a tunnel token)

[!WARNING] The sample docker-compose.yml binds Qdrant (6333) and Ollama (11434) to 127.0.0.1 because neither has authentication. Keep them off any shared interface; if you need them from another machine, put them behind a tunnel or firewall, not a published port.

Tests

The suite runs fully offline. It uses an in-memory Qdrant and a deterministic hash embedder, so there is no Ollama, no Qdrant server, and no GPU.

uv sync --extra dev
PYTHONPATH=src uv run pytest -q

CI runs ruff, mypy (ratcheted), and the test suite on every push and pull request. See CONTRIBUTING.md.

Status

LLMemory is built for one user and runs daily as its author's memory behind Claude Code and claude.ai. It is not packaged for multi-tenant use. Planned work lives in Issues and in Plans/.

Documentation

Doc	What it covers
ARCHITECTURE.md	Contracts and boundaries
docs/V2_ARCHITECTURE_SPEC.md	The binding design
docs/IMPLEMENTATION_NOTES.md	Judgment calls made during the build
docs/SILOING_DESIGN.md	Category scoping and permissions
docs/V3_DEPLOY_RUNBOOK.md	Deploying and upgrading
decisions.md	Decision log with alternatives considered

Layout

src/llmemory/
  server.py        FastMCP entrypoint
  config.py        settings
  schema/          entity and relationship models
  graph/           graph store, system of record
  vectors/         Qdrant dense and sparse store
  validator/       entity-versus-relationship guard
  worker/          async embedding worker, outbox drain
  retrieval/       hybrid retriever and fallback cascade
  tools/           MCP tool surface
  community/       community detection (NetworkX); assistant-written summaries
  ui/              web UI at /ui
hollowdeck/        client module for the HollowDeck workspace app
scripts/           backup, reconcile, and migration scripts
tests/
data/              runtime DB and journal (gitignored)

Contributing

Bug reports, fixes, and features are welcome. See CONTRIBUTING.md and the Code of Conduct.

License

Apache-2.0. See LICENSE and NOTICE.

Acknowledgements

LadybugDB and Kùzu for the embedded graph engine, Qdrant, FastMCP, and Ollama.