Architecture

How the CLI, agent loop, file tools, and schema fit together.

The schema

schema.md is the LLM's behavioral spec. It defines directory structure, page format, YAML frontmatter conventions, cross-linking rules, naming conventions, and step-by-step workflows for ingest, query, and lint. The agent reads it at the start of every operation.

Editing schema.md is the primary way to customize behavior — no code changes needed.

The agent loop

Every command that calls the LLM (ingest, query, lint) runs the same agentic loop. The loop sends a prompt to the model, receives a response, executes any tool calls the model makes, feeds results back, and repeats — up to 40 turns — until the model signals it is done.

The model is given five file tools:

ToolPurpose
read_file(path)Read any file relative to the wiki root.
write_file(path, content)Write or overwrite a file. Creates parent directories as needed.
append_to_file(path, content)Append content to a file. Used for log.md.
list_directory(path)List files and subdirectories at a path.
search_wiki(query)Full-text search across all wiki/*.md files.

All paths are validated against the wiki root to prevent directory traversal.

Package structure

wiki_builder/
├── cli.py        # Typer CLI — init, ingest, query, lint, status, config
├── agent.py      # Agent loop, Anthropic + OpenAI backends, prompt builders
├── tools.py      # The five file tools the LLM calls
├── config.py     # Provider and API key resolution
└── templates.py  # Default schema.md, index.md, log.md written by init

Ingest workflow

When you run wiki ingest raw/paper.md, the agent:

  1. Reads schema.md and the source file content.
  2. Lists wiki/sources/, wiki/concepts/, and wiki/entities/ to understand what already exists.
  3. Writes a summary page to wiki/sources/<slug>.md.
  4. Creates or updates concept pages in wiki/concepts/.
  5. Creates or updates entity pages in wiki/entities/.
  6. Updates wiki/index.md with new entries.
  7. Appends an entry to wiki/log.md.

A typical ingest touches 5–15 files across 10–20 tool-calling turns.

Query workflow

When you run wiki query "...", the agent:

  1. Reads schema.md and wiki/index.md.
  2. Identifies relevant pages based on the question and the index.
  3. Reads those pages in full.
  4. Synthesizes an answer with citations to source pages.
  5. If --save is set, writes the answer to wiki/concepts/ and appends to log.md.

Lint workflow

When you run wiki lint, the agent:

  1. Reads schema.md and lists all wiki pages.
  2. Reads pages to check for orphans, broken links, contradictions, and stale claims.
  3. Produces a structured lint report.
  4. If --fix is set, rewrites pages to repair issues and appends to log.md.