# Memory Console 指南

在 /me 浏览个人 Web 控制台，以检查、搜索和更正记忆、查看 agent 归属、管理空间、导出记录并配置设置。

- Canonical: https://docs.xmemo.dev/zh/docs/guides/memory-console
- Locale: zh-CN
- Content-Locale: zh-CN
- Canonical-Content-Digest: 4aea951f5bf9f94fc8465b3b4089d9fe087baec4eab55f135bd33c84f878c7e8
- Edition-Digest: 39f12fe6654750a2d9eb8c67c1a6ad6c1b9aebb9d7788bf51f5482a9eb53ad02
- Source-Revision: sha256:ed359fa7ac7e89021568a98e14885eb4624796d3c8401d0c47d80a787520d3cf

## 用户目标与控制台概述

Memory Console 在 /me（别名为 /memory-console）提供了可视化 Web 界面，用于检查、搜索和管理记忆记录、agent 连接、项目以及安全设置。开发者和团队成员不必仅通过 CLI 命令或 MCP 工具进行交互，而是可以使用控制台来审核 agent 记录的内容、更正不准确的记忆、检查 agent 归属、管理 API 令牌以及控制数据导出和删除。

## 可用性与前提条件

已通过身份验证的用户可以在任何现代浏览器中使用 Memory Console。控制台布局将各项能力组织为不同工作区和访问部分，可通过侧边栏导航和直接 URL 哈希锚点进行访问：

