环境Win11WSL2Ubuntu24.04一、相关文档.1. 持久化记忆外部记忆提供程序为了获得比 MEMORY.md 和 USER.md 更深层次的持久化记忆Hermes 附带了 8 个外部记忆提供程序插件 — 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。外部提供程序与内置记忆并行运行从不替代它并增加了诸如知识图谱、语义搜索、自动事实提取和跨会话用户建模等功能。hermes memory setup # pick a provider and configure it hermes memory status # check whats active说明这个setup只是安装客户端2. 记忆提供程序Hermes Agent 自带 8 个外部内存提供程序插件为代理提供超出内置 MEMORY.md 和 USER.md 的持久化、跨会话知识。同一时间只能激活一个外部提供程序 —— 内置内存始终与其并行工作。Memory Providers这个里有userPeerAliases的说明3. Honcho 记忆Honcho Memory这个里有userPeerAliases的说明4. Honcho Memory Provider这个里有userPeerAliases的说明5. Hermes Agent Honcho不常用二、推荐方案根据不同使用需求分级推荐1. 入门零成本首选Holographic无需部署额外服务、安装额外依赖基于系统原生 SQLite 运行在 WSL2 环境中启用零门槛。支持全文搜索、信任评分、实体代数查询足够满足基础的跨会话记忆增强需求。2. 国产 / 结构化知识管理首选OpenViking国产开源方案支持文件系统风格的知识层级、分级检索L0 摘要→L2 全文能自动提取个人资料、偏好、实体等 6 类记忆。适合需要结构化沉淀项目知识的场景可直接在 WSL2 Ubuntu 中部署服务端完全免费。3. 重度使用 / 高阶能力首选Honcho自托管版所有提供程序中功能最完整的方案支持辩证推理自动构建用户画像、双层上下文注入、多代理身份隔离、会话级摘要适配复杂的多配置集、多角色使用场景。自托管版本完全免费和 Hermes 集成深度最高适合长期重度使用。说明hermes外部记忆honcho功能强大安装比较复杂除了客户端还需要服务端在线的收费本地安装的免费。如果是个人使用的hermes感觉没必要装这个复杂的。三、安装honcho服务端通过docker安装启动3.1 git下载~$ git clone https://github.com/plastic-labs/honcho.git~$ cd honcho/3.2复制配置文件adminUD26~/honcho$ cp .env.template .envadminUD26:~/honcho$ cp docker-compose.yml.example docker-compose.yml3.3 修改配置文件-在线模型.env# .env 配置示例适配阿里云百炼 # 直接替换 / 新增到你的 .env 文件中即可 # 1. 基础核心配置 # 本地部署关闭认证与 Hermes 客户端配置对应 # AUTH_USE_AUTHfalse 阿里云百炼 API Key填你的 DashScope API Key LLM_OPENAI_API_KEYsk-59b092640e2f4b969c3ee71234567890 Docker Compose 部署专用数据库配置必须修改主机为db # DB_CONNECTION_URIpostgresqlpsycopg://postgres:postgreslocalhost:5432/postgres DB_CONNECTION_URIpostgresqlpsycopg://postgres:postgresdb:5432/postgres 向量存储保持默认 pgvector VECTOR_STORE_TYPEpgvector 2. 向量嵌入模型配置语义搜索必需 text-embedding-v4 默认维度 1024 维 EMBEDDING_VECTOR_DIMENSIONS1536 EMBEDDING_MAX_INPUT_TOKENS8192 EMBEDDING_MODEL_CONFIG__TRANSPORTopenai EMBEDDING_MODEL_CONFIG__MODELtext-embedding-v4 EMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 3. 辩证推理分档位模型配置核心功能 5个推理档位分别配置可按需调整对应模型 minimal 档位基础事实提取 DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODELqwen3.6-flash DIALECTIC_LEVELS__minimal__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 low 档位基础推理Hermes 客户端默认档位 DIALECTIC_LEVELS__low__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__low__MODEL_CONFIG__MODELqwen3.6-flash DIALECTIC_LEVELS__low__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 medium 档位多维度综合分析 DIALECTIC_LEVELS__medium__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__medium__MODEL_CONFIG__MODELqwen3.7-plus DIALECTIC_LEVELS__medium__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 high 档位复杂行为模式推理 DIALECTIC_LEVELS__high__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__high__MODEL_CONFIG__MODELqwen3.7-plus DIALECTIC_LEVELS__high__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 max 档位审计级深度分析 DIALECTIC_LEVELS__max__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__max__MODEL_CONFIG__MODELqwen3.7-plus DIALECTIC_LEVELS__max__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 4. 其他后台功能模型配置 后台记忆提取 WorkerDeriver DERIVER_MODEL_CONFIG__TRANSPORTopenai DERIVER_MODEL_CONFIG__MODELqwen3.6-flash DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 会话摘要Summary SUMMARY_MODEL_CONFIG__TRANSPORTopenai SUMMARY_MODEL_CONFIG__MODELqwen3.6-flash SUMMARY_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 梦境整合Dream双模型 梦境演绎模型高阶模型 DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORTopenai DREAM_DEDUCTION_MODEL_CONFIG__MODELqwen3.7-plus DREAM_DEDUCTION_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 梦境归纳模型轻量模型 DREAM_INDUCTION_MODEL_CONFIG__TRANSPORTopenai DREAM_INDUCTION_MODEL_CONFIG__MODELqwen3.6-flash DREAM_INDUCTION_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1后续修改.env后需要重新构建docker compose up -d3.4 修改配置文件-本地模型待补充3.5 构建服务镜像并启动安装dockeradminUD26:~/honcho$ docker compose up -d --buildThe command docker could not be found in this WSL 2 distro.We recommend to activate the WSL integration in Docker Desktop settings.For details about using Docker Desktop with WSL 2, visit:https://docs.docker.com/go/wsl2/方案一启用 Docker Desktop WSL2 集成推荐无需在 WSL 内重复安装点击Apply restart后关闭wsl终端或重启wsl新开wsl终端测试docker --versiondocker compose version方案二WSL2 Ubuntu 内原生安装 Docker Engine不使用 Docker Desktop...重启WSL集成adminUD26:~/honcho$C:\Users\adminwsladminUD26:~$ cd ~/honchoadminUD26:~/honcho$ docker --versionDocker version 29.6.1, build 8900f1dadminUD26:~/honcho$ docker compose versionDocker Compose version v5.3.0adminUD26:~/honcho$ docker compose up -d --buildunable to get image honcho-api: failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory点击Restart the WSL integration网络错误1adminUD26:~/honcho$ docker compose up -d --build[] up 2/2✘ Image pgvector/pgvector:pg15 Error unknown: failed to resolve reference docker.io/pgvector/pgvector:pg15: unexpected status from HEAD request to https://dbmkkzay.mirror.aliyuncs.com/v2/pgve... 21.4s! Image redis:8.2 Interrupted 21.4sError response from daemon: unknown: failed to resolve reference docker.io/pgvector/pgvector:pg15: unexpected status from HEAD request to https://dbmkkzay.mirror.aliyuncs.com/v2/pgvector/pgvector/manifests/pg15?nsdocker.io: 403 Forbidden开网络代理网络错误2adminUD26:~/honcho$ docker compose up -d --build[] up 28/28✔ Image redis:8.2 Pulled 41.2s✔ Image pgvector/pgvector:pg15 Pulled 78.1s[] Building 11.4s (4/4) FINISHED [internal] load local bake definitions 0.0s reading from stdin 881B 0.0s [api internal] load build definition from Dockerfile 0.0s transferring dockerfile: 1.76kB 0.0s ERROR [api internal] load metadata for ghcr.io/astral-sh/uv:0.9.24 11.2s ERROR [api internal] load metadata for docker.io/library/python:3.13-slim-bookworm 11.2s------ [api internal] load metadata for ghcr.io/astral-sh/uv:0.9.24:------[] up 28/30✔ Image redis:8.2 Pulled 41.2s✔ Image pgvector/pgvector:pg15 Pulled 78.1s⠙ Image honcho-deriver Building 11.4s⠙ Image honcho-api Building 11.4sDockerfile:5--------------------3 | FROM python:3.13-slim-bookworm4 |5 | COPY --fromghcr.io/astral-sh/uv:0.9.24 /uv /bin/uv6 |7 | # Set Working directory--------------------target deriver: failed to solve: failed to fetch anonymous token: Get https://ghcr.io/token?scoperepository%3Aastral-sh%2Fuv%3Apullserviceghcr.io: net/http: TLS handshake timeoutadminUD26:~/honcho$开网络代理重启WSL构建启动成功C:\Users\adminwsladminUD26:~$ cd ~/honchoadminUD26:~/honcho$ docker compose up -d --buildadminUD26:~/honcho$ docker compose up -d --build unable to get image pgvector/pgvector:pg15: failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory 再次执行 adminUD26:~/honcho$ docker compose up -d --build [] Building 111.2s (24/24) FINISHED [internal] load local bake definitions 0.0s reading from stdin 881B 0.0s [deriver internal] load build definition from Dockerfile 0.0s transferring dockerfile: 1.76kB 0.0s [api internal] load metadata for ghcr.io/astral-sh/uv:0.9.24 4.0s [api internal] load metadata for docker.io/library/python:3.13-slim-bookworm 10.3s [api internal] load .dockerignore 0.0s transferring context: 188B 0.0s [api] FROM ghcr.io/astral-sh/uv:0.9.24sha256:816fdce3387ed2142e37d2e56e1b1b97ccc1ea87731ba199dc8a25c04e4997c5 13.9s resolve ghcr.io/astral-sh/uv:0.9.24sha256:816fdce3387ed2142e37d2e56e1b1b97ccc1ea87731ba199dc8a25c04e4997c5 0.0s sha256:9f6813bb3661b8791d11d9856107e821ca3d88db2f8f433e3c08f480e24ea7b4 98B / 98B 0.6s sha256:e6040e18015132ec5d84db1866c517a616eff56e82e3c391aed7230d8ded313e 22.50MB / 22.50MB 13.6s extracting sha256:e6040e18015132ec5d84db1866c517a616eff56e82e3c391aed7230d8ded313e 0.2s extracting sha256:9f6813bb3661b8791d11d9856107e821ca3d88db2f8f433e3c08f480e24ea7b4 0.0s [deriver internal] load build context 0.1s transferring context: 2.76MB 0.1s [deriver stage-0 1/13] FROM docker.io/library/python:3.13-slim-bookwormsha256:9d7f287598e1a5a978c015ee176d8216435aaf335ed69ac3c38dd1bbb10e8d64 7.9s resolve docker.io/library/python:3.13-slim-bookwormsha256:9d7f287598e1a5a978c015ee176d8216435aaf335ed69ac3c38dd1bbb10e8d64 0.0s sha256:34aa232ecaaac16361c5aa2528fdbfa952668e065ae4fc0c8ccc90e7512e2073 249B / 249B 1.8s sha256:2941ee8edc00910c3131427c7417a0c02996cf042e94d8bd3d4deaa5de06e7e5 12.57MB / 12.57MB 6.1s sha256:b4558791a7f73b5ec27f2ce53c863264be012b6795789cfdcc6508df8ffe1017 3.52MB / 3.52MB 7.5s extracting sha256:b4558791a7f73b5ec27f2ce53c863264be012b6795789cfdcc6508df8ffe1017 0.1s extracting sha256:2941ee8edc00910c3131427c7417a0c02996cf042e94d8bd3d4deaa5de06e7e5 0.1s extracting sha256:34aa232ecaaac16361c5aa2528fdbfa952668e065ae4fc0c8ccc90e7512e2073 0.0s [deriver stage-0 2/13] COPY --fromghcr.io/astral-sh/uv:0.9.24 /uv /bin/uv 0.1s [api stage-0 3/13] WORKDIR /app 0.0s [api stage-0 4/13] RUN --mounttypecache,target/root/.cache/uv --mounttypebind,sourceuv.lock,targetuv.lock --mounttypebind,sourcepyproject.toml,targetpyproject.toml uv sync - 44.0s [api stage-0 5/13] COPY uv.lock pyproject.toml /app/ 0.1s [api stage-0 6/13] RUN --mounttypecache,target/root/.cache/uv uv sync --frozen --no-group dev 0.5s [deriver stage-0 7/13] RUN addgroup --system app adduser --system --group app mkdir -p /tmp/uv-cache chown -R app:app /app /tmp/uv-cache 21.9s [api stage-0 8/13] COPY --chownapp:app src/ /app/src/ 0.1s [api stage-0 9/13] COPY --chownapp:app migrations/ /app/migrations/ 0.0s [deriver stage-0 10/13] COPY --chownapp:app scripts/ /app/scripts/ 0.0s [api stage-0 11/13] COPY --chownapp:app docker/ /app/docker/ 0.0s [api stage-0 12/13] COPY --chownapp:app alembic.ini /app/alembic.ini 0.0s [deriver stage-0 13/13] COPY --chownapp:app config.toml* /app/ 0.0s [deriver] exporting to image 19.8s exporting layers 14.2s exporting manifest sha256:31186a4bcbfd20842577f5a64e776fd3aadb8b92ee72b7e44dbb7e4eef21f6c6 0.0s exporting config sha256:54c8e4b16cde7e2dff7711a395451ce854ac56c627db9c13c81730e86ea30a7e 0.0s exporting attestation manifest sha256:045b4a856a505822caae0afb79494bf8a989315a5aa44155bdc3b430a58c95ab 0.0s exporting manifest list sha256:2f415ee3bdb459a01f1a8d24745663a126395ef64ffc9d2b3cca6e3207e12bdc 0.0s naming to docker.io/library/honcho-deriver:latest 0.0s unpacking to docker.io/library/honcho-deriver:latest 5.5s [api] exporting to image 19.8s exporting layers 14.2s exporting manifest sha256:3ecd677981369a810ebaf024224a17b76a9771d7899605d17a35732f594ee7cb 0.0s exporting config sha256:6675735f6e4b0eb0138dcce1af54768d731fde462bb094571007c7640cdf4e93 0.0s exporting attestation manifest sha256:90b5511c78cb070ce543fcd727c13e67b20958f44b432e260a27f94239f959d8 0.0s exporting manifest list sha256:9457e87cd65f2ba0e0041c1f11a734c65118210b2f6942bd35236f56ec615b37 0.0s naming to docker.io/library/honcho-api:latest 0.0s unpacking to docker.io/library/honcho-api:latest 5.5s [api] resolving provenance for metadata file 0.0s [deriver] resolving provenance for metadata file 0.0s [] up 9/9 ✔ Image honcho-api Built 111.2s ✔ Image honcho-deriver Built 111.2s ✔ Network honcho_default Created 0.3s ✔ Volume honcho_pgdata Created 0.0s ✔ Volume honcho_redis-data Created 0.0s ✔ Container honcho-database-1 Healthy 8.7s ✔ Container honcho-redis-1 Healthy 8.7s ✔ Container honcho-api-1 Healthy 18.2s ✔ Container honcho-deriver-1 Started 18.6s3.6 列出与 Docker Compose 项目相关的容器及其状态adminUD26:~/honcho$ docker compose psNAME IMAGE COMMAND SERVICE CREATED STATUS PORTShoncho-api-1 honcho-api sh docker/entrypoin… api 8 minutes ago Up 8 minutes (healthy) 127.0.0.1:8000-8000/tcphoncho-database-1 pgvector/pgvector:pg15 docker-entrypoint.s… database 8 minutes ago Up 8 minutes (healthy) 127.0.0.1:5432-5432/tcphoncho-deriver-1 honcho-deriver /app/.venv/bin/pyth… deriver 8 minutes ago Up 7 minutes 8000/tcphoncho-redis-1 redis:8.2 docker-entrypoint.s… redis 8 minutes ago Up 8 minutes (healthy) 127.0.0.1:6379-6379/tcp四、安装honcho客户端hermes memory setup或hermes memory setup honchohermes 配置外部记忆honcho客户端安装五、查看服务状态5.1 查看honcho服务状态adminUD26:~/honcho$ curl http://localhost:8000/health{status:ok}5.2 查看honcho帮助adminUD26:~$ hermes honcho -h usage: hermes honcho [-h] [--target-profile NAME] {setup,status,peers,sessions,map,peer,mode,strategy,tokens,identity,migrate,enable,disable,sync} ... Honcho AI-native memory — cross-session user modeling with dialectic QA, semantic search, and persistent conclusions. positional arguments: {setup,status,peers,sessions,map,peer,mode,strategy,tokens,identity,migrate,enable,disable,sync} setup Initial Honcho setup (redirects to hermes memory setup) status Show current Honcho config and connection status peers Show peer identities across all profiles sessions List known Honcho session mappings map Map current directory to a Honcho session name (no arg list mappings) peer Show or update peer names and dialectic reasoning level mode Show or set recall mode (hybrid/context/tools) strategy Show or set session strategy (per-session/per-directory/per-repo/global) tokens Show or set token budget for context and dialectic identity Seed or show the AI peers Honcho identity representation migrate Step-by-step migration guide from openclaw-honcho to Hermes Honcho enable Enable Honcho for the active profile disable Disable Honcho for the active profile sync Sync Honcho config to all existing profiles options: -h, --help show this help message and exit --target-profile NAME Target a specific profiles Honcho config without switching5.3 查看honcho状态adminUD26:~$ hermes honcho status Honcho status ──────────────────────────────────────── Host: hermes Enabled: True Auth: API key (not set) Workspace: hermes Config: /home/admin/.hermes/honcho.json AI peer: hermes User peer: admin Session key: admin Session strat: per-directory Recall mode: hybrid Context budget: (uncapped) tokens Dialectic cad: every 1 turn Reasoning: baselow, caphigh, heuristicon Observation: user(meTrue,othersTrue) ai(meTrue,othersTrue) Write freq: async Connection... No peer data yet (accumulates after first conversation) OK5.4 查看hermes记忆状态hermes memory statusadminUD26:~$ hermes memory status Memory status ──────────────────────────────────────── Built-in: always active Provider: honcho Plugin: installed ✓ Status: available ✓ Installed plugins: • byterover (API key / local) • hindsight (API key / local) • holographic (local) • honcho (API key / local) ← active • mem0 (API key / local) • openviking (API key / local) • retaindb (API key / local) • supermemory (requires API key)六、honcho测试验证6.1 聊天中的honcho工具Honcho tools available in chat: honcho_context -- session context: summary, representation, card, messages honcho_search -- semantic search over history honcho_profile -- peer card, key facts honcho_reasoning -- ask Honcho a question, synthesized answer honcho_conclude -- persist a user fact to memory英文文档说明honcho_context (session context — summary, representation, card, messages)honcho_search (semantic search)honcho_profile (read/update peer card)honcho_reasoning (LLM-synthesized)honcho_conclude (create/delete conclusions)中文文档说明honcho_context会话上下文——摘要、表示、卡片、消息honcho_search语义搜索honcho_profile读取/更新同僚卡片honcho_reasoningLLM 合成honcho_conclude创建/删除结论6.2 聊天内逐个验证 Honcho 工具进入 Hermes 聊天界面后直接输入工具名 对应内容即可触发按以下顺序验证覆盖写入→读取→检索→推理全流程1. 验证记忆写入honcho_conclude输入内容honcho_conclude 我常用的开发环境是WSL2 Ubuntu 24.04验证目标确认记忆写入链路、服务端基础 LLM 提取功能、数据库存储正常。通过标准模型回复确认已持久化该事实无报错。2. 验证用户画像读取honcho_profile输入内容honcho_profile验证目标确认记忆读取、用户画像整合功能正常。通过标准返回结构化的用户画像卡片且包含你刚才写入的「WSL2 Ubuntu 24.04 开发环境」相关内容。3. 验证会话上下文honcho_context输入内容honcho_context验证目标确认会话管理、上下文摘要功能正常。通过标准返回当前会话的汇总信息包含会话摘要、历史消息片段。4. 验证语义搜索honcho_search输入内容honcho_search 开发环境验证目标确认向量嵌入模型、pgvector 向量存储、语义检索功能正常这个环节最容易暴露嵌入模型配置错误。通过标准能检索匹配到你刚才写入的开发环境相关记忆内容。5. 验证辩证推理honcho_reasoning输入内容honcho_reasoning 总结一下我的开发环境偏好验证目标确认辩证推理模块Honcho 的核心功能的 LLM 配置与工具调用能力是否正常。通过标准模型能够基于已存储的记忆返回经过综合推理得出的总结性结论且整个调用过程无任何报错表明推理档位的模型配置已完全生效。异常排查方向如果某个工具调用报错优先查两个地方1. Honcho 服务端日志在 honcho 项目目录执行 docker compose logs api大概率是 LLM 的模型名、Base URL、API 密钥配置错误或模型不支持工具调用。2. 客户端配置执行 hermes honcho status 确认 Recall mode 为 hybrid 或 tools只有这两个模式会开放 Honcho 工具。七、报错处理7.1 向量模型维度不匹配ValueError: Embedding dimension mismatch for openai:text-embedding-v4. Expected 1536, got 1024.src.startup.embedding_validator.StartupValidationError: public.documents.embedding dim (1536) does not match EMBEDDING_VECTOR_DIMENSIONS (1024). Run uv run python scripts/configure_embeddings.py or fix EMBEDDING_VECTOR_DIMENSIONS.honcho默认是1536text-embedding-v4 默认是1024可以修改配置文件.env指定维度参数。text-embedding-v4 默认维度 1024 维EMBEDDING_VECTOR_DIMENSIONS1536EMBEDDING_MAX_INPUT_TOKENS8192
hermes 配置外部记忆honcho服务端安装
环境Win11WSL2Ubuntu24.04一、相关文档.1. 持久化记忆外部记忆提供程序为了获得比 MEMORY.md 和 USER.md 更深层次的持久化记忆Hermes 附带了 8 个外部记忆提供程序插件 — 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。外部提供程序与内置记忆并行运行从不替代它并增加了诸如知识图谱、语义搜索、自动事实提取和跨会话用户建模等功能。hermes memory setup # pick a provider and configure it hermes memory status # check whats active说明这个setup只是安装客户端2. 记忆提供程序Hermes Agent 自带 8 个外部内存提供程序插件为代理提供超出内置 MEMORY.md 和 USER.md 的持久化、跨会话知识。同一时间只能激活一个外部提供程序 —— 内置内存始终与其并行工作。Memory Providers这个里有userPeerAliases的说明3. Honcho 记忆Honcho Memory这个里有userPeerAliases的说明4. Honcho Memory Provider这个里有userPeerAliases的说明5. Hermes Agent Honcho不常用二、推荐方案根据不同使用需求分级推荐1. 入门零成本首选Holographic无需部署额外服务、安装额外依赖基于系统原生 SQLite 运行在 WSL2 环境中启用零门槛。支持全文搜索、信任评分、实体代数查询足够满足基础的跨会话记忆增强需求。2. 国产 / 结构化知识管理首选OpenViking国产开源方案支持文件系统风格的知识层级、分级检索L0 摘要→L2 全文能自动提取个人资料、偏好、实体等 6 类记忆。适合需要结构化沉淀项目知识的场景可直接在 WSL2 Ubuntu 中部署服务端完全免费。3. 重度使用 / 高阶能力首选Honcho自托管版所有提供程序中功能最完整的方案支持辩证推理自动构建用户画像、双层上下文注入、多代理身份隔离、会话级摘要适配复杂的多配置集、多角色使用场景。自托管版本完全免费和 Hermes 集成深度最高适合长期重度使用。说明hermes外部记忆honcho功能强大安装比较复杂除了客户端还需要服务端在线的收费本地安装的免费。如果是个人使用的hermes感觉没必要装这个复杂的。三、安装honcho服务端通过docker安装启动3.1 git下载~$ git clone https://github.com/plastic-labs/honcho.git~$ cd honcho/3.2复制配置文件adminUD26~/honcho$ cp .env.template .envadminUD26:~/honcho$ cp docker-compose.yml.example docker-compose.yml3.3 修改配置文件-在线模型.env# .env 配置示例适配阿里云百炼 # 直接替换 / 新增到你的 .env 文件中即可 # 1. 基础核心配置 # 本地部署关闭认证与 Hermes 客户端配置对应 # AUTH_USE_AUTHfalse 阿里云百炼 API Key填你的 DashScope API Key LLM_OPENAI_API_KEYsk-59b092640e2f4b969c3ee71234567890 Docker Compose 部署专用数据库配置必须修改主机为db # DB_CONNECTION_URIpostgresqlpsycopg://postgres:postgreslocalhost:5432/postgres DB_CONNECTION_URIpostgresqlpsycopg://postgres:postgresdb:5432/postgres 向量存储保持默认 pgvector VECTOR_STORE_TYPEpgvector 2. 向量嵌入模型配置语义搜索必需 text-embedding-v4 默认维度 1024 维 EMBEDDING_VECTOR_DIMENSIONS1536 EMBEDDING_MAX_INPUT_TOKENS8192 EMBEDDING_MODEL_CONFIG__TRANSPORTopenai EMBEDDING_MODEL_CONFIG__MODELtext-embedding-v4 EMBEDDING_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 3. 辩证推理分档位模型配置核心功能 5个推理档位分别配置可按需调整对应模型 minimal 档位基础事实提取 DIALECTIC_LEVELS__minimal__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__minimal__MODEL_CONFIG__MODELqwen3.6-flash DIALECTIC_LEVELS__minimal__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 low 档位基础推理Hermes 客户端默认档位 DIALECTIC_LEVELS__low__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__low__MODEL_CONFIG__MODELqwen3.6-flash DIALECTIC_LEVELS__low__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 medium 档位多维度综合分析 DIALECTIC_LEVELS__medium__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__medium__MODEL_CONFIG__MODELqwen3.7-plus DIALECTIC_LEVELS__medium__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 high 档位复杂行为模式推理 DIALECTIC_LEVELS__high__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__high__MODEL_CONFIG__MODELqwen3.7-plus DIALECTIC_LEVELS__high__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 max 档位审计级深度分析 DIALECTIC_LEVELS__max__MODEL_CONFIG__TRANSPORTopenai DIALECTIC_LEVELS__max__MODEL_CONFIG__MODELqwen3.7-plus DIALECTIC_LEVELS__max__MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 4. 其他后台功能模型配置 后台记忆提取 WorkerDeriver DERIVER_MODEL_CONFIG__TRANSPORTopenai DERIVER_MODEL_CONFIG__MODELqwen3.6-flash DERIVER_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 会话摘要Summary SUMMARY_MODEL_CONFIG__TRANSPORTopenai SUMMARY_MODEL_CONFIG__MODELqwen3.6-flash SUMMARY_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 梦境整合Dream双模型 梦境演绎模型高阶模型 DREAM_DEDUCTION_MODEL_CONFIG__TRANSPORTopenai DREAM_DEDUCTION_MODEL_CONFIG__MODELqwen3.7-plus DREAM_DEDUCTION_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 梦境归纳模型轻量模型 DREAM_INDUCTION_MODEL_CONFIG__TRANSPORTopenai DREAM_INDUCTION_MODEL_CONFIG__MODELqwen3.6-flash DREAM_INDUCTION_MODEL_CONFIG__OVERRIDES__BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1后续修改.env后需要重新构建docker compose up -d3.4 修改配置文件-本地模型待补充3.5 构建服务镜像并启动安装dockeradminUD26:~/honcho$ docker compose up -d --buildThe command docker could not be found in this WSL 2 distro.We recommend to activate the WSL integration in Docker Desktop settings.For details about using Docker Desktop with WSL 2, visit:https://docs.docker.com/go/wsl2/方案一启用 Docker Desktop WSL2 集成推荐无需在 WSL 内重复安装点击Apply restart后关闭wsl终端或重启wsl新开wsl终端测试docker --versiondocker compose version方案二WSL2 Ubuntu 内原生安装 Docker Engine不使用 Docker Desktop...重启WSL集成adminUD26:~/honcho$C:\Users\adminwsladminUD26:~$ cd ~/honchoadminUD26:~/honcho$ docker --versionDocker version 29.6.1, build 8900f1dadminUD26:~/honcho$ docker compose versionDocker Compose version v5.3.0adminUD26:~/honcho$ docker compose up -d --buildunable to get image honcho-api: failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory点击Restart the WSL integration网络错误1adminUD26:~/honcho$ docker compose up -d --build[] up 2/2✘ Image pgvector/pgvector:pg15 Error unknown: failed to resolve reference docker.io/pgvector/pgvector:pg15: unexpected status from HEAD request to https://dbmkkzay.mirror.aliyuncs.com/v2/pgve... 21.4s! Image redis:8.2 Interrupted 21.4sError response from daemon: unknown: failed to resolve reference docker.io/pgvector/pgvector:pg15: unexpected status from HEAD request to https://dbmkkzay.mirror.aliyuncs.com/v2/pgvector/pgvector/manifests/pg15?nsdocker.io: 403 Forbidden开网络代理网络错误2adminUD26:~/honcho$ docker compose up -d --build[] up 28/28✔ Image redis:8.2 Pulled 41.2s✔ Image pgvector/pgvector:pg15 Pulled 78.1s[] Building 11.4s (4/4) FINISHED [internal] load local bake definitions 0.0s reading from stdin 881B 0.0s [api internal] load build definition from Dockerfile 0.0s transferring dockerfile: 1.76kB 0.0s ERROR [api internal] load metadata for ghcr.io/astral-sh/uv:0.9.24 11.2s ERROR [api internal] load metadata for docker.io/library/python:3.13-slim-bookworm 11.2s------ [api internal] load metadata for ghcr.io/astral-sh/uv:0.9.24:------[] up 28/30✔ Image redis:8.2 Pulled 41.2s✔ Image pgvector/pgvector:pg15 Pulled 78.1s⠙ Image honcho-deriver Building 11.4s⠙ Image honcho-api Building 11.4sDockerfile:5--------------------3 | FROM python:3.13-slim-bookworm4 |5 | COPY --fromghcr.io/astral-sh/uv:0.9.24 /uv /bin/uv6 |7 | # Set Working directory--------------------target deriver: failed to solve: failed to fetch anonymous token: Get https://ghcr.io/token?scoperepository%3Aastral-sh%2Fuv%3Apullserviceghcr.io: net/http: TLS handshake timeoutadminUD26:~/honcho$开网络代理重启WSL构建启动成功C:\Users\adminwsladminUD26:~$ cd ~/honchoadminUD26:~/honcho$ docker compose up -d --buildadminUD26:~/honcho$ docker compose up -d --build unable to get image pgvector/pgvector:pg15: failed to connect to the docker API at unix:///var/run/docker.sock; check if the path is correct and if the daemon is running: dial unix /var/run/docker.sock: connect: no such file or directory 再次执行 adminUD26:~/honcho$ docker compose up -d --build [] Building 111.2s (24/24) FINISHED [internal] load local bake definitions 0.0s reading from stdin 881B 0.0s [deriver internal] load build definition from Dockerfile 0.0s transferring dockerfile: 1.76kB 0.0s [api internal] load metadata for ghcr.io/astral-sh/uv:0.9.24 4.0s [api internal] load metadata for docker.io/library/python:3.13-slim-bookworm 10.3s [api internal] load .dockerignore 0.0s transferring context: 188B 0.0s [api] FROM ghcr.io/astral-sh/uv:0.9.24sha256:816fdce3387ed2142e37d2e56e1b1b97ccc1ea87731ba199dc8a25c04e4997c5 13.9s resolve ghcr.io/astral-sh/uv:0.9.24sha256:816fdce3387ed2142e37d2e56e1b1b97ccc1ea87731ba199dc8a25c04e4997c5 0.0s sha256:9f6813bb3661b8791d11d9856107e821ca3d88db2f8f433e3c08f480e24ea7b4 98B / 98B 0.6s sha256:e6040e18015132ec5d84db1866c517a616eff56e82e3c391aed7230d8ded313e 22.50MB / 22.50MB 13.6s extracting sha256:e6040e18015132ec5d84db1866c517a616eff56e82e3c391aed7230d8ded313e 0.2s extracting sha256:9f6813bb3661b8791d11d9856107e821ca3d88db2f8f433e3c08f480e24ea7b4 0.0s [deriver internal] load build context 0.1s transferring context: 2.76MB 0.1s [deriver stage-0 1/13] FROM docker.io/library/python:3.13-slim-bookwormsha256:9d7f287598e1a5a978c015ee176d8216435aaf335ed69ac3c38dd1bbb10e8d64 7.9s resolve docker.io/library/python:3.13-slim-bookwormsha256:9d7f287598e1a5a978c015ee176d8216435aaf335ed69ac3c38dd1bbb10e8d64 0.0s sha256:34aa232ecaaac16361c5aa2528fdbfa952668e065ae4fc0c8ccc90e7512e2073 249B / 249B 1.8s sha256:2941ee8edc00910c3131427c7417a0c02996cf042e94d8bd3d4deaa5de06e7e5 12.57MB / 12.57MB 6.1s sha256:b4558791a7f73b5ec27f2ce53c863264be012b6795789cfdcc6508df8ffe1017 3.52MB / 3.52MB 7.5s extracting sha256:b4558791a7f73b5ec27f2ce53c863264be012b6795789cfdcc6508df8ffe1017 0.1s extracting sha256:2941ee8edc00910c3131427c7417a0c02996cf042e94d8bd3d4deaa5de06e7e5 0.1s extracting sha256:34aa232ecaaac16361c5aa2528fdbfa952668e065ae4fc0c8ccc90e7512e2073 0.0s [deriver stage-0 2/13] COPY --fromghcr.io/astral-sh/uv:0.9.24 /uv /bin/uv 0.1s [api stage-0 3/13] WORKDIR /app 0.0s [api stage-0 4/13] RUN --mounttypecache,target/root/.cache/uv --mounttypebind,sourceuv.lock,targetuv.lock --mounttypebind,sourcepyproject.toml,targetpyproject.toml uv sync - 44.0s [api stage-0 5/13] COPY uv.lock pyproject.toml /app/ 0.1s [api stage-0 6/13] RUN --mounttypecache,target/root/.cache/uv uv sync --frozen --no-group dev 0.5s [deriver stage-0 7/13] RUN addgroup --system app adduser --system --group app mkdir -p /tmp/uv-cache chown -R app:app /app /tmp/uv-cache 21.9s [api stage-0 8/13] COPY --chownapp:app src/ /app/src/ 0.1s [api stage-0 9/13] COPY --chownapp:app migrations/ /app/migrations/ 0.0s [deriver stage-0 10/13] COPY --chownapp:app scripts/ /app/scripts/ 0.0s [api stage-0 11/13] COPY --chownapp:app docker/ /app/docker/ 0.0s [api stage-0 12/13] COPY --chownapp:app alembic.ini /app/alembic.ini 0.0s [deriver stage-0 13/13] COPY --chownapp:app config.toml* /app/ 0.0s [deriver] exporting to image 19.8s exporting layers 14.2s exporting manifest sha256:31186a4bcbfd20842577f5a64e776fd3aadb8b92ee72b7e44dbb7e4eef21f6c6 0.0s exporting config sha256:54c8e4b16cde7e2dff7711a395451ce854ac56c627db9c13c81730e86ea30a7e 0.0s exporting attestation manifest sha256:045b4a856a505822caae0afb79494bf8a989315a5aa44155bdc3b430a58c95ab 0.0s exporting manifest list sha256:2f415ee3bdb459a01f1a8d24745663a126395ef64ffc9d2b3cca6e3207e12bdc 0.0s naming to docker.io/library/honcho-deriver:latest 0.0s unpacking to docker.io/library/honcho-deriver:latest 5.5s [api] exporting to image 19.8s exporting layers 14.2s exporting manifest sha256:3ecd677981369a810ebaf024224a17b76a9771d7899605d17a35732f594ee7cb 0.0s exporting config sha256:6675735f6e4b0eb0138dcce1af54768d731fde462bb094571007c7640cdf4e93 0.0s exporting attestation manifest sha256:90b5511c78cb070ce543fcd727c13e67b20958f44b432e260a27f94239f959d8 0.0s exporting manifest list sha256:9457e87cd65f2ba0e0041c1f11a734c65118210b2f6942bd35236f56ec615b37 0.0s naming to docker.io/library/honcho-api:latest 0.0s unpacking to docker.io/library/honcho-api:latest 5.5s [api] resolving provenance for metadata file 0.0s [deriver] resolving provenance for metadata file 0.0s [] up 9/9 ✔ Image honcho-api Built 111.2s ✔ Image honcho-deriver Built 111.2s ✔ Network honcho_default Created 0.3s ✔ Volume honcho_pgdata Created 0.0s ✔ Volume honcho_redis-data Created 0.0s ✔ Container honcho-database-1 Healthy 8.7s ✔ Container honcho-redis-1 Healthy 8.7s ✔ Container honcho-api-1 Healthy 18.2s ✔ Container honcho-deriver-1 Started 18.6s3.6 列出与 Docker Compose 项目相关的容器及其状态adminUD26:~/honcho$ docker compose psNAME IMAGE COMMAND SERVICE CREATED STATUS PORTShoncho-api-1 honcho-api sh docker/entrypoin… api 8 minutes ago Up 8 minutes (healthy) 127.0.0.1:8000-8000/tcphoncho-database-1 pgvector/pgvector:pg15 docker-entrypoint.s… database 8 minutes ago Up 8 minutes (healthy) 127.0.0.1:5432-5432/tcphoncho-deriver-1 honcho-deriver /app/.venv/bin/pyth… deriver 8 minutes ago Up 7 minutes 8000/tcphoncho-redis-1 redis:8.2 docker-entrypoint.s… redis 8 minutes ago Up 8 minutes (healthy) 127.0.0.1:6379-6379/tcp四、安装honcho客户端hermes memory setup或hermes memory setup honchohermes 配置外部记忆honcho客户端安装五、查看服务状态5.1 查看honcho服务状态adminUD26:~/honcho$ curl http://localhost:8000/health{status:ok}5.2 查看honcho帮助adminUD26:~$ hermes honcho -h usage: hermes honcho [-h] [--target-profile NAME] {setup,status,peers,sessions,map,peer,mode,strategy,tokens,identity,migrate,enable,disable,sync} ... Honcho AI-native memory — cross-session user modeling with dialectic QA, semantic search, and persistent conclusions. positional arguments: {setup,status,peers,sessions,map,peer,mode,strategy,tokens,identity,migrate,enable,disable,sync} setup Initial Honcho setup (redirects to hermes memory setup) status Show current Honcho config and connection status peers Show peer identities across all profiles sessions List known Honcho session mappings map Map current directory to a Honcho session name (no arg list mappings) peer Show or update peer names and dialectic reasoning level mode Show or set recall mode (hybrid/context/tools) strategy Show or set session strategy (per-session/per-directory/per-repo/global) tokens Show or set token budget for context and dialectic identity Seed or show the AI peers Honcho identity representation migrate Step-by-step migration guide from openclaw-honcho to Hermes Honcho enable Enable Honcho for the active profile disable Disable Honcho for the active profile sync Sync Honcho config to all existing profiles options: -h, --help show this help message and exit --target-profile NAME Target a specific profiles Honcho config without switching5.3 查看honcho状态adminUD26:~$ hermes honcho status Honcho status ──────────────────────────────────────── Host: hermes Enabled: True Auth: API key (not set) Workspace: hermes Config: /home/admin/.hermes/honcho.json AI peer: hermes User peer: admin Session key: admin Session strat: per-directory Recall mode: hybrid Context budget: (uncapped) tokens Dialectic cad: every 1 turn Reasoning: baselow, caphigh, heuristicon Observation: user(meTrue,othersTrue) ai(meTrue,othersTrue) Write freq: async Connection... No peer data yet (accumulates after first conversation) OK5.4 查看hermes记忆状态hermes memory statusadminUD26:~$ hermes memory status Memory status ──────────────────────────────────────── Built-in: always active Provider: honcho Plugin: installed ✓ Status: available ✓ Installed plugins: • byterover (API key / local) • hindsight (API key / local) • holographic (local) • honcho (API key / local) ← active • mem0 (API key / local) • openviking (API key / local) • retaindb (API key / local) • supermemory (requires API key)六、honcho测试验证6.1 聊天中的honcho工具Honcho tools available in chat: honcho_context -- session context: summary, representation, card, messages honcho_search -- semantic search over history honcho_profile -- peer card, key facts honcho_reasoning -- ask Honcho a question, synthesized answer honcho_conclude -- persist a user fact to memory英文文档说明honcho_context (session context — summary, representation, card, messages)honcho_search (semantic search)honcho_profile (read/update peer card)honcho_reasoning (LLM-synthesized)honcho_conclude (create/delete conclusions)中文文档说明honcho_context会话上下文——摘要、表示、卡片、消息honcho_search语义搜索honcho_profile读取/更新同僚卡片honcho_reasoningLLM 合成honcho_conclude创建/删除结论6.2 聊天内逐个验证 Honcho 工具进入 Hermes 聊天界面后直接输入工具名 对应内容即可触发按以下顺序验证覆盖写入→读取→检索→推理全流程1. 验证记忆写入honcho_conclude输入内容honcho_conclude 我常用的开发环境是WSL2 Ubuntu 24.04验证目标确认记忆写入链路、服务端基础 LLM 提取功能、数据库存储正常。通过标准模型回复确认已持久化该事实无报错。2. 验证用户画像读取honcho_profile输入内容honcho_profile验证目标确认记忆读取、用户画像整合功能正常。通过标准返回结构化的用户画像卡片且包含你刚才写入的「WSL2 Ubuntu 24.04 开发环境」相关内容。3. 验证会话上下文honcho_context输入内容honcho_context验证目标确认会话管理、上下文摘要功能正常。通过标准返回当前会话的汇总信息包含会话摘要、历史消息片段。4. 验证语义搜索honcho_search输入内容honcho_search 开发环境验证目标确认向量嵌入模型、pgvector 向量存储、语义检索功能正常这个环节最容易暴露嵌入模型配置错误。通过标准能检索匹配到你刚才写入的开发环境相关记忆内容。5. 验证辩证推理honcho_reasoning输入内容honcho_reasoning 总结一下我的开发环境偏好验证目标确认辩证推理模块Honcho 的核心功能的 LLM 配置与工具调用能力是否正常。通过标准模型能够基于已存储的记忆返回经过综合推理得出的总结性结论且整个调用过程无任何报错表明推理档位的模型配置已完全生效。异常排查方向如果某个工具调用报错优先查两个地方1. Honcho 服务端日志在 honcho 项目目录执行 docker compose logs api大概率是 LLM 的模型名、Base URL、API 密钥配置错误或模型不支持工具调用。2. 客户端配置执行 hermes honcho status 确认 Recall mode 为 hybrid 或 tools只有这两个模式会开放 Honcho 工具。七、报错处理7.1 向量模型维度不匹配ValueError: Embedding dimension mismatch for openai:text-embedding-v4. Expected 1536, got 1024.src.startup.embedding_validator.StartupValidationError: public.documents.embedding dim (1536) does not match EMBEDDING_VECTOR_DIMENSIONS (1024). Run uv run python scripts/configure_embeddings.py or fix EMBEDDING_VECTOR_DIMENSIONS.honcho默认是1536text-embedding-v4 默认是1024可以修改配置文件.env指定维度参数。text-embedding-v4 默认维度 1024 维EMBEDDING_VECTOR_DIMENSIONS1536EMBEDDING_MAX_INPUT_TOKENS8192
