Honcho 内存

Honcho 是一个 AI 原生记忆后端，它在 Hermes 内置记忆系统之上增加了辩证推理和深度用户建模能力。Honcho 不是简单的键值存储，而是通过在对话发生后对其进行推理，持续维护一个关于用户是谁的模型 —— 包括用户的偏好、沟通风格、目标和行为模式。

Honcho 是一个记忆提供商插件

Honcho 已集成到 Memory Providers 系统中。以下所有功能都可以通过统一的记忆提供商接口使用。

Honcho 增加了什么

能力	内置记忆	Honcho
跨会话持久化	✔ 基于文件的 MEMORY.md / USER.md	✔ 服务端，通过 API
用户画像	✔ Agent 手动整理	✔ 自动辩证推理
会话摘要	—	✔ 会话范围的上下文注入
多 Agent 隔离	—	✔ 按 peer 分离画像
观察模式	—	✔ 统一观察或定向观察
结论（派生洞察）	—	✔ 服务端对模式进行推理
跨历史搜索	✔ FTS5 会话搜索	✔ 对结论进行语义搜索

辩证推理：在每个对话轮次之后（由 dialecticCadence 控制），Honcho 会分析这次交流，并推导出关于用户偏好、习惯和目标的洞察。这些洞察会随着时间积累，让 Agent 获得超越用户明确表达内容的更深层理解。辩证推理支持多轮深度（1–3 轮），并会自动选择冷启动/热启动提示词 —— 冷启动查询关注一般用户事实，而热启动查询优先关注会话范围的上下文。

会话范围上下文：基础上下文现在会包含会话摘要，以及用户表示和 peer card。这让 Agent 能够了解当前会话中已经讨论过的内容，从而减少重复并支持连续性。

多 Agent 画像：当多个 Hermes 实例与同一个用户对话时（例如，一个编码助手和一个个人助手），Honcho 会维护独立的 “peer” 画像。每个 peer 只看到自己的观察和结论，从而避免上下文交叉污染。

设置

hermes memory setup    # 从提供商列表中选择 "honcho"

或者手动配置：

~/.hermes/config.yaml

memory:
  provider: honcho

echo 'HONCHO_API_KEY=***' >> ~/.hermes/.env

在 honcho.dev 获取 API key。

架构

双层上下文注入

每一轮（在 hybrid 或 context 模式下），Honcho 都会组装两层上下文，并将其注入到 system prompt 中：

1. 基础上下文 —— 会话摘要、用户表示、用户 peer card、AI 自我表示，以及 AI 身份卡。按 contextCadence 刷新。这是“这个用户是谁”这一层。
2. 辩证补充 —— 由 LLM 综合生成的、关于用户当前状态和需求的推理。按 dialecticCadence 刷新。这是“当前什么最重要”这一层。

两层会被拼接在一起，并截断到 contextTokens 预算内（如果已设置）。

冷/热提示词选择

辩证推理会在两种提示词策略之间自动选择：

• 冷启动（尚无基础上下文）：通用查询 —— “这个人是谁？他们有什么偏好、目标和工作风格？”
• 热会话（已有基础上下文）：会话范围查询 —— “根据本会话目前已经讨论的内容，关于这个用户的哪些上下文最相关？”

这会根据基础上下文是否已经填充自动发生。

三个正交配置旋钮

成本和深度由三个相互独立的旋钮控制：

旋钮	控制内容	默认值
contextCadence	两次 context() API 调用之间的轮数（基础层刷新）	1
dialecticCadence	两次 peer.chat() LLM 调用之间的轮数（辩证层刷新）	2（推荐 1–5）
dialecticDepth	每次辩证调用中的 .chat() 轮数（1–3）	1

这些是正交的 —— 你可以频繁刷新上下文但不频繁进行辩证推理，也可以以较低频率执行深度多轮辩证推理。示例：contextCadence: 1、dialecticCadence: 5、dialecticDepth: 2 表示每轮刷新基础上下文，每 5 轮运行一次辩证推理，并且每次辩证运行执行 2 轮。

辩证深度（多轮）

当 dialecticDepth > 1 时，每次辩证调用都会运行多轮 .chat()：

• 第 0 轮：冷启动或热启动提示词（见上文）
• 第 1 轮：自我审计 —— 识别初始评估中的缺口，并从最近会话中综合证据
• 第 2 轮：协调 —— 检查前几轮之间是否存在矛盾，并生成最终综合结论

