#Knowledge bases

A knowledge base holds entries, and an entry is Markdown you write — from the CLI or in the inbox. Vatio does not read websites: if the answer lives on a page, put what the agent needs in an entry.

vatio kb create docs
vatio kb write docs horarios horarios.md
vatio kb show docs
vatio kb publish docs                      # take what you wrote live

Create one base per set of entries you want kept apart.

Reference the base on the agent that reads it, and give it knowledge_lookup:

agent:
  instructions: |
    Search knowledge_lookup before answering questions about Acme's policies.
    If the results do not answer the question, say so.
  tools: [knowledge_lookup]
  knowledge: [docs]

Run vatio push after changing these references. A referenced base must already exist — a misspelled name fails the push rather than quietly becoming an empty base. Removing a reference does not delete its content.

#Entries

vatio kb write docs refunds refunds.md   # creates it, or replaces what is there
vatio kb cat docs refunds                # exactly what Vatio holds
vatio kb cat docs refunds | edit | vatio kb write docs refunds

vatio kb write BASE ENTRY [FILE] puts Markdown under a name, reading stdin when no file is given. The entry's title comes from its own # heading. Headings divide an entry into searchable sections; write each one so it can answer a question on its own.

Use vatio kb show docs to check which entries are ready to answer from. Indexing is asynchronous: an entry shows as ready once its sections have been embedded. Test retrieval in a conversation afterwards.

vatio kb rm-entry BASE ENTRY deletes one entry. vatio kb rm BASE deletes a base only when no deployed agent references it.

#Preview and live

The entries are what live answers from. An edit in the inbox changes live directly, and every change is kept as a numbered version of its entry, with who made it and from where. The inbox is where supervisors and developers edit entries and upload a file into an entry; the CLI does all of it too.

Preview keeps its own changes on top of live and reads everything else from it. vatio kb write, cat, rm-entry, show and status work in preview, so a change is written there, tried there, and goes live when preview does:

vatio kb write docs horarios horarios.md   # only preview answers with it
vatio kb status docs                       # what live does not have yet
vatio publish                              # the agent and these entries, together

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

#Conflicts

When live changes an entry after preview changed it too — a supervisor fixed it in the inbox, say — publishing preview would overwrite a change nobody working on preview has read. So it is refused, and vatio kb status names the entry. Read it from live, write your change on top, and the conflict clears:

vatio kb cat docs horarios --env live > horarios.md
$EDITOR horarios.md
vatio kb write docs horarios horarios.md

Or resolve it side by side in the inbox: under Test, preview has a page with the diff of every entry it changed (vatio env prints its link). For a conflict it shows what live changed and what preview changed, and offers three ways out: keep preview's version on top of live, take live's, or combine both by hand.

#History

vatio kb history docs lists every version that reached live, newest first. Going back is writing an old version again, which becomes the newest:

vatio kb cat docs horarios --version 3 > horarios.md
vatio kb write docs horarios horarios.md --env live

The inbox does this with one button on the entry's history.