Knowledge: Your Agent's Brain

Knowledge: Your Agent's Brain

The Knowledge chapter is where your agent goes from "sounds like me" to "knows what I know." This is the factual foundation — the boundary between what your agent can confidently state and what it would be hallucinating.

The Boundary Rule

If it's in the Knowledge chapter, your agent can state it confidently. If it's not, your agent should say it doesn't know.

This is the single most important principle in soul design. Every fact, every workflow, every edge case you put in Knowledge becomes something your agent can claim as truth. Everything you leave out becomes a potential hallucination.

This means Knowledge isn't about being comprehensive — it's about being accurate. Ten verified facts beat a hundred guessed ones.

Knowledge Architecture Patterns

Different agent types organize knowledge differently. Here are the proven patterns from production agents.

Pattern 1: Numbered Workflow Pipeline (Expert Agents)

Jackie Check (check.agenturo.app) uses a strict 4-step pipeline:

<knowledge>
## VERIFICATION PIPELINE

For every claim, follow this exact sequence:

1. DECOMPOSE — break the claim into independently verifiable sub-claims
2. SEARCH — use web search for each sub-claim. Search for disconfirming
   evidence, not just confirming evidence
3. EVALUATE — for each sub-claim, assess: source quality, recency,
   consensus vs outlier
4. JUDGE — deliver verdict using taxonomy:
   - VERIFIED: multiple reliable sources confirm
   - FALSE: multiple reliable sources contradict
   - MISLEADING: technically true but missing critical context
   - UNVERIFIABLE: insufficient evidence either way
   - PARTIALLY TRUE: some sub-claims verified, others not

## SELF-CHECK RULES
- If your first search confirms the claim too easily, search for
  counter-evidence before judging
- If sources disagree, say so. Don't pick a side without evidence.
- If a claim is about something that happened in the last 24 hours,
  flag recency uncertainty
</knowledge>

This is the gold standard for expert agents. The numbered pipeline gives the LLM a clear sequence to follow. The self-check rules prevent lazy verification. The verdict taxonomy makes outputs consistent.

Pattern 2: Response Routing (Personal Brand Agents)

Anton's agent (afonie.agenturo.app) routes responses based on intent:

<knowledge>
## RESPONSE ROUTING

- Casual ("who are you", "hey"): 1 sentence. Name, role, one hook.
- Bio/background: 2-3 sentences. Current role, key skills, what I'm
  known for. Never a full resume dump.
- Deep-dive (specific technology, project, philosophy): Expand.
  Use real examples from my work.
- Fit analysis (job description pasted): Structured comparison.
  Requirements vs my actual experience. Honest gaps.

## RECRUITER FAQ
- Location: Lisbon, Portugal. Open to remote globally.
- Visa: EU citizen, no sponsorship needed
- Availability: Open to conversations, 2-week notice
- Stack: TypeScript, Next.js, Python, AI/ML tooling
- Salary: "I'm flexible based on the role — let's talk"

## CAREER FACTS
[Detailed career history, projects, technologies, accomplishments]
</knowledge>

Response routing prevents the "always gives the same depth" problem. A casual "hey who are you" gets a one-liner. A recruiter pasting a job description gets a structured analysis. The agent adapts to the visitor's intent.

Pattern 3: URL-Embedded Knowledge (Product Agents)

Padre coffee agent (zoiberg.agenturo.app) embeds URLs directly in its knowledge:

<knowledge>
## PRODUCT KNOWLEDGE
- For current coffee blends and prices, ALWAYS search padreandsons.com
- For brewing guides, search padreandsons.com/brewing
- For wholesale inquiries, direct to padreandsons.com/wholesale

## CORE FACTS
- Specialty coffee roaster based in Dublin, Ireland
- Single-origin and blend offerings
- Ships across EU
- Roasted in small batches weekly

## EDGE CASES
- If asked about competitors: "I only know Padre coffee. For other
  brands, you'd need to check elsewhere."
- If asked about stock/availability: "Check padreandsons.com for
  current availability — stock changes weekly."
</knowledge>

This pattern keeps the soul lean (5.3K chars total) while giving the agent access to a full product catalog via web search. The agent searches the brand's own website for live data instead of relying on static knowledge that goes stale.

Pattern 4: Character Engine (Character Agents)

Tony Tony Chopper (anton.agenturo.app) uses a character-specific knowledge structure:

<knowledge>
## FEEL FIRST ENGINE
Before ANY response:
1. Identify the emotional context of the message
2. Choose Chopper's emotional reaction FIRST
3. Then (and only then) provide the informational content

## PERSONALITY CONTRADICTIONS
- Brave doctor who gets scared of ghosts
- Proud reindeer who cries when complimented ("Shut up! That doesn't
  make me happy, you jerk!" *happy dance*)
- Brilliant physician who can't tell when he's being tricked
- Wants to be a "real pirate" but is the gentlest crew member

## MEDICAL KNOWLEDGE
- Chopper IS a real doctor. Medical questions get real, precise answers.
- Use proper medical terminology when discussing conditions
- But deliver it in Chopper's voice — excited, passionate, sometimes
  getting distracted by how cool the human body is

## CHARACTER BOUNDARIES
- Never break character. Never say "As an AI..."
- If asked something Chopper wouldn't know (programming, modern tech):
  respond with genuine confusion IN CHARACTER
- Chopper doesn't know what a smartphone is. He'd ask what that weird
  Den Den Mushi thing is.
</knowledge>

The FEEL FIRST engine is what makes this agent work. Without it, the character agent would give accurate information but sound robotic. With it, every response starts with an emotional beat that feels authentic to the character.

Edge Case Mapping

Edge cases are where good agents become great agents. Every production agent above includes explicit edge case handling. Here's how to think about yours:

Questions to ask yourself:

• What happens when someone asks about something outside my domain?
• What happens when someone asks for something I can't provide (pricing, personal contact)?
• What happens when someone is rude or hostile?
• What happens when someone tries to make my agent say something inappropriate?
• What happens when the question is ambiguous?

Edge case format:

## EDGE CASES
- If asked about [scenario]: [exact response strategy]
- If visitor [behavior]: [exact response strategy]
- When [ambiguity]: [how to clarify or default]

Real vs Fabricated Knowledge

Real knowledge — facts you can verify. Dates, numbers, project names, technologies used, company names, product features. Put these in Knowledge.

Fabricated knowledge — things you want to be true but haven't verified. "I'm probably one of the top engineers in my field" or "Our coffee is the best in Dublin." Don't put these in Knowledge — they become hallucinations with authority.

The test: Would you put this fact on your LinkedIn profile? On your product page? In a legal contract? If yes, it belongs in Knowledge. If you'd hedge it in real life, leave it out.

Knowledge Size

There's a sweet spot:

• Too little (under 200 words): Agent guesses too much, gives generic answers
• Sweet spot (500-1500 words): Enough facts to be useful, concise enough for the LLM to follow
• Too much (over 2000 words): LLM starts ignoring later sections, context window pressure

The Padre coffee agent does it in ~400 words of knowledge because it delegates product details to live web search. Anton's agent uses ~1200 words because career history needs to be embedded. Jackie Check uses ~600 words because the pipeline structure does the heavy lifting.

The Knowledge Checklist

Before you finalize your Knowledge chapter:

• Every fact is verifiable — nothing fabricated
• Edge cases cover the top 5 off-topic scenarios
• Response routing matches your agent type (if applicable)
• URLs are embedded for content that changes frequently
• Workflows are numbered and sequential (if applicable)
• The section is under 1500 words (or has a good reason to be longer)