[分享] Hermes Memory Sidecar v3.0 — 给任意 AI 智能体加装长期记忆

[cycloner]

项目地址： https://github.com/mage0535/hermes-memory-installer

背景

用过 AI 智能体（ Claude Code / Cursor / Hermes ）的人应该都体会过：每次新对话就是一张白纸。上个会话讨论过的架构决策、当事人、项目背景，下个会话全不记得。重新描述一次两次忍了，十次二十次就麻了。

这个项目的思路是：在智能体旁边跑一个记忆 sidecar ，不碰智能体核心代码。智能体正常写会话，sidecar 负责归档、索引、治理、召回。

v3.0 做了什么

v3.0 实现了完整的外挂记忆管线：

1. 会话采集 → session_to_gbrain.py （增量归档到 gbrain ）
2. 治理重建 → memory_governance_rebuild.py （ FTS5 索引、memory object 多版本状态、向量嵌入）
3. 分层召回 → tiered_context_injector.py （ L1 最近会话 / L2 关键词搜索 / L3 治理对象 + 语义向量，RRF 融合 + 意图重排序）
4. 健康监控 → memory_guardian.py （容量、重复率、stuck 操作检测、安全排空）
5. 编排 + 验收 → memory_maintenance_cycle.py + sidecar_acceptance_check.py

几个值得说的设计

多智能体兼容 统一用 AGENT_HOME 环境变量定位智能体数据目录，向后兼容 HERMES_HOME 。设个变量就能挂到不同智能体上。

多版本记忆对象 同一个事实的多版陈述自动分 conflict group ，最新最好的标记 active ，其余 superseded （设 valid_to ）。查询只返回 active ，但历史不丢。

可选向量索引 配置 EMBEDDING_API_URL （ OpenAI 兼容格式）即可自动为 memory object 生成嵌入存到 canonical_semantic_index 表。不配的话，全文本检索（ FTS5 / LIKE / hindsight / gbrain ）完全正常。

Focused Dossier 重要人物 / 关系 / 项目可以提升为一级记忆对象。生产版已验证了 relationship dossier 。

生产情况

生产服务器跑了半年多，12600+ 会话、2GB state.db 、75MB governance.db 。每周跑一次完整维护周期（归档→重建→排空→召回验证），持续稳定。

欢迎 PR / Issue / Star ⭐

使用方式

git clone https://github.com/mage0535/hermes-memory-installer.git
cd hermes-memory-installer
python3 installer/install.py --noninteractive
AGENT_HOME=/root/.hermes python3 /root/.hermes/scripts/memory_maintenance_cycle.py