honcho-memory

使用 Honcho 作为记忆

Honcho 是 Agent 的记忆层。你将对话中的消息提供给它；它会在后台对这些消息进行推理，并构建每位参与者的表征。你可以随时用自然语言询问有关用户的问题（“他们有多懂技术？”、“他们想做什么？”），并获得有依据、经过推理的回答。

此技能适用于 Honcho 已连接到你的情况，你希望使用它。如果你是要从头开始将 Honcho 添加到代码库，请使用 honcho-integration 技能。

哪些内容稳定，哪些内容需要查阅。 下文的概念以及回忆／记录循环很少变化——可以依赖这些内容。经常变化的具体信息——确切的集成列表、工具名称、安装命令、请求头和默认值——在此仅作示例；请以链接的文档（以及你当前实际可用的工具列表）为准，并在需要了解详情时查阅。

心智模型

• Peer — 任意参与者，无论是人类还是 AI。你和用户都是 Peer。Honcho 会为它观察到的 Peer（通常是用户，而不是你）构建表征。
• Session — 一个对话线程；消息保存在 session 中。Honcho 会结合一个 session 中的消息进行推理，因此应将每个 session 限定在一个连贯的上下文中（对话、频道、任务或项目），并将该上下文中的轮次保存在同一个 session 中，而不是拆分到许多零散的 session 中。对于低频或零散输入，应追加到一个持续进行的 session，而不是每次都新建一个。请参阅设计模式和推理。
• Message — 你提供的原始对话轮次。没有消息 → 没有推理 → 没有记忆。
• Conclusion — Honcho 推导出的（或你存储的）有关某个 Peer 的事实。Conclusion 为表征提供支持。
• Representation / peer card — 对某个 Peer 综合形成的理解，可通过 chat 查询。Peer 的表征会累积所有包含该 Peer 的 session 中的信息——这就是跨对话记忆。限定在 session 范围内的数据（近期消息、摘要）则保留在各自的 session 中。

推理会异步进行。记录一轮对话后，不要轮询或等待——表征会在后台更新，下次询问时内容会更丰富。

循环：回忆 → 回复 → 记录

每次对话都这样做。这就是此技能的全部内容。

1. 每次对话一次——确保存在一个以你和用户为 Peer 的 session（观察用户，不要观察你自己）。
2. 回复前，在个性化有帮助时——获取用户当前的上下文（get_session_context / get_representation），或搜索过往消息（search）——这些都是快速读取操作。若要针对具体问题给出经过推理的回答，请发起辩证对话（chat）——这需要几秒钟，因此仅在确有价值时使用。
3. 每轮交流后——记录用户的消息和你的回复。这是 Honcho 学习的基础。不要跳过。

此外，如果你了解到不想等后台推理自动提取的持久事实，可以直接存储一条结论。

回忆时会获取到什么

提取记忆有三种方式，按成本从低到高排列：

• 表征（get_representation）— Honcho 对用户综合形成的理解，以文本形式呈现，可直接放入系统提示词。读取几乎即时完成。
• 上下文（get_session_context）— 更完整的会话视图：会话摘要 + 覆盖对话的近期消息；并且，只有指定了 peer 时，才会附带该 peer 的表征。若未指定 peer，则内容仅限当前会话（近期轮次 + 摘要），不包含跨对话记忆。读取几乎即时完成。
• 辩证推理（chat）— 针对特定问题给出经过推理的自然语言回答（“这个用户喜欢怎样接收反馈？”）。会实时推理，因此需要几秒钟。纯粹读取无法回答问题时使用。

辩证推理（chat）还支持设置推理级别，以速度换取深度：从 minimal（快速查找事实），到 low（默认平衡级别），再到 max（针对最难问题进行深度综合）。选择能够回答问题的最低级别；级别越高，速度越慢、成本越高。各级别的完整说明和模型路由见 chat 文档。

---

选择接入方式

整个流程相同；具体操作取决于你如何接入 Honcho。优先选择专门构建的集成，而不是自行接入原始 MCP——它们会为你处理会话、peer 和记录流程，保持最新，并针对不同环境进行调优。

