Knowledge Base

Knowledge supplies reference material for the agent: product facts, policies, terminology, and operating procedures. Keep it in amodal/knowledge/ and version it with the agent.

Use stores for changing structured records and connections for live API access. Knowledge is available to the agent's model; do not put secrets or private customer records in it.

Document Format

Small documents are Markdown files:

amodal/knowledge/
├── support-policy.md
└── product-glossary.md

---
description: Use when a support ticket involves account access or a disputed charge.
category: support
tags: [account-access, billing]
---
 
# Support Policy
 
- Check account-access verification before recommending account changes.
- Confirm a refund's status in the billing system before reporting it as complete.
- Escalate a disputed charge to the billing team with the invoice and ticket IDs.

The filename without .md is the document name: support-policy. The title comes from frontmatter title, then the first # heading, then the filename. Optional frontmatter includes description, category, and tags.

How Knowledge Enters Context

A root session's prompt lists document names and descriptions. The model retrieves a body with:

load_knowledge({ knowledge: 'support-policy' });

The description comes from frontmatter description. Without it, the body's first paragraph supplies a description truncated to 400 characters. Write it to identify when the document applies.

A delegated subagent receives its authored prompt rather than the root's compiled knowledge index. Declare load_knowledge in the subagent's tools; the tool description lists available documents.

Searchable Corpora

Use a corpus for a manual or reference collection that should be searched and read in sections. Put a knowledge.json manifest beside its pages:

amodal/knowledge/reference-manual/
├── knowledge.json
├── _SECTIONS.tsv
└── pages/
    ├── 01-overview.md
    └── 02-procedures.md

{
  "type": "corpus",
  "title": "Reference Manual",
  "description": "Operating procedures and section references.",
  "pages": "pages",
  "index": "_SECTIONS.tsv",
  "provenance": {
    "edition": "2026-01",
    "source": "https://example.com/manual"
  }
}

The optional TSV index has section, title, page, and line columns. Without it, citations identify pages and lines rather than indexed sections.

Corpus tools search and read bounded excerpts instead of loading the whole collection. knowledge_search supports content, file, and section-title search; hybrid semantic search requires a configured index backend. Declare knowledge_search and knowledge_read in a named agent's tools as needed. See CLI corpus commands for preparing and checking a corpus.

Knowledge vs Skills vs Stores

Updating Knowledge

Edit the source, review the diff, commit, and deploy. Run evals that require the changed material before activating the deployment. Include a check for a fact found only in that document, so the eval verifies retrieval as well as the answer.