Skip to content

Give a model your knowledge base#

A deployment's model can work with a knowledge base of its workspace through two built-in tools, run by the gateway for the model:

Tool What the model does What it gets
search_knowledge Searches the base when a question needs it At most 8 passages, numbered, each with its document, headings and page or line — about 6 000 characters in all, so they fit its context — to answer from and cite as [1], [2]
save_to_knowledge Keeps a note in the base when asked to save, keep or remember something Ask before saving (the default): a draft you save or discard in the chat. Save on its own: the note is saved at once, and listed on the base with an undo

The search is the base's own: hybrid, or by keywords for a base without an embedding model (Choose how a base searches).

Before you begin#

  • A chat deployment that takes tools (Eos) and a knowledge base, in the same workspace. The base may hold documents, notes you write (Write notes) or both.
  • To change the deployment: deployments:update (the workspace roles editor, admin).
  • To undo a model's save: knowledge-bases:write-content.

Who searches through the deployment

A deployment's tools are part of the deployment: anyone who may call the deployment — people of the workspace, API keys, workspaces it is shared with — can have its model search the base through it, even without permission to search the base themselves. Give a base to a deployment only if its callers may read it.

Give it the tools#

Open Eos ▸ Deployments, the deployment, and its Tools tab (or the Knowledge section of the deployment form when you create one). Under Knowledge, add the base and tick:

  • Search — search_knowledge;
  • Save notes — save_to_knowledge, then choose Ask before saving (the default) or Save on its own. The console warns you before it saves the second.
$ astra eos tools chat knowledge handbook --search --save
$ astra eos tools chat knowledge journal --save-on-its-own
$ astra eos tools chat knowledge handbook          # none: the base's tools removed
$ astra eos tools chat
TOOL                    FUNCTION                      APPROVAL
search_knowledge        (search_knowledge: handbook)  -
save_to_knowledge       (save_to_knowledge: handbook) -
save_to_journal         (save_to_knowledge: journal, saves on its own) -

In spec.tools of the deployment (PUT /v1/eos/deployments/chat, the spec whole):

"tools": [
  {"builtin": "search_knowledge", "knowledge_base": "handbook"},
  {"builtin": "save_to_knowledge", "knowledge_base": "handbook"},
  {"builtin": "save_to_knowledge", "knowledge_base": "journal", "confirm": false}
]

confirm is true by default (ask before saving) and is only written when false. The first tool of each kind is called search_knowledge and save_to_knowledge; the next ones get the base's name (search_journal, save_to_journal), or the name you give. description changes what the model is told, as for any tool.

The base must be of the deployment's own workspace. The tools are answered by the hosted gateway, the API and the Playground. A machine's own gateway (an edge machine) answers them as unavailable — the base is reached through Astralyx, which a machine's gateway does not call on a person's behalf — and the model is told so.

Search: answers with citations#

Ask the deployment something the base knows: "How many vacation days do I have?". The model calls search_knowledge with a query and gets:

{
  "knowledge_base": "handbook",
  "mode": "hybrid",
  "results": [
    {"ref": 1, "document": "docs:handbook/leave.md", "title": "Leave policy", "where": "Leave policy › Vacation › line 7", "text": "Each person has 25 vacation days a year…"}
  ],
  "note": "Answer from these passages and cite each one you use as [ref] with its document."
}

and answers citing [1] and handbook/leave.md. Nothing found is said as such, and the model is told not to make an answer up. A base that is not serving (its machine off) makes the call fail with why; the model answers without it and says so. Each call has its signed receipt, as every tool call (Give a model tools).

Save: ask first, or on its own#

Ask before saving works as Let a model save when asked: the chat shows a card with the title and text, and nothing is kept until you choose Save.

Save on its own saves the note at once, in the base's saved/ folder, with front matter that says where it came from:

---
title: "Offsite"
date: "2026-10-12T10:05:00Z"
source: "model"
conversation: "Planning the year"
model: "chat"
---

# Offsite

The offsite is in Porto in March.

The chat shows Saved to journal with the title, a link to the note and Undo. Every save is also listed on the base: open it in Metis ▸ Knowledge bases and find Saved by models — the note, the deployment, the conversation, when, and whether it is still as saved — with Undo. The conversation is named by the title your application sends in the chat request's metadata.conversation_title, else by the conversation's id.

Limits and safeguards:

  • Never on by default. A deployment saves on its own only for a base where you set it.
  • At most 30 saves an hour per base from models; past that the model is told to ask the person (SAVE_LIMIT).
  • Undo removes the note. If someone changed it since, undo asks first (the API answers 409 NOTE_CHANGED; ?force=true removes it with the changes).
curl -s -H "Authorization: Bearer $ASTRALYX_TOKEN" "$ASTRALYX_API/metis/knowledge-bases/journal/model-saves"
curl -s -X POST -H "Authorization: Bearer $ASTRALYX_TOKEN" "$ASTRALYX_API/metis/knowledge-bases/journal/model-saves/s_4f2a9c1b7d3e5a60/undo"

Why saving on its own is a choice

What a base holds is what later answers rely on. A model saving on its own may keep a misunderstanding, or words planted in a document it read, and the next answer would cite them. Keep Save on its own for bases that are a log you review — a journal, a scratchpad — and Ask before saving for bases people trust.