OpenClaw 记忆集成 Honcho 实战:本地部署、踩坑、端到端验证,以及 vs. Cognee 对比-夜雨聆风

OpenClaw 记忆集成 Honcho 实战:本地部署、踩坑、端到端验证,以及 vs. Cognee 对比

给 OpenClaw 接上 Honcho 做长期记忆：本地 Docker 部署、1536 维强约束踩坑、embedding MRL 截断补丁、端到端验证；顺带对比 Honcho 与 Cognee 的定位差异。

本机给 vs-openclaw-mgr agent 接一套 Honcho 做长期记忆。目标是 只给当前这台机器的 OCPlatform 实例用，不影响其它集群节点。整个过程遇到了一个不算小的坑（embedding 维度），最后靠给 Honcho 源码打补丁解决。

我是 AI灵感闪现，使用 OpenClaw 小龙虾让 AI 自主管理工作和生活上的问题；使用 Claude Code + BMAD AI 驱动敏捷开发框架，让 AI 自主开发和交付软件来表达想法和灵感。是 MoneyMind 省钱思维 App 和 HeartPetBond 心宠纽带 App 开发者。正在实践和分享让 AI 自主解决健康、生活、投资和等方面的问题。我尽可能让 AI 自己完成从目标到交付以及演进的闭环，以最少的人为交互与监督，让 AI 自己跑流程。我只给 AI 想法或目标，全程不陪跑，让 AI 自主运行类似 Tesla FSD 自动驾驶。

0. 为什么是 Honcho？

Honcho 是 Plastic Labs 开源的 “AI agent long-term memory” 服务，核心卖点不是”给你一个向量库”，而是：

用 peer + session + message 三层抽象建模对话；
内置 deriver 管道，从对话里自动抽 observations（”owner 说过 X”、”owner 纠正了 agent 的 Y”），维护一份 peer representation（你是谁、偏好什么、信什么）；
下次对话，agent 可以查这个 representation 做上下文注入。

与之对比，Cognee 更像”从一堆文档里建知识图谱”，偏客观知识；Honcho 偏人设建模。文末有详细对比。

1. 目标和约束

只给本机实例用：不共享到其它 OpenClaw 节点
本地 Docker 跑：减少对外部 SaaS 的依赖
端口不撞车：本机 38830–38832
LLM 走 OpenRouter：复用已有 key，避免再跑本地大模型
Embedding 用 Qwen3-Embedding-8B：质量好、多语友好

2. 架构

OpenClaw agent       │ (agent_end hook)       ▼@honcho-ai/openclaw-honcho (plugin, kind=memory)       │ HTTP  http://127.0.0.1:38830       ▼Honcho API container ──► Deriver container       │                        │       ├────────────┬───────────┘       ▼            ▼  Postgres 15      Redis 8  + pgvector     (队列/缓存)  (38831)          (38832)(LLM + Embedding 都走 OpenRouter)

3. 端口规划

组件	容器内	宿主机	说明
API	8000	38830	REST API，plugin 连这个
PostgreSQL	5432	38831	本机 5432 已被系统 PG 占用，必须改
Redis	6379	38832	避开其它服务

预留 38830–38839 段给 Honcho 以后扩展。

4. 目录结构

~/Dockers/honcho/├── .env                    # 配置（含 OpenRouter key，勿提交）├── docker-compose.yml      # 本项目的 compose（自带）└── src/                    # git clone https://github.com/plastic-labs/honcho.git    ├── Dockerfile    └── src/                # Honcho Python 源码

选”从源码构建”而非 image: 直拉，有两个原因：

Honcho 没有公开的稳定 docker image tag
后面要给源码打补丁（见第 6 节），本地构建最自然

5. `.env` 配置（关键段）

# ---- 基础 ----LOG_LEVEL=INFODB_CONNECTION_URI=postgresql+psycopg://postgres:postgres@database:5432/postgresAUTH_USE_AUTH=false# ---- LLM：全部走 OpenRouter ----LLM_OPENAI_API_KEY=sk-or-v1-...     # OpenRouter key (Honcho 内部用的 openai SDK 变量名)# Deriver 抽 observationsDERIVER_ENABLED=trueDERIVER_MODEL_CONFIG__TRANSPORT=openaiDERIVER_MODEL_CONFIG__MODEL=deepseek/deepseek-v3.2DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1# Dialectic 各 level 都用同一个模型DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORT=openaiDIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODEL=deepseek/deepseek-v3.2DIALECTIC_LEVELS__minimal__MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1# ... low / medium / high / max 同构，全指 deepseek-v3.2# SummarySUMMARY_MODEL_CONFIG__TRANSPORT=openaiSUMMARY_MODEL_CONFIG__MODEL=deepseek/deepseek-v3.2SUMMARY_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1# ---- Embedding ----EMBED_MESSAGES=trueEMBEDDING_MODEL_CONFIG__TRANSPORT=openaiEMBEDDING_MODEL_CONFIG__MODEL=qwen/qwen3-embedding-8bEMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URL=https://openrouter.ai/api/v1# 不要设 EMBEDDING_VECTOR_DIMENSIONS —— 默认 1536 就是 Honcho 唯一支持值# ---- 关闭 Dream（先不开）----DREAM_ENABLED=false

