在 Hermes Agent 里搭建全中文 Honcho 记忆系统踩过的坑

大型UFO
8 阅读6分钟

背景

我的Hermes Agent配置了多个 profile，记忆系统选择了基于 Honcho，通过 Postgres + pgvector 存储对话历史，用 LLM 提取观察、归纳人格画像。

但是Honcho的提示词是英文的，它的API服务也是英文环境。在全中文使用环境下，当然是中文语料、中文提示词、中文能力强的大模型最合适，避免中-英-中互译的信息偏移。本文是完整本地部署全中文 Honcho 的坑。注意一般4G内存的服务器本地部署的话，内存可能会爆。

架构总览

┌─────────────────────────────────────────────┐
│  Hermes Gateway (5 profiles)                │
│  └─ plugins/memory/honcho/  ← 插件层        │
│     └─ session.py, client.py, ...           │
├─────────────────────────────────────────────┤
│  Honcho API (FastAPI, 127.0.0.1:8000)       │
│  ├─ Honcho Deriver (观察提取, src.deriver)   │
│  ├─ Honcho Embedding (768-dim, :8080)        │
│  ├─ Dialectic (辨证推理层)                   │
│  ├─ Dream (离线画像演绎)                     │
│  └─ Summarizer (会话压缩)                    │
├─────────────────────────────────────────────┤
│  PostgreSQL + pgvector                       │
│  └─ honcho 数据库                            │
└─────────────────────────────────────────────┘

三个 systemd 服务：

服务端口进程
honcho-api8000uvicorn src.main:app
honcho-deriver-python -m src.deriver
honcho-embedding8080自定义 FastAPI + bge-base-zh-v1.5

部署前置坑一：pip install honcho 装错包

PyPI 上有一个叫 honcho 的包——但它是一个进程管理器（类似 Foreman），不是 Plastic Labs 的记忆系统。如果直接 pip install honcho，导入后没有 src.main 模块，uvicorn 启动直接报 ModuleNotFoundError。

正确做法：从 GitHub 克隆源码，用 pip install -e . 安装。

git clone https://github.com/plastic-labs/honcho.git /opt/honcho2
cd /opt/honcho2 && pip install -e .

部署前置坑二：pgvector 扩展需单独安装

apt install postgresql 不会自动带 pgvector。建表时才报错，新手容易卡在这一步。

apt install -y postgresql-16-pgvector
su - postgres -c "psql -c 'CREATE EXTENSION vector;' -d honcho"

部署前置坑三：数据库迁移未执行

Honcho 源码安装后，数据库是空的——没有表结构，API 启动报 Required vector columns missing。必须运行 alembic 迁移：

cd /opt/honcho2
HONCHO_CONFIG_PATH=/opt/honcho2/config.toml alembic upgrade head

这步在 Honcho 官方文档里有，但很容易在"先配 config 再迁移"的顺序中被跳过。

部署前置坑四：Embedding 维度与数据库不匹配

alembic 默认创建 1536 维向量列（适配 OpenAI embedding），但 bge-base-zh-v1.5 是 768 维。API 启动时会校验维度，报 documents.embedding dim (1536) does not match EMBEDDING_VECTOR_DIMENSIONS (768)。

必须运行 Honcho 自带的配置脚本：

echo y | HONCHO_CONFIG_PATH=/opt/honcho2/config.toml python scripts/configure_embeddings.py

安装第一坑：DeepSeek structured output 模式

Honcho 的 Deriver、Dialectic、Dream、Summarizer 全都需要 LLM 输出结构化 JSON。Honcho 代码里默认使用 json_schema 模式（严格模式），但 DeepSeek API 不支持，只支持 json_object（宽松模式）。

症状：Deriver 启动后无报错但静默失败，数据库没有任何新 observation。

解决：在 Honcho 的 config.toml 中，所有 model_config 块都要显式指定：

[deriver.model_config]
transport = "openai"
model = "deepseek-v4-pro"
structured_output_mode = "json_object"  # ← 关键配置

涉及 7 个 model_config 块（deriver、dialectic × 5 levels、summary、dream × 2）。

安装第二坑：Embedding 模型的国内下载

Honcho 需要本地 embedding 模型做语义搜索。选的是 BAAI/bge-base-zh-v1.5（768 维中文模型）。

问题 1：HuggingFace 国内无法直连。

解决：代理下载，保存到 /opt/models/bge-base-zh-v1.5/。然后写一个自定义 embedding 服务：

# /opt/embedding-server.py — 绑定本地模型文件
MODEL_NAME = "/opt/models/bge-base-zh-v1.5"
model = SentenceTransformer(MODEL_NAME)


