title: “Honcho — Configure and troubleshoot Honcho memory for Hermes” sidebar_label: “Honcho” description: “Configure and troubleshoot Honcho memory for Hermes”

{/* 本页面由 website/scripts/generate-skill-docs.py 根据技能对应的 SKILL.md 文件自动生成。请直接编辑源文件 SKILL.md，而非此页面。 */}

Honcho

用于配置及排查 Hermes 中的 Honcho 内存相关问题。

技能元数据

参考：完整的 SKILL.md 文件

:::info 以下是当触发该技能时 Hermes 所加载的完整技能定义。技能激活后，智能体看到的指令即为此内容。

::

Hermes 的 Honcho 内存功能

Honcho 提供了基于人工智能的跨会话用户建模功能。它能够跨多次对话识别用户身份，为每个 Hermes 用户档案赋予独立的身份标识，同时实现统一的用户视图。

适用场景

• 部署 Honcho（云部署或自托管）
• 解决内存功能失效/节点无法同步的问题
• 构建多配置文件环境，使每个 Agent 都拥有独立的 Honcho 节点
• 调整观察频率、召回率、推理深度或写入频率等参数
• 了解五种 Honcho 工具的功能及其适用场景
• 配置上下文额度与会话摘要注入功能

部署指南

云部署（app.honcho.dev）

hermes memory setup honcho
# select "cloud", paste API key from https://app.honcho.dev

自主托管模式

hermes memory setup honcho
# select "local", enter base URL (e.g. http://localhost:8000)

参见：https://docs.honcho.dev/v3/guides/integrations/hermes#running-honcho-locally-with-hermes

验证

hermes honcho status    # shows resolved config, connection test, peer info

架构设计

基础上下文注入

当 Honcho 将上下文注入系统提示词中（在“混合模式”或“上下文检索模式”下），它会按以下顺序构建基础上下文模块：

1. 会话摘要——当前会话的简短概要（置于最前端，以便模型快速保持对话连贯性）
2. 用户画像——Honcho 所积累的关于该用户的模型信息（包括偏好、事实及行为模式）
3. AI 对等体卡片——该 Hermes 配置下 AI 对等体的身份标识

若存在之前的会话，会话摘要会在每个对话轮次开始时由 Honcho 自动生成。这样无需重新回放完整历史记录，即可让模型快速进入工作状态。

冷启动/热启动提示词选择

Honcho 会自动在两种提示词策略之间进行选择：

无需手动配置此功能——系统会根据会话状态自动选择相应策略。

对等体机制

Honcho 将对话视为对等体之间的交互。Hermes 会在每个会话中创建两个对等体：

• 用户对等体（peerName）：代表人类用户。Honcho会根据观察到的消息构建该用户的表征。
• AI对等体（aiPeer）：代表当前的Hermes实例。每个配置文件都会对应一个独立的AI对等体，从而使智能体能够形成各自的独立认知。

观察功能

每个对等体都包含两个观察开关，用于控制Honcho从哪些方面获取信息：

默认设置：四个开关均为开启状态（实现完全的双向观察）。

可在 honcho.json 文件中为每个对等体单独配置这些选项：

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

或者使用简写的预设配置：

在 Honcho 控制面板 中进行的设置会在会话启动时同步回来——服务器端配置优先于本地默认设置。

会话

会话决定了消息和观测数据存储的范围。可用策略如下：

可手动覆盖配置：hermes honcho map my-project-name

回忆模式

智能体访问 Honcho 内存的方式：

三个相互独立的调节参数

Honcho 的辩证行为由三个独立维度控制。分别调整这些参数不会相互影响：

频率（何时）

控制辩证逻辑调用和上下文调用的频率。

较高的间隔值意味着辩证式大语言模型被调用的频率更低。例如，将 dialecticCadence 设置为 2 表示引擎每隔一轮才调用一次；而设置为 1 则表示每轮都会调用。

推理深度（轮数）

用于控制 Honcho 对每个查询执行多少轮辩证式推理。

当 dialecticDepth 设置为 2 时，Honcho 会进行两轮辩证式推理。第一轮生成初步答案，第二轮则对答案进行优化。

dialecticDepthLevels 允许您分别为每一轮独立设置推理层级：

{
  "dialecticDepth": 3,
  "dialecticDepthLevels": ["low", "medium", "high"]
}

如果省略 dialecticDepthLevels，则轮次将使用基于 dialecticReasoningLevel（即基础值）计算出的按比例分配的层级：

