Dragon Brain

English | 中文 | 日本語 | Español | Русский | 한국어 | Português | Deutsch | Français

Persistent memory infrastructure for AI agents.

100% LongMemEval R@5 · 1,599 memories · 34 MCP tools · Graph + Vector hybrid · sub-200ms search · No LLM required

An open-source MCP server that gives any LLM long-term memory using a knowledge graph + vector search hybrid. Store entities, observations, and relationships — then recall them semantically across sessions. Works with any MCP client: Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Gemini CLI, VS Code Copilot, or any LLM that speaks Model Context Protocol.

Unlike flat chat history or simple RAG, Dragon Brain understands relationships between memories — not just similarity. An autonomous agent ("The Librarian") periodically clusters and synthesizes memories into higher-order concepts.

Quick Start

Prerequisites: Docker and Docker Compose. Detailed setup: See docs/SETUP.md for comprehensive instructions including prerequisites, platform-specific notes, and troubleshooting.

1. Start the Services

docker compose up -d

This spins up 4 containers:

• FalkorDB (knowledge graph) — port 6379
• Qdrant (vector search) — port 6333
• Embedding API (BGE-M3, CPU default) — port 8001
• Dashboard (Streamlit) — port 8501

GPU users: docker compose --profile gpu up -d for NVIDIA CUDA acceleration.

Verify everything is healthy:

docker ps --filter "name=claude-memory"

pip install dragon-brain

Note: Dragon Brain requires FalkorDB and Qdrant running as Docker services. The pip package installs the MCP server — run docker compose up -d first for the infrastructure. The embedding model (~1GB) is served via Docker, not downloaded locally.

2. Connect Your AI Agent

Claude Code (recommended):

claude mcp add dragon-brain -- python -m claude_memory.server

Add to your MCP client config:

{
  "mcpServers": {
    "dragon-brain": {
      "command": "python",
      "args": ["-m", "claude_memory.server"],
      "env": {
        "FALKORDB_HOST": "localhost",
        "FALKORDB_PORT": "6379",
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6333",
        "EMBEDDING_API_URL": "http://localhost:8001"
      }
    }
  }
}

See mcp_config.example.json for a full template. This server works with any MCP-compatible client via stdio transport.

3. Start Remembering

You: "Remember that I'm building Atlas in Rust and I prefer functional patterns."
AI:  [creates entity "Atlas", adds observations about Rust and functional patterns]

You (next session): "What do you know about my projects?"
AI:  "You're building Atlas in Rust with a functional approach..." [recalled from graph]

What It Does

Capability	How It Works
Store memories	Creates entities (people, projects, concepts) with typed observations
Semantic search	Finds memories by meaning, not just keywords — "that thing about distributed systems" works
Graph traversal	Follows relationships between memories — "what's connected to Project X?"
Time travel	Queries your memory graph at any point in time — "what did I know last Tuesday?"
Auto-clustering	Background agent discovers patterns and creates concept summaries
Relationship discovery	Semantic Radar finds missing connections by comparing vector similarity against graph distance
Session tracking	Remembers conversation context and breakthroughs

How It Compares

Feature	Dragon Brain	cipher	basic-memory	mcp-knowledge-graph	context-portal	nocturne_memory
Real Graph Database	FalkorDB (Cypher)	—	—	JSON files	—	—
Vector Search	Qdrant (HNSW)	—	SQLite FTS	—	SQLite (vectors)	—
Hybrid Search (RRF)	✓	—	—	—	—	—
Autonomous Clustering	✓ (DBSCAN)	—	—	—	—	—
Relationship Discovery	✓ (Semantic Radar)	—	—	—	—	—
Time Travel Queries	✓	—	—	—	—	—
GPU Acceleration	CUDA (BGE-M3)	—	—	—	—	—
Typed Relationships	Weighted edges	—	—	Edges	—	—
Session Tracking	✓	—	—	—	✓	—
Model Agnostic	Any MCP client	✓	✓	✓	✓	✓
Test Suite	1,281 tests	—	—	—	—	—
Mutation Testing	✓	—	—	—	—	—
Dashboard	Streamlit	—	—	—	—	✓
MCP Tools	34	—	—	—	—	—

Feature comparison based on public READMEs as of March 2026. Open an issue if anything is inaccurate.

Benchmark

Dragon Brain scores 100% recall@5 on LongMemEval (ICLR 2025), the industry-standard benchmark for AI memory systems — 500 questions across 6 categories, no LLM required for retrieval.

System	Score	Metric	LLM Required	Local
Dragon Brain v1.1.0	100%	R@5	No	Yes
MemPalace (Haiku rerank)	100%	R@5	Yes	Yes
MemPalace (raw)	96.6%	R@5	No	Yes
OMEGA	95.4%	QA accuracy	No	Yes
Mastra OM	94.87%	QA accuracy	Yes	No
Hindsight	91.4%	QA accuracy	No	No
Mem0	~85%	R@5	Yes	No

