How to Build a Knowledge Base Agents Actually Use

Source & credit

Distilled from Machina (@EXM7777) — the short version: x.com/i/status/2081092390660792604 (“I simply can’t comprehend why everyone isn’t building this yet…”).

Full blueprint (one-person AI business: two assets, five lanes, knowledge vault, memory levels, operating rules): x.com/i/status/2081017272924361162 / X Article. (Piece is sponsored by Viktor; the architecture ideas transfer whether you use that product or a custom agent stack.)

This page is a practical rewrite for our stack — especially Mike’s Headless Empire OS, Company Brain, and the agent memory / OS patterns across this site.

The one-line thesis

Your offers, ad angles, content pipeline, writing voice, and every decision you already made — in one place any model can skim in seconds. The workers are interchangeable. The vault is the business.

Most people keep “context” as a giant system prompt or a chat that drifts. That doesn’t compound. A real knowledge base is a small set of durable markdown notes the whole operation reads from — and that you update when reality changes, not when a model invents a new personality.

Why this matters (two assets, not ten tools)

Machina’s framing: a one-person business scales on two assets wired together:

1. Software that already wins at its job — Stripe for billing, CRM for pipeline, Meta for ads, booking tools for scheduling. That layer is solved; your job is operating it.
2. Business knowledge — who the client is, what you charge, what a good lead looks like, which requests escalate, how delivery actually works.

The missing middle used to be a hire: someone who knows your business and runs the software daily. An AI worker is that connection — but only if the knowledge is loadable, sliced, and corrected once.

Same idea at company scale as Eric Siu’s “single brain” and Loro’s GitHub + Claude company OS: stop scattering tribal knowledge across heads and chats; put it where agents and humans both read.

The vault: five notes deep

Strongest version is embarrassingly simple: a folder of markdown files (Obsidian is popular because it’s text on disk, linked, human-readable and agent-readable). Structure by what the business knows, one note per fact cluster:

Rulings: fix once, not forever

Pattern from the article: every time you correct an agent, add one line to rulings. Every worker reads rulings before starting. That is how a correction becomes permanent instead of a weekly re-teach.

In Headless Empire OS this maps cleanly to:

• 02-tasks-projects/decision-log.md — decisions with dates and owners
• 05-knowledge-base/ — company, people, products, market research
• 06-systems-sops/ — durable how-we-work
• Agent identity files under 04-ai-agents/ — stable “who I am / never do”

If you only steal one habit: maintain a single rulings (or decision-log) surface that every brief loads. Skip that and you will edit forever.

Slice the vault: one agent, one job

The fragile setup is one giant assistant with one enormous prompt expected to do everything. Builds that hold up do the opposite: one agent, one job.

• Research agent only researches
• Writer only writes — and loads the voice note, not the whole brain
• Outreach worker loads client (+ offer slice), not your content calendar
• Reviewer is never the author (self-grading agents approve their own work)

Each specialist is assembled from the same four parts:

Keep identity separate from memory, always. Identity stays stable so a passing fact never rewrites who the agent is. Memory is where churn belongs. That separation is the difference between an agent that stays itself for months and one that drifts the first time it saves a bad note — related to why Dreaming / memory consolidation and bounded agent memory matter.

Memory: three levels (stop early)

Memory is where new builders overspend. Move up only when the problem forces you:

Keep the always-loaded core small. Cap working memory files (hundreds of lines, not novels); load the rest on demand. Memory that grows without a ceiling crowds out the actual work.

The hard half of memory is forgetting: review dates, sweep what didn’t earn its place, write the new fact and mark the old one as replaced so bad beliefs are traceable. One production store in the article’s world logged ~10k entries in a month and ~200 worth keeping.

For operator-side “clear the brain so the vault can hold it,” see Clear Mental Fog and the live Mental Fog Reset in Headless Empire OS. For agent self-improvement over transcripts, see Dreaming. For RAM/process chaos when you run too many agents at once, see agent memory problem hacks (different kind of “memory,” same discipline: bound and reap).

