qmd Canonical Doc Indexing

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• CLAUDE.md
• session_manager.py
• models.py
• memory-bank/index.md

qmd manages the retrieval and indexing of canonical documents within the project's layered memory architecture. It serves as the primary system for accessing human-maintained "canonical truth," such as design specifications, architectural decisions, and runbooks. By isolating document retrieval from semantic memory retrieval, qmd ensures that high-confidence, durable documentation remains distinct from ephemeral reasoning or machine-generated artifacts.

Sources: README.md:14-25, CLAUDE.md:21-21

Retrieval Ownership Split

The project separates retrieval responsibilities to prevent overlapping systems from conflicting. qmd specifically handles document collections and canonical files, while the Zvec system manages semantic recall for promoted machine memory.

Retrieval Domains

System	Ownership	Data Types
qmd	Canonical Docs	ADRs, Design Docs, Runbooks, Module Maps, Handoff Docs
Zvec	Promoted Memory	Investigation summaries, Stable code summaries, Handoff bundles
Metadata Store	Lifecycle State	Confidence, Evidence, Provenance, Sync State

Sources: README.md:38-48, CLAUDE.md:21-25

Indexing Workflow and Policy

qmd indexing operates as a controlled workflow rather than an automatic background process. The system batches indexing tasks to maintain performance and avoid database corruption.

Indexing Rules

1. Queue/Batch Operations: You must queue or batch indexing work instead of triggering updates on every file change.
2. No Direct Access: Do not modify the qmd database directly. Use the provided tools and API interfaces.
3. Controlled Scope: Indexing should focus on the active task context to manage token ceilings effectively.

Sources: README.md:80-82, CLAUDE.md:37-39

Document to Index Flow

The following diagram illustrates how canonical documents move from raw Markdown files into the searchable qmd index.

The diagram shows the asynchronous flow of documentation from the human-readable Markdown layer into the qmd database for agent retrieval.

Sources: README.md:32-36, CLAUDE.md:37-39

Canonical Truth Definition

Within qmd, "Canonical Truth" refers to durable, human-maintained documentation. This differs from "Machine Memory," which consists of promoted conclusions from agent reasoning sessions.

Content Categories indexed by qmd

• Architectural Decision Records (ADRs): Documents tracking significant design choices.
• Design Documents: High-level system overviews and specifications.
• Module Maps: Structural representations of the codebase.
• Runbooks: Step-by-step guides for operational tasks.
• Handoff Docs: Essential context passed between different agents or human operators.

Sources: README.md:32-36, session_manager.py:270-300

Integration with MCP Tools

The qmd system integrates with the Model Context Protocol (MCP) to provide agents with stable search interfaces.

Core Retrieval Tools

• search_docs: Queries the qmd index for relevant sections of canonical documents.
• retrieve_context: Fetches a combined context bundle including qmd document snippets and Zvec memory artifacts.

The sequence diagram details the interaction between the agent, the MCP tool interface, and the underlying qmd retrieval logic.

Sources: README.md:70-78, CLAUDE.md:54-61

Token Management in Indexing

qmd retrieval respects the project's token management policies. By providing on-demand retrieval instead of preloading the entire codebase, it helps the system stay within context ceilings.

• Active Context Ceiling: Target 64K tokens.
• Compaction Trigger: Policy defaults suggest compaction at 45K tokens.
• On-Demand Retrieval: qmd fetches only relevant snippets to conserve token budget.

Sources: README.md:60-68, CLAUDE.md:31-35

Summary

qmd Canonical Doc Indexing provides a structured, high-reliability gateway to the project's durable documentation. By enforcing a controlled indexing policy and separating document retrieval from semantic memory, the system maintains the integrity of the "canonical human truth" while supporting efficient agent-based reasoning. The integration with MCP tools allows for granular, on-demand context retrieval that optimizes token usage across long-running development tasks.