知识库指南

用户目标

在个人或团队工作区中维护结构化知识库，摄取 markdown 和格式化文档，发布经过验证的不可变修订版本，并配置自主 agent 以检索带有来源归属的引用事实。

可用性与前提条件

如果您的账户启用了 Knowledge，则可在 Web 控制台的 https://xmemo.dev/me#knowledge（个人工作区）或 https://xmemo.dev/me?space=<team_id>#knowledge（团队工作区）中进行知识库的编写和检查。在开始之前，请确认满足以下前提条件：

• 认证要求：需要处于活动状态的用户会话。未认证的访问将被重定向到 /login（登录页面）。
• 令牌作用域：编程式访问需要 knowledge:read 用于搜索和寻址读取，以及 knowledge:write 用于创建或编辑条目。
• 支持的文件格式：浏览器内文本/代码阅读器支持 .md、.markdown、.txt、.json、.csv、.py、.js、.ts、.tsx、.html、.yaml、.yml 和 .toml。文档内容提取支持 .pdf、.docx、.pptx 和 .xlsx。
• 拖放界面：控制台显示 "Drag & drop files here" 并附带帮助文本 "Supports PDF, Word, PowerPoint, Excel, Markdown, and text files (.pdf, .docx, .pptx, .xlsx, .md, .txt, .csv, .json, etc.)"。

1. 在 Web 控制台中创建知识库

在浏览器中导航至 https://xmemo.dev/me#knowledge。点击 "Create Knowledge Base" 打开创建对话框。在 Name 中输入 "Engineering Runbooks"，在 Description 中输入 "Operational runbooks and deployment procedures."。确认创建以初始化活动知识库。

# 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. 添加并发布合成知识条目

打开新创建的 "Engineering Runbooks" 知识库，点击 "Create Knowledge item" 从 markdown 或本地文件创建条目。输入 Title "Deployment Guidelines" 并粘贴初始合成说明。条目以状态 "draft" 初始化：

## Deployment Guidelines

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

3. 发布草稿条目供 agent 检索

在 "draft" 状态下，该条目仅人类编辑者可见。要使其可供 agent 发现，请点击 "Publish"。控制台会显示提示 "Published content becomes eligible for authorized Knowledge search."。确认后，条目状态进入 "published"，将修订版本 1 确立为当前可搜索的修订版本。

• 草稿私密性：草稿条目被排除在 agent 发现和查询搜索之外。
• 发布操作：发布会将条目状态更新为 "published"，并将 current_revision_id 设置为修订版本 1。
• 不可变修订：修订版本 1 的规范内容、哈希值和元数据保持不可变。

4. 通过 agent 引用检索知识

在公开 search_knowledge 的客户端环境（如 cursor-plugin 或 ordinary-full）中，经授权的 agent 可以查询已发布的运行手册。该工具会返回带有明确引用参考指针的排序摘录：

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

5. 更新内容并发布不可变的新修订版本

当技术流程发生变更时，打开 "Deployment Guidelines" 并点击 "Edit Knowledge item"。更新内容以反映新的操作要求。点击 "Save new revision"。控制台显示 "Saving content creates an immutable new revision. Metadata changes do not create a revision."：

## Deployment Guidelines

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

可观察结果

在 Web 控制台和通过 agent 搜索验证已发布的条目及其修订版本来源溯源：

• 控制台徽章：条目卡片显示状态徽章 "Published" 并指向当前活动的修订版本。
• 修订版本谱系：打开 "Revision history" 会将修订版本 2 显示为当前版本，将修订版本 1 显示为历史版本，并附带时间戳和作者归属。
• Agent 搜索结果：查询搜索仅评估修订版本 2。历史修订版本 1 仍可通过指定确切 knowledge_revision_id 的寻址读取进行访问。

Agent 可以访问的内容

知识库针对 agent 集成强制执行严格的访问和可见性边界：

• 仅限已发布条目：Agent 无法访问草稿条目。查询搜索仅评估活动知识库中已发布的条目。
• 当前修订版本边界：查询搜索会自动解析至 current_revision_id。被取代的修订版本不会出现在查询搜索结果中。
• 配置文件可用性：只读 MCP 工具 search_knowledge 严格在 cursor-plugin 和 ordinary-full 客户端配置文件中可用 (config/mcp-documentation-contract.json)。其他客户端配置文件使用 recall_context，在启用并授权时会自动包含 Knowledge。
• Recall 行为：当您的账户启用了 Knowledge 且令牌包含 knowledge:read 时，MCP recall_context 会自动包含 Knowledge。并非每个 recall 都会搜索 Knowledge。

共享与存储边界

知识库保持严格的空间隔离和管理角色边界：

• 个人空间与团队空间：个人知识库 (/me#knowledge) 对该账户私有。团队知识库 (?space=<team_id>#knowledge) 强制执行团队角色访问控制 (routes/knowledge.py:129-134)。
• 角色能力：Owner 和 Admin 拥有 base:admin 和 item:write 权限（创建、归档、更新、删除知识库和条目）。Member 拥有 item:write 权限（创建、编辑和发布条目）。Viewer 仅拥有读取权限。
• 归档与永久删除：归档（"Are you sure you want to archive knowledge base '<name>'? Archived bases will no longer be retrieved by agents."）可暂停检索而不会丢失数据。永久删除（"Are you sure you want to permanently delete knowledge base '<name>' and all its items? This action cannot be undone."）会物理移除数据。
• 项目记忆独立性：知识库独立于项目的 working/knowledge 记忆分区运行。从项目中取消关联记忆不会触及知识库文档。

故障恢复

使用以下诊断步骤解决常见的知识库访问和提取问题：

• 文档内容提取进行中：上传 .pdf、.docx、.pptx 或 .xlsx 文档时，请在显示 "Extraction is still in progress. Try again when it succeeds." 时等待。
• 文档内容提取失败：如果处理失败，控制台会显示 "Extraction failed. Retry the Document from its existing Document surface first."。请验证文件完整性或上传纯 markdown 文本。
• 条目未在 agent 查询中返回：验证条目状态为 "Published"（而非 "draft"），知识库处于活动状态（未归档），并且客户端令牌包含 knowledge:read 作用域。
• 并发更新冲突：如果其他用户或 agent 在您打开编辑时更新了该条目，控制台会显示 "This Knowledge item changed elsewhere. Refresh it and try again."。刷新页面并重新应用更改。
• 搜索模式选择：如果混合搜索遗漏了确切的运行手册符号或配置键，请切换到词法模式 (mode="lexical") 进行精确 token 匹配。

相关参考

继续了解知识库概念、相关工具和工作区管理：

• 概念：知识库 (/docs/concepts/knowledge-bases) — 架构模型、修订版本 DAG 和检索模式。
• 工具：search_knowledge (/docs/tools/search-knowledge) — 寻址读取和搜索参数的工具参考。
• 工具：recall_context (/docs/tools/recall-context) — 具备自动 Knowledge 检索功能的上下文打包工具。
• 指南：Memory Console (/docs/guides/memory-console) — 完整的 Web 控制台导航指南。
• 概念：来源溯源与归属 (/docs/concepts/provenance-attribution) — 引用封装与作者归属。