Honcho 记忆
Honcho 是一个 AI 原生的记忆后端,在 Kopi Agent 内置记忆系统的基础上增加了辩证推理(dialectic reasoning)与深度用户建模能力。Honcho 不做简单的键值存储,而是通过在对话结束后进行推理,持续维护一份关于"用户是谁"的模型——包括他们的偏好、沟通风格、目标和行为模式。
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 中:
- 基础上下文——会话摘要、用户表示、用户 peer card、AI 自我表示,以及 AI identity card。在
contextCadence时刷新。这是"这个用户是谁"这一层。 - 辩证补充——由 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 | 默认值 | 说明 |
|---|---|---|
contextTokens | null(无上限) | 每轮自动注入上下文的 token 预算。设置为整数(例如 1200)可设上限。截断发生在单词边界处 |
contextCadence | 1 | context() API 调用之间的最小轮数(base 层刷新) |
dialecticCadence | 2 | peer.chat() LLM 调用之间的最小轮数(dialectic 层)。推荐值 1–5。在 tools 模式下不适用 —— 由模型显式调用 |
dialecticDepth | 1 | 每次 dialectic 调用的 .chat() 遍数。会被限制在 1–3 范围内 |
dialecticDepthLevels | null | 可选的数组,为每一遍指定推理级别,例如 ["minimal", "low", "medium"]。会覆盖按比例分配的默认值 |
dialecticReasoningLevel | 'low' | 基础推理级别:minimal、low、medium、high、max |
dialecticDynamic | true | 当为 true 时,模型可通过 tool 参数在每次调用时覆盖推理级别 |
dialecticMaxChars | 600 | 注入 system prompt 的 dialectic 结果的最大字符数 |
recallMode | 'hybrid' | hybrid(自动注入 + 工具)、context(仅注入)、tools(仅工具) |
writeFrequency | 'async' | 何时 flush 消息:async(后台线程)、turn(同步)、session(结束时批量),或整数 N |
saveMessages | true | 是否将消息持久化到 Honcho API |
observationMode | 'directional' | directional(全部启用)或 unified(共享池)。可用 observation 对象覆盖以实现细粒度控制 |
messageMaxChars | 25000 | 通过 add_messages() 发送的每条消息的最大字符数。超出时会分块 |
dialecticMaxInputChars | 10000 | 传给 peer.chat() 的 dialectic 查询输入的最大字符数 |
sessionStrategy | 'per-directory' | per-directory、per-repo、per-session 或 global |
pinUserPeer | false | 仅 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 模式的设置项:
| 设置项 | hybrid | context | tools |
|---|---|---|---|
writeFrequency | flush 消息 | 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 me | pinUserPeer: 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 people | pinUserPeer: false,可选的 runtimePeerPrefix —— 每个用户拥有各自的 peer |
在提示处选择 [e],可以直接设置这三个 key。
解析器会自上而下尝试这些 key,首个匹配生效:pinUserPeer → userPeerAliases[id] → runtimePeerPrefix + id → 原始运行时 ID → peerName → session-key 兜底。
将 pinUserPeer 从 true 切换到 false 不会迁移数据 —— 在 peerName 下积累的记忆仍留在原处,而平台用户会解析到全新且空的 peer。若要保持你自己的连续性,请选择 pooled 路径,让你的运行时 ID 重新别名到 peerName。向导检测到这种切换时会自动给出此建议。
pinPeerName 是 pinUserPeer 的遗留别名 —— 仍会被读取以保持向后兼容(两者同时设置时 pinUserPeer 优先),但从不写入。重新运行 setup 会将其迁移到规范 key 上。
观察(定向 vs. 统一)
Honcho 将对话建模为 peers 之间交换消息。每个 peer 有两个观察开关,与 Honcho 的 SessionPeerConfig 一一对应:
| 开关 | 效果 |
|---|---|
observeMe | Honcho 根据该 peer 自己的消息构建其表征 |
observeOthers | 该 peer 观察对方 peer 的消息(为跨 peer 推理提供输入) |
两个 peer × 两个开关 = 四个标志。observationMode 是一个简写预设:
| 预设 | 用户标志 | AI 标志 | 语义 |
|---|---|---|---|
"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 不应通过自我观察更新 | "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:
- 你现有的配置(
honcho.json或~/.honcho/config.json)会被保留 - 你的服务端数据(记忆、结论、用户资料)完好无损
- 在 config.yaml 中设置
memory.provider: honcho即可重新激活
无需重新登录或重新设置。运行 kopi memory setup 并选择 "honcho" —— 向导会检测到你现有的配置。
完整文档
参见 Memory Providers — Honcho 获取完整参考。