选型理由：

deepseek/deepseek-v3.2：支持 tool calling，价格友好，中文强
qwen/qwen3-embedding-8b：多语 embedding 首选，但需要处理维度（下面详解）
Dream 是 Honcho 的离线反思/整理流程，先跑起来再说

6. 坑点：Embedding 维度冲突

问题现象

容器刚起来：

api | ValueError: EMBEDDING.VECTOR_DIMENSIONS must remain 1536    | while pgvector is active or vector-store migration is incomplete

api 和 deriver 容器一起 crash-loop。

根因

Honcho 这边：src/config.py 里硬约束

ifself.EMBEDDING.VECTOR_DIMENSIONS != 1536and (self.VECTOR_STORE.TYPE == "pgvector"ornotself.VECTOR_STORE.MIGRATED):raise ValueError("EMBEDDING.VECTOR_DIMENSIONS must remain 1536 while pgvector is "        + "active or vector-store migration is incomplete"    )

因为 Postgres schema 是 embedding VECTOR(1536) 硬编码。想换维度得换 vector store（LanceDB 等），或做 schema migration，成本高。

Qwen3-Embedding-8B 这边：原生输出 4096 维。

两边对不上，死循环崩。

解法：MRL + `dimensions` 参数

Qwen3-Embedding 系列是 MRL（Matryoshka Representation Learning） 训练的 —— 前 N 维本身就是一个可用的”压缩版” embedding，质量几乎不降。可以安全截断到 512 / 1024 / 1536 / 2048 / 4096。

OpenAI embeddings API 标准化了这个接口：传 dimensions=1536，服务端返回截断+重归一化后的向量。OpenRouter 对 qwen/qwen3-embedding-8b 也遵循此协议（我事先 curl 验证过，返回确实是 1536 维）。

Honcho 代码缺失

Honcho 的 openai transport 路径（src/embedding_client.py）调用 embeddings.create() 时只传 model 和 input，没传 dimensions。它假设 “openai transport 的模型都原生 1536 维”（对 text-embedding-3-small 成立，但对第三方模型不够通用）。

补丁（3 处）

# src/embedding_client.py# 位置 1（单条 embed）response = awaitself.client.embeddings.create(    model=self.model, input=query, dimensions=self.vector_dimensions,)# 位置 2（simple_batch_embed）response = awaitself.client.embeddings.create(input=batch,    model=self.model,    dimensions=self.vector_dimensions,)# 位置 3（batch_embed_chunks）response = awaitself.client.embeddings.create(    model=self.model, input=[item.text for item in batch],    dimensions=self.vector_dimensions,)

然后 .env 里 EMBEDDING_VECTOR_DIMENSIONS保持默认 1536（或干脆不写）。

补丁性质提醒

改的是 Docker 镜像里打包进去的 src/ 源码
docker compose build [--no-cache] 会重新打镜像、带上补丁
如果将来 cd src && git pull 覆盖了这三行，需要重新打补丁
长期想稳：fork 一份 Honcho，或维护本地 patch 文件

7. 启动

cd ~/Dockers/honchodocker compose up -d --build

构建会久一点（~5 分钟，Python 依赖多）。起来后：

docker ps --format 'table {{.Names}}\t{{.Status}}'# honcho-api-1        Up# honcho-deriver-1    Up# honcho-database-1   Up (healthy)# honcho-redis-1      Up (healthy)

验证 API：

curl -sS http://127.0.0.1:38830/openapi.json | jq '.paths | keys[:5]'# [#   "/v3/workspaces",#   "/v3/workspaces/list",#   ...# ]

（注意是 /v3/，不是 /v1/。）

创建 workspace：

curl -sS -X POST http://127.0.0.1:38830/v3/workspaces \  -H "Content-Type: application/json" \  -d '{"id":"ocp-local-vs"}'

8. OpenClaw plugin 配置

openclaw plugins install @honcho-ai/openclaw-honcho

安装完 plugin 自动：

加到 plugins.load 列表
memory slot 自动指向 openclaw-honcho（说明它”接管了”memory 角色）

补 config 进 ~/.openclaw/openclaw.json：

{"plugins":{"entries":{"openclaw-honcho":{"enabled":true,"config":{"baseUrl":"http://127.0.0.1:38830","workspaceId":"ocp-local-vs"}}}}}

自持部署不用 apiKey（Honcho .env 里 AUTH_USE_AUTH=false）。

重启 gateway 让 plugin 生效：

launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

9. 端到端冒烟测试

plugin 挂了 agent_end hook —— gateway 重启后的每一条对话都会自动被捕获。随便聊几句后查 Honcho：

