Skip to content

Knowledge Base

The KB consists of three artifact types: cards, API documentation annotations (Doxygen for C/C++, Sphinx docstrings for Python), and math documents. All are organized following the tree-structured knowledge principle.

Tree Structure

Every KB collection uses a tree layout rooted at an index file. An agent working with the KB follows the same pattern a researcher uses in a library: read the index, locate the relevant entries, pull only those artifacts.

Flat (small projects):

INDEX.md -> card_A.md
             card_B.md
             card_C.md

Categorized (larger projects):

INDEX.md -> solver/
              INDEX.md -> card_S01.md
                          card_S02.md
            io/
              INDEX.md -> card_I01.md

The same pattern applies to the reference library (library/INDEX.md \(\to\) PDFs) and math documents (math/ directory).

Key Point

When a collection outgrows a single index (roughly 30--50 entries), introduce a category layer. Each category gets its own sub-directory with its own INDEX.md. The root index then points to categories instead of individual artifacts. This keeps every index scannable and every lookup fast.

Cards

Structured markdown documents, one card per source file, always. No sub-cards or splitting.

If a card becomes unwieldy, the response depends on the type of complexity:

  • Essential complexity (e.g., a dense kernel file with many mathematically distinct variants): extract heavy sections (Algorithm, Math) into dedicated tex documents in the math directory. The card references them.
  • Accidental complexity (the file is doing too much): the kb-developer flags it with complexity-flag: "accidental" in frontmatter. This surfaces in the kb-reviewer's board view as a code-quality diagnostic.

Key Point

If you cannot write a coherent card, the code is not coherent. KB quality becomes a diagnostic tool for code quality, not just documentation.

Card Sections

Standard cards include: Overview, Interface, Call Graph, Algorithm, Design Rationale, Engineering Notes, Failure Modes, Constants & Thresholds, Math, Verification. Omit empty sections rather than writing "N/A."

Doxygen Annotations

Every non-static function in source files gets a Doxygen comment block:

/**
 * @brief One-line purpose (< 80 chars, active voice).
 *
 * @param[in]     x       Description
 * @param[in,out] result  Description
 * @return 1 on success, 0 on failure
 * @see related_function [card-ID]
 */

API Documentation Site

The framework also maintains an auto-generated HTML site (Doxygen for C/C++, Sphinx for Python) with call graphs, file dependency diagrams, and API reference. The INDEX links each source file to its HTML page, so agents can follow the link to see machine-generated relationship data alongside the hand-written card.

See Doxygen Site or Sphinx Site depending on the project's docs_tool setting.

Math Documents

LaTeX documents in the KB math directory formalizing algorithms, theorems, and numerical properties. Written when a card's Math section involves non-trivial derivations, or when multiple cards reference the same concept.

Reference Library

A curated collection of reference PDFs (books, papers, technical reports) stored in the KB directory alongside cards and math documents:

doc/kb/
  cards/          One card per source file
  math/           LaTeX derivations
  library/        Reference PDFs
    INDEX.md      Catalog with metadata
    *.pdf         The actual files

Every PDF has an entry in library/INDEX.md with: key, title, authors, year, topics, filename, and notes. Keys follow the convention {author}{year} (e.g., davis2006).

Cross-Referencing

Other KB artifacts cite library entries using the library: prefix:

  • In cards: [library:davis2006, Ch. 4]
  • In math docs: % library:davis2006, Theorem 3.2
  • In research artifacts: library:davis2006

The library: prefix distinguishes library references from card IDs. The kb-reviewer checks that all library:{key} citations resolve to valid INDEX entries (part of the Consistency score).

Storage

PDFs are large binary files. Two approaches are supported (configured via library_storage in project-config.md):

  • git-lfs (recommended): track library/*.pdf with LFS.
  • gitignore: ignore PDFs, store externally; only INDEX.md is versioned.

INDEX and SYNCLOG

  • INDEX.md --- master file index mapping IDs to source files and cards.
  • SYNCLOG.md --- change log recording every artifact creation, update, verification, or deletion.