domesday 0.1.7

A shared knowledge base that keeps AI tools informed of your team's project-specific information.

domesday-book

A shared knowledge base that keeps AI tools informed of your team's project-specific information.

The natives call this book "Domesday" ... concerning the matters contained in the book, its word cannot be denied or set aside.
wikipedia.org/wiki/Domesday_Book

Status

🚧 Ongoing development! 🚧

Core functionality implemented as a working protoype. See Roadmap for next steps.

Why this exists

Research teams accumulate critical tacit knowledge — processing caveats, data access optimizations, troubleshooting tips — that lives in Teams conversations, scattered notes, and people's heads. This is information AI tools (and other people) need access to.

We need a system where:

• Adding knowledge is as easy as pasting a text snippet into a box
• The system automatically processes new entries
• Multiple team members can contribute and curate entries
• The knowledge base is queryable by AI tools like Claude, giving answers with citations to the original snippets

Comparison to alternatives

Approach	Pros	Cons
Wiki / shared docs (Confluence, Notion)	Familiar, collaborative	Keyword search only, full-page retrieval adds noise and cost
Single document in context (CLAUDE.md, system prompt)	Simple, no infra, fast	Doesn't scale, context bloat increases cost and noise
Built-in knowledge bases (Claude Projects)	Integrated, zero setup	Vendor lock-in, not programmable, not open
Generic RAG (LangChain + vector DB)	Flexible, open	High setup and maintenance cost, custom glue code
domesday-book	Easy setup, multi-project, works with any AI tool	requires API keys for faster embedding/LLM

Quickstart

Note: in this early-stage prototype, interaction with the system is via the CLI, however that is not the intended end-user interface.

# Install
uv tool install domesday[voyage,mcp]

# Set API keys
export VOYAGE_API_KEY=voy-...
export ANTHROPIC_API_KEY=sk-ant-...

# Add a snippet to a project
domes -p vbo add "The VBO dataset has an off-by-one error in timestamps before 2023-06-01."

# Bulk ingest a folder
domes -p vbo ingest ./project-notes/ --author ben

# Semantic search within a project to find matching snippets (retrieval only)
domes -p vbo search "VBO timestamp issues"

# Ask a question (retrieve matching snippets → LLM generates answer with citations)
domes -p vbo ask "What are the known caveats with the dataset?"

# Actual answer from Claude Sonnet 4.6
# **VBO Dataset Timestamp Error**: The VBO dataset has an **off-by-one error in timestamps** for any data dated **before 2023-06-01**. [snippet-1fffb1]  

# Search across all projects
domes search "timestamp bugs" --all-projects

# Browse and inspect
domes projects             # list all projects with snippet counts
domes -p vbo list          # recent snippets in a project
domes stats --all-projects # stats across everything

Development

# clone repo and install:
uv sync --all-extras

# run tests:
uv run task test

How it works

Add snippet (paste/CLI/MCP)
  → Store raw text + metadata (SQLite)
  → Chunk (prose/code-aware, ~400 tokens)
  → Embed (Voyage / OpenAI / local model)
  → Index (ChromaDB vector store)

Ask a question (CLI/MCP/API)
  → Embed query
  → Vector similarity search (cosine, with score threshold)
  → [Optional] LLM reranker filters irrelevant results
  → Format context with author, date, tags
  → Generate answer via Claude with inline citations

Every backend is behind a Protocol interface — swap storage, embedding, or generation by changing config. See Architecture for details.

Projects

A single domesday instance can hold multiple projects. Each snippet belongs to exactly one project. Queries are scoped to a project by default, preventing cross-contamination between unrelated knowledge bases.

# Set a default project in config
# domesday.toml: default_project = "vbo"

# Or specify per-command (--project / -p goes before the subcommand)
domes -p vbo add "some caveat"
domes -p ephys-rig add "different caveat"

# Search within a project
domes -p vbo search "timing issues"

# Search across everything
domes search "timing issues" --all-projects

# See what projects exist
domes projects

# Rename a project
domes rename-project old-name new-name

The --project flag (or -p) can also be set at the top level, applying to all subcommands:

domes -p vbo add "some caveat"
domes -p vbo search "timing"
domes -p vbo ask "what are the known issues?"

For MCP, pass the project in tool arguments, or set DOMESDAY_DEFAULT_PROJECT in the server environment.

Configuration

Place domesday.toml in your project root:

default_project = "main"      # used when --project is not specified

[embedder]
backend = "voyage"             # voyage | openai | local
model = "voyage-4-large"

[generator]
backend = "claude"
model = "claude-sonnet-4-6"