Note: R@5 (retrieval recall) and QA accuracy are different metrics — shown together for context. Systems marked with QA accuracy use an LLM to generate answers; R@5 measures retrieval only. Dragon Brain's 100% R@5 means the correct evidence sessions appear in the top 5 results for every question.

Per-Category Breakdown

Category	Questions	R@5
Knowledge update	78	100%
Multi-session	133	100%
Temporal reasoning	133	100%
Single-session assistant	56	100%
Single-session preference	30	100%
Single-session user	70	100%

Reproduce It

pip install dragon-brain
docker compose up -d
python -m benchmarks.longmemeval.runner --dataset oracle

Full methodology, raw data, and the journey from 25% to 100%: RESULTS.md

🔥 Use Cases — See It In Action

Same Dragon Brain, different story. Each demo shows a real scenario with example queries and results. Browse all demos →

⚖️ Legal Discovery

Find contradictions across depositions. Trace hidden money flows. Surface leads no human found.

🔬 Research Lab

Track your lab's evolving understanding. Replay intellectual journeys. Connect papers to experiments.

🚀 Startup CTO

Never lose a design decision. Trace incident root causes. Onboard new engineers instantly.

🔍 Investigative Journalist

Connect the dots across sources. Detect temporal clustering. Find leads you didn't know existed.

🎲 Game Master

Remember 50 sessions of campaign history. Trace consequences. Manage dramatic irony.

🧠 Personal Knowledge

Cross-domain connections across millennia. The Zettelkasten that actually thinks.

🛡️ Cybersecurity SOC

Link IOCs, TTPs, and actors. Detect emerging campaigns. Threat intel that connects.

📦 OSS Maintainer

3 years of issues, PRs, and RFCs — instantly searchable. Institutional knowledge preserved.

📈 Portfolio Manager

Track theses, correlations, and lessons. Replay your mental state from 6 months ago.

🏥 Medical Practice

Connect symptoms, treatments, and outcomes across visits. Context your EHR buries.

⚙️ Engineering R&D

Trace failure modes across subsystems. Link test results to design revisions.

📚 Teacher · 🎓 Student

Track misconceptions across cohorts. Discover cross-course concept connections.

Every demo uses the exact same Dragon Brain — no plugins, no customization, no domain-specific code. Just data + queries + connections you didn't know existed.

Architecture

graph TB
    Client["Any MCP Client<br/>(Claude, Cursor, Cline, ...)"]
    Server["Dragon Brain MCP Server<br/>34 tools · FastMCP"]
    FalkorDB["FalkorDB<br/>Knowledge Graph · Cypher"]
    Qdrant["Qdrant<br/>Vector Search · HNSW"]
    Embeddings["Embedding Service<br/>BGE-M3 · 1024d"]
    Librarian["The Librarian<br/>Auto-clustering · DBSCAN"]
    Dashboard["Dashboard<br/>Streamlit · Graph Viz"]

    Client <-->|"MCP (stdio/SSE)"| Server
    Server --> FalkorDB
    Server --> Qdrant
    Server --> Embeddings
    Server -.->|"periodic"| Librarian
    Librarian --> FalkorDB
    Dashboard --> FalkorDB
    Dashboard --> Qdrant

• Graph Layer: FalkorDB stores entities, relationships, and observations as a Cypher-queryable knowledge graph
• Vector Layer: Qdrant stores 1024d embeddings for semantic similarity search
• Hybrid Search: Queries hit both layers, merged via Reciprocal Rank Fusion (RRF) with spreading activation enrichment
• Semantic Radar: Discovers missing relationships by comparing vector similarity against graph distance
• The Librarian: Autonomous agent that clusters memories and synthesizes higher-order concepts

Project Structure

Dragon-Brain/
├── src/
│   ├── claude_memory/          # MCP server — 34 tools, services, repositories
│   │   ├── server.py           # FastMCP entry point
│   │   ├── tools.py            # MCP tool definitions
│   │   ├── search.py           # Hybrid search (vector + graph + RRF)
│   │   ├── repository.py       # FalkorDB graph operations
│   │   ├── vector_store.py     # Qdrant vector operations
│   │   ├── librarian.py        # Autonomous clustering agent
│   │   ├── search_advanced.py  # Semantic radar + associative search
│   │   ├── temporal.py         # Time travel queries
│   │   └── ...                 # Schema, embedding, analysis, etc.
│   └── dashboard/              # Streamlit monitoring dashboard
├── tests/
│   ├── unit/                   # 1,027 unit tests (3-evil/1-sad/1-happy per function)
│   └── gauntlet/               # 139 mutation, fuzz, property-based, concurrency tests
├── docs/                       # Architecture, user manual, runbook, ADRs
│   └── adr/                    # 7 Architecture Decision Records
├── scripts/                    # Docker, backup, health check, e2e tests
│   └── internal/               # 27 migration, verification, and repair scripts
├── docker-compose.yml          # One-command setup (FalkorDB + Qdrant + Embeddings + Dashboard)
└── pyproject.toml              # Python 3.12+, pip install -e ".[dev]"

