memos-memory-guide

MemOS 本地记忆 — Agent 指南

本技能介绍如何使用 MemOS 记忆工具，以便可靠地搜索和使用用户的长期对话历史、查询团队共享数据、共享任务，以及发现或获取可复用的技能。

存在两个共享范围，切勿混淆：

• 本地 Agent 共享： 仅对同一 OpenClaw 工作区中的 Agent 可见。
• 团队共享： 通过配置的团队服务对队友可见。

每轮如何提供记忆

• 自动回忆（钩子）： 每轮开始时，系统会根据用户当前消息执行记忆搜索，并将相关的过往记忆注入你的上下文。你无需为此调用任何工具。
• 自动回忆不足时： 如果用户的消息很长、含糊不清，或自动搜索未返回任何记忆，你应自行生成简短、聚焦的查询，并调用 memory_search。
• 记忆隔离： 每个 Agent 只能查看自己的本地私有记忆和本地 public 记忆。只有在使用 scope="group" 或 scope="all" 搜索时，才会显示团队共享数据。

工具 — 功能与调用时机

memory_search

• 功能： 搜索长期对话记忆，查找过往对话、用户偏好、决定和经历。返回相关摘录，其中包含 chunkId，并可能包含 task_id。只返回属于当前 Agent 或标记为公开的记忆。
• 调用时机：
  • 自动回忆未运行或未返回任何内容。
  • 用户的查询很长或不清晰——自行生成简短查询，并调用 memory_search(query="...")。
  • 需要从不同角度搜索（例如按 role='user' 筛选）。
• 参数：
  • query（字符串，必填）——自然语言搜索查询。
  • scope（字符串，可选）——'local'（默认值），搜索当前 Agent 和本地共享记忆；或使用 'group' / 'all' 包含团队共享记忆。
  • maxResults（数字，可选）——如果首次搜索范围太窄，可调高此值。
  • minScore（数字，可选）——如果召回条件过于严格，可略微调低此值。
  • role（字符串，可选）——按 'user'、'assistant'、'tool' 或 'system' 筛选本地结果。

memory_get

• 功能： 获取记忆片段的完整原文。用于核实搜索结果中的确切细节。
• 调用时机： memory_search 命中项看起来相关，但你需要查看完整原文，而非仅查看摘要或摘录。
• 参数：
  • chunkId（字符串，必填）——搜索结果中的 chunkId。
  • maxChars（数字，可选）——返回的最大字符数（默认值为 4000，最大值为 12000）。

memory_write_public

• 功能： 创建全新的本地共享记忆。在使用 memory_search 时，同一 OpenClaw 工作区中的所有 Agent 都可查看这些记忆。此操作不会将任何内容发布到团队服务。
• 调用时机： 在多 Agent 或协作场景中，需要从头创建新的持久共享笔记时（例如共享决定、约定、配置或工作流）。如果已有要公开的特定记忆片段，则不要使用此工具。
• 参数：
  • content（字符串，必填）——要写入本地共享记忆的内容。
  • summary（字符串，可选）——内容的简短摘要。

memory_share

• 功能： 将已有记忆分享给本地 OpenClaw Agents、团队，或两者。
• 调用时机：
  • 如果要将对话内容分享给团队或 hub，请先检索与该内容相关的记忆，以获取正确的 chunkId，然后再分享。
  • target='agents'（默认）：如果这些记忆明显有助于同一工作区中的其他 Agent，可以主动分享，无需询问用户。
  • target='hub' 或 'both'：只有在用户明确同意后，才能在内容对协作者有帮助时分享——简要说明并先征求同意，然后再调用 hub/both（必须配置 Hub）。绝不可在未告知的情况下分享至 Hub。
• 不要在以下情况下使用： 要创建没有现有 chunk 的全新共享笔记时，请改用 memory_write_public。
• 参数：
  • chunkId（字符串，必填）——现有记忆 chunk ID。
  • target（字符串，可选）——'agents'（默认）、'hub' 或 'both'。
  • visibility（字符串，可选）——当 target 包含团队时的团队可见性：'public'（默认）或 'group'。
  • groupId（字符串，可选）——当 visibility='group' 时可选的团队组 ID。

