Hermes Memory System

给 AI Agent 搭一套确定性记忆系统 — 零 LLM 依赖、零 Agent 主动性、纯规则驱动。

为什么需要这个

大多数 AI Agent 的记忆靠两件事：1) Agent 自己主动写记忆（不可靠，LLM 会忘记）；2) 后台调 LLM 做摘要蒸馏（贵、慢、容易幻觉）。

这个方案完全不同：Hook 自动拦截错误 → 纯规则分类 → 计数器决定晋升 → 定时清理过期数据。全程不需要 LLM 参与。

核心设计

工具报错 → Hook 拦截 → 规则分类 → 写入 raw_logs
                                    ↓ (出现 >= 3 次)
                              自动晋升到 insights
                                    ↓ (引用 >= 5 次)
                              候选 skill 队列
                                    ↓ (30 天无引用)
                              自动标记过期

三层架构

层	表	作用	生命周期
Layer 1	raw_logs	原始错误累积（去重+模板化）	14 天单次自动删
Layer 2	insights	晋升后的经验（带解决建议）	30 天无引用降级
Layer 3	skill_candidates	高频经验 → 候选 skill	人工确认

功能特性

memory-hook 插件

• 错误自动捕获: 包装 registry.dispatch() 静默拦截工具错误
• 自动搜索解决方案: 错误发生时自动搜索已知解决方案并注入提示
• Memory Search 工具: 注册 memory_search(query, top_k) 查询累积的错误模式
• Skill 使用追踪: 监控 skill_view 调用用于生命周期管理
• 向量搜索强制: 检测用户意图中的知识库搜索关键词并强制执行向量搜索

pinecone-memory 插件

• 向量记忆搜索: 使用 Pinecone 进行语义搜索
• 自动同步: 监控文件变更自动同步到向量库
• Core.md 注入: 每轮对话自动注入核心记忆文件

安装

前置条件

• Hermes Agent 已安装并正常工作
• Python 3.8+
• (可选) Pinecone API Key (用于向量搜索)

步骤

1. 克隆仓库:

   cd ~/.hermes/plugins/
   git clone https://github.com/srgb140/hermes-memory-system.git memory-system

2. 初始化记忆系统:

   mkdir -p ~/.hermes/memory-system

3. 重启 Hermes 加载插件。

文件结构

hermes-memory-system/
├── README.md
├── LICENSE
├── install.sh
└── src/
    ├── config/
    │   └── config.yaml.example
    ├── memory-system/
    │   ├── learning_bridge.py
    │   └── memory.db (运行时生成)
    └── plugins/
        ├── memory-hook/
        │   ├── __init__.py
        │   └── plugin.yaml
        └── pinecone-memory/
            ├── __init__.py
            └── plugin.yaml

配置

基础配置

插件开箱即用，无需配置。

向量搜索配置 (可选)

如果使用 Pinecone 向量搜索：

1. 设置环境变量:

   export PINECONE_API_KEY="your-api-key"

2. 在 ~/.hermes/config.yaml 中添加:

   platform_toolsets:
     cli:
       - vector-memory

工作原理

错误捕获

当任何工具调用失败时，插件会:

• 提取错误消息
• 记录到 memory.db 的 raw_logs 表
• 尝试提取关键词用于未来搜索

自动提示系统

发生错误时，插件会:

1. 搜索 insights 表中的匹配错误模式
2. 如果找到，注入已知解决方案作为提示
3. Agent 可以无需用户干预直接应用修复

Memory Search 工具

插件注册一个 memory_search 工具，Agent 可以调用:

memory_search(query="terminal timeout", top_k=5)

返回数据库中匹配的错误模式和已提升的洞察。

数据库 Schema

raw_logs

列	类型	描述
id	INTEGER	主键
timestamp	REAL	Unix 时间戳
tool_name	TEXT	失败的工具
error_text	TEXT	错误消息
context	TEXT	附加上下文

insights

列	类型	描述
id	INTEGER	主键
error_pattern	TEXT	匹配模式
resolution	TEXT	已知修复
confidence	REAL	置信度 (0-1)
created_at	REAL	Unix 时间戳

故障排除

插件未加载

检查 Hermes 日志:

hermes logs | grep memory-hook

数据库错误

确保记忆系统目录存在:

mkdir -p ~/.hermes/memory-system
chmod 700 ~/.hermes/memory-system

开发

插件是单文件 (__init__.py)，除了 Python 标准库外没有外部依赖。

关键函数

• register(ctx) — 插件入口点
• _wrapped_dispatch() — 拦截工具调用
• _auto_search_and_hint() — 搜索已知解决方案
• _log_silent() — 记录错误到数据库
• _memory_search_handler() — 处理 memory_search 工具调用

License

MIT

Contributing

Issues and pull requests welcome at https://github.com/srgb140/hermes-memory-system