@app.post("/v1/embeddings")
async def embed(req: EmbedRequest):
    vectors = model.encode(texts, normalize_embeddings=True)
    return {"data": [{"embedding": v.tolist(), "index": i} for i, v in enumerate(vectors)]}

Honcho 配置中指向此服务：

[embedding.model_config]
transport = "openai"
model = "bge-base-zh-v1.5"


[embedding.model_config.overrides]
base_url = "http://127.0.0.1:8080/v1"

问题 2 ：HF Hub 下载的模型目录里大量使用 symlink。如果下载时经过了代理中转、或者复制目录时没带 -L 参数，symlink 全部断链。SentenceTransformer 加载时会报 file not found，但错误信息不直观。

解决：不用 snapshot_download 缓存目录，直接把模型文件平铺到一个目录下，json、safetensors、tokenizer 文件全部同级放置，零 symlink。

安装第三坑：全链路 Prompt 中文化

Honcho 发布时默认 Prompt 全是英文。DeepSeek 对英文 Prompt 也能工作，但会产生中英混杂的输出，在 dialectic（辨证推理）环节尤其严重——英文思考过程夹杂中文，最终 observation 质量差。

发现的 9 处英文 Prompt：

文件组件修复
src/deriver/prompts.py观察提取改中文
src/dreamer/specialists.pyDeduction specialist改中文
src/dreamer/specialists.pyInduction specialist改中文
src/dreamer/specialists.pyCard update specialist改中文
src/dialectic/prompts.pyAgent 系统指引改中文
src/dialectic/prompts.py会话上下文展示改中文
src/dialectic/prompts.py推理输出格式改中文
src/summarizer/prompts.py对话压缩改中文
src/dialectic/prompts.pyPeer representation改中文

改完之后重新跑。

安装第四坑：Representation 缓存的幽灵数据

数据层干净了，但 honcho_context 返回的还是旧的英文垃圾。

根因：Honcho 的 honcho_context/honcho_search 返回的是预计算并缓存的 representation。删了旧 observation、跑了新 Dream 之后，这个缓存不会自动刷新。必须开新会话（/new）让 Peer 对象重建，才会从数据库重新拉取。

配置：Hermes 的 session_reset 有两种触发方式——每日凌晨 4 点自动重置，或空闲 1440 分钟（24 小时）后自动重置。

安装第五坑：Hermes Honcho 插件的 observer bug

开新会话之后，本以为一切正常，Dream 生成了纯中文 observation，representation 也刷新了。但 honcho_context 仍然返回空。

定位：排查发现 Honcho API 直接调用是正常的（observer=hermes, target=user 能查到数据），问题出在 Hermes 的 Honcho 插件层。

根因：plugins/memory/honcho/session.py第 736 行，_fetch_session_context 方法在调用 _fetch_peer_context 时，直接传了 session.user_peer_id 作为 observer，而正确做法应该是用 _resolve_observer_target 解析出真正的 observer（即 hermes 自身的 peer_id）。其他所有调用点（get_peer_card、honcho_search、honcho_reasoning）都正确使用了 _resolve_observer_target，唯独这一处遗漏。

修复：

# Before（错误）:
user_ctx = self._fetch_peer_context(session.user_peer_id, ...)


# After（正确）:
observer_peer_id, target_peer_id = self._resolve_observer_target(session, "user")
user_ctx = self._fetch_peer_context(observer_peer_id, ...)

修复后已向上游 提交 PR #62982。

最终效果

honcho_context 返回：
├── Summary:     纯中文会话摘要
├── Representation: 25 条中文用户观察
├── Card:        身份/属性/偏好/关系（全中文）
└── Recent messages: 最近消息记录

避坑清单

  1. pip install honcho 装的是错误包：PyPI 上的 honcho 是进程管理器，必须从 GitHub 克隆
  2. pgvector 扩展需单独安装：apt install postgresql 不带 pgvector
  3. 数据库迁移必跑：alembic upgrade head，否则 API 直接拒启动
  4. Embedding 维度需适配：alembic 默认 1536 维，bge 是 768 维，必须跑 configure_embeddings.py
  5. DeepSeek 必须用 json_object，不能用默认的 json_schema，涉及 7 个配置块
  6. Embedding 模型本地化：HF 不可直连，symlink 会断链，平铺目录最可靠
  7. Prompt 中文化是全局的：deriver + dreamer + dialectic + summarizer 共 9 处
  8. Representation 缓存不会自动刷新：改完数据后要 /new
  9. Hermes 插件的 observer 参数：必须走 _resolve_observer_target，不能直接传 user_peer_id

相关链接

avatar
文章
阅读
粉丝