Skip to main content
Query a knowledge base to search for relevant chunks by semantic similarity.

​
What this means in practice

When you have organized information into a knowledge base (via import or chunking), use crystal_query_knowledge_base to:
  • Retrieve relevant information by semantic meaning (not just keyword match)
  • Scope queries to a specific knowledge base
  • Filter by agent or channel if the knowledge base supports it
  • Limit results to reduce noise and context overhead
This matters most for mixed private/shared deployments:
  • private KBs can stay peer-scoped for coach/client isolation
  • shared training KBs can live at scope: "...:main" with peerScopePolicy: "permissive"
  • the backend now supports querying those shared-main KBs from peer-scoped coach sessions when the agent is allowed

​
Parameters

ParameterTypeRequiredDescription
knowledgeBaseIdstringConditionalThe ID of the knowledge base to query. Either this or knowledgeBaseName is required.
knowledgeBaseNamestringConditionalThe human-readable name of the knowledge base. Either this or knowledgeBaseId is required.
querystringYesThe search query. Automatically embedded and searched against KB chunks.
limitnumberNoMaximum results to return. Default: unspecified. Range: 1–20.
agentIdstringNoOptional agent identifier for scoped queries.
channelstringNoOptional channel identifier for scoped queries.

​
Returns

{
  "chunks": [
    {
      "id": "chunk_abc123",
      "content": "The queried knowledge base chunk content.",
      "metadata": {
        "score": 0.92,
        "source": "import_name",
        "title": "Optional chunk title"
      }
    }
  ],
  "totalCount": 1,
  "query": "user's search query",
  "knowledgeBaseId": "kb_xyz789"
}

​
Examples

Basic query by name: 
{
  "knowledgeBaseName": "Product API Docs",
  "query": "How do I authenticate with the API?"
}
Query by ID with result limit: 
{
  "knowledgeBaseId": "kb_abc123",
  "query": "pricing tiers",
  "limit": 5
}
Scoped query for a specific agent: 
{
  "knowledgeBaseName": "Engineering Handbook",
  "query": "deployment checklist",
  "agentId": "release-agent",
  "limit": 3
}
Shared-main KB queried from a peer-scoped coach session: 
{
  "knowledgeBaseName": "Social Posts",
  "query": "Nice Guy Triangle sexless marriages",
  "agentId": "coach",
  "channel": "peer-coach:511172388",
  "limit": 5
}

​
When to use vs alternatives

Use caseTool
Search a specific knowledge base by semantic meaningcrystal_query_knowledge_base
Semantic search across all memories (not KBs)crystal_recall
Exact text match in messagescrystal_search_messages
Get all KBs available to the usercrystal_list_knowledge_bases
Import or create a new knowledge baseUse dashboard or API

​
Error handling

ErrorCauseResolution
Knowledge base not foundThe specified ID or name doesn’t exist or is not accessible.Verify the KB name/ID via crystal_list_knowledge_bases.
query is requiredNo query parameter was provided.Provide a non-empty query string.
knowledgeBaseId or knowledgeBaseName is requiredNeither ID nor name was provided.Provide at least one identifier.
Empty resultsThe query matched no chunks above the similarity threshold.Try a simpler or more general query.

​
Source of truth

  • mcp-server/src/tools/query-knowledge-base.ts — tool definition and HTTP handler
  • convex/crystal/knowledgeBases.ts — backend query logic
  • apps/web/app/(dashboard)/knowledge-bases/ — KB management UI

​
Notes

​
Chunk-level peer scope filter (new in 0.7.15)

Both the queryKnowledgeBase action and the internal getKBMemoriesInternal path now apply a chunk-level peer scope filter that mirrors the KB-level visibility guard. A permissive shared KB will return its parent-scoped chunks plus chunks explicitly scoped to the requesting peer; cross-peer chunks are dropped. Trailing-colon channels (e.g. peer-coach:) fail closed.