Map: Machina vault ↔ Headless Empire OS

You don’t need a second system. Map the five notes onto the OS you already run (or clone):

Command center files (TODAY.md, WEEK.md, inbox.md) are execution, not the vault. Don’t dump permanent business facts only into TODAY — they’ll rot by Friday. Capture fast → route durable knowledge into 05 / 06 / rulings (same capture discipline as the OS daily workflow).

Public framework: github.com/HeadlessEmpire/headless-empire-os · HeadlessEmpire.com

Compare: vault vs Company Brain vs AI OS vs lanes

Practical stack for this site’s world: vault (markdown) → Headless Empire OS command center → specialist agents / lanes → closed loops ( Loops, Dreaming ) → optional collab surface ( Buzz, Open Tag, Slack).

Operating rules (management beats magic prompts)

Lanes and vaults fail when you treat agents like genius interns with no blast radius. Steal these rules:

1. The brief carries the context. Name the deliverable and what “done” means. A lazy brief produces confident work in the wrong direction.
2. Permissions by blast radius. Routine internal work can run free; anything that sends or spends waits for your yes. The day the strictness annoys you is the day it saves you.
3. You review on a schedule. Two windows a day to clear drafts/approvals — lanes produce faster than you read.
4. Cap the bill on day one. Quote-before-execute in every context message. Untended agents teach you pricing the hard way.
5. Next lane only when the last runs without you. Scaling is one question: did this morning’s lane produce without a prompt from me?

Your job shifts to the approval queue: drafts in, decisions out, and every decision writes a line in rulings so tomorrow’s queue is shorter. Same spirit as Boris’s AI-first roles and agentic setup checklists: verification and ownership, not more chat.

Build sheet (run once per lane or agent)

□ One agent or one channel per lane — never one assistant for everything
□ Knowledge base = business: offer, client, voice, playbooks, rulings
□ Identity file separate from memory file
□ Hand each worker only its slice of the vault
□ Every correction → one line in rulings (agents read rulings first)
□ Schedules before ad-hoc prompts (e.g. 8:00 standup is one sentence in a brief)
□ Permissions by blast radius; send/spend behind your yes
□ Budget cap + quote-before-execute from day one
□ Next lane only when the last one runs without you
□ Stay on memory Level 1 until Level 1 is honestly too small

Fast path (product workspace like Viktor-style “AI employee in Slack”): one channel per lane + one pinned context message = the vault in miniature. Custom path: same structure, files on your disk, full control. Ideas transfer either way.

Starter templates (copy into your vault)

offer.md

# Offer
## What we sell
## Pricing / packages
## Included
## Explicitly out of scope
## Proof / case snippets
## How we say no

client.md

# Client / ICP
## Who buys (and who doesn't)
## Verticals
## Qualified lead criteria
## Disqualifiers
## Common pains we solve
## Example accounts (anonymized OK)

voice.md

# Voice
## Tone (3 bullets)
## Words we never use
## Structure preferences (hooks, length, CTAs)
## 3 gold examples (link or paste)
## Anti-examples (what we sound like when we fail)

playbooks.md

# Playbooks
## Project stages + exit criteria
## Checklists per stage
## Handoffs (human / agent)
## Escalation rules
## Definition of done

rulings.md

# Rulings (append-only, agents read first)
# Format: YYYY-MM-DD — Rule — Why (optional)
- 2026-07-25 — Never send outreach without human approve — blast radius
- 2026-07-25 — Do not invent pricing; quote only from offer.md

Related on this site

References

• Machina (@EXM7777) — short thread on knowledge vaults
• Machina (@EXM7777) — full AI one-person business blueprint / X Article
• Headless Empire OS — public repo
• On this site: Headless Empire OS, Company Brain, AI OS, Dreaming, Loops