# Knowledge Bases

将结构化知识保存在不可变 revision 中，并检索已发布的当前内容或带有引用的精确历史版本。

- Canonical: https://docs.xmemo.dev/zh/docs/concepts/knowledge-bases
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 6abd27813899cf8de3d349ccd4016d92fe96f6b1cca4e84f29dab16a78c512a4
- Edition-Digest: 35cbce8fbb01d5470c3eac67ff0053b4b35d14eab005aaff9ecf3f197f6a25d7
- Source-Revision: sha256:fd48f8faf2e2fd5083059df93e298741fed8b459995a58140a2b3724b315e545

## Base、Item 与 Revision 架构

Knowledge Base 是 owner-scoped 或 team-scoped 的参考文档、规范和 runbook 集合。它将技术知识组织为三个不同的分层实体：

- Knowledge Base：顶层容器（例如 "Engineering Runbooks"）。base 具有名称、描述、状态（active 或 archived）以及空间所有权（Personal 或 Team）。
- Knowledge Item：base 内的独立文档或规范（例如 "Deployment Guidelines"）。item 具有标题、定位符（locator）、状态（draft、published 或 archived）、来源类型（user_created 或 file）以及 current_revision_id 指针。
- Knowledge Revision：包含规范内容（canonical content）、revision 编号、内容格式（如 markdown）、内容哈希、来源元数据和出处来源（provenance）的不可变快照。
- 发布生命周期：item 最初处于 draft 状态。发布后，其当前 revision 即可供 agent 发现。后续编辑会创建不可变的新 revision 并推进当前指针，而不会更改历史 revision。

## 发布边界与 Agent 可见性

Knowledge Base 在人工编写与自主 agent 检索之间实施严格的发布边界。调用方可在 query search 与 addressed read 之间进行选择。Query search 通过仅评估处于当前活动 revision 的已发布 item 来保证新鲜度：

- 仅限活动 base：已归档（archived）的 base 会被排除在 agent 发现之外。归档会暂停所有包含 item 的检索，而不会销毁内容。
- 仅限已发布 item：草稿（draft）item 在明确发布之前对作者和团队编辑保持私密。Agent 无法在 query search 中发现或引用草稿 item。
- 默认评估当前 revision：Query search 仅评估由 current_revision_id 引用的 revision。被替代的历史 revision 不会作为 query search 结果出现。
- 寻址读取（Addressed read）：寻址读取可以通过在提供 knowledge_item_id 的同时提供 knowledge_revision_id 来检查精确的历史 revision，从而保留可复现的引用。

```text
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>)
```

## 检索模式：Hybrid、RRF、Semantic 和 Lexical

搜索运行时支持四种检索模式，以平衡词法精度与语义理解：

- hybrid（默认）：使用参数 alpha（默认 0.5）对归一化词法得分与语义得分进行线性组合。alpha 越接近 1 越偏向精确词法重合，alpha 越接近 0 越偏向概念语义相似度。当向量分数不可用时回退到词法检索。
- rrf（倒数排名融合，Reciprocal Rank Fusion）：使用排名常数 k（默认 60）融合独立的词法与语义排名列表，确保平衡排序而无需分数校准。
- semantic：基于嵌入表示的向量相似度排名，在未配置嵌入时回退到词法匹配。
- lexical：针对精确符号、函数名、错误代码和配置键优化的归一化 token 与短语匹配。

## 支持的文件类型与上传管线

Knowledge item 可以直接以 markdown 编写，也可以通过两种不同的摄取机制从本地文件导入：

- 浏览器读取的文本与代码文件：纯文本和代码文件（.md、.markdown、.txt、.json、.csv、.py、.js、.ts、.tsx、.html、.yaml、.yml、.toml）直接在浏览器中读取，并保存为规范 markdown 内容。
- 文档提取管线：格式化文档（.pdf、.docx、.pptx、.xlsx）通过 Documents API 上传，经文本提取 worker 处理，一旦提取成功便快照为 Knowledge item。
- 文件边界：摄取边界适用于客户端和服务器环境。为保证可靠处理，请将知识组织为集中、模块化的文档，而不是整块的文件转储。

## Agent 访问接口与客户端 Profile

授权的 agent 通过专用的 MCP 工具与独立 Skill 命令访问 Knowledge：

- MCP search_knowledge：专用的只读搜索工具，需要 knowledge:read 令牌范围。特别在 cursor-plugin 和 ordinary-full 客户端 profile（config/mcp-documentation-contract.json）中公开；未在 chatgpt-public 或 generic-public profile 中公开。
- MCP recall_context：当您的账户启用了 Knowledge 且令牌包含 knowledge:read 时，自动在情景记忆之外包含相关 Knowledge item。
- 独立 XMemo Skill：使用显式知识包含执行 recall-context：node scripts/xmemo-skill.mjs recall-context --query "api authentication" --include_knowledge true。
- 范围强制：并非每次 recall 都会自动查询 Knowledge；仅在配置允许、令牌范围许可且受活动客户端 profile 支持时才执行检索。
- REST 配套端点：经过身份验证的配套端点 POST /api/v1/knowledge/search 为后端服务和自定义工具提供对知识搜索的直接编程式访问。

