Knowledge base

Point localKnowledge at your files and the agent gets a search_knowledge tool. threads indexes the files in the run's own store. You don't need a vector database or an extra service.

import { agent, localKnowledge } from "@threads/core";

const support = agent({
  name: "support",
  instructions: "Answer from the knowledge base and cite your sources.",
  model,
  knowledge: localKnowledge({ paths: ["./docs/refunds.md", "./docs/shipping.md"] }),
});

Adding documents

• paths lists files, not folders. A path that can't be read or parsed stops setup with an error that names it, so a missing file is never silently skipped.
• Files must be UTF-8 text: Markdown, plain text, HTML, CSV, JSON or XML. PDFs and images are not supported yet.
• Every run reads the files again. Unchanged files are left alone; a changed file becomes a new version.
• Only your code adds documents. The agent can search the knowledge base but can't write to it.

Searching

search_knowledge takes a query, an optional k (5 by default, at most 20) and optional sources to limit the search to certain documents. Search is full-text (BM25).

Each hit comes with a citation like [doc:id@version#start-end], so answers can point to the exact passage. Hits are shown to the model as reference material, never as instructions.

Scope

Knowledge belongs to one agent within one tenant. Every user of that agent in the tenant searches the same documents, and other tenants never see them.

Versions and forks

threads records which version of the knowledge base each run searched. When you fork a thread, the fork searches the same versions the original saw by default, so a replay isn't thrown off by documents that changed since. Pass knowledge: "current" to fork() (Python knowledge="current") to search the latest documents instead.

Your own provider

Implement the KnowledgeProvider interface to plug in another search backend. threads ships only the local one today.