跳到主要内容

Honcho 记忆

Honcho 是一个 AI 原生的记忆后端,在 Kopi Agent 内置记忆系统的基础上增加了辩证推理(dialectic reasoning)与深度用户建模能力。Honcho 不做简单的键值存储,而是通过在对话结束后进行推理,持续维护一份关于"用户是谁"的模型——包括他们的偏好、沟通风格、目标和行为模式。

Honcho 是一个 Memory Provider Plugin

Honcho 已集成到 Memory Providers 系统中。以下所有功能都通过统一的 memory provider 接口提供。

Honcho 增加了什么​

能力内置记忆Honcho
跨会话持久化✔ 基于文件的 MEMORY.md/USER.md✔ 基于 API 的服务端存储
用户画像✔ 由 agent 手动整理✔ 自动辩证推理
会话摘要—✔ 会话级上下文注入
多 agent 隔离—✔ 按 peer 分离的画像
观察模式—✔ 统一观察或定向观察
结论(推导出的洞察)—✔ 服务端针对模式进行推理
跨历史搜索✔ FTS5 会话搜索✔ 针对结论的语义搜索

辩证推理:在每次对话轮次之后(由 dialecticCadence 控制),Honcho 会分析这段交流并推导出关于用户偏好、习惯和目标的洞察。这些洞察随时间不断累积,让 agent 获得超越用户明确表述内容的、不断深化的理解。辩证推理支持多轮深度(1–3 次 pass),并自动选择冷启动/热启动 prompt——冷启动查询聚焦于用户的通用事实,而热启动查询优先考虑会话级上下文。

会话级上下文:基础上下文现在在用户表示(user representation)和 peer card 之外,还包含会话摘要。这让 agent 能感知当前会话中已经讨论过的内容,减少重复并实现更好的连续性。

多 agent 画像:当多个 Kopi Agent 实例与同一个用户对话时(例如一个编程助手和一个个人助理),Honcho 会为每个 "peer" 维护独立的画像。每个 peer 只能看到自己的观察和结论,避免上下文相互污染。

设置​

kopi memory setup    # select "honcho" from the provider list

或手动配置:

# ~/.kopi/config.yaml
memory:
provider: honcho
echo 'HONCHO_API_KEY=***' >> ~/.kopi/.env

在 honcho.dev 获取 API key。

架构​

两层上下文注入​

每个轮次(在 hybrid 或 context 模式下),Honcho 会组装两层上下文并注入到系统 prompt 中:

  1. 基础上下文——会话摘要、用户表示、用户 peer card、AI 自我表示,以及 AI identity card。在 contextCadence 时刷新。这是"这个用户是谁"这一层。
  2. 辩证补充——由 LLM 合成的关于用户当前状态与需求的推理。在 dialecticCadence 时刷新。这是"此刻什么是重要的"这一层。

两层内容会被拼接,并截断到 contextTokens 预算(如果设置了)。

冷启动/热启动 Prompt 选择​

辩证推理会在两种 prompt 策略之间自动选择:

  • 冷启动(尚无基础上下文):通用查询——"这个人是谁?他们的偏好、目标和工作风格是什么?"
  • 热会话(已有基础上下文):会话级查询——"考虑到本次会话到目前为止讨论的内容,关于这个用户的哪些上下文最相关?"

这会根据基础上下文是否已填充来自动进行。

三个正交的配置旋钮​

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

旋钮控制内容默认值
contextCadence两次 context() API 调用之间的轮次数(基础上下文刷新)1
dialecticCadence两次 peer.chat() LLM 调用之间的轮次数(辩证层刷新)2(建议 1–5)
dialecticDepth每次辩证调用执行的 .chat() 次数(1–3)1

这些旋钮是正交的——你可以让上下文刷新很频繁而辩证推理很低频,也可以让低频的辩证推理进行深度多 pass 处理。示例:contextCadence: 1, dialecticCadence: 5, dialecticDepth: 2 每个轮次刷新基础上下文,每 5 个轮次执行一次辩证推理,并且每次辩证推理执行 2 个 pass。

辩证深度(多 Pass)​

当 dialecticDepth > 1 时,每次辩证调用会运行多个 .chat() pass:

  • Pass 0:冷启动或热启动 prompt(见上文)
  • Pass 1:自我审计——识别初步评估中的缺口,并从近期会话中合成证据
  • Pass 2:调和——检查各 pass 之间是否存在矛盾,并产出最终综合结果

每个 pass 使用成比例的推理级别(早期 pass 更轻量,主 pass 使用基础级别)。可以用 dialecticDepthLevels 按 pass 覆盖级别——例如,在深度 3 的运行中使用 ["minimal", "medium", "high"]。

如果上一个 pass 已返回强信号(长且结构化的输出),后续 pass 会提前退出,因此深度 3 并不总是意味着 3 次 LLM 调用。