1. 你的环境有一流集成吗？有就使用它。 在 Claude Code 中，安装 Claude Code 插件（/plugin marketplace add plastic-labs/claude-honcho），即可开箱使用持久化记忆；此外还有适用于 OpenCode、LangGraph、CrewAI、Discord 等的插件/集成。查看始终保持最新的列表：https://honcho.dev/docs/v3/guides/overview.md。
2. 没有集成，但你有 MCP 工具（create_session、add_messages_to_session、chat，等等）→ 使用上述流程来驱动它们。MCP 服务会在连接时注入自己的使用指南，因此无需额外加载；若要自行连接客户端，请参阅下方的设置。这是已连接 Agent 的备用方案。
3. 终端中可以使用 honcho CLI → 使用 honcho-cli 技能，处理回忆/记录流程，并验证记忆是否确实在建立（消息是否已写入？表征是否在增长？为什么它不记得我？）。
4. 将 Honcho 集成到你自己的代码库中（而不只是使用已连接的实例）→ 使用 honcho-integration 技能。

如果不确定，请先列出可用工具，查找 Honcho 记忆工具（MCP 连接），然后再考虑使用 CLI。即使使用 MCP，若记忆似乎不正常，验证流程是否正常运行的最佳方式也是使用 honcho-cli 技能。

---

设置（尚未连接时）

你需要一个 Honcho API 密钥——在 https://app.honcho.dev 免费获取（以 hch- 开头）。然后通过上述选定的方式连接——使用专门构建的集成（推荐），或直接连接：

• MCP — 将客户端指向 https://mcp.honcho.dev，并使用 Authorization: Bearer hch-your-key-here。可选的 X-Honcho-Workspace-ID 会在省略 workspace_id 工具参数时填入该参数；否则，请在每次调用时传入 workspace_id（使用 list_workspaces 查找 ID）。添加配置后，请彻底重启客户端。各客户端（Claude Desktop、Cursor、Codex、Windsurf、VS Code、Cline、Zed）的配置示例见 MCP 集成指南。连接后，服务会自动告知助手如何使用这些工具。
• CLI — 使用 honcho-cli 技能。

---

经验法则

• 始终记录每轮对话。 只有你传入的消息才会增加记忆。记录是唯一不可省略的步骤。
• 是否对助手建模由你决定。 在助手对等方上设置 observe_me: false，即可跳过对它建模——这只适用于确定性机器人（输出是脚本化的，没有有意义的内容可供建模）。对于 AI 助手，如果你也想为 Agent 建模，保持观察开启即可。
• 每个实体使用一个稳定的对等方 ID。 在所有会话和渠道中，对同一个人重复使用相同的 peer_id；拆分成不同 ID（user、user-web、user-discord）会生成彼此独立的表征，并使记忆碎片化。
• 将会话限定在连贯的上下文范围内。 Honcho 会综合推理一个会话中的消息。将会话限定为一次活跃的交互（按对话、渠道、任务或项目划分）；当上下文确实重置时（新话题、新的一天），创建新会话；只要上下文需要持续积累，就重复使用现有会话。将同一上下文的各轮对话放在一个会话中，能形成连贯的表征；分散在多个会话中则会使其碎片化。
• 不要等待推理完成。 推理是异步的。现在就回复；下次再用时，表征会更加丰富。
• 读取成本低，推理成本高。 获取表征或上下文（get_session_context、get_representation、search）几乎是即时的读取操作——可以放心使用。辩证式对话（chat）会实时推理，需要几秒钟，因此只在确实需要经过推理的答案时使用，而不是每轮都用。
• 存储前先检查。 后台推理会自动得出大多数结论。只有当你希望某个长期有效的事实能立即使用时，才手动存储结论；先用 list/query 检查，避免重复。
• 每个应用或用户上下文使用一个工作区。 不要将同一用户的记忆分散到多个工作区。
• 使用共享工作区和对等方 ID，在多个工具间统一记忆。 若要让同一用户在多个应用或 Agent（例如 Claude Code、Cursor 或你自己的应用）中拥有连续的记忆，请让它们使用同一个工作区，并重复使用相同的对等方 ID——这个共享 ID 会将表征关联起来。请参阅统一记忆设置。

资源

以下是便于大模型使用的 Markdown 版本（在任意 Honcho 文档 URL 后附加 .md，即可获取原始 Markdown；完整的机器可读索引位于 https://honcho.dev/docs/llms.txt）。

• 完整文档索引（供 Agent 使用）：https://honcho.dev/docs/llms.txt
• 所有集成和插件：https://honcho.dev/docs/v3/guides/overview.md
• MCP 服务和客户端设置：https://honcho.dev/docs/v3/guides/integrations/mcp.md
• 完整的 MCP 使用指南：https://raw.githubusercontent.com/plastic-labs/honcho/refs/heads/main/mcp/instructions.md
• Agent 开发概览：https://honcho.dev/docs/v3/documentation/introduction/vibecoding.md
• CLI 参考：https://honcho.dev/docs/v3/documentation/reference/cli.md