# Agent 实例身份

将用于归因的非机密安装标签与授权请求的凭据分开。

- Canonical: https://docs.xmemo.dev/zh/docs/concepts/agent-instance-identity
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: c0db15eaca6541c974e88179495cf7a7f5832695889a2ff2abef284fd7daf337
- Edition-Digest: c92165765cd0a3ee6254a8228ed9cf59d4fa59b2605dc58f3a4971b2f91acecd
- Source-Revision: sha256:af573969af4a97ad87f12425b51f333259b42a829512f8644875a77c1bba2ddb

## 实例 ID 不是凭据

XMEMO_AGENT_INSTANCE_ID 用于标识本地客户端或运行器实例；它不会授权请求。API key 或 OAuth grant 才是访问凭据。服务器会根据实例值生成 agent_instance_id_hash，并将边界权限报告为 attribution_only。

- Credential：X-API-Key 或受支持的 OAuth bearer grant 控制访问权限。
- Instance label：X-Memory-OS-Agent-Instance-ID 让服务器能够比较写入 runner 与后续 caller。
- Agent label：X-Memory-OS-Agent-ID 将逻辑 agent 与某一次安装分别标识。

## 先规范化，再哈希

运行时会去除 instance id 两端空白、拒绝空值，并在哈希前最多接受 256 个字符。存储的 hash 会规范化为 sha256:<64 hexadecimal characters>；格式错误的预哈希值会被忽略，不会被当作凭据。

```python
from memory_manager.auth.agent_identity import agent_instance_id_hash

instance_hash = agent_instance_id_hash("codex-local-install")
# sha256:<64 hexadecimal characters>
```

## 每次本地安装保留一个值

在 repository 外保存一个非机密的 instance 值，并将它与访问凭据一起发送。同一安装重启后继续复用它；不同的本地 profile 应选择不同的值。

```http
X-API-Key: <your-assigned-api-key>
X-Memory-OS-Agent-ID: codex
X-Memory-OS-Agent-Instance-ID: <stable-local-instance-id>
```

## 边界语义是明确的

memory_agent_boundary 会将 caller 的 agent_id 和 instance hash 与数据行中的值比较。两者都匹配时为 self；agent_id 匹配但 hash 不同时为 same_agent_other_instance；缺少可比较身份时报告为 unverified 或 unknown。这些标签用于解释归因，不能替代 token authorization。

```json
{
  "relation": "self",
  "ownership": "current_agent",
  "boundary_authority": "attribution_only",
  "current_agent_trust": "client_asserted"
}
```

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