Knowledge Base: Living Documents

A bank's knowledge base is a set of knowledge pages: living documents the bank writes about itself, organized in folders like a wiki. Each page answers one question, such as "What are our refund and cancellation policies?" or "How is the API deployed?", and rewrites itself as the bank learns more.

You don't write a page's text. You give it a source query, the question that rebuilds it, and Hindsight synthesizes the answer from the bank's memories. Because a page is defined by its question rather than its wording, it doesn't go out of date the way a hand-written document does.

How pages stay current

A knowledge page is a mental model underneath, with defaults chosen for documents:

• Built from observations. A page reads the bank's consolidated observations, which are deduplicated and evidence-backed, rather than raw conversation. It reads as a settled document, not a transcript summary.
• Refreshed after consolidation. Whenever consolidation produces new knowledge in a page's scope, the page rewrites itself. Activity elsewhere in the bank doesn't trigger it.
• Edited, not regenerated. Each refresh edits the existing document with what's new, so its structure and wording carry over between refreshes. Only the first build generates it from scratch.
• Never self-citing. A page never reads other pages, so pages can't cite each other into a feedback loop where one wrong claim spreads across the knowledge base.
• A larger content budget than a plain mental model (4,096 tokens by default), because it's a document rather than an answer.

You can change any of these per page. For example, refresh a page on a schedule instead of after consolidation, or widen what it reads. Every mental model trigger setting applies. To change the defaults for new pages in a bank, use the bank's Knowledge Page Default Trigger setting; it applies to pages created from then on.

Tags scope a page

A page's tags are not labels. They are the filter for which memories the page is built from. By default a tagged page reads only memories that carry every one of its tags, and untagged memories are excluded. That makes per-user or per-topic pages easy: tag the memories, then give the page the same tags. A page with no tags reads the whole bank.

A type: tag (for example type:runbook) also sets the page's type, shown with the page and in its exported frontmatter.

Using the knowledge base in the console

Open a bank and select Knowledge base in the bank sidebar, alongside memories and mental models.

• New folder and New page create nodes anywhere in the tree. A page needs a name (unique within its folder) and a source query; tags are optional.
• While a new page is built, it shows Generating.... When it's ready you see the page, plus How this page is derived and Backed by N memories, so you can see what it drew on.
• Each page shows In sync or Stale: whether new memories have landed in its scope since it last read them. Pages that refresh themselves clear their own badge; for the rest, a Stale badge tells you a refresh is worth running.
• Search finds pages across the whole knowledge base, and the tag filter narrows the tree.
• Edit a page's name, source query or tags at any time. Changing the source query rebuilds the page.
• Deleting a folder deletes everything in it, after a confirmation naming what will go.

Members with read-only access can browse and read the knowledge base but not change it.

Using the knowledge base from the API

All endpoints are relative to a bank: /v1/default/banks/{bank_id}/knowledge-base.

Method	Path	Description
GET	/knowledge-base/tree	The folder and page tree, with each page's staleness
POST	/knowledge-base/folders	Create a folder
POST	/knowledge-base/pages	Create a page; the first build runs in the background
GET	/knowledge-base/pages/{page_id}	Read a page as markdown
GET	/knowledge-base/search	Search pages by keyword and meaning
PATCH	/knowledge-base/nodes/{node_id}	Rename, move or reconfigure a folder or page
DELETE	/knowledge-base/nodes/{node_id}	Delete a folder or page (and a folder's contents)
GET	/knowledge-base/export	Export the whole knowledge base as markdown files

Create a page

curl -X POST https://api.hindsight.vectorize.io/v1/default/banks/my-bank/knowledge-base/pages \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund policy",
    "source_query": "What are our refund and cancellation policies?",
    "tags": ["policies"]
  }'

The response returns the new page_id, its backing mental_model_id, and an operation_id for the first build. Poll the operation to know when the content is ready. Pass parent_id to create the page inside a folder; omit it to create it at the root.

Read and search pages

# Read a page: `body` is the markdown; `markdown` adds YAML frontmatter
curl https://api.hindsight.vectorize.io/v1/default/banks/my-bank/knowledge-base/pages/PAGE_ID \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

# Search pages
curl "https://api.hindsight.vectorize.io/v1/default/banks/my-bank/knowledge-base/search?q=refunds" \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY"

Search returns whole pages, ranked, with snippets. It combines keyword and semantic matching, so it's fast enough to be the first thing an agent checks. Use page search to find a document; use recall to find specific memories.

Knowledge pages and reflect

Knowledge pages are mental models, so reflect can use them like any other mental model: it checks mental models first, then observations, then raw facts. A knowledge base that covers your most important questions gives reflect fast, consistent answers to them.

Pricing. A page is a mental model underneath, so it bills on the same meters, with no separate charge:

• Creating a page, rebuilding it, or a refresh triggered by new knowledge is a Refresh Model call.
• Reading a page is a Retrieve Model read.

Pages refresh themselves after consolidation by default, so a busy bank with many pages makes more refresh calls. A page only refreshes when new knowledge lands in its own scope. To cap refreshes, give a page a schedule instead. See Billing for rates.