honcho-intro

Honcho Memory Plugin for Nanobot

1. 一句话定位

Honcho 是 peer-centric 的状态和洞察层：它围绕 workspace、peer、session、message 建模，再由后台 worker 生成 representation、summary 和更高层 insight。

2. 核心心智模型

• Honcho 不只是 memory search；它把人和 agent 都建模为 peer。
• session 是多个 peers 的交互空间，message 必须带来源 peer。
• 写入 message 后，deriver/dreamer 在后台处理，不应由 Adapter 同步调用。
• 读取时优先用 context、representation、chat 等原生 endpoint。
• Adapter 应使用 SDK/REST API，不导入 Honcho server 内部模块。

3. 数据模型

Workspace
  |-- Peer: user
  |-- Peer: assistant
  |-- Session
       |-- peers: user, assistant
       |-- messages: peer-labeled turns
  |-- Collections
       |-- Documents / representations / summaries

字段	来源	用途
workspace_id	benchmark app/run	顶层隔离
peer_id	user / assistant	参与者身份
session_id	Nanobot session	会话边界
message.peer	role mapping	标记消息来源
target	query config	查询哪个 peer 的洞察
tokens	prompt budget	控制 context 大小

4. 运行时流程

Write path
Nanobot turn
  -> HonchoPlugin maps role to peer
  -> POST session messages
  -> Honcho enqueue background tasks
  -> deriver updates representation/summary/peer card
  -> dreamer may schedule higher-level processing
 
Read path
Nanobot needs context
  -> session.context or peer.context
  -> optional peer.representation
  -> optional peer.chat for natural-language insight
  -> formatted context for Nanobot

5. 原生 API

API	参数	返回值	用途
session.add_messages / messages REST	peer-labeled messages	created messages	写入交互
session.context / session context REST	summary, tokens, peer options	context object	获取会话上下文
peer.search / search REST	query, scope, filters	matched messages/docs	搜索原始或派生内容
peer.chat / /peers/{id}/chat	query, target, reasoning level	answer	向 Honcho 查询 peer insight
session.representation(peer) / representation REST	peer/session	representation doc	低延迟人格/偏好上下文

6. 存储后端

• Honcho server 使用 Postgres；README 要求 Postgres connection URI，并提到 pgvector。
• config 中有 vector store 配置，支持 pgvector、Turbopuffer、LanceDB 等形态。
• deriver 是独立后台进程：uv run python -m src.deriver。
• dreamer 由 deriver/queue 体系调度；不是 Nanobot adapter 的同步函数。

7. Nanobot 集成边界

Nanobot 概念	Honcho 概念
benchmark app/run	workspace
human persona	peer
Nanobot assistant	peer
conversation	session
user/assistant turn	peer-labeled message
prompt memory context	session context + representation

不能绕过的原生路径：

• 不直接写 Honcho DB。
• 不直接 import src.deriver 或 src.dreamer。
• 不用 raw search 取代 context/representation/chat。
• 不把 user 和 assistant 合并成一个 peer。

8. 性能保留原则

• deriver/dreamer 保持后台异步；Adapter 只观察状态或读取已生成结果。
• 保留 token budget，例如 tokens=10000。
• 对刚写入的数据接受 eventual consistency，必要时显示 pending。
• 保留 peer/session scope，避免 workspace 级全量搜索过宽。
• 批量写 message 时使用 Honcho API 的 batch 行为，不逐字段手写 DB。

9. 集成风险 + 校验清单

• 检查 user peer 和 assistant peer 被正确区分。
• 检查写入后 message 顺序稳定，session 不串。
• 检查 deriver 运行时 representation/summary 会更新。
• 检查 deriver 未完成时 Adapter 有 fallback 或 pending 标记。
• 分别记录 context、search、chat、representation 的 latency 和输出长度。