# Knowledge Bases guide

Create knowledge bases, upload technical documentation, publish versioned items, and enable agents to retrieve cited facts with provenance.

- Canonical: https://docs.xmemo.dev/docs/guides/knowledge-bases
- Locale: en-US
- Content-Locale: en-US
- Canonical-Content-Digest: 2faabeb6639476c2bec41c9f59884052c43ffc31e31ef6169044e5bb414552fe
- Edition-Digest: 5a01fe2224a1a13673c8fa6b2d9e20d9f93826d55c9a4a6fae2239026c487968
- Source-Revision: sha256:c0d24fff7e465ea3dbb6daf903fbcba1cab87eecc6514e3b935a312cafc20ddd

## User goal

Maintain structured knowledge bases in your personal or team workspace, ingest markdown and formatted documents, publish verified immutable revisions, and configure autonomous agents to retrieve cited facts with source attribution.

## Availability and prerequisites

Knowledge Base authoring and inspection are available in the web console at https://xmemo.dev/me#knowledge (Personal workspace) or https://xmemo.dev/me?space=<team_id>#knowledge (Team workspace) if Knowledge is enabled for your account. Before getting started, verify the following prerequisites:

- Authentication requirement: An active user session is required. Unauthenticated visits redirect to /login (the sign-in page).
- Token scopes: Programmatic access requires knowledge:read for search and addressed reads, and knowledge:write for creating or editing items.
- Supported file formats: In-browser text/code reader supports .md, .markdown, .txt, .json, .csv, .py, .js, .ts, .tsx, .html, .yaml, .yml, and .toml. Document extraction supports .pdf, .docx, .pptx, and .xlsx.
- Drag and drop interface: The console presents "Drag & drop files here" with helper text "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)".

## 1. Create a Knowledge Base in web console

Navigate to https://xmemo.dev/me#knowledge in your browser. Click "Create Knowledge Base" to open the creation dialog. Enter "Engineering Runbooks" in Name and "Operational runbooks and deployment procedures." in Description. Confirm creation to initialize the active base.

```bash
# Access personal knowledge workspace
https://xmemo.dev/me#knowledge

# Access team knowledge workspace with explicit space parameter
https://xmemo.dev/me?space=<team_id>#knowledge
```

## 2. Add and publish a synthetic knowledge item

Open the newly created "Engineering Runbooks" base and click "Create Knowledge item" to create an entry from markdown or local file. Enter Title "Deployment Guidelines" and paste the initial synthetic instructions. The item initializes with status "draft":

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, and verified canary health.
```

## 3. Publish the draft item for agent retrieval

While in draft status, the item remains private to human editors. To make it discoverable to agents, click "Publish". The console displays the hint "Published content becomes eligible for authorized Knowledge search.". Once confirmed, the item advances to status "published", establishing revision 1 as the current searchable revision.

- Draft privacy: Draft items are excluded from agent discovery and query search.
- Publish action: Publishing updates the item status to published and sets current_revision_id to revision 1.
- Immutable revision: The canonical content, hash, and metadata of revision 1 are preserved immutably.

## 4. Retrieve knowledge with agent citation

Authorized agents in client environments exposing search_knowledge (such as cursor-plugin or ordinary-full) can query the published runbook. The tool returns ranked excerpts with explicit citation reference pointers:

```bash
# Query knowledge via standalone Skill CLI
node scripts/xmemo-skill.mjs recall-context --query "production deployments" --include_knowledge true
```

## 5. Update content and publish an immutable new revision

When technical procedures change, open "Deployment Guidelines" and click "Edit Knowledge item". Update the content to reflect new operational requirements. Click "Save new revision". The console displays "Saving content creates an immutable new revision. Metadata changes do not create a revision.":

```markdown
## Deployment Guidelines

