Knowledge Base

⚡ 3 min read

The Knowledge Base holds durable facts the agent must not invent — product names, URLs, token names, brand decisions, approved claims, and API contracts. Every Persona ships with one. In the desktop app it appears as its own Knowledge Base section next to Instruction, Rules, and Skills.

A Knowledge document is not a policy and not a workflow. Write the fact itself, then give it a description that answers when the agent should open it.

New Personas include a starter document, What belongs in Knowledge Base. Read it once, then add your own entries. Do not put Must/Never policy here — that belongs in Rules. Do not put a step-by-step procedure here — that belongs in Skills.

Compared with the other kinds

Kind	Job
Instruction	Who the agent is and how it works on every request
Rule	Standing Must / Never policy for a situation
Skill	A repeatable workflow with steps and a deliverable
Knowledge Base	Facts the agent must look up instead of guessing

Add knowledge in the desktop app

Open a Persona.
In the file list, find Knowledge Base and choose Add Knowledge.
Give it a Name and a Description. The description should answer “When should this knowledge be referenced?”
Write the facts in Markdown, or drop a Markdown / text file (under 8 MB).

You can also ask Ask Transcodes in the desktop app to add or edit a knowledge document. File import still uses the Add Knowledge dialog.

Shape

Each entry is one Markdown file. File names are lowercase kebab-case — billing-api.md, design-tokens.md. Do not use spaces, underscores, or camelCase.


Frontmatter	Non-empty `name` (title) and non-empty `description`
Body	The fact as the answer itself — not a reminder to look it up later


---
name: Design tokens
description: Read when choosing colors, type, or spacing for this product
---
 
# Knowledge
- Brand purple is `--color-brand`, not a raw hex in UI code
- Page titles use the product name **Transcodes**, never Transcode
- Public download URLs live on the GitHub `latest` release, with no version in the path

The agent matches the current task against those descriptions. If one matches, it reads that file before answering. If none match, it says the fact is not in the Knowledge Base, then either answers from labeled general knowledge or asks you — it must not invent a project-specific fact, and it must not fail the task only because a reference is missing.

What the agent sees

Internally, Knowledge Base is a reserved Skill named knowledge-base. Its SKILL.md is an index generated from every reference file. The desktop app owns that index — do not rewrite it, and do not add scripts, assets, or extra folders inside Knowledge Base.

On apply, host apps receive the same bundle as the rest of the Persona. In the Instruction # Output line, list the Knowledge documents that were actually used, or none.

Next: Apply · Versioning