- 认证要求：需要处于活动状态的用户会话。未认证的访问将被重定向到 /login（登录页面）。
- 概述 (#overview)：个人记忆工作区、近期活动、连接的 agent 以及存储信号的快速摘要。
- 记忆 (#memory)：使用全文搜索、类型过滤器和来源过滤器搜索、筛选、检查和编辑记忆记录。
- Knowledge (#knowledge)：查看和维护供经授权的 agent 查阅的技术知识文档。
- 项目 (#projects)：浏览项目工作区、上下文说明以及与项目关联的记忆。
- Cloud Skill (#skills)：编写、导入和管理过程性云端技能。带有 Preview 徽章，并在您的账户启用时可用。
- Dream (#dream)：在反复出现的模式和综合建议成为持久记忆之前对其进行审查。带有 Preview 徽章，并在您的账户启用时可用。
- Agent (#agents)：查看连接到此工作区的 agent、检查上次活动时间戳并审查权限。
- 团队 (#teams)：创建和管理团队、邀请成员并配置团队工作区角色。带有 Preview 徽章，并在您的账户启用时可用。
- 个人资料 (#profile)：账户身份、邮箱验证状态和个人偏好设置。
- 会话 (#sessions)：查看活动的登录会话和已连接的设备。
- API 密钥 (#api-keys)：为 CLI、agent 和自动化签发、轮换和撤销具有作用域的访问令牌。
- 设置 (#memory-settings)：隐私态势、安全模式、数据导出请求和记忆删除控制。

## 一项完整任务：检查并更正合成记忆

在此演练中，您将定位在快速入门指南期间保存的合成约定记忆，检查其 agent 归属，在控制台中更正其文本，验证更新，并确认个人工作区边界。

## 1. 在记忆面板中定位合成记忆

导航至 /me，并通过在侧边栏中点击 Memories 或导航至 #memory 打开记忆面板。在搜索栏中输入 "demo project timestamp format" 或按 Facts 类别进行筛选。列表呈现匹配的记忆卡片，显示摘要内容、创建时间和可见性徽章。

```bash
# Access personal workspace
https://xmemo.dev/me#memory

# Access team workspace with explicit team context
https://xmemo.dev/me?space=<team_id>#memory
```

## 2. 检查 agent 归属与元数据

点击记忆卡片展开 Explain 面板。控制台显示写入时捕获的来源溯源与归属详情：

- 写入者类型与 agent 标识：显示记忆是由 agent、人类用户还是导入的脚本写入，并附带 agent 名称和 ID。
- Agent 实例显示：显示特有的 agent 实例标识符 (agent_instance_display)，以区分同一 agent 的独立运行。
- 设备与传输：显示设备标签 (device_label) 以及提交写入时所使用的传输通道。
- 可见性与作用域：指明记录是个人独享还是团队共享 (team_id)，并附带项目和 bucket 分配情况。
- 版本历史记录：显示当前修订版本号，并链接到版本谱系抽屉。

## 3. 内联更正记忆内容

点击记忆卡片上的 Edit 按钮打开内联编辑器。更新内容以反映完善后的项目约定，然后点击 Save：

- 更新内容：将 "demo project timestamp format" 更改为 "Demo project timestamps use UTC with ISO 8601 formatting."。
- 保存操作：控制台发出带有 CSRF 保护的已认证更新请求，递增修订版本计数器。
- 冲突保护：如果 agent 同时更新了该记忆，控制台会检测到修订版本不匹配 (HTTP 409)，并提示 "CAS version conflict: Data has been updated elsewhere. Please refresh and try again."，以便在覆盖之前查看最新内容。

## 4. 跨控制台与 agent 召回验证更新

保存后，控制台会显示成功通知并更新记忆卡片。版本谱系抽屉显示先前的修订版本已被新的修订版本所取代。要验证连接的 agent 是否能立即观察到更正，请在终端中执行 recall：

```bash
node scripts/xmemo-skill.mjs recall --query "demo project timestamp format" --limit 1
```

## 可观察结果

成功的控制台更正会在 Web UI 和 agent 界面上产生可观察的变化：

- Web 控制台 Toast：屏幕底部出现确认提示（"Memory updated"）。
- 卡片呈现：卡片立即显示更新后的文本、刷新后的时间戳和递增后的修订版本索引。
- 谱系抽屉：版本谱系抽屉显示词级 diff，将先前的修订版本与更新后的文本进行比对。
- Agent 召回输出：对 "demo project timestamp format" 的查询将返回更新后的文本及其最新修订版本引用。

## Agent 可以访问的内容

Agent 和控制台用户在不同的身份验证和权限边界下运行：

- 控制台权限：控制台用户通过带有 CSRF 验证的浏览器 Cookie 访问数据。控制台中的操作反映了登录的用户个人资料。
- Agent 权限：Agent 使用在 API 密钥面板 (#api-keys) 中签发的带作用域 API 密钥或 OAuth 令牌进行身份验证。允许的令牌作用域包括 memory:read、memory:write、knowledge:read、ledger:read、ledger:write 和 read:audit。
- Agent 可见性边界：Agent 无法查看账户密码、活动浏览器会话或账单详情。签发了个人令牌的 agent 只能查询个人记忆和公共知识；除非显式绑定到该团队，否则无法检查团队工作区。

## 共享与存储边界

Memory Console 强制对个人数据和团队工作区进行严格隔离：

- 空间选择：空间选择器通过查询参数 ?space=<team_id>（由 useSpaceContext 管理）在个人记忆和团队工作区之间切换。省略该参数或设置 ?space=personal 会将视图范围限定为个人记忆。
- 设置隔离：浏览团队空间时，设置面板 (#memory-settings) 会自动隐藏，以防止跨租户配置漂移。在团队空间中尝试打开设置会将活动空间重置为 Personal。
- 数据导出边界：用户可以从设置 (#memory-settings) 请求安全保密的导出归档 (/api/v1/me/export-requests)。个人导出包括个人记忆记录、版本谱系、个人账本交易和个人文档。团队记忆严格排除在个人导出之外。
- 导出下载授权：生成的导出归档需要通过 sudo 质询以获取临时下载授权令牌，然后才能获取 xmemo-personal-export.zip。导出工件可随时撤销和删除。
- 记忆删除控制：用户可以在确认后删除单条记忆、清除所有记忆，或通过确认其账户邮箱并输入确认短语 "RESET MY XMEMO MEMORY" 来重置记忆。自助式账户注销要求在删除前转移名下拥有的团队 (HTTP 409)。
- TODO 入口点：控制台在项目 (#projects) 下的项目卡片中将 TODO 显示为聚合计数器，显示与每个工作区关联的未完成行动项数量。
- 账本入口点：账本记录作为可筛选的类型类别显示在记忆 (#memory) 下，可在 API 密钥 (#api-keys) 下对 API 令牌划分作用域 (ledger:read, ledger:write)，并包含在个人数据导出归档中。

## 故障恢复

使用以下步骤解决常见的控制台错误和访问问题：

- 搜索中未找到记忆：检查空间选择器是否设置为正确的空间（个人对比团队 ?space=<team_id>）。清除工具栏中处于活动状态的筛选器下拉菜单（如 Type 或 Visibility）以扩大搜索结果。
- 并发编辑错误 (HTTP 409)：如果 agent 或其他标签页在您打开编辑时更新了该记忆，控制台会显示 "CAS version conflict: Data has been updated elsewhere. Please refresh and try again."。刷新列表、检查新修订版本并重新应用您的更改。
- 侧边栏中看不到设置选项：查看团队空间时，设置会被隐藏。打开侧边栏中的空间下拉菜单并切换回 Personal 工作区，以恢复对设置 (#memory-settings) 的访问。
- 导出下载授权已过期：Sudo 下载授权令牌的有效期很短。在下载提示中重新输入您的账户凭据以生成新的下载授权。

## 相关参考

有关底层机制和 API 契约，请参阅相关的概念和工具文档：

- 快速入门：/docs/quickstart 了解初始设置和合成记忆创建。
- 记忆更正：/docs/concepts/memory-correction 了解修订历史和取代语义。
- 记忆删除：/docs/concepts/memory-deletion 了解软删除和墓碑生命周期。
- 来源溯源与归属：/docs/concepts/provenance-attribution 了解 agent 实例和写入者类型规范。
- 项目：/docs/concepts/projects 了解项目工作区边界和上下文范围。
- 团队：/docs/capabilities/teams 了解团队工作区创建、角色和协作。
- 知识库：/docs/concepts/knowledge-bases 了解文档知识库和发布规则。
- Cloud Skills：/docs/concepts/cloud-skills 了解过程性云端技能编写。
- Dream 反思：/docs/concepts/dream-reflection 了解模式分析概念。
- 治理与保留：/docs/concepts/governance-retention 了解保留策略和 DSAR 控制。
- 数据边界：/docs/security/data-boundary 了解加密、多租户和隔离。
- TODO 工具：/docs/tools/todos 了解 agent 任务跟踪工具参数。
- 账本工具：/docs/tools/ledger 了解金融交易工具参数。

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