# 在其他助手中使用个人记忆

个人记忆连接让支持 MCP 的外部助手读取你已经确认并同意分享的信息，也能提出新的记忆建议。这不是沙箱应用的 `platform.*` API，应用不能使用这条连接绕过 Bridge。

## 开放状态

个人记忆服务通过明确的环境配置开放。连接入口关闭或维护时，「连接的助手」会显示具体说明；客户端不能在本地服务不可用时自动切换生产。

生产连接地址：`https://agent.awell.one/mcp`。本地连接地址：`http://127.0.0.1:8787/mcp`。客户端需要支持 Streamable HTTP 与浏览器 OAuth 授权；不提供长期 API key 或把登录 cookie 当作授权凭据。

## 连接与管理

1. 在外部助手添加个人记忆地址。
2. 浏览器打开茄总并登录，选择允许该助手读取的个人资料类别。连接可能同时提供应用构建等能力，请阅读对应操作说明。
3. 在 Web 或 iOS 的「个人信息 → 连接的助手」逐条选择可以分享的信息。
4. 外部助手提出建议时，在同一页面修改、确认或忽略。确认前不会成为长期记忆。

默认只允许基本信息、偏好、习惯、目标与工作学习类别。类别是范围上限，不等于自动分享全部历史信息。健康、人际、未分类、检测到的敏感信息和不确定猜测暂不共享。已有信息修改后，旧共享确认失效，需要重新选择。

连接管理只能减少已经授予的操作和类别。增加权限或恢复移除的权限，需要在外部助手重新发起授权。撤销立即停止后续访问，但不能从外部服务收回已经发送或被其保存的信息。

## 核心工具

### `get_user_context`

参数为空对象。返回 `summary`、`facts`、`version`、`updated_at`、`has_more`、`offset`、`next_offset`、`next_uri`。只包含逐条确认分享、版本有效、类别允许的事实，不返回证据原文或完整对话。摘要由这组可见事实生成，不使用内部全量摘要。

### `propose_memory`

参数包括 `op`（`add`、`update`、`archive`）、`category`、`label`、`value`、`evidence`，修改或忘记时必须提供 `target_fact_id`。新增和修改必须提供内容；忘记可以省略内容。

字段名最多 40 字符，内容和一句证据各最多 300 字符。不接受额外字段、完整对话、多行证据、密钥或验证码。

新建议返回 `{ "id": "...", "status": "pending" }`，这不表示已经记住。相同且未过期的 pending 建议返回同一 ID；已经处理或过期的重复建议明确返回冲突。建议有效期 30 天。用户确认时会检查原信息是否被修改，冲突不会覆盖最新内容。

## 画像 Resource 与有限检索

支持 Resources 的客户端可以读取 `lifeos://profile/summary`（`application/json`）。内容与 `get_user_context` 相同；`version` 是 64 位 SHA-256 内容版本。重复读取检查版本即可获取最新上下文，不提供跨请求推送订阅。

`search_user_context` 需要 `context:search` 与 `profile:read`。参数 `query` 最多 200 字符，`offset` 是非负整数，`limit` 为 1 至 10。结果返回已分享的事实、版本、分页位置和 `next_offset`；不得把分页结果称为完整个人画像。单次序列化结果最多 16 KiB，画像概览最多 50 条；超出概览可按需检索，不会默默丢弃后声称完整。

检索不包含证据原文、内部全量摘要、待确认内容、知识库正文和数据表。仅有 `profile:read` 也可以继续读取：概览的 `next_uri` 是带版本的分页 Resource，或调用 `read_user_context_page`，参数为 `offset` 与概览返回的 `version`。当前共享内容变化时返回 conflict，要求重新读取概览，不继续使用过期页引用。续读不需要额外检索权限。

检索 offset 上限为 10,000。到达窗口但还有匹配结果时，返回 `window_exhausted: true` 与明确提示，请缩小 query 后重新搜索；不会把窗口结束伪装成全部数据已经读取。客户端不支持 Resources 时，使用 `get_user_context` 和 `read_user_context_page` 仍可读取同样内容。

## 权限与失败

- `profile:read`：读取允许分享的信息。
- `profile:propose`：提交添加建议。
- `profile:correct`：提交修改或忘记建议。
- `context:search`：额外允许按问题检索已分享的画像，必须同时允许 `profile:read`；默认不授予，增加时需要新的授权。

OAuth 授权码最多有效 5 分钟，access token 有效 10 分钟，refresh 授权最长 30 天。刷新会轮换令牌；旧令牌重放会撤销整组授权。令牌只以哈希保存，不进入 URL、产品页面或日志。

鉴权使用 HTTP 401/403；工具执行失败使用 MCP `isError` 与具体错误码。同一操作和参数连续失败 3 次会阻止继续空转，调整参数后可以继续。网络中断时先重新读取、核对操作结果，不自动重试不确定写入。

## 重要边界

MCP 服务不能读取外部助手的全部会话，也不能保证外部助手每次都会主动调用工具。是否自动载入上下文取决于客户端支持与其行为。连接后可在外部助手要求“读取我已经分享的个人信息”。

当前不开放知识库正文、数据表遍历或整库导出。外部助手的隐私、保存和训练规则由对应服务决定；在授权前检查对方的政策。