```json
{
  "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
    }
  ]
}
```

## 团队角色、空间与生命周期操作

Knowledge Base 支持具有基于角色的访问控制的个人与协作工作区：

- 角色权能：Owner 与 Admin 拥有 base:admin 和 item:write 权限（创建、归档、更新、删除 base 与 item）。Member 拥有 item:write 权限（创建、编辑和发布 item，但无法删除或归档 base）。Viewer 仅拥有读取权限。
- 空间边界：个人空间（/me#knowledge）对所有者私有。团队空间（?space=<team_id>#knowledge）在经过身份验证的团队成员之间共享已发布的文档。
- 归档与永久删除：归档 base 会将状态设为 archived，立即将所有 item 排除在 agent 查询之外，同时允许完全恢复。永久删除会在物理上不可逆地销毁 base 及所有关联 revision。

## 与项目记忆的区别

Knowledge Base 提供经过整理的参考文档，其运作机制遵循不同于对话式项目记忆的保障：

- Knowledge Base item：经过整理、版本化的参考文档（例如 runbook、设计文档和编码规范），具有多 revision 历史记录与精确引用关联（knowledge:<item-id>@<revision-id>）。
- 项目 Knowledge/Working 记忆：在项目工作区内分类为持久上下文（knowledge）与瞬态任务状态（working 记忆）的对话式记忆记录。
- 独立性：从项目中移除记忆记录或取消文档关联不会修改、归档或删除底层 Knowledge Base item。

## 可用性与运行时启用

Knowledge Base 被记录为核心功能，而非 Preview。如果您的账户启用了 Knowledge，则可用性处于活动状态。当后端知识运行时未配置或被禁用时，请求将返回 HTTP 503 与错误代码 knowledge_runtime_disabled。目录方案标识（例如 Plus 方案配额）代表方案许可额度而非运行时强制执行机制；没有任何 API 路由强制执行方案等级。

## ChatGPT 用户

让 ChatGPT 持久访问你的 XMemo 偏好、项目事实、决策和 TODO，同时不把 bearer token 粘贴到聊天里。

通过 ChatGPT/OpenAI app 的 OAuth 流程连接托管 XMemo MCP server，然后为你的 XMemo 账户批准 memory:read 与 memory:write 授权。

保存一条合成偏好或项目笔记，开启新聊天，再让 ChatGPT 在继续工作前通过 XMemo 召回它。

如果 OAuth 失败或工具未出现，先在宿主应用里退出该 MCP server，重新连接 XMemo server URL 并重试，再考虑创建 direct token。

## Copilot / Codex 开发者

在 IDE 与 CLI agent 之间携带仓库决策、编码规范、bug 修复说明和任务历史。

在可用时对 VS Code / GitHub Copilot 和 Gemini CLI 使用 OAuth。对于 Copilot CLI、Codex、Cursor 或其他直连 MCP 客户端，请在本地环境或密钥存储中保留 XMEMO_KEY，并设置稳定的 XMEMO_AGENT_INSTANCE_ID。

记录一条代码库决策或 bug 修复，然后让下一个 IDE 或 CLI agent 在编辑前召回相关 XMemo 上下文。

如果召回为空，检查所选 MCP 配置路径、direct client 的 XMEMO_KEY 环境变量，以及宿主应用中是否存在过期 OAuth 凭据。

## 团队 / 企业 pilot owner

用账户控制、来源归因、导出/删除流程和 reviewer-safe 设置证据来评估共享记忆。

创建或进入受保护的 XMemo workspace，邀请已批准用户，然后根据 readiness badges 通过 OAuth 或 scoped direct credential 连接各客户端。

让一名 pilot 成员保存一条合成团队记忆，在 XMemo 中确认来源归因，然后审阅删除/导出和支持路径。

如果成员无法连接，先检查角色权限、OAuth 批准、客户端 readiness 状态和支持指引，再签发新 token。

## 自主 agent operator

让 headless 或定时 agent 记录进度、取回历史决策，并保持稳定的非秘密实例身份。

获取 /api/v1/mcp/config/autonomous-agent。当 runner 支持 OAuth + 自定义 headers 时优先使用 auth_modes.oauth；只有完全 headless 的 runner 才使用 auth_modes.xmemo_key，并从密钥库读取 XMEMO_KEY。

运行一个会向 XMemo 写入进度的合成任务，重启 runner，并确认它使用同一个 XMEMO_AGENT_INSTANCE_ID 召回该进度。

如果归因变化或召回分散到多个实例，请把 XMEMO_AGENT_INSTANCE_ID 持久化到 git 之外，并确认 runner 不会每次启动都重新生成它。