# Memory MCP · Agent 自助接入

你正在接入 VET Memory MCP。不要要求用户复制、发送或粘贴任何访问 Key。

## 协议

1. `POST https://auth.eggyeggy.online/v1/auth/device/authorize`，JSON 为 `{"client_name":"Codex","scope":"memory.read memory.write"}`。
2. 将响应中的 `verification_uri_complete` 交给用户打开并登录确认。用户名和密码只在 VET 页面输入，绝不输入到 Agent 或终端。
3. 每隔响应 `interval` 秒向 `POST https://auth.eggyeggy.online/v1/auth/device/token` 发送 `{"device_code":"..."}`；收到 `authorization_pending` 时继续等待。成功时使用 `access_token`。
4. 对 Codex：将 token 写为用户环境变量 `VET_AGENT_KEY`，再执行：

```powershell
codex mcp add memory --url https://memory.eggyeggy.online/mcp --bearer-token-env-var VET_AGENT_KEY
```

5. 验证 MCP 可列出 Memory 工具，并实际调用 `memory_list_roots`；两者任一失败都必须报告“接入失败”，不得把本地 `.memory` 文件、静态配置或不可见工具面当成服务端成功。不得伪造 session ID，也不得自行调用 AIPD MCP 作为补救。

6. 选择环境时区分以下标识：`environment_key`（例如 `eggy-se`）只用于识别环境；`namespace_id` 必须是服务端返回的命名空间 UUID；环境路径（例如 `/environments/eggy-se`）和显示名称都不能当作 `namespace_id`。需要限定到某个环境时，先调用 `memory_list_environments` 按 `key` 精确匹配并使用返回的 `namespace_id`；若没有该项，再调用 `memory_list_roots` 按 `owner_id` 或 `path` 找到授权根并使用其 `id`。不需要限定环境时，省略 `namespace_id`，由服务端按当前 Key 的 ACL 检索。不要使用 `namespace="eggy-se"` 或猜测 UUID；否则会收到 `403 Forbidden`。

7. 安装与 MCP 配套的 `memory-aware` 行为 Skill，使 Agent 在历史、项目约定、技术环境、偏好或既有结论可能影响结果时主动调用 `memory_prepare_context`：

```powershell
$memorySkillDir = Join-Path $env:USERPROFILE ".codex\skills\memory-aware"
New-Item -ItemType Directory -Force -Path $memorySkillDir | Out-Null
Invoke-WebRequest "https://memory.eggyeggy.online/agent-skills/memory-aware/SKILL.md" -OutFile (Join-Path $memorySkillDir "SKILL.md")
New-Item -ItemType Directory -Force -Path (Join-Path $memorySkillDir "scripts") | Out-Null
Invoke-WebRequest "https://memory.eggyeggy.online/agent-skills/memory-aware/scripts/memory_capture_hook.py" -OutFile (Join-Path $memorySkillDir "scripts\memory_capture_hook.py")
```

重新启动 Codex 后生效。项目根目录的 `.memory/environment.json` 可以保存工程的 `environment_key`，但不能替代 MCP 请求中的 `namespace_id`；涉及环境的读写仍须按上面的步骤解析 UUID。其他支持 Skill/Hook 的 Agent 应安装同一文件；不支持持久 Skill 的客户端应把其中的检索规则加入自己的系统提示或会话启动 Hook。该行为层只在既有知识可能影响结果时检索，不能取代用户当前指令。

此 token 是统一 VET Agent Key。Memory 将它映射为该用户已授权的个人记忆空间。