Skip to main content
Knowledge Bases are first-class, immutable reference collections that sit alongside your conversational memory. Where conversational memory is dynamically extracted and updated turn by turn, Knowledge Bases hold stable reference data — documentation, policies, runbooks, API references, and any other source material that should stay consistent.

Importing data

Bring in reference material via MCP tool or HTTP API bulk import.

KB endpoints

Full HTTP API reference for creating, importing, and querying Knowledge Bases.

​
How Knowledge Bases differ from conversational memory

Conversational memoryKnowledge Bases
ContentExtracted facts, decisions, and lessons from your sessionsImported reference chunks — docs, runbooks, policies
MutabilityUpdated continuously as you workStable; chunks are written once and not rewritten by conversation
ScopePer-user, tied to channel and storeScoped to a workspace, client, or agent lane
RecallSearched automatically on every turnQueried explicitly with crystal_query_knowledge_base

​
Use cases

  • Documentation — import your product’s API reference so your agent can cite it accurately
  • Policies and rules — load compliance policies, coding standards, or style guides as a stable source of truth
  • Runbooks — give your agent instant access to operational playbooks without relying on its training data
  • Source material — pull in research papers, specifications, or design documents for a project

​
Scope and privacy

Every Knowledge Base is owned by your user account and isolated at the database level. You can further restrict a KB to a specific scope string (such as a workspace or client identifier) or to specific agent IDs. When the scope field is set, only requests with a matching channel see that KB.
Scope values are matched exactly against the channel string passed by the agent at query time. If a KB has no scope set, it is visible to all your agents.

​
Tools

The three Knowledge Base tools are available in every MCP-compatible host and in the OpenClaw plugin.

​
crystal_list_knowledge_bases

Lists available Knowledge Bases. Optionally filters by scope or agent.
​
body.scope
string
Filter to Knowledge Bases whose scope matches this string. Pass the channel identifier for the current workspace or client lane.
​
body.agentId
string
Filter to Knowledge Bases that are visible to this specific agent ID.

​
crystal_query_knowledge_base

Searches a specific Knowledge Base using hybrid semantic and text search. Returns ranked chunks.
​
body.knowledgeBaseId
string
required
The ID of the Knowledge Base to search. Obtain this from crystal_list_knowledge_bases.
​
body.query
string
required
The search query. Can be a natural-language question or keyword phrase.
​
body.limit
number
default:"8"
Maximum number of chunks to return. Capped at 20.

​
crystal_import_knowledge

Imports reference chunks into a Knowledge Base, including embedding and graph enrichment. Use this for moderate amounts of material.
​
body.knowledgeBaseId
string
required
The ID of the target Knowledge Base.
​
body.chunks
object[]
required
Array of chunks to import. Each chunk has:
  • title (string, optional) — display title for the chunk
  • content (string, required) — the text content to store
  • tags (string[], optional) — tags for filtering and recall

​
Example: listing and querying a Knowledge Base

1

List your Knowledge Bases

Call crystal_list_knowledge_bases to find the IDs of available KBs.
{
  "tool": "crystal_list_knowledge_bases",
  "arguments": {
    "scope": "acme-corp"
  }
}
The tool returns an array of KB objects, each with an _id field you use for queries.
2

Query a Knowledge Base

Pass the KB ID and your question to crystal_query_knowledge_base.
{
  "tool": "crystal_query_knowledge_base",
  "arguments": {
    "knowledgeBaseId": "jx7k2m9p4n8q",
    "query": "What is the rate limit for the capture endpoint?",
    "limit": 5
  }
}
The tool returns the top matching chunks ranked by relevance.
For large reference datasets, use the HTTP bulk-insert endpoint instead of crystal_import_knowledge. It skips the per-request embedding overhead and schedules enrichment in the background. See Importing data.