每一轮都会使用按比例调整的推理级别（早期轮次较轻，主要轮次使用基础级别）。可以使用 dialecticDepthLevels 覆盖每轮级别 —— 例如，对于深度为 3 的运行，使用 ["minimal", "medium", "high"]。

如果前一轮已经返回强信号（较长、结构化的输出），后续轮次会提前退出，因此深度 3 并不总是意味着 3 次 LLM 调用。

会话启动预热

在会话初始化时，Honcho 会在后台以完整配置的 dialecticDepth 发起一次辩证调用，并将结果直接交给第 1 轮的上下文组装。冷 peer 上的单轮预热通常会返回较薄的输出 —— 多轮深度会在用户开始说话之前运行审计/协调循环。如果预热结果在第 1 轮之前尚未完成，第 1 轮会回退到带有有界超时的同步调用。

查询自适应推理级别

自动注入的辩证推理会根据查询长度缩放 dialecticReasoningLevel：≥120 个字符时 +1 级，≥400 个字符时 +2 级，并受 reasoningLevelCap 限制（默认 "high"）。使用 reasoningHeuristic: false 可禁用该机制，使每次自动调用都固定为 dialecticReasoningLevel。可用级别：minimal、low、medium、high、max。

配置选项

Honcho 可在 ~/.honcho/config.json（全局）或 $HERMES_HOME/honcho.json（profile 本地）中配置。设置向导会为你处理这些。

完整配置参考

Key	默认值	描述
contextTokens	null（不限制）	每轮自动注入上下文的 token 预算。设置为整数（例如 1200）以进行限制。会在单词边界处截断
contextCadence	1	两次 context() API 调用之间的最小轮数（基础层刷新）
dialecticCadence	2	两次 peer.chat() LLM 调用之间的最小轮数（辩证层）。推荐 1–5。在 tools 模式下无关 —— 模型会显式调用
dialecticDepth	1	每次辩证调用中的 .chat() 轮数。限制在 1–3
dialecticDepthLevels	null	可选的每轮推理级别数组，例如 ["minimal", "low", "medium"]。会覆盖按比例设置的默认值
dialecticReasoningLevel	'low'	基础推理级别：minimal、low、medium、high、max
dialecticDynamic	true	为 true 时，模型可以通过工具参数按调用覆盖推理级别
dialecticMaxChars	600	注入到 system prompt 中的辩证结果最大字符数
recallMode	'hybrid'	hybrid（自动注入 + 工具）、context（仅注入）、tools（仅工具）
writeFrequency	'async'	何时刷新消息：async（后台线程）、turn（同步）、session（会话结束时批量），或整数 N
saveMessages	true	是否将消息持久化到 Honcho API
observationMode	'directional'	directional（全部开启）或 unified（共享池）。可使用 observation 对象覆盖以进行粒度控制
messageMaxChars	25000	通过 add_messages() 发送的每条消息最大字符数。超出则分块
dialecticMaxInputChars	10000	传给 peer.chat() 的辩证查询输入最大字符数
sessionStrategy	'per-directory'	per-directory、per-repo、per-session 或 global

Session strategy 控制 Honcho sessions 如何映射到你的工作：

• per-session —— 每次 hermes 运行都会获得一个新的 session。干净启动，通过工具使用记忆。推荐给新用户。
• per-directory —— 每个工作目录一个 Honcho session。上下文会跨运行累积。
• per-repo —— 每个 git 仓库一个 session。
• global —— 所有目录共用一个 session。

Recall mode 控制记忆如何流入对话：

• hybrid —— 上下文会自动注入到 system prompt 中，并且工具可用（模型决定何时查询）。
• context —— 仅自动注入，隐藏工具。
• tools —— 仅工具，不自动注入。Agent 必须显式调用 honcho_reasoning、honcho_search 等。

各 recall mode 下的设置：

设置	hybrid	context	tools
writeFrequency	刷新消息	刷新消息	刷新消息
contextCadence	控制基础上下文刷新	控制基础上下文刷新	无关 —— 无注入
dialecticCadence	控制自动 LLM 调用	控制自动 LLM 调用	无关 —— 模型显式调用
dialecticDepth	每次调用多轮	每次调用多轮	无关 —— 模型显式调用
contextTokens	限制注入	限制注入	无关 —— 无注入
dialecticDynamic	控制模型覆盖	不适用（无工具）	控制模型覆盖