[chunker]
max_tokens = 400
overlap_tokens = 50

[retrieval]
min_score = 0.3               # cosine similarity threshold

[reranker]
enabled = false               # LLM-based relevance filtering (adds latency)
model = "claude-haiku-4-5"
relevance_threshold = 0.5

Environment variables override config: DOMESDAY_EMBEDDER__BACKEND, DOMESDAY_EMBEDDER__MODEL, DOMESDAY_GENERATOR__MODEL.

CLI reference

All commands accept --project / -p to scope to a specific project. This can also be set at the top level: domes -p myproject <command>.

Use --verbose / -v for INFO-level logs or --debug / -d for full DEBUG output:

domes -v search "timestamp issues"     # see search flow
domes -d ingest ./notes/               # see every chunk and embedding call

Command	Description
domes add "text"	Add a snippet (also accepts --file, stdin, or opens $EDITOR)
domes add --author ben --tags "vbo,bug"	Add with metadata
domes -p myproject ingest ./folder/	Bulk ingest files into a project
domes search "query"	Semantic search within the current project
domes search "query" --all-projects	Search across all projects
domes ask "question"	Retrieve relevant snippets then generate an answer with citations
domes ask "question" --show-sources	Also print which snippets were used
domes list	Show recent snippets in current project
domes list --all-projects	Show recent snippets across all projects
domes projects	List all projects with snippet counts
domes rename-project old new	Rename a project across all stores
domes stats	Show stats for current project
domes stats --all-projects	Show stats across all projects

MCP integration

domesday exposes itself as an MCP server, making the knowledge base available from Claude Desktop, Cursor, VS Code, or any MCP-compatible client.

Local (stdio) — add to claude_desktop_config.json:

{
  "mcpServers": {
    "domesday": {
      "command": "python",
      "args": ["-m", "domesday.mcp_server"],
      "env": {
        "DOMESDAY_DATA_DIR": "/absolute/path/to/data",
        "DOMESDAY_DEFAULT_PROJECT": "vbo",
        "VOYAGE_API_KEY": "voy-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Remote (SSE) — for team access:

{
  "mcpServers": {
    "domesday": {
      "url": "https://your-server.internal:8080/mcp/sse"
    }
  }
}

Available MCP tools:

Tool	Description
search_knowledge(query, project?, n_results?, tags?)	Semantic search over snippets
add_snippet(text, project?, author?, tags?)	Add new knowledge from any client
get_snippet(snippet_id)	Retrieve a snippet by full or short (8-char) ID
list_recent(n?, project?, author?)	Browse recent additions
list_projects()	List all projects with snippet counts
rename_project(old_name, new_name)	Rename a project across all stores
ask(question, project?, n_context?)	Retrieve relevant context and generate an answer with citations

All tools accept an optional project parameter. Pass "all" to search across all projects.

Evaluation

domesday includes an evaluation framework for measuring retrieval quality and generation faithfulness. See Evaluation for full details.

# Run retrieval eval against test corpus
python -m domesday.eval.runner

# Also judge generation quality with Haiku
python -m domesday.eval.runner --judge

# Parameter sweep (min_score, k, chunk size, overlap)
python -m domesday.eval.runner --sweep --quick

# Interactive: inspect individual queries and results
python -m domesday.eval.runner -i

Project structure

domesday/
├── pyproject.toml
├── domesday.toml
├── domesday/
│   ├── core/
│   │   ├── models.py           # Snippet, Chunk, SearchResult, RAGResponse
│   │   ├── protocols.py        # Swappable interfaces for all backends
│   │   └── pipeline.py         # Orchestrator: add, ingest, search, ask
│   ├── stores/
│   │   ├── sqlite_store.py     # SnippetStore → SQLite
│   │   └── chroma_store.py     # VectorStore → ChromaDB
│   ├── embedders.py            # Voyage, OpenAI, sentence-transformers
│   ├── generators.py           # Claude via Anthropic API
│   ├── chunking.py             # Prose/code-aware text splitting
│   ├── config.py               # defaults + parsing from file/env
│   ├── cli.py                  # CLI commands
│   ├── mcp_server.py           # MCP tool definitions
│   └── eval/
│       ├── models.py           # Eval metrics (precision, recall, MRR)
│       ├── runner.py           # Eval runner + parameter sweeps
│       └── llm_judge.py        # Haiku-based quality scoring + reranker
├── tests/
│   └── fixtures/
│       └── test_corpus.py      # 30 synthetic snippets + 21 eval queries
└── docs/
    ├── architecture.md
    └── evaluation.md

Further reading

• Architecture & design decisions
• Evaluation framework