MCP Tools (Top 10)

Tool	What It Does
create_entity	Store a new person, project, concept, or any typed node
add_observation	Attach a fact or note to an existing entity
search_memory	Semantic + graph hybrid search across all memories
get_hologram	Get an entity with its full connected context (neighbors, observations, relationships)
create_relationship	Link two entities with a typed, weighted edge
get_neighbors	Explore what's directly connected to an entity
point_in_time_query	Query the graph as it existed at a specific timestamp
record_breakthrough	Mark a significant learning moment for future reference
semantic_radar	Discover missing relationships via vector-graph gap analysis
graph_health	Get stats on your memory graph — node counts, edge density, orphans

All 34 tools are documented in docs/MCP_TOOL_REFERENCE.md.

Quality

This isn't a weekend hack. It's tested like production software:

• 1,281 tests across 76 test files, 0 failures, 0 skipped
• Mutation testing — 2,270 mutants, 1,184 killed across 27 source files (3-evil/1-sad/1-happy per function)
• Property-based testing — 38 Hypothesis properties
• Fuzz testing — 30K+ inputs, 0 crashes
• Static analysis — mypy strict mode (0 errors), ruff (0 errors)
• Security audit — Cypher injection audit, credential scanning
• Dead code detection — Vulture (0 findings)
• Dragon Brain Gauntlet — 20-round automated quality audit, A- (95/100)

Full gauntlet results: GAUNTLET_RESULTS.md

Why I Built This

Claude is brilliant but forgets everything between conversations. Every new chat starts from scratch — no context, no continuity, no accumulated understanding. I wanted Claude to remember me: my projects, preferences, breakthroughs, and the connections between them. Not a flat chat history dump, but a living knowledge graph that grows richer over time.

Documentation

Doc	What's In It
User Manual	How to use each tool with examples
MCP Tool Reference	API reference: all 34 tools, params, return shapes
Architecture	System design, data model, component diagram
Maintenance Manual	Backups, monitoring, troubleshooting
Runbook	10 incident response recipes
Code Inventory	File-by-file manifest
Gotchas	Known traps and edge cases

Local Development

Requires Python 3.12+.

# Install
pip install -e ".[dev]"

# Run tests
tox -e pulse

# Run server locally
python -m claude_memory.server

# Run dashboard
streamlit run src/dashboard/app.py

Claude Code CLI

claude mcp add dragon-brain -- python -m claude_memory.server

For environment variables, create a .env file or export them:

export FALKORDB_HOST=localhost
export FALKORDB_PORT=6379
export QDRANT_HOST=localhost
export EMBEDDING_API_URL=http://localhost:8001

Troubleshooting

Another service (Redis, another FalkorDB/Qdrant instance) is using the port. Either stop the conflicting service or change the port mapping in docker-compose.yml:

ports:
  - "6380:6379"  # Map to a different host port

Then update your environment variables to match.

Ensure you're using the GPU profile: docker compose --profile gpu up -d

Requirements:

• NVIDIA GPU with CUDA support
• NVIDIA Container Toolkit installed
• Docker configured for GPU access

CPU mode works fine for most workloads — GPU mainly speeds up bulk embedding operations.

1. Verify all 4 containers are running: docker ps --filter "name=claude-memory"
2. Check the embedding API is healthy: curl http://localhost:8001/health
3. Ensure your claude_desktop_config.json paths are correct (use forward slashes)
4. Restart Claude Desktop after config changes

Install in development mode: pip install -e .

Or set the PYTHONPATH environment variable to point to the src/ directory:

export PYTHONPATH=/path/to/Dragon-Brain/src

Docker volumes store persistent data. If you used docker-compose down -v, the volumes were deleted. Use docker-compose down (without -v) to preserve data.

To verify data persistence:

docker exec claude-memory-mcp-graphdb-1 redis-cli GRAPH.QUERY claude_memory \
  "MATCH (n) RETURN count(n)"

More: docs/GOTCHAS.md · docs/RUNBOOK.md

Roadmap

Dragon Brain is under active development. See the CHANGELOG for recent updates.

Current focus areas:

• Semantic Radar — relationship discovery via vector-graph gap analysis
• Drift detection and quality monitoring for long-lived graphs
• Search result ranking improvements
• Performance optimization for large graphs (10K+ nodes)

Have an idea? Open an issue.

Contributing

See CONTRIBUTING.md for testing policy, code style, and how to submit changes.

Community

• Questions & Discussion: GitHub Discussions
• Bug Reports: GitHub Issues
• Feature Requests: GitHub Issues

License

MIT