Production deployments require two peer approvals, clean migration dry-runs, verified canary health, and automated smoke verification.
```

## Observable result

Verify the published item and its revision provenance in the web console and through agent search:

- Console badge: The item card displays status badge "Published" and points to the current active revision.
- Revision Lineage: Opening "Revision history" shows revision 2 as current and revision 1 as historical, with timestamps and author attribution.
- Agent search result: Query searches evaluate only revision 2. Historical revision 1 remains accessible via addressed reads specifying exact knowledge_revision_id.

## What agents can access

Knowledge Bases enforce strict access and visibility boundaries for agent integration:

- Published items only: Agents cannot access draft items. Query searches evaluate only published items in active bases.
- Current revision boundary: Query search automatically resolves to current_revision_id. Superseded revisions cannot appear in query search results.
- Profile availability: The read-only MCP tool search_knowledge is available strictly in the cursor-plugin and ordinary-full client profiles (config/mcp-documentation-contract.json). Other client profiles utilize recall_context, which automatically includes Knowledge when enabled and authorized.
- Recall behavior: MCP recall_context includes Knowledge automatically when Knowledge is enabled for your account and the token includes knowledge:read. Not every recall searches Knowledge.

## Sharing and storage boundaries

Knowledge Bases maintain strict space isolation and administrative role boundaries:

- Personal vs Team space: Personal bases (/me#knowledge) are private to the account. Team bases (?space=<team_id>#knowledge) enforce team role access (routes/knowledge.py:129-134).
- 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). Viewer holds read rights only.
- Archive vs Permanent deletion: Archiving ("Are you sure you want to archive knowledge base '<name>'? Archived bases will no longer be retrieved by agents.") suspends retrieval without loss. Permanent deletion ("Are you sure you want to permanently delete knowledge base '<name>' and all its items? This action cannot be undone.") physically removes data.
- Project memory independence: Knowledge Bases operate independently of Project working/knowledge memory partitions. Unlinking a memory from a Project does not touch Knowledge Base documents.

## Failure recovery

Address common Knowledge Base access and extraction issues using the following diagnostic steps:

- Document extraction in progress: When uploading .pdf, .docx, .pptx, or .xlsx documents, wait while "Extraction is still in progress. Try again when it succeeds.".
- Document extraction failed: If processing fails, the console displays "Extraction failed. Retry the Document from its existing Document surface first.". Verify file integrity or upload plain markdown text.
- Item not returned in agent query: Verify that the item status is "Published" (not "draft"), that the base is active (not archived), and that the client token holds knowledge:read scope.
- Concurrent update conflict: If another user or agent updated the item while your edit was open, the console displays "This Knowledge item changed elsewhere. Refresh it and try again.". Refresh the page and re-apply changes.
- Search mode selection: If exact runbook symbols or configuration keys are missed by hybrid search, switch to lexical mode (mode="lexical") for exact token matching.

## Related reference

Continue exploring Knowledge Base concepts, related tools, and workspace management:

- Concepts: Knowledge Bases (/docs/concepts/knowledge-bases) — Architectural model, revision DAG, and retrieval modes.
- Tools: search_knowledge (/docs/tools/search-knowledge) — Tool reference for addressed reads and search parameters.
- Tools: recall_context (/docs/tools/recall-context) — Context packing tool with automatic Knowledge retrieval.
- Guides: Memory Console (/docs/guides/memory-console) — Complete web console navigation guide.
- Concepts: Provenance and Attribution (/docs/concepts/provenance-attribution) — Citation envelopes and author attribution.

## ChatGPT user

Give ChatGPT durable access to your XMemo preferences, project facts, decisions, and TODOs without pasting bearer tokens into a chat.

Connect the hosted XMemo MCP server through the ChatGPT/OpenAI app OAuth flow, then approve the memory:read and memory:write grant for your XMemo account.

Save a synthetic preference or project note, start a new chat, then ask ChatGPT to recall it through XMemo before continuing work.

If OAuth fails or tools do not appear, sign out of the MCP server in the host app, reconnect the XMemo server URL, and retry before creating direct tokens.

## Copilot / Codex developer

Carry repo decisions, coding conventions, bug-fix notes, and task history between IDE and CLI agents.

Use OAuth for VS Code / GitHub Copilot and Gemini CLI when available. For Copilot CLI, Codex, Cursor, or other direct MCP clients, keep XMEMO_KEY in the local environment or secret store and set a stable XMEMO_AGENT_INSTANCE_ID.

Record a codebase decision or bug fix, then ask the next IDE or CLI agent to recall the relevant XMemo context before editing.

If recalls are empty, verify the selected MCP config path, the XMEMO_KEY environment variable for direct clients, and any stale OAuth credential in the host app.

## Team / enterprise pilot owner

Evaluate shared memory with account controls, source attribution, export/delete workflows, and reviewer-safe setup evidence.

Create or enter the protected XMemo workspace, invite approved users, then connect each client through OAuth or a scoped direct credential according to the readiness badges.

Have a pilot member save a synthetic team memory, confirm source attribution in XMemo, then review delete/export and support paths.

If a member cannot connect, check role permissions, OAuth approval, client readiness status, and support guidance before issuing a new token.

## Autonomous agent operator

Let headless or scheduled agents record progress, retrieve prior decisions, and keep a stable non-secret instance identity.

Fetch /api/v1/mcp/config/autonomous-agent. Prefer auth_modes.oauth when the runner supports OAuth + custom headers; use auth_modes.xmemo_key with XMEMO_KEY from a secret store only for fully headless runners.

Run one synthetic task that writes progress to XMemo, restart the runner, and confirm it recalls that progress using the same XMEMO_AGENT_INSTANCE_ID.

If attribution changes or recalls split across instances, persist XMEMO_AGENT_INSTANCE_ID outside git and verify the runner is not regenerating it on every start.