WS=ocp-local-vs# peerscurl -sS -X POST "http://127.0.0.1:38830/v3/workspaces/$WS/peers/list" \     -H "Content-Type: application/json" -d '{}' | jq '.items[].id'# "owner"# "agent-main"# "agent-vs-openclaw-mgr"# sessionscurl -sS -X POST "http://127.0.0.1:38830/v3/workspaces/$WS/sessions/list" \     -H "Content-Type: application/json" -d '{}' | jq '.items[].id'# "agent-vs-openclaw-mgr-memory-honcho-20260420-1-webchat"# 消息落库SID=agent-vs-openclaw-mgr-memory-honcho-20260420-1-webchatcurl -sS -X POST "http://127.0.0.1:38830/v3/workspaces/$WS/sessions/$SID/messages/list" \     -H "Content-Type: application/json" -d '{}' | jq '.total'# 4# 语义搜索curl -sS -X POST "http://127.0.0.1:38830/v3/workspaces/$WS/search" \     -H "Content-Type: application/json" \     -d '{"query":"embedding dimensions 1536"}' | jq '.[0].content[:80]'# "[Mon 2026-04-20 16:52 GMT+8] 已解决 embedding 维度冲突..."

Deriver 工作情况（docker logs honcho-deriver-1）：

╭────── ⚡ PERFORMANCE - minimal_deriver_4_agent-vs-openclaw-mgr ──────╮│   Starting Message Id        3        ││   Ending Message Id          4        ││   Llm Call Duration          23492 ms ││   Total Processing Time      24913 ms ││   Observation Count          9        │╰────────────────────────────────────────╯

全链路贯通清单：

组件	状态
OpenClaw → Honcho 写入	✅ 消息全落库
Peers / Sessions 自动创建	✅
Embedding (Qwen3 → 1536 维)	✅ sync_vectors 周期性跑通
pgvector 存储	✅ 无维度报错
Deriver LLM (deepseek-v3.2)	✅ 抽出 9 / 19 个 observations
Workspace 语义搜索	✅ 命中相关消息

10. 隔离策略（只给本机用）

Honcho plugin 对每个 agent 自动生成 agent-{agentId} peer，对每个 OpenClaw session 自动生成一个 Honcho session。所以天然就是 agent 级隔离，不会串台。

集群维度怎么隔离？有两层选择：

一机一套 Honcho（当前做法）：物理隔离，最干净
单实例多 workspace：给不同机器用不同 workspaceId（Honcho 以 workspace 为隔离边界）

目前选 1，简单可靠，不占带宽。

11. Honcho vs. Cognee 对比

功能定位

维度	Cognee	Honcho
核心抽象	知识图谱 (KG)	人设 / 关系模型 (peer representation)
存储模型	entities + relations + DataPoints	peers + sessions + messages + observations
数据基座	Neo4j/Kuzu graph + LanceDB vector	PostgreSQL + pgvector + Redis
在回答什么问题	“跟 X 有关的事实、实体、关系”	“这个用户是谁、偏好什么、信什么”
Deriver 做什么	抽 entities 和 relations，建图	抽 observations，更新 peer 心智模型
隔离粒度	dataset 级	workspace / peer / session 三层

一句话：Cognee 记”世界”，Honcho 记”人”。

本机实测对比

操作	Cognee（本地 ollama）	Honcho（OpenRouter）
单条消息写入 ack	几百 ms	几十 ms
Deriver 处理一条消息	批次 200 DataPoint 要 10 分钟（gemma4:9b）	20–30 秒/消息
语义搜索	依赖 LLM 路由，并发易拖死 ollama	pgvector ANN + 可选 rerank，百毫秒级
Embedding	本地 qwen3-embedding-8b 25 GB VRAM	OpenRouter 远程，~几百 ms/次
稳定性	⚠️ 31B 会把 ollama runner 死锁；9B 够用但吃内存	✅ Docker 全部本地，LLM 远程

资源占用

Cognee 全家桶（LLM 本地）：gemma4:9b 13 GB + qwen3-embedding-8b 25 GB + 图数据库 + 向量库 ≈ 40 GB 常驻内存
Honcho 全家桶（LLM 远程）：api + deriver + postgres + redis ≈ 1.5 GB 内存

主要痛点

	Cognee	Honcho
痛点	本地 LLM 长尾把 ollama 玩死；ERRORED dataset 恢复麻烦	pgvector 硬绑 1536 维，第三方 embedding 要打补丁
恢复成本	高（删 cache、重 cognify）	低（`docker compose up` 即可，状态都在 Postgres）

场景建议

全局知识搜索 / 跨 session 事实检索 → Cognee 更合适
agent 了解用户 / 长期陪伴 / 上下文注入 → Honcho 更合适
能同时用吗？ OpenClaw 的 memory slot 目前只能挂一个，但 plugin 机制允许扩展；也可以一个当主、另一个通过独立 plugin 写入

12. 运维备忘

查消息：docker logs -f honcho-deriver-1 | grep PERFORMANCE
查 queue：curl -sS http://127.0.0.1:38830/v3/workspaces/$WS/queue/status | jq
完整重置：docker compose down -v → 清空 pg/redis volume → docker compose up -d --build
升级 Honcho：cd src && git pull && docker compose build && docker compose up -d