Candlekeep

The great library fortress on the Sword Coast, where all knowledge is preserved.

A RAG knowledge base server that gives AI agents the power to search, retrieve, and manage technical documentation through the Model Context Protocol. Ask a question, and the library answers — with the right scroll, expanded to full context, in milliseconds.

The Arcane Arts

• Bardic Knowledge — Documents are enriched with title and description at ingestion, woven into every embedding
• Bardic Inspiration — Result-time metadata boosting that ensures specific technical guides outrank generic content
• Arcane Recall — Intelligent expansion using Scholar's Discernment and Arcane Coalescence to return full sections without token waste
• Wild Magic — Hybrid retrieval merging Vector and BM25 (lexical) search, fixing "keyword blindness" for exact identifiers
• Divine Insight — Cross-encoder reranking for when precision matters more than speed
• The Relevance Ward — Results below a configured threshold are filtered, so the library says "I don't know" instead of guessing

Features

• Adaptive Search Routing: Three paths — simple (Vector), hybrid (BM25+Vector), and precise (Reranked)
• Statistical Rigor: Validated against The Centurion Set (100+ multi-category queries)
• Quality Gate: Documents must have frontmatter and structure to enter the library
• Embedding Protection: Auto-detects model mismatch on remote databases
• 8 MCP Tools: Search, ingest, critique, generate docs, and more
• Token Auth: Bearer token authentication for remote ChromaDB

Quick Start

# Enter the library
pip install -e .
./scripts/setup.sh       # Download the tomes (embedding models)
./scripts/configure.sh   # Set your wards (configuration)
./scripts/start_chroma.sh # Awaken the vault (ChromaDB)
candlekeep               # Open the gates

MCP Client Integration

HTTP mode (recommended) — one server, multiple agents. Models loaded once, shared memory, no cold-start per agent (~230ms first query vs ~6s in stdio mode):

# Start the server once
CANDLEKEEP_TRANSPORT=http CANDLEKEEP_HTTP_PORT=8111 candlekeep

{
  "mcpServers": {
    "candlekeep": {
      "url": "http://localhost:8111/mcp"
    }
  }
}

stdio mode — each agent spawns its own server process. Simpler setup, but each agent pays ~6s cold-start and loads its own copy of the models:

{
  "mcpServers": {
    "candlekeep": {
      "command": "/path/to/.venv/bin/candlekeep",
      "args": [],
      "env": {
        "CANDLEKEEP_SPICE": "true"
      }
    }
  }
}

See Setup Guide for auth configuration and production deployment.

The Tomes (Documentation)

• Setup Guide — Local and remote installation
• Authentication — Token configuration
• Architecture — System design and technical reference
• Design Decisions & Benchmarks — Why things are the way they are, with measured results
• Interactive Benchmark Chart — Visual comparison of paths
• Glossary of Retrieval — IR metrics explained in wizard sage style
• Research Diary — The full journey, every experiment, archived plans
• The Keeper's Chronicle — The story of how the library was built

MCP Tools

• search — Semantic search with adaptive routing (simple 22–36ms, precise ~1550ms)
• list_documents — List all indexed tomes
• get_stats — Library statistics
• critique_document — Check document quality before ingestion
• generate_documentation — Scan a project and create structured docs
• ingest — Add documents with automatic quality validation
• delete_document — Remove a tome from the index
• repopulate_database — Clear and rebuild the library

Access to write tools is managed by your database permissions (configured via CHROMA_AUTH_TOKEN).

Testing

# Unit tests — no database required (~1.4s)
pytest tests/test_router.py tests/test_quality_gate.py tests/test_arcane_recall_unit.py \
       tests/test_protection.py tests/test_processor.py tests/test_search.py

# Benchmarks — requires local ChromaDB on localhost:8000
./scripts/start_chroma.sh
pytest tests/test_router_benchmark.py -v -s

37 unit tests covering router, quality gate, chunk expansion, embedding protection, and document processing. Benchmark tests include regression assertions that fail if precision or content match drops below 80%.

Requirements

• Python 3.10+
• ChromaDB server (local or remote)

---

_{Candlekeep is a trademark of Wizards of the Coast. This project is unofficial fan content and is not endorsed by or affiliated with Wizards of the Coast.}