memory_unshare

• 功能： 取消将现有记忆分享给本地 Agent、团队，或两者。
• 调用时机： 当某条记忆不应再对当前 Agent 之外的对象可见，或需要从团队中移除时。
• 参数：
  • chunkId（字符串，必填）——现有记忆 chunk ID。
  • target（字符串，可选）——'agents'、'hub' 或 'all'（默认）。
  • privateOwner（字符串，可选）——仅在较旧的公共记忆未记录原始所有者时使用的备用参数，较少见。

task_summary

• 功能： 获取完整任务的详细摘要：标题、状态、叙述性摘要和相关技能。用于 memory_search 返回包含 task_id 的命中结果，且你需要了解完整情况时。保留关键信息：URL、文件路径、命令、错误代码和分步说明。
• 调用时机： memory_search 的命中结果包含 task_id，且你需要了解该任务的完整上下文时。
• 参数：
  • taskId（字符串，必填）——来自 memory_search 命中结果的 task_id。

skill_get

• 功能： 通过 skillId 或 taskId 获取已验证的技能（经验指南）。如果传入 taskId，系统会自动查找相关技能。
• 调用时机： 搜索命中结果包含 task_id，且该任务有“如何再次完成此操作”的指南时。使用此工具遵循相同方法或复用步骤。
• 参数：
  • skillId（字符串，可选）——直接指定技能 ID。
  • taskId（字符串，可选）——任务 ID；系统会查找与该任务关联的技能。
  • 必须提供 skillId 或 taskId 中的至少一个。

skill_search

• 功能： 使用自然语言搜索可用技能。搜索你自己的技能、本地共享技能，或两者。也可以包含团队技能。
• 调用时机： 当前任务需要你尚不具备的能力或指南时。先使用 skill_search 查找；找到后，使用 skill_get 阅读，然后使用 skill_install 加载，以供后续回合使用。
• 参数：
  • query（字符串，必填）——所需技能的自然语言描述。
  • scope（字符串，可选）——'mix'（默认，自有技能 + 本地共享技能）、'self'、'public'（仅本地共享技能），或包含团队搜索结果的 'group' / 'all'。

skill_install

• 功能： 将已学习的技能安装到 Agent 工作区，使其永久可用。安装后，该技能会在未来会话中自动加载。
• 调用时机： 在 skill_get 之后，当该技能对持续使用有帮助时。
• 参数：
  • skillId（字符串，必填）——要安装的技能 ID。

skill_publish

• 用途： 与本地 Agent 分享技能，或将其发布到团队。
• 调用时机： 你有一项实用技能，其他 Agent 或团队可能会从中受益。
• 参数：
  • skillId（字符串，必填）— 要发布的技能 ID。
  • target（字符串，可选）— 'agents'（默认）或 'hub'。
  • visibility（字符串，可选）— 当 target='hub' 时，使用 'public'（默认）或 'group'。
  • groupId（字符串，可选）— 当 target='hub' 且 visibility='group' 时，可选的团队群组 ID。
  • scope（字符串，可选）— 兼容旧调用的别名。新调用优先使用 target + visibility。

skill_unpublish

• 用途： 停止与本地 Agent 分享、移除已发布到团队的副本，或同时执行两者。
• 调用时机： 你想停止分享之前发布的技能。
• 参数：
  • skillId（字符串，必填）— 要取消发布的技能 ID。
  • target（字符串，可选）— 'agents'（默认）、'hub' 或 'all'。

network_memory_detail

• 用途： 获取团队搜索结果背后的完整内容。
• 调用时机： memory_search 结果来自团队，且你需要完整的共享记忆内容。
• 参数： remoteHitId。

task_share / task_unshare

• 用途： 将本地任务分享给团队，或之后将其移除。
• 调用时机： 某项任务对你的群组或整个团队有价值，应当能通过共享搜索找到。
• 参数： taskId，以及必要时的分享可见性/范围。

