Hermes Agent 中搭建全中文 Honcho 记忆系统踩坑经验

背景

在配置Hermes Agent时，我给记忆系统选的是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 服务：

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

先说第一个坑：pip install honcho 这个命令，一不小心就装错了。PyPI上确实有个叫 honcho 的包，但它是个进程管理器（类似Foreman），不是Plastic Labs的记忆系统。直接装上去，导入后没有 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。代码里默认用的是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：

改完之后重新跑，效果立竿见影。

安装第四坑：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