在 tools 模式下，模型完全掌控 —— 它会在需要时调用 honcho_reasoning，并选择任何它想要的 reasoning_level。Cadence 和预算设置只适用于带有自动注入的模式（hybrid 和 context）。

观察（定向 vs. 统一）

Honcho 将对话建模为 peers 之间交换消息。每个 peer 都有两个观察开关，它们与 Honcho 的 SessionPeerConfig 一一对应：

开关	作用
observeMe	Honcho 会根据该 peer 自己的消息构建该 peer 的表示
observeOthers	该 peer 会观察另一个 peer 的消息（用于跨 peer 推理）

两个 peers × 两个开关 = 四个 flags。observationMode 是一个快捷预设：

预设	用户 flags	AI flags	语义
"directional"（默认）	me: on, others: on	me: on, others: on	完全相互观察。启用跨 peer 辩证推理 —— “根据用户说了什么以及 AI 回复了什么，AI 对用户了解到了什么。”
"unified"	me: on, others: off	me: off, others: on	共享池语义 —— AI 只观察用户消息，用户 peer 只进行自我建模。单观察者池。

使用显式 observation 块覆盖该预设，以进行按 peer 控制：

"observation": {
  "user": { "observeMe": true,  "observeOthers": true },
  "ai":   { "observeMe": true,  "observeOthers": false }
}

常见模式：

意图	配置
完全观察（大多数用户）	"observationMode": "directional"
AI 不应该根据自己的回复重新建模用户	"ai": {"observeMe": true, "observeOthers": false}
AI peer 有强 persona，不应该通过自我观察更新	"ai": {"observeMe": false, "observeOthers": true}

通过 Honcho dashboard 设置的服务端开关优先于本地默认值 —— Hermes 会在 session 初始化时将它们同步回来。

工具

当 Honcho 作为记忆提供商处于激活状态时，会有五个工具可用：

工具	用途
honcho_profile	读取或更新 peer card —— 传入 card（事实列表）进行更新，省略则读取
honcho_search	对上下文进行语义搜索 —— 原始摘录，不进行 LLM 综合
honcho_context	完整会话上下文 —— 摘要、表示、card、最近消息
honcho_reasoning	来自 Honcho 的 LLM 的综合答案 —— 传入 reasoning_level（minimal/low/medium/high/max）来控制深度
honcho_conclude	创建或删除结论 —— 传入 conclusion 创建，传入 delete_id 移除（仅限 PII）

CLI 命令

只有当 Honcho 是当前激活的记忆提供商时（config.yaml 中 memory.provider: honcho），才会注册 hermes honcho 子命令。先运行 hermes memory setup 并选择 Honcho；下一次调用时该子命令就会出现。

hermes honcho status          # 连接状态、配置和关键设置
hermes honcho setup           # 重定向到 `hermes memory setup`
hermes honcho strategy        # 显示或设置 session strategy（per-session/per-directory/per-repo/global）
hermes honcho peer            # 显示或更新 peer 名称 + 辩证推理级别
hermes honcho mode            # 显示或设置 recall mode（hybrid/context/tools）
hermes honcho tokens          # 显示或设置上下文和辩证推理的 token 预算
hermes honcho identity        # 初始化或显示 AI peer 的 Honcho 身份
hermes honcho sync            # 将 Honcho 配置同步到所有现有 profiles
hermes honcho peers           # 显示所有 profiles 中的 peer 身份
hermes honcho sessions        # 列出已知的 Honcho session 映射
hermes honcho map             # 将当前目录映射到一个 Honcho session 名称
hermes honcho enable          # 为当前 profile 启用 Honcho
hermes honcho disable         # 为当前 profile 禁用 Honcho
hermes honcho migrate         # 从 openclaw-honcho 迁移的分步指南

从 hermes honcho 迁移

如果你之前使用过独立的 hermes honcho 设置：

1. 你现有的配置（honcho.json 或 ~/.honcho/config.json）会被保留
2. 你的服务端数据（memories、conclusions、user profiles）保持完整
3. 在 config.yaml 中设置 memory.provider: honcho 即可重新激活

不需要重新登录或重新设置。运行 hermes memory setup 并选择 “honcho” —— 向导会检测你现有的配置。

完整文档

请参阅 Memory Providers — Honcho 获取完整参考。