Knowledge-base endpoints - Memory Crystal

These are the HTTP doors for the Knowledge Base shelf.

What this means in practice

Important endpoint families include:

list/create knowledge bases
patch knowledge-base metadata and scope policy
import chunks
query a knowledge base
backfill or maintenance-related KB flows

How it actually works

Key repo surfaces:

convex/crystal/knowledgeHttp.ts
convex/crystal/knowledgeBases.ts
packages/mcp-server/README.md

Endpoint Reference

List Knowledge Bases

`GET /api/knowledge-bases`

Retrieve all knowledge bases for the authenticated user. This endpoint is agent/scope aware when you pass query parameters like:

agentId
scope

Request:

curl -X GET https://your-deployment.convex.site/api/knowledge-bases \
  -H "Authorization: Bearer $MEMORY_CRYSTAL_API_KEY"

Response:

{
  "knowledgeBases": [
    {
      "id": "kb_123",
      "name": "Product Docs",
      "description": "API reference and guides",
      "chunkCount": 245,
      "createdAt": 1681234567890,
      "updatedAt": 1681234567890
    },
    {
      "id": "kb_456",
      "name": "Internal Wiki",
      "description": "Architecture decisions and runbooks",
      "chunkCount": 89,
      "createdAt": 1681234567000,
      "updatedAt": 1681234567000
    }
  ]
}

Create Knowledge Base

`POST /api/knowledge-bases`

Create a new knowledge base. Request:

{
  "name": "Q3 Planning Docs",
  "description": "Quarterly planning materials and decisions",
  "agentIds": ["coach", "dm-replies"],
  "scope": "peer-team:main",
  "peerScopePolicy": "permissive"
}

Response:

{
  "id": "kb_789",
  "name": "Q3 Planning Docs",
  "description": "Quarterly planning materials and decisions",
  "chunkCount": 0,
  "createdAt": 1681234567890
}

Import Chunks

`POST /api/knowledge-bases/:knowledgeBaseId/import`

Bulk-import document chunks into a knowledge base. Request:

{
  "chunks": [
    {
      "content": "# API Authentication\n\nAll requests require a Bearer token...",
      "metadata": {
        "title": "Authentication Guide",
        "sourceUrl": "https://docs.example.com/auth",
        "chunkIndex": 0,
        "totalChunks": 5
      }
    },
    {
      "content": "API keys are generated via the dashboard...",
      "metadata": {
        "title": "Authentication Guide",
        "sourceUrl": "https://docs.example.com/auth",
        "chunkIndex": 1,
        "totalChunks": 5
      }
    }
  ]
}

Response:

{
  "importId": "imp_123",
  "chunksProcessed": 2,
  "embeddingsCreated": 2,
  "timestamp": 1681234567890
}

Upsert by key. Give a chunk a stable dedupeKey (e.g. a title or slug) to replace the existing chunk with the same (knowledgeBaseId, dedupeKey) in place — one key = one chunk — instead of appending a duplicate. Re-importing a key edits that chunk (content, title) and re-embeds it; keyless chunks append as before.

{
  "chunks": [
    { "dedupeKey": "guide:authentication", "content": "..." },
    { "dedupeKey": "guide:rate-limits", "content": "..." }
  ]
}

The response includes importedCount (newly inserted) and updatedCount (upsert-replaced). Behavior:

Each chunk is embedded using the same model as memories (text-embedding-3-small)
With a dedupeKey, re-imports replace the matching chunk in place (no duplicate)
Without a dedupeKey, duplicate chunks are deduplicated within the batch by SHA256 of content
Failed chunks are logged but don’t block the import

Enumerate Chunks

`GET /api/knowledge-bases/:knowledgeBaseId/memories`

Walk every chunk in a KB with real cursor pagination and ids — unlike the relevance-capped query endpoint, this enumerates the whole KB so an agent can inspect, clean, or update it programmatically. Query params: limit (1–200, default 100) and cursor (pass the previous response’s continueCursor). Response:

{
  "knowledgeBaseId": "kb_123",
  "memories": [
    { "id": "md_...", "title": "...", "content": "...", "dedupeKey": "guide:rate-limits", "createdAt": 1681234567890 }
  ],
  "isDone": false,
  "continueCursor": "..."
}

Each returned id works with POST /api/mcp/update (edit content in place) and POST /api/mcp/forget (delete). Page until isDone is true.

Empty a Knowledge Base

`POST /api/knowledge-bases/:knowledgeBaseId/empty`

Delete all chunks while keeping the KB row, id, and agent bindings, so you can re-import into the same id without re-pointing agents. Returns { deletedMemories, kept: true }.

Patch Knowledge Base

