# 来源与归因

保留记忆的来源，同时避免将来源元数据与授权或所有权混淆。

- Canonical: https://docs.xmemo.dev/zh/docs/concepts/provenance-attribution
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 019b1c6aab84d15e8b791ec3f9b7ecd3d545865415ceba204e14301dea665c6a
- Edition-Digest: a3a4af1cdc3e54aa2cf81915188829c4fa6b79905ac3355404556355b8407bc6
- Source-Revision: sha256:3922476e09ce20617ab30ead32aa1ccd8f95082d0f395b172b3eadd0d8fd2d45

## 来源信息是公开记忆记录的一部分

memory contract 会在 content、path、source_identity、agent_id、agent_instance_id_hash 和 agent_instance_source 旁公开 provenance。Provenance 是关于记录如何产生的结构化证据；它不是 bearer token，也不能扩大 caller 的访问权限。

- source_identity 是写入和审计路径使用的简洁 caller/source 标签。
- provenance 是承载 source、adapter、event 或其他证据字段的 JSON object。
- agent_instance_id_hash 是保护隐私的安装归因值。

## Agent 事件携带其来源

AgentEvent.to_memory_candidate 会创建一个 MemoryCandidate，其 provenance 包含 source=agent_integration、adapter=<event source> 和 event_id。共享 sanitizer 运行后，candidate metadata 还会保留 event type、time、agent id、task id、tool name、command、file path 和 status。

```json
{
  "provenance": {
    "source": "agent_integration",
    "adapter": "codex",
    "event_id": "evt_<stable-event-id>"
  },
  "metadata": {
    "agent_event": {
      "event_type": "decision_made",
      "task_id": "<task-id>"
    }
  }
}
```

## 将归因信息与记忆一起写入

公开的 remember 和 store request model 接受 source 与 provenance。在捕获时提供稳定且非机密的标签；将访问凭据保留在 header 或 environment 中，让服务器在持久化前清理 content、metadata 和 provenance。

```http
POST /v1/remember
X-API-Key: <your-assigned-api-key>
Content-Type: application/json

{
  "content": "The deployment decision was verified.",
  "path": "projects/memory-os/decisions",
  "source": "codex",
  "provenance": {
    "source": "agent_integration",
    "adapter": "codex",
    "event_id": "evt_<stable-event-id>"
  }
}
```

## 清理不会抹去 lineage

persistence sanitizer 会结构化遍历 content、metadata 和 provenance。凭据形态的值会被移除；如果发生 redaction，服务器会记录 privacy.server_write_sanitizer audit metadata，同时保留安全的 provenance 字段。应将结果记录视为经过清理的证据，而不是原始 event archive。

## 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 不会每次启动都重新生成它。