这种方式能在早期轮次保持较低成本，同时在最终合成阶段使用最大深度。

会话启动时的深度设置。 会话启动前的预热阶段会在第1轮之前在后台运行完整配置的 dialecticDepth。在对冷启动的合作伙伴进行单轮预热时，通常只能得到较为简略的输出——而多轮深度预温则会在用户发言之前就完成审核/对齐流程。第1轮会直接使用预热结果；如果预热未能及时完成，第1轮则会回退为带有时间限制的同步调用。

级别（难度）

用于控制每轮辩证推理的强度。

更高的级别能生成更丰富的合成结果，但会在 Honcho 后端消耗更多令牌。

多配置文件设置

每个 Hermes 配置文件拥有独立的 Honcho AI 对象，同时共享相同的工作空间（用户上下文）。这意味着：

• 所有配置文件均显示相同的用户信息呈现方式
• 每个配置文件会构建独立的 AI 身份及观测数据
• 由某个配置文件生成的结论可通过共享工作空间被其他配置文件查看

使用 Honcho 同伴功能创建配置文件

hermes profile create coder --clone
# creates host block hermes.coder, AI peer "coder", inherits config from default

--clone 参数在 Honcho 中的作用：

1. 在 honcho.json 文件中创建一个 hermes.coder 主机配置块；
2. 设置 aiPeer: "coder"（即对应的配置文件名称）；
3. 沿用默认值设置 workspace、peerName、writeFrequency、recallMode 等参数；
4. 立即在 Honcho 中创建该对应节点，确保在接收第一条消息之前它就已经存在。

补充现有配置文件

hermes honcho sync    # creates host blocks for all profiles that don't have one yet

每个配置文件的独立设置

可覆盖主机块中的任何设置：

{
  "hosts": {
    "hermes.coder": {
      "aiPeer": "coder",
      "recallMode": "tools",
      "dialecticDepth": 2,
      "observation": {
        "user": { "observeMe": true, "observeOthers": false },
        "ai": { "observeMe": true, "observeOthers": true }
      }
    }
  }
}

工具

该智能体拥有 5 个双向的 Honcho 工具（在“上下文回溯”模式下会隐藏）：

honcho_profile

读取或更新对方信息卡片——其中包含精心整理的关键信息（名称、角色、偏好及沟通风格）。如需更新信息，请传入 card: [...] 参数；如仅需读取则无需传入该参数。此操作不会调用 LLM。

honcho_search

在存储的上下文中对特定对象进行语义搜索。返回按相关性排序的原始内容片段，不进行综合处理。默认返回 800 个标记，最多 2000 个。当您需要特定的历史事实以便自行推理而非获取综合答案时，此工具非常有用。

honcho_context

获取来自 Honcho 的完整会话上下文快照——包括会话摘要、对方信息展示、卡片内容以及最新消息。此操作不会调用 LLM。当您希望一次性查看 Honcho 所掌握的关于当前会话及对方的全部信息时，可使用此工具。

honcho_reasoning

通过 Honcho 的辩证推理引擎（在 Honcho 后端调用大型语言模型）来回答自然语言问题。该方式成本较高，但输出质量更优。可通过传递 reasoning_level 参数控制推理深度：minimal（快速/低成本）→ low → medium → high → max（全面深入）。若不指定该参数，则使用默认值 low。此功能用于深入理解用户的习惯、目标或当前状态。

honcho_conclude

用于创建或删除关于某个对象的持久性结论。如需创建结论，可传递 conclusion: "..." 参数；如需删除结论（尤其是涉及个人身份信息时——Honcho 会逐步自动修正错误的结论，因此仅当涉及敏感信息时才需手动删除），则需传递 delete_id: "..." 参数。必须仅选择这两个参数中的一个使用。

双向对象定位功能

上述 5 种工具均支持可选的 peer 参数：

• peer: "user"（默认值）——针对用户对象操作
• peer: "ai" ——针对当前配置文件中的 AI 对象操作
• peer: "<explicit-id>" ——工作空间中的任意对象 ID

示例：

honcho_profile                        # read user's card
honcho_profile peer="ai"              # read AI peer's card
honcho_reasoning query="What does this user care about most?"
honcho_reasoning query="What are my interaction patterns?" peer="ai" reasoning_level="medium"
honcho_conclude conclusion="Prefers terse answers"
honcho_conclude conclusion="I tend to over-explain code" peer="ai"
honcho_conclude delete_id="abc123"    # PII removal

