Memory Console 指南

用户目标与控制台概述

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 类别进行筛选。列表呈现匹配的记忆卡片，显示摘要内容、创建时间和可见性徽章。

# 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：

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 了解金融交易工具参数。