会话启动预热​

在会话初始化时,Honcho 会在后台以完整配置的 dialecticDepth 发起一次辩证调用,并将结果直接交给第 1 轮的上下文组装。对于冷启动的 peer,单 pass 预热通常返回的输出很单薄——而多 pass 深度会在用户开口之前就完成审计/调和流程。如果到第 1 轮时预热尚未完成,第 1 轮会退化为一次带超时上限的同步调用。

查询自适应推理级别​

自动注入的辩证推理会根据查询长度缩放 dialecticReasoningLevel:长度 ≥120 个字符时 +1 级,≥400 个字符时 +2 级,并以 reasoningLevelCap(默认 "high")为上限。使用 reasoningHeuristic: false 可禁用此行为,将所有自动调用固定为 dialecticReasoningLevel。可用级别:minimal、low、medium、high、max。

配置选项​

Honcho 在 ~/.honcho/config.json(全局)或 $KOPI_HOME/honcho.json(配置文件局部)中进行配置。设置向导会替你完成这一步。

带身份验证的自托管 Honcho​

当将 Kopi Agent 指向自托管的 Honcho 服务器时,kopi honcho setup(以及 kopi memory setup)会在 base URL 之后询问 local JWT / bearer token。粘贴一个使用服务器 AUTH_JWT_SECRET(Honcho compose 环境变量)签名的 JWT 即可启用经过身份验证的访问;如果服务器以 AUTH_USE_AUTH=false 运行,则留空即可。该 local token 保存在 host 块下(honcho.json 中的 hosts.<host>.apiKey),与任何云端 apiKey 分开存储,因此你之后可以将 Cloud or local? 提示改回 cloud,而不会丢失其中任何一个凭据。

完整配置参考​

Key默认值说明
contextTokensnull(无上限)每轮自动注入上下文的 token 预算。设置为整数(例如 1200)可设上限。截断发生在单词边界处
contextCadence1context() API 调用之间的最小轮数(base 层刷新)
dialecticCadence2peer.chat() LLM 调用之间的最小轮数(dialectic 层)。推荐值 1–5。在 tools 模式下不适用 —— 由模型显式调用
dialecticDepth1每次 dialectic 调用的 .chat() 遍数。会被限制在 1–3 范围内
dialecticDepthLevelsnull可选的数组,为每一遍指定推理级别,例如 ["minimal", "low", "medium"]。会覆盖按比例分配的默认值
dialecticReasoningLevel'low'基础推理级别:minimal、low、medium、high、max
dialecticDynamictrue当为 true 时,模型可通过 tool 参数在每次调用时覆盖推理级别
dialecticMaxChars600注入 system prompt 的 dialectic 结果的最大字符数
recallMode'hybrid'hybrid(自动注入 + 工具)、context(仅注入)、tools(仅工具)
writeFrequency'async'何时 flush 消息:async(后台线程)、turn(同步)、session(结束时批量),或整数 N
saveMessagestrue是否将消息持久化到 Honcho API
observationMode'directional'directional(全部启用)或 unified(共享池)。可用 observation 对象覆盖以实现细粒度控制
messageMaxChars25000通过 add_messages() 发送的每条消息的最大字符数。超出时会分块
dialecticMaxInputChars10000传给 peer.chat() 的 dialectic 查询输入的最大字符数
sessionStrategy'per-directory'per-directory、per-repo、per-session 或 global
pinUserPeerfalse仅 Gateway。当为 true 时,所有平台用户都会归并到 peerName
userPeerAliases{}仅 Gateway。将 runtime ID 映射到 peer({"7654321": "alice"})。多对一
runtimePeerPrefix""仅 Gateway。当没有 alias 匹配时,为未知的 runtime ID 指定命名空间(telegram_7654321)

Session 策略控制 Honcho session 如何映射到你的工作:

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

Recall 模式控制记忆如何流入对话:

  • hybrid —— 上下文自动注入 system prompt,并且工具可用(由模型决定何时查询)。
  • context —— 仅自动注入,隐藏工具。
  • tools —— 仅工具,无自动注入。Agent 必须显式调用 honcho_reasoning、honcho_search 等。

每种 recall 模式的设置项:

设置项hybridcontexttools
writeFrequencyflush 消息flush 消息flush 消息
contextCadence控制 base 上下文刷新控制 base 上下文刷新不适用 —— 无注入
dialecticCadence控制自动 LLM 调用控制自动 LLM 调用不适用 —— 由模型显式调用
dialecticDepth每次调用多遍执行每次调用多遍执行不适用 —— 由模型显式调用
contextTokens限制注入量限制注入量不适用 —— 无注入
dialecticDynamic控制模型覆盖N/A(无工具)控制模型覆盖

在 tools 模式下,模型完全掌控 —— 它会在自己需要时调用 honcho_reasoning,并使用它所选择的任意 reasoning_level。节奏和预算设置仅适用于带自动注入的模式(hybrid 和 context)。

