Knowledge Bases

Base, item, and revision architecture

A Knowledge Base is an owner-scoped or team-scoped collection of reference documents, specifications, and runbooks. It organizes technical knowledge into three distinct hierarchical entities:

• Knowledge Base: The top-level container (such as "Engineering Runbooks"). A base has a name, description, status (active or archived), and space ownership (Personal or Team).
• Knowledge Item: A distinct document or guideline within a base (such as "Deployment Guidelines"). An item has a title, locator, status (draft, published, or archived), source type (user_created or file), and a current_revision_id pointer.
• Knowledge Revision: An immutable snapshot containing canonical content, revision number, content format (such as markdown), content hash, source metadata, and provenance.
• Publication lifecycle: An item starts in draft status. When published, its current revision becomes discoverable to agents. Subsequent edits create immutable new revisions and advance the current pointer without altering historical revisions.

Publication boundaries and agent visibility

Knowledge Bases enforce strict publication boundaries between human authoring and autonomous agent retrieval. Callers choose between query search and addressed read. Query searches protect freshness by evaluating only published items at their current active revisions:

• Active bases only: Archived bases are excluded from agent discovery. Archiving suspends retrieval across all contained items without destroying content.
• Published items only: Draft items remain private to the author and team editors until explicitly published. Agents cannot discover or cite draft items in query search.
• Current revision by default: Query search evaluates only the revision referenced by current_revision_id. Superseded historical revisions cannot appear as query search results.
• Addressed read: An addressed read can inspect an exact historical revision by supplying knowledge_revision_id alongside knowledge_item_id, preserving reproducible citations.

query search       -> active base + published item + current_revision_id
addressed (no pin) -> published item's current revision
addressed (pinned) -> exact immutable revision (e.g. knowledge:<item-id>@<revision-id>)

Retrieval modes: Hybrid, RRF, Semantic, and Lexical

The search runtime supports four retrieval modes to balance lexical precision and semantic comprehension:

• hybrid (default): Linear combination of normalized lexical and semantic scores using parameter alpha (default 0.5). Alpha closer to 1 favors exact lexical overlap, while alpha closer to 0 favors conceptual semantic similarity. Falls back to lexical when vector scores are unavailable.
• rrf (Reciprocal Rank Fusion): Fuses independent lexical and semantic ranked lists using rank constant k (default 60), ensuring balanced ordering without requiring score calibration.
• semantic: Vector similarity ranking based on embedding representations, falling back to lexical matching when embeddings are unconfigured.
• lexical: Normalized token and phrase matching optimized for exact symbols, function names, error codes, and configuration keys.

Supported file types and upload pipelines

Knowledge items can be authored directly in markdown or imported from local files through two distinct ingestion mechanisms:

• Browser-read text and code files: Plain text and code files (.md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, .toml) are read directly in the browser and saved as canonical markdown content.
• Document extraction pipeline: Formatted documents (.pdf, .docx, .pptx, .xlsx) are uploaded via the Documents API, processed through text extraction workers, and snapshotted into Knowledge items once extraction succeeds.
• File boundaries: Ingestion boundaries apply across client and server environments. For reliable processing, organize knowledge into focused, modular documents rather than monolithic file dumps.

Agent access surfaces and client profiles

Authorized agents access Knowledge through dedicated MCP tools and standalone Skill commands:

• MCP search_knowledge: Dedicated read-only search tool requiring knowledge:read token scope. Exposed specifically in the cursor-plugin and ordinary-full client profiles (config/mcp-documentation-contract.json); not exposed in chatgpt-public or generic-public profiles.
• MCP recall_context: Automatically includes relevant Knowledge items alongside episodic memory when Knowledge is enabled for your account and the token includes knowledge:read.
• Standalone XMemo Skill: Executes recall-context with explicit knowledge inclusion: node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true.
• Scope enforcement: Not every recall automatically queries Knowledge; retrieval occurs only when configured, permitted by token scope, and supported by the active client profile.
• REST companion: The authenticated companion endpoint POST /api/v1/knowledge/search provides direct programmatic access to knowledge search for backend services and custom tooling.

{
  "type": "knowledge_search",
  "results": [
    {
      "knowledge_item_id": "item_runbook_deploy",
      "knowledge_revision_id": "rev_v2_deploy_runbook",
      "title": "Production Deployment Runbook",
      "content": "Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.",
      "reference": "knowledge:item_runbook_deploy@rev_v2_deploy_runbook",
      "score": 3.84
    }
  ]
}

Team roles, spaces, and lifecycle operations

Knowledge Bases support personal and collaborative workspaces with role-based access control:

• Role capabilities: Owner and Admin hold base:admin and item:write rights (create, archive, update, delete bases and items). Member holds item:write rights (create, edit, and publish items, but cannot delete or archive bases). Viewer holds read rights only.
• Space boundaries: Personal space (/me#knowledge) is private to the owner. Team space (?space=<team_id>#knowledge) shares published documentation across authenticated team members.
• Archive vs Permanent Deletion: Archiving a base sets status to archived, instantly excluding all items from agent queries while allowing full restoration. Permanent deletion physically destroys the base and all associated revisions irreversibly.

Distinction from Project memory

Knowledge Bases provide curated reference documentation, which operates under different guarantees than conversational Project memory:

• Knowledge Base items: Curated, versioned reference documents (such as runbooks, design docs, and coding standards) with multi-revision history and exact citation references (knowledge:<item-id>@<revision-id>).
• Project Knowledge/Working memory: Conversational memory records categorized within a project workspace as durable context (knowledge) versus transient task state (working memory).
• Independence: Removing a memory record or unlinking a document from a Project does not modify, archive, or delete underlying Knowledge Base items.

Availability and runtime enablement

Knowledge Base is documented as a core capability, not as Preview. Availability is active if Knowledge is enabled for your account. When the backend knowledge runtime is unconfigured or disabled, requests return HTTP 503 with code knowledge_runtime_disabled. Catalog plan designations (such as Plus tier allocations) represent plan allowances rather than runtime enforcement mechanisms; no API routes enforce plan tiers.