#A knowledge base for your AI agent

A knowledge base is what an AI agent answers from when a question needs facts: return policies, delivery zones, how a service works. In Vatio it is a set of Markdown entries you write, from the CLI or the inbox, that the agent searches with the built-in knowledge_lookup tool; Vatio does not read websites. You plug it into the agent in your vatio.yml, try every change on preview, and publish it together with the agent, which answers from it on WhatsApp, Instagram and the web.

#What it is, and why it matters

Without a knowledge base, an agent asked about your return policy can only say it does not know, or guess. Pasting every policy into the instructions does not scale either: the prompt grows, rules get buried, and only a developer can fix a stale fact.

A knowledge base keeps long facts out of the prompt. The agent searches it when a question calls for it and reads only the sections that match, and supervisors can correct an entry the moment a fact changes.

It is one of three places an answer can come from, and choosing the right one avoids a whole class of wrong replies:

The test: if the answer could be wrong by this afternoon, it comes from a tool that calls your API. Knowledge is not a cache of your catalog.

#How it works

1. A base holds entries. Create one base per set of entries you want kept apart, and list on the agent the bases it reads.
2. An entry is Markdown you write. Its title comes from its own # heading, and each ## heading starts a section that is searched on its own.
3. The agent searches with knowledge_lookup, a built-in tool you enable in agent.tools. When nothing matches, the tool says so, and your instructions decide what the agent does next.
4. Indexing is asynchronous. An entry can be searched once its sections are embedded; vatio kb show says which entries are ready.
5. Live answers from published entries. Preview keeps its own changes on top of live and reads everything else from it.

#Step by step

#1. Create the base and write entries

vatio kb create shop
vatio kb write shop shipping shipping.md
vatio kb write shop returns returns.md
vatio kb write shop brewing brewing.md
vatio kb show shop

vatio kb write BASE ENTRY FILE creates the entry, or replaces what is there. With no file it reads stdin, so editing in place is one line: vatio kb cat shop returns | edit | vatio kb write shop returns. vatio kb cat prints exactly what Vatio holds.

#2. Plug it into the agent

agent:
  instructions: |
    Shipping, returns and brewing: search knowledge_lookup first. If the
    results do not answer the question, say so and offer to pass it to
    the team.
  tools: [knowledge_lookup]
  knowledge: [shop]

A referenced base must already exist: a misspelled name fails the push instead of quietly becoming an empty base. Removing a reference later does not delete the base’s content.

#3. Push and test retrieval

vatio push
vatio chat "How long does shipping take to Denver?"
vatio chat show

chat show lists the knowledge lookup the agent made and what came back. If the answer is missing, check vatio kb show shop: an entry still indexing cannot be found yet.

#Write entries that answer on their own

The agent receives the sections that match a question, not the whole entry in order. A section that leans on another one answers badly. This entry reads fine top to bottom and fails as search results:

# Shipping

We ship nationwide. Details below.

## More info
Same as above, but longer for Alaska and Hawaii.
Free over the amount we mentioned.

This one answers from any section:

# Shipping

## Delivery times
Orders ship from Portland. Delivery takes 2–4 business days to the
contiguous US and 5–8 business days to Alaska and Hawaii.

## Shipping cost
Free on orders over $60. Below that, $6.50 to the contiguous US and
$14 to Alaska and Hawaii.

## Order cut-off
Orders paid before 1 p.m. Pacific on a business day leave the same day.

• One entry per topic, and every ## heading a question a customer actually asks, with the whole answer under it.
• No “see above”, “as mentioned” or “details below”.
• Numbers, conditions and exceptions, written out.
• The customer’s words. “Delivery times”, not “Fulfillment SLA”.
• Never a credential. Keys and passwords do not belong in knowledge.

#Supervisors edit in the inbox

Supervisors, invited from Team in the inbox, open the knowledge in the inbox, edit entries and fill one from a file. Saving there takes the change live right away, with no deploy. Every change, from the inbox or the CLI, becomes a numbered version of its entry, recording who made it and from where.

