Knowledge Base

Knowledge files turn a general-purpose reasoning engine into an agent that understands your domain. They live in amodal/knowledge/ as Markdown and are versioned with the rest of the agent repo.

Use knowledge for stable context:

product or workflow facts
support policies
escalation rules
known terms and definitions
examples of good answers
boundaries the agent should respect

Do not put secrets, raw customer data, private credentials, or volatile incident logs in knowledge files. Put structured records in stores, and put API access in connections.

amodal/knowledge/
├── support-policy.md
├── product-glossary.md
├── escalation-paths.md
└── response-style.md

Document Format

Each file is normal Markdown. The first heading becomes the document title, and the filename becomes the document ID.

# Support Policy
 
- Explain what data was checked before recommending an action.
- Separate confirmed facts from assumptions.
- Never expose credentials, payment tokens, or internal-only notes.
- For account changes, ask the operator to verify identity first.

Keep each document focused. A few short, specific files are easier to review and update than one long policy dump.

What To Put In Knowledge

Category	Good Examples	Avoid
Product facts	Feature names, plan limits, lifecycle states	Hard-coded customer records
Workflows	Triage steps, escalation criteria, handoff rules	One-off incident transcripts
Glossary	Domain terms and acronyms	Internal jokes or tribal shorthand
Response policy	Tone, uncertainty handling, disclosure rules	Secrets, credentials, private tokens
Known patterns	Common benign situations and how to verify them	Security allowlists copied from production

Example: Product Glossary

# Product Glossary
 
- **Workspace**: A team-owned container for agents, users, billing, and automation tokens.
- **Agent**: A deployed runtime backed by a git repo.
- **Deploy**: A materialized build of agent source that can be promoted or rolled back.
- **Session**: A persisted conversation with messages, tool calls, model usage, and metadata.

Example: Support Triage Policy

# Support Triage Policy
 
When answering support questions:
 
1. Restate the issue in one sentence.
2. Identify the relevant ticket, user, workspace, or order ID.
3. Check available data before recommending an action.
4. Explain uncertainty when data is incomplete.
5. Give the operator one concise next step.
 
Do not promise refunds, approvals, credits, or account changes unless the connected system confirms that status.

Example: Escalation Paths

# Escalation Paths
 
- Account access issues: verify identity before recommending changes.
- Billing questions: summarize the visible invoice or usage state; escalate if the customer disputes a charge.
- Security concerns: do not expose sensitive fields; escalate when credentials, payment tokens, or private data may be involved.
- Product defects: collect reproduction steps, affected workspace, expected behavior, and observed behavior.

These examples are intentionally generic. Real agent repos should use your own terms and procedures, but they should still avoid secrets and raw customer records.

How Knowledge Enters Context

Knowledge documents are loaded into the agent context at session start. The agent should not need a retrieval step to know core policy, glossary, or workflow guidance.

Keep the knowledge set compact. If it grows large enough to crowd the prompt, split the agent by session type or move structured, queryable facts into stores.

Knowledge vs Skills vs Stores

Source	Use For	Example
`amodal/knowledge/`	Stable facts and policy	"Refund status must be confirmed before promising action."
`amodal/skills/`	Reasoning workflows	"Triage the issue, inspect data, separate facts from assumptions."
`amodal/stores/`	Structured records that can grow over time	Ticket summaries, findings, customer-safe notes
`amodal/connections/`	External system access	Ticket API, account API, product catalog API

Updating Knowledge

Knowledge is source. Review it like code:

Edit Markdown in the repo or Amodal.
Review the diff.
Commit and deploy.
Run smoke tests and evals.
Promote the deploy when behavior looks correct.

If the agent discovers a recurring pattern during sessions, record it first in a store or an operator note. Promote it into amodal/knowledge/ only after a human has reviewed it.