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

2. Connect Your AI Agent

Claude Code (recommended):

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

{
  "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"
      }
    }
  }
}

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

How It Compares

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.

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

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 →

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)

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

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

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

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

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