That is what keeps the base current: the person who learns that pickup hours changed can fix the entry in a minute. When a wrong reply has a deeper cause, they flag it instead, and the fix goes through preview and evals; see Improve your agent.

#Try changes on preview

Once the agent is live, change knowledge the way you change the prompt. kb write, cat, rm-entry, show and status work in preview, so only preview answers from what you wrote:

vatio kb write shop shipping shipping.md
vatio chat "How much is shipping to Hawaii?"
vatio kb status shop        # what live does not have yet
vatio eval                  # with flags, publish wants preview tested first
vatio publish               # the agent and these entries, together

vatio kb publish shop takes one base’s changes live on their own, without the agent, and --env live reads and writes live directly.

#Conflicts

If live changes an entry after preview changed it too, because a supervisor fixed it in the inbox, publishing would overwrite a change nobody working on preview has read. So it is refused, and vatio kb status names the entry. Two ways out:

• From the terminal: read the entry from live, write your change on top, and the conflict clears.

  vatio kb cat shop shipping --env live > shipping.md
  $EDITOR shipping.md
  vatio kb write shop shipping shipping.md

• In the inbox: the knowledge changes page under Test has the diff of every entry preview changed (vatio env prints the link). For a conflict it shows both sides and offers three options: keep preview’s version on top of live, take live’s, or combine both by hand.

#History and going back

vatio kb history shop                                    # every version that reached live
vatio kb cat shop shipping --version 3 > shipping.md
vatio kb write shop shipping shipping.md --env live      # version 3 becomes the newest

Going back is writing an old version again. In the inbox it is one button, Restore this version, on the entry’s history.

vatio rollback goes further. A live deployment is a snapshot of the configuration and the version of every entry it answered from, so a rollback restores the previous live configuration and knowledge together. An inbox edit leaves a snapshot too, which means the first rollback after a supervisor’s fix undoes that fix. Read vatio kb history before rolling back.

#A worked example

Lupine Tea sells loose-leaf tea online and answers on WhatsApp and its website:

workspace: lupine-tea
agent:
  name: Lupine Tea
  personality: Warm and brief. Plain words.
  instructions: |
    You help customers of Lupine Tea choose teas and answer questions
    about shipping, returns, brewing and storage.

    Shipping, returns, brewing and storage: search knowledge_lookup
    first. If it does not answer, say so and offer to pass the question
    to the team. Never quote a shipping cost or time that is not in the
    knowledge.

    Stock and prices: call check_stock. Never state a stock level or a
    price that check_stock did not return.
  tools: [check_stock, knowledge_lookup]
  knowledge: [shop]

The shop base holds four entries: shipping, returns, brewing and storage. Prices and stock are not in it, because they change every day; check_stock reads them from the store’s API.

In December the carrier announces new rates for January. A developer rewrites the cost section of shipping and tries it in a chat on preview. Meanwhile a supervisor fixes the order cut-off time in the same entry from the inbox, and live answers with that fix immediately. When the developer runs vatio kb status shop, shipping is listed as a conflict. They read it from live, apply the new rates on top of the supervisor’s fix, write it again and publish. Live gets the new rates and keeps the corrected cut-off.

#Pitfalls

• Live data in knowledge. Stock or prices that change hourly go stale the moment you write them. Use a tool.
• “See our website.” The agent cannot follow a link to read a page. Write the answer into an entry.
• A base the agent cannot reach. It needs both knowledge: [shop] and knowledge_lookup in agent.tools.
• Testing too early. Indexing is asynchronous; check vatio kb show before deciding retrieval is broken.
• No instruction for “not found”. Without “if it does not answer, say so”, a model is tempted to fill the gap.
• Rolling back blind. An inbox edit is a snapshot, so check the history first.

#What next

When a wrong reply has a deeper cause than a stale entry, see Improve your agent. Every command is in the knowledge docs.

Updated: October 11, 2026