network_skill_pull

• 用途： 将团队共享的技能包拉取到本地存储。
• 调用时机： skill_search 找到了一项实用的团队技能，而你想在本地或离线使用它。
• 参数： skillId。

network_team_info

• 用途： 返回当前团队服务的连接信息、用户、角色和群组。
• 调用时机： 你需要确认团队分享是否已配置，或当前客户端属于哪些群组。
• 请先调用此工具，再调用： memory_share(... target='hub'|'both')、memory_unshare(... target='hub'|'all')、task_share、task_unshare、skill_publish(... target='hub')、skill_unpublish(... target='hub'|'all') 或 network_skill_pull。
• 参数： 无。

memory_timeline

• 用途： 展开记忆搜索结果的上下文。传入搜索结果中的 chunkId，即可读取周边的对话消息。
• 调用时机： memory_search 结果相关，但你需要查看周边对话。
• 参数：
  • chunkId（字符串，必填）— 来自 memory_search 结果的 chunkId。
  • window（数字，可选）— 上下文窗口 ±N 条消息，默认为 2。

memory_viewer

• 用途： 显示 MemOS Memory Viewer URL。用户询问如何查看、浏览、管理或检查自己的记忆时，请调用此工具。它会返回用户可在浏览器中打开的 URL。
• 调用时机： 用户询问在哪里查看或管理自己的记忆。
• 参数： 无。

快速决策流程

1. 上下文中没有记忆，或自动召回没有结果 → 使用自行生成的简短查询调用 memory_search(query="...")。

2. 需要查看搜索结果的完整原文 → 调用 memory_get(chunkId="...")。

3. 搜索结果包含 task_id，且你需要完整上下文 → 调用 task_summary(taskId="...")。

4. 任务有你想遵循的经验指南 → 调用 skill_get(taskId="...") 或 skill_get(skillId="...")。如需以后使用，可选择调用 skill_install(skillId="...")。

5. 需要查看搜索结果对应的确切上下文对话 → 调用 memory_timeline(chunkId="...")。

6. 需要自己尚不具备的能力或指南 → 调用 skill_search(query="...", scope="mix")，发现可用技能。

7. 有对所有本地 Agent 都有用的新共享知识 → 调用 memory_write_public(content="...")。

8. 已有记忆片段，想要公开或隐藏它 → 调用 memory_share(chunkId="...", target="agents|hub|both") 或 memory_unshare(chunkId="...", target="agents|hub|all")。

9. 准备进行任何团队共享操作 → 如果不确定团队服务是否可用，先调用 network_team_info()。

10. 想要与本地 Agent 或团队共享技能，或停止共享 → 优先使用 skill_publish(skillId="...", target="agents|hub", visibility=...) 和 skill_unpublish(skillId="...", target="agents|hub|all")。

11. 用户询问在哪里查看或管理记忆 → 调用 memory_viewer() 并分享 URL。

编写优质搜索查询

• 优先使用简短、聚焦的查询（几个词或一个明确的问题）。
• 使用具体术语：名称、主题、工具或决策。
• 如果用户的消息很长，提炼一两个子查询，而不要粘贴整段消息。
• 若要专门查找用户说过的内容，请使用 role='user'。

记忆归属与 Agent 隔离

每条记忆都带有 owner 标签（例如 agent:main、agent:sales-bot）。系统会自动处理——你无需传入任何 owner 参数。

• **你的记忆：**所有工具（memory_search、memory_get、memory_timeline）都会自动将查询范围限定为你自己的 Agent 记忆。
• **本地共享记忆：**标记为本地共享的记忆对同一 OpenClaw 工作区中的所有 Agent 可见。使用 memory_write_public 创建此类记忆，或使用 memory_share(target='agents') 公开已有片段。
• **跨 Agent 隔离：**你无法查看其他 Agent 所有的记忆（公开记忆除外）。
• **工作原理：**系统从 OpenClaw 运行时上下文中识别你的 Agent ID，并在每次搜索、召回和检索时自动应用 owner 筛选。