Agent 使用模式

当 Honcho 内存处于激活状态时，Hermes 的使用指南。

对话开始时

1. honcho_profile                  → fast warmup, no LLM cost
2. If context looks thin → honcho_context  (full snapshot, still no LLM)
3. If deep synthesis needed → honcho_reasoning  (LLM call, use sparingly)

请勿在每个对话轮次都调用 honcho_reasoning 函数。自动注入机制已能负责持续更新上下文，仅当基础上下文无法提供所需的信息，且确实需要通过推理工具生成综合见解时，才应使用该功能。

当用户要求记住某些内容时

honcho_conclude conclusion="<specific, actionable fact>"

良好结论示例：“更倾向于提供代码示例而非文字说明”，“截至2026年4月仍在从事Rust异步项目开发”
不良结论示例：“用户提到了Rust”（过于模糊），“用户似乎具备技术背景”（这一信息已在初始描述中体现）

honcho_search query="<topic>"       → fast, no LLM, good for specific facts
honcho_context                       → full snapshot with summary + messages
honcho_reasoning query="<question>"  → synthesized answer, use when search isn't enough

何时使用 peer: "ai"

可使用 AI 对等体功能来构建并查询智能体自身的自我认知：

• honcho_conclude conclusion="我在解释架构时往往话较多" peer="ai" —— 自我修正
• honcho_reasoning query="我通常如何处理含义模糊的请求？" peer="ai" —— 自我审计
• honcho_profile peer="ai" —— 查看自身的身份信息

何时不应调用工具

在 hybrid 和 context 模式下，基础上下文（用户描述 + 身份卡片 + 会话摘要）会在每一轮对话开始前自动注入。无需重新获取已注入的内容。仅在以下情况才需调用工具：

• 需要注入的上下文中没有所需信息
• 用户明确要求你调取或检查记忆内容
• 需要针对新信息撰写结论时

调用频率控制

在工具端使用 honcho_reasoning 的成本与自动注入机制相同。在明确调用工具之后，自动注入的频率会重置——从而避免在同一轮对话中重复计费。

配置参考

配置文件路径： $HERMES_HOME/honcho.json（针对特定配置文件）或 ~/.honcho/config.json（全局配置）。

主要设置项

辩证推理设置

上下文预算与注入机制

contextTokens 的限额会在内容注入时进行校验。如果会话中的摘要、表示形式及卡片内容总和超过该限额，Honcho 会首先截断摘要，再截断表示形式，而保留卡片内容。此举可避免在长会话中出现上下文过度膨胀的问题。

内存上下文净化

为防止提示注入及内容格式错误，Honcho 会在注入前对 memory-context 块进行净化处理：

• 移除用户生成的结论中的 XML/HTML 标签；
• 规范化空白字符与控制字符；
• 截断长度超过 messageMaxChars 的单个结论；
• 转义可能破坏系统提示结构的分隔符序列。

此机制可解决那些包含标记或特殊字符的原始用户结论可能损坏注入上下文块的特殊情况。

故障排除

“未配置 Honcho”

运行命令 hermes honcho setup，并确保 ~/.hermes/config.yaml 文件中包含 memory.provider: honcho 这一配置项。

会话之间内存无法持久化

请运行 hermes honcho status 检查设置，确保 saveMessages: true 且 writeFrequency 不设置为 session（该模式仅在会话退出时才写入数据）。

Profile 无法获取独立节点

创建 Profile 时请使用 --clone 参数：hermes profile create <name> --clone。对于已存在的 Profile，则需执行 hermes honcho sync。

仪表板中的观测结果未同步更新

每次会话启动时，观测配置都会从服务器同步而来。在 Honcho UI 中修改设置后，请重新启动新会话。

消息被截断

长度超过 messageMaxChars（默认为 25,000 字符）的消息会自动分割，并添加 [continued] 标记。如果该问题频繁出现，请检查是否是工具输出或技能内容导致消息体积过大。

上下文注入量过大

若出现上下文预算超限的警告，请降低 contextTokens 值或减少 dialecticDepth 设置。当预算紧张时，会首先截断会话摘要内容。

会话摘要缺失

生成会话摘要需要当前 Honcho 会话中至少有过一次对话历史。在冷启动状态（全新会话且无历史记录）下，系统会省略摘要部分，转而使用冷启动提示策略。

CLI 命令