返回主页为 Hermes Agent 接入
Hermes × Hy-Memory · 安装指南
为 Hermes Agent 接入
Hy-Memory 长期记忆
Step 01
安装
Hermes 通过扫描目录 ~/.hermes/plugins/<name>/ 发现 memory provider，不认 pip 的 entry point。所以 pip install 之后必须"激活"到该目录——0.2.0+ 已内置 install 命令自动完成。
方式 A：一键向导（推荐）
bash
# 1. 安装插件（务必带 [init]，向导依赖的 questionary 在这个 extra 里）
pip install "hermes-hy-memory[init]"
# 2. 交互式配置 —— 跑完会自动激活插件（symlink + 写 config.yaml）
hermes-hy-memory init
# 3. 重启 Hermes，然后体检
hermes-hy-memory doctorinit 向导做了什么
4 步向导（LLM → Embedder → 向量库 → User ID），把配置写进~/.hermes/.env，并自动： 把插件 symlink 到 ~/.hermes/plugins/hy-memory； 把 memory.provider: hy-memory 写进 config.yaml； 确保 hy-memory SDK 装进了 Hermes 实际运行的 venv。方式 B：手动（不走向导）
bash
# 1. 安装
pip install "hermes-hy-memory[init]"
# 2. 激活到 Hermes（自动 symlink + 装 SDK 进 Hermes 的 venv）
hermes-hy-memory install
# 如果它找不到 Hermes 的 Python，可显式指定：
# hermes-hy-memory install --hermes-python /path/to/hermes/venv/bin/python
# 3. 手动写配置（见第 5 节的 .env 模板）
nano ~/.hermes/.env
# 4. 启用 provider
hermes config set memory.provider hy-memory
# 5. 体检
hermes-hy-memory doctorinstall vs init
install 只负责"激活插件 + 装 SDK"，不会帮你写 .env，也不会设 memory.provider（这两步走方式 B 要自己做）。安装成功的标志
bash
hermes memory status应能看到 hy-memory 出现在已安装列表， 且 Provider: hy-memory ← active。
Step 05
配置
环境变量配置模板（~/.hermes/.env）。手动配置或想覆盖向导结果时使用。
bash
# ===== HY-Memory 配置 =====
HY_MEMORY_USER_ID=alice # 必填：你的记忆命名空间
HY_MEMORY_AGENT_ID=hermes # 可选：二级隔离，默认 hermes
HY_MEMORY_MODE=pro # lite / pro / ultra，默认 pro
# 记忆抽取 LLM
MEMORY_LLM_PROVIDER=openai
MEMORY_LLM_MODEL=gpt-4o-mini
MEMORY_LLM_API_KEY=sk-...
# MEMORY_LLM_BASE_URL=https://api.deepseek.com # 用 DeepSeek 等兼容端点时填
# Embedder（向量化）
MEMORY_EMBEDDER_PROVIDER=openai
MEMORY_EMBEDDER_MODEL=text-embedding-3-small
MEMORY_EMBEDDER_API_KEY=sk-...
MEMORY_EMBEDDING_DIMS=1536 # 与所选 embedder 的实际维度一致
# 向量库
MEMORY_VECTOR_STORE=chroma # chroma / qdrant / faiss完整可调变量
| 变量 | 必填 | 默认 | 说明 |
|---|---|---|---|
| HY_MEMORY_USER_ID | ✅ | — | 一级隔离（记忆命名空间） |
| HY_MEMORY_AGENT_ID | ❌ | hermes | 二级隔离 |
| HY_MEMORY_MODE | ❌ | pro | lite / pro / ultra |
| HY_MEMORY_WRITE_TURN_WINDOW | ❌ | 5 | 攒够 N 轮批量写一次（1＝每轮都写） |
| HY_MEMORY_PREFETCH_MAX_CHARS | ❌ | 2000 | 注入 prefetch 文本的最大字符数 |
| HY_MEMORY_SYNC_WORKERS | ❌ | 2 | 后台写回线程池大小 |
| HY_MEMORY_SHUTDOWN_GRACE_SEC | ❌ | 10 | 退出时等待在途写入的最大秒数 |
| MEMORY_LLM_* | ✅* | — | 抽取 LLM：PROVIDER / MODEL / API_KEY / BASE_URL |
| MEMORY_EMBEDDER_* | ✅ | — | Embedder：PROVIDER / MODEL / API_KEY / BASE_URL / DIMS |
| MEMORY_VECTOR_STORE | ❌ | chroma | chroma / qdrant / faiss |
| HY_MEMORY_LOG_LEVEL | ❌ | (未设置) | 设 INFO/DEBUG 查看搜索/写入活动 |
| MEMORY_LOG_PROPAGATE | ❌ | true | 将 SDK 日志路由到 Hermes 根日志器 |
* pro / ultra 必须有 LLM Key；lite 只需 Embedder。
处理模式（HY_MEMORY_MODE）
lite
纯向量（不调 LLM），最快，仅向量相似度
pro（默认）
LLM 事实/身份抽取 + 整合演化，profile + fact 分层
ultra
pro + System2 异步认知（Schema/Intention），最全 + 跨域归纳
lite 模式不适合 Hermes 的被动召回
lite 只做 embedding、不抽取，记忆停在 L1_RAW 层，而 SDK 的 list / search 会过滤掉 L1_RAW —— 也就是写得进但永远召不回（prefetch 恒空）。Hermes 请用 pro（默认）或 ultra。~/.hermes/config.yaml
yaml
memory:
provider: hy-memory向导会自动写入；环境变量优先级高于此文件。
Step 03
验证
hermes memory status vs hermes-hy-memory doctor
| hermes memory status | hermes-hy-memory doctor | |
|---|---|---|
| 视角 | Hermes 端（激活的权威来源） | SDK 端（内部健康探测） |
| 回答 | Hermes 会加载并使用此 provider 吗？ | 记忆引擎本身能工作吗？ |
| 检查 | config.yaml 中的 memory.provider；插件目录已发现；is_available() | HY_MEMORY_USER_ID 已设置；HyMemoryClient 构造成功；list_memories 可达 |
| 健康输出 | Plugin: installed ✓ / Status: available ✓ | All checks passed |
经验法则
如果hermes memory status 没有显示 installed ✓ / available ✓，Hermes 根本没在使用 HY Memory——先修复 status。更新插件
bash
hermes-hy-memory install # 检测版本差异；过时则升级 + 重新链接
hermes-hy-memory --version # 查看当前版本
hermes memory status # 确认 Hermes 端已加载新版install 会比较 Hermes venv 中的插件版本与最新版本，不同时就地升级。 也可手动：uv pip install --python /path/to/hermes/venv/bin/python -U hermes-hy-memory
Step 04
常见故障排查
| 现象 | 原因 | 解决 |
|---|---|---|
| hermes memory status 看不到 hy-memory | 只 pip install 了、没激活 | 跑 hermes-hy-memory install（或重跑 init） |
| install 报找不到 Hermes 的 Python | Hermes 装在独立 venv，自动探测失败 | hermes-hy-memory install --hermes-python /path/to/venv/bin/python |
| doctor 报 HY_MEMORY_USER_ID unset | .env 没配 / 没跑 init | 跑 init 或手填 ~/.hermes/.env |
| doctor 报 HyMemoryClient init failed | Embedder/LLM Key 缺失或错误 | 检查 MEMORY_EMBEDDER_API_KEY / MEMORY_LLM_API_KEY |
| prefetch 注入为空 / 召不回 | ① 用了 lite 模式；② 确实没相关记忆；③ query < 3 字符 | 改 pro/ultra；先 list 确认有数据 |
| unsupported version of sqlite3 | 系统 sqlite < 3.35 | pip install pysqlite3-binary，或换 qdrant/faiss |
| 安装报 Requires-Python >=3.10 | Python 太旧 | 升级到 Python ≥ 3.10 |
| questionary not installed | 装包没带 [init] | pip install "hermes-hy-memory[init]" |
| 退出后 sync_turn 似乎没写 | 守护线程随主进程退出被杀 | 用 Hermes daemon 模式；或调大 SHUTDOWN_GRACE_SEC |
| Plugin: not installed ✗ | pip 安装了但没创建 Hermes 扫描目录 | 运行 hermes-hy-memory install |
| Status: not available ✗ | HY_MEMORY_USER_ID 未在 ~/.hermes/.env 中设置 | 重跑 hermes-hy-memory init |
| 看不到搜索/写入日志 | 日志级别未设置 | 设置 HY_MEMORY_LOG_LEVEL=INFO 或 DEBUG |
| sync_turn 似乎不写入 | 写入被节流（默认每 5 轮） | 设 HY_MEMORY_WRITE_TURN_WINDOW=1 调试 |
Step 05
卸载 / 回滚
bash
# 关闭 provider
hermes config set memory.provider ""
# 移除插件激活目录（symlink）
rm -rf ~/.hermes/plugins/hy-memory
# 卸载包（可选）
pip uninstall -y hermes-hy-memory hy-memory
# 删除记忆数据（可选，谨慎）
hermes-hy-memory reset --user-id <你的id> # 仅当前 agent
# hermes-hy-memory reset --user-id <你的id> --all-agents -y # 该用户全部 agentStep 09
CLI 速查
standalone：hermes-hy-memory <cmd>；经 Hermes 主进程：hermes hy-memory <cmd>（需 provider 已激活）。
| 命令 | 作用 |
|---|---|
| hermes-hy-memory init | 交互式 4 步配置向导（写 .env + 自动激活） |
| hermes-hy-memory install | 激活插件到 Hermes（symlink + 装 SDK；过时时自动升级） |
| hermes-hy-memory install --hermes-python <path> | 手动指定 Hermes 的 Python 路径 |
| hermes-hy-memory install --copy | 复制而非符号链接（网络挂载场景） |
| hermes-hy-memory doctor | 只读体检（env / client / list） |
| hermes-hy-memory --version | 查看当前版本 |
| hermes-hy-memory add "<text>" | 手动写入一条记忆 |
| hermes-hy-memory search "<query>" [--limit N] | 搜索记忆 |
| hermes-hy-memory search "<q>" --user-id X --agent-id Y | 跨用户/agent 搜索 |
| hermes-hy-memory list [--limit N] | 列出最近记忆 |
| hermes-hy-memory reset [--all-agents] [-y] | 删除记忆（破坏性，默认需确认） |
| hermes memory status | Hermes 端查看 provider 加载状态 |