`PATCH /api/knowledge-bases/:knowledgeBaseId`

Update metadata and visibility policy. Example:

{
  "agentIds": ["coach", "coach-beta", "dm-replies", "support-bot"],
  "scope": "peer-team:main",
  "peerScopePolicy": "permissive"
}

Use this when converting a KB from agent-private to shared-open access under one API key.

Query Knowledge Base

`POST /api/knowledge-bases/:knowledgeBaseId/query`

Vector search a knowledge base by semantic query. Request:

{
  "query": "how do I set up authentication",
  "limit": 5,
  "threshold": 0.6
}

Response:

{
  "results": [
    {
      "chunkId": "chunk_123",
      "content": "All requests require a Bearer token in the Authorization header...",
      "metadata": {
        "title": "Authentication Guide",
        "sourceUrl": "https://docs.example.com/auth",
        "chunkIndex": 0
      },
      "relevance": 0.92
    },
    {
      "chunkId": "chunk_124",
      "content": "API keys are generated via the dashboard. Each key is unique to a user...",
      "metadata": {
        "title": "Authentication Guide",
        "sourceUrl": "https://docs.example.com/auth",
        "chunkIndex": 1
      },
      "relevance": 0.87
    }
  ]
}

Chunk-level peer scope filter (new in 0.7.15). Both the queryKnowledgeBase action and the internal KB-chunk reader 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 and return no chunks.

Parameters:

query (required): The semantic query string
limit (optional): Maximum results to return (default: 10, max: 50)
threshold (optional): Minimum relevance score 0–1 (default: 0.0, all results)
agentId (optional): Agent visibility context
channel (optional): Channel/scope context

Usage Patterns

Example 1: Import API Documentation

# Extract chunks from your docs
python extract_chunks.py docs/ > chunks.json

# Import into a KB
curl -X POST https://your-deployment.convex.site/api/knowledge-bases/kb_123/import \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d @chunks.json

Example 2: Query Documentation Before Response

In an agent workflow:

User asks question
Query KB: crystal_query_knowledge_base(kb_id="kb_123", query=user_question)
Inject retrieved chunks into context
Generate response
Call crystal_remember to save key insights

Scope and Tenancy

Knowledge bases are:

Per-user — isolated by userId from authentication token
Agent/scope aware — visibility can differ for peer-scoped vs shared-main agent lanes
Persistent — survive session restarts

Shared-main KB pattern

To make one training KB available to many agents/chats under one key:

set scope to something like peer-team:main
set peerScopePolicy to "permissive"
include all allowed agent IDs in agentIds

To keep private client notes private:

keep agentIds: ["coach"]
do not move them to a shared :main scope

Common mistakes

documenting KB endpoints without mentioning their relationship to the MCP KB tools
assuming imported data is the same as conversational memory
ignoring scope and tenancy when describing KB behavior

Source of truth

Primary files behind this page:

convex/crystal/knowledgeHttp.ts
convex/crystal/knowledgeBases.ts
packages/mcp-server/README.md

​What this means in practice

​How it actually works

​Endpoint Reference

​List Knowledge Bases

​GET /api/knowledge-bases

​Create Knowledge Base

​POST /api/knowledge-bases

​Import Chunks

​POST /api/knowledge-bases/:knowledgeBaseId/import

​Enumerate Chunks

​GET /api/knowledge-bases/:knowledgeBaseId/memories

​Empty a Knowledge Base

​POST /api/knowledge-bases/:knowledgeBaseId/empty

​Patch Knowledge Base

​PATCH /api/knowledge-bases/:knowledgeBaseId

​Query Knowledge Base

​POST /api/knowledge-bases/:knowledgeBaseId/query

​Usage Patterns

​Example 1: Import API Documentation

​Example 2: Query Documentation Before Response

​Scope and Tenancy

​Shared-main KB pattern

​Common mistakes

​Source of truth

What this means in practice

How it actually works

Endpoint Reference

List Knowledge Bases

`GET /api/knowledge-bases`

Create Knowledge Base

`POST /api/knowledge-bases`

Import Chunks

`POST /api/knowledge-bases/:knowledgeBaseId/import`

Enumerate Chunks

`GET /api/knowledge-bases/:knowledgeBaseId/memories`

Empty a Knowledge Base

`POST /api/knowledge-bases/:knowledgeBaseId/empty`

Patch Knowledge Base

`PATCH /api/knowledge-bases/:knowledgeBaseId`

Query Knowledge Base

`POST /api/knowledge-bases/:knowledgeBaseId/query`

Usage Patterns

Example 1: Import API Documentation

Example 2: Query Documentation Before Response

Scope and Tenancy

Shared-main KB pattern

Common mistakes

Source of truth