Gateway 身份映射​

这些设置仅在你运行 Kopi Agent gateway 时才起作用 —— 这是用户带着平台原生运行时 ID(Telegram UID、Discord snowflake、Slack user)到达的唯一入口。CLI、TUI 和桌面会话没有运行时 ID,始终解析为 peerName,因此在 gateway 之外,这些 key 不会起任何作用。

设置向导会检测是否已连接 gateway 平台,如果没有,则完全跳过此步骤。运行时,它会询问一个问题 —— 谁会与这个 gateway 对话? —— 并据此推导出相关 key:

回答结果
just mepinUserPeer: true —— 每个非 agent 的 gateway 用户都会合并到你的 peer 上。Pin 会覆盖所有别名,因此只有当用户侧身份不需要各自的 peer 时才选择此项。如果有多个 agent 访问 gateway 且各自需要独立的 peer,请不要 pin —— 保留 pinUserPeer: false,并通过 userPeerAliases([e] 编辑器)为它们映射
me + other people(pooled)pinUserPeer: false + userPeerAliases,将你的运行时 ID 映射到 peerName —— 你继续使用共享历史,其他人各自拥有独立的 peer
only other peoplepinUserPeer: false,可选的 runtimePeerPrefix —— 每个用户拥有各自的 peer

在提示处选择 [e],可以直接设置这三个 key。

解析器会自上而下尝试这些 key,首个匹配生效:pinUserPeer → userPeerAliases[id] → runtimePeerPrefix + id → 原始运行时 ID → peerName → session-key 兜底。

取消 pin 会使 pooled 记忆变成孤儿数据

将 pinUserPeer 从 true 切换到 false 不会迁移数据 —— 在 peerName 下积累的记忆仍留在原处,而平台用户会解析到全新且空的 peer。若要保持你自己的连续性,请选择 pooled 路径,让你的运行时 ID 重新别名到 peerName。向导检测到这种切换时会自动给出此建议。

已弃用的 key

pinPeerName 是 pinUserPeer 的遗留别名 —— 仍会被读取以保持向后兼容(两者同时设置时 pinUserPeer 优先),但从不写入。重新运行 setup 会将其迁移到规范 key 上。

观察(定向 vs. 统一)​

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

开关效果
observeMeHoncho 根据该 peer 自己的消息构建其表征
observeOthers该 peer 观察对方 peer 的消息(为跨 peer 推理提供输入)

两个 peer × 两个开关 = 四个标志。observationMode 是一个简写预设:

预设用户标志AI 标志语义
"directional"(默认)me: on, others: onme: on, others: on完全双向观察。支持跨 peer 辩证推理 —— "基于用户所说的内容以及 AI 的回复,AI 对用户了解多少。"
"unified"me: on, others: offme: 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 不应通过自我观察更新"ai": {"observeMe": false, "observeOthers": true}

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

工具​

当 Honcho 作为 memory provider 激活时,会提供五个工具:

工具用途
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 命令​

kopi honcho 子命令仅在 Honcho 是激活的 memory provider 时才注册(即 config.yaml 中的 memory.provider: honcho)。在全新安装时,请直接使用 kopi memory setup honcho 配置 Honcho(或运行 kopi memory setup 并从列表中选择);kopi honcho 子命令会在下次调用时出现。

kopi memory setup honcho    # Configure Honcho directly (works before activation)
kopi honcho status # Connection status, config, and key settings
kopi honcho setup # Redirects to `kopi memory setup` (post-activation alias)
kopi honcho strategy # Show or set session strategy (per-session/per-directory/per-repo/global)
kopi honcho peer # Show or update peer names + dialectic reasoning level
kopi honcho mode # Show or set recall mode (hybrid/context/tools)
kopi honcho tokens # Show or set token budget for context and dialectic
kopi honcho identity # Seed or show the AI peer's Honcho identity
kopi honcho sync # Sync Honcho config to all existing profiles
kopi honcho peers # Show peer identities across all profiles
kopi honcho sessions # List known Honcho session mappings
kopi honcho map # Map current directory to a Honcho session name
kopi honcho enable # Enable Honcho for the active profile
kopi honcho disable # Disable Honcho for the active profile
kopi honcho migrate # Step-by-step migration guide from openclaw-honcho

从 kopi honcho 迁移​

如果你之前使用的是独立的 kopi honcho setup:

  1. 你现有的配置(honcho.json 或 ~/.honcho/config.json)会被保留
  2. 你的服务端数据(记忆、结论、用户资料)完好无损
  3. 在 config.yaml 中设置 memory.provider: honcho 即可重新激活

无需重新登录或重新设置。运行 kopi memory setup 并选择 "honcho" —— 向导会检测到你现有的配置。

完整文档​

参见 Memory Providers — Honcho 获取完整参考。