Hermes 五层记忆体系
搭建日期:2026-06-17 ~ 2026-07-03
目标:让 AI Agent 跨会话保持认知连续性,从分钟级到月级全时间尺度覆盖编号说明:本文按"抽象精度从细到粗"编号,日层日志是第 1 层,语义库 agent-memory 是第 5 层。后来的 HexaMind 系列(六层记忆、搭建攻略)改成了"从底到顶"的 L1–L6,agent-memory 变成 L1。两套编号指的是同一套系统,换了个数数方向而已,对照表在那两篇里。
一、为什么需要五层?
单层记忆会面临三个矛盾:
- 精度 vs 容量:日志太细(200KB/天)上下文装不下,太粗丢失细节
- 速度 vs 深度:语义搜索要算向量,但每次请求只能 1-2 秒
- 冷启动 vs 持久化:新会话如何快速召回上次做到一半的事?
五层分层解决:
抽象度 →
时 ┌─────────────┬──────────────┬────────────────┐
间 │ 日层(1) │ HOT/WARM(4) │ 语义层(5) │ 分钟~小时
跨 │ 操作日志 │ 惯用模式 │ FTS5+向量搜索 │
度 ├─────────────┼──────────────┼────────────────┤
↓ │ 本体层(3) │ COLD(4) │ │ 天~周
│ 知识图谱 │ 归档记忆 │ │
├─────────────┼──────────────┼────────────────┤
│ │ │ embedding(2) │ 永久
│ │ │ 1536维向量索引 │
└─────────────┴──────────────┴────────────────┘
二、逐层详解
第 5 层:agent-memory(语义记忆)
定位:跨会话的永久事实和教训,支持关键词搜索和语义搜索。
| 指标 | 值 |
|---|---|
| 存储 | ~/.agent-memory/memory.db(5.2MB SQLite + FTS5) |
| facts | 179 条,含标签分类 |
| lessons | 14 条(8 正面 / 6 负面) |
| entities | 10 个 |
| 标签覆盖 | venxine×40, fund-web×46, config×74, security×6, deployment×5 |
| 时间跨度 | 2026-06-17 → 2026-07-03 |
核心 API:
from src.memory import AgentMemory
mem = AgentMemory()
# 写入
mem.remember("venxine.vip Nginx 配置从 210 行精简到 62 行", tags=["venxine", "nginx", "optimization"])
mem.learn(action="gunicorn sync workers 比 gthread 更稳定",
context="gthread 在 3.6GB 机器反复 OOM", outcome="positive",
insight="低内存机器优先使用 sync workers")
# 查询
mem.recall("nginx") # FTS5 关键词搜索
mem.semantic_search("网站性能优化有哪些经验", limit=5) # 向量语义搜索
示例事实:
"venxine.vip 首页从 Tailwind CDN 约 300KB 改为本地构建 17KB CSS,首屏加载减少 86%"
Tags:[venxine, tailwind, performance, frontend]
示例教训:
"Nginx location 级 add_header 会覆盖 server 级安全头" → negative
Insight: "每个 location 块必须显式重复声明安全响应头四件套"
第 4 层:self-improving(模式记忆)
定位:HOT/WARM/COLD 三级热度管理,类似 CPU 缓存淘汰策略。
文件结构:
~/self-improving/
├── memory.md ← HOT 层(≤100行,session 注入上下文)
├── corrections.md ← 修正日志(格式: Type/Context/Confirmed)
├── index.md ← 热度索引 + 上次 compact 时间
├── projects/
│ └── fund-web.md ← WARM 层(270行,项目架构知识)
├── domains/
│ └── fund.md ← WARM 层(领域经验)
└── archive/ ← COLD 层(超30天未使用降级到此)
HOT 层内容:
Confirmed Preferences(永不过期):
- 部署命令统一:sudo systemctl restart fund-web
- 一次只改一个点,改完立即验证
- 模板安全铁律:修改/删除模板前必须备份并等用户确认
Active Patterns(出现 3+ 次后晋升):
- cron prompt 精简:移除大 skill 减少 75% token 量
- gunicorn systemd 部署:sync workers + service 文件(非 systemd-run)
- Flask g DB 复用:_get_state_db() 检查-创建-显式关闭
- Nginx 安全头覆盖规则:location 级 add_header 覆盖 server 级
淘汰机制: - Recent → 3 次确认 → Active(晋升) - Active → 30 天未用 → WARM(降级) - WARM → 30 天未用 → COLD(归档) - HOT 永不超过 100 行,超过自动 compact
第 3 层:ontology(知识图谱)
定位:实体-关系图,回答"哪些 Bug 影响了哪些 Project?"
存储:~/memory/ontology/ — JSONL 行式追加 + YAML schema 定义
Schema 类型:Person | Project | DataFile | Skill | Workflow | Version | Tool | Config | Bug | Template | Event
当前规模:
| 实体类型 | 数量 | 示例 |
|---|---|---|
| Bug | 12 | gunicorn gthread workers OOM on 3.6GB → status: fixed |
| Skill | 9 | nginx-site-optimization, flask-to-gunicorn-migration |
| Config | 9 | nginx_venxine.vip_v6.10, gunicorn_venxine, venxine.env |
| Tool | 6 | hermes, gunicorn, sqlite3 |
| Template | 5 | base_layout.html, fundtracker.html |
| DataFile | 4 | utils.py, tailwind.min.css |
| Event | 4 | venxine.vip v5.8.1 交付, v6.10 全站优化 |
| Version | 2 | venxine.vip v6.10 |
| Project | 1 | venxine.vip (proj_58d05ddc) |
关系示例:
proj_58d05ddc ──[uses]──→ nginx-site-optimization
proj_58d05ddc ──[has_bug]──→ gthread workers OOM
proj_58d05ddc ──[has_version]──→ venxine.vip v6.10
cfg_nginx_venxine ──[configures]──→ proj_58d05ddc
data_utils_py ──[consumed_by]──→ proj_58d05ddc
第 2 层:embedding(向量记忆)
定位:第 5 层的向量索引,同一份数据两种查询方式。
| 指标 | 值 |
|---|---|
| 覆盖 | 179/179 facts 全部向量化 |
| 模型 | openai/text-embedding-3-small via OpenRouter |
| 维度 | 1536 |
| 生成方式 | embedding-setup.py 批量调用 → UPDATE facts SET embedding=... |
| DB 大小 | 5.2MB(含 FTS5 + vector blobs) |
与 FTS5 的分工:
| 场景 | 走 FTS5 | 走 embedding |
|---|---|---|
| 精确关键词 | ✅ "nginx 配置" | ❌ 过泛 |
| 同义词/语义 | ❌ "网页加速"找不到 CDN | ✅ "网页加速"→语义匹配 tailwind 优化 |
| 速度 | 毫秒级 | 毫秒级(本地向量) |
| 写入后 | 即时可用 | 需重新运行 embedding-setup |
降级策略:
- 如果 OpenRouter API 不可达 → semantic_search() 自动回退 FTS5
- 如果 facts 无向量 → 自动降级
第 1 层:memory(日层日志)
定位:按日期的原始操作记录,人类可直接阅读。
| 文件 | 行数 | 内容 |
|---|---|---|
2026-06-20.md |
38 行 | 路由清理、DEMO1 修复、Nginx 修复、system 页面重构 |
2026-07-02.md |
40 行 | 16 项优化全记录 + 关键架构 + 踩坑记录 |
2026-07-02.md 结构示例:
## venxine.vip 全站 13 项优化
### 🔴 高优先级(安全加固)
### 🟡 中优先级(性能提升)
### 🟢 低优先级(工程优化)
### 关键架构
### 踩坑记录
### 输出清单
三、附属缓冲区:proactivity
文件:~/proactivity/memory/working-buffer.md
作用:Agent 启动时加载,告诉它"上次之后需要盯什么"。
# Proactivity Working Buffer
## venxine.vip · 主动监控项
- gunicorn 进程: systemctl status venxine-gunicorn,确认 Active: running
- Nginx 重载: 每次改配置后 nginx -t → nginx -s reload,验证安全头不丢失
- .env 安全: FLASK_SECRET_KEY 已随机化,DEMO_PASSWORD 不硬编码
- DB 连接: 禁止直接 sqlite3.connect(),必须走 _get_state_db()
- 新路由: 新增 Flask 路由时同步检查 Nginx proxy 正则是否覆盖
- Tailwind 重建: 修改 index.html class 后需重新构建
- 日志监控: tail -f /tmp/gunicorn_error.log | grep -i error
四、完整数据流
新会话启动
│
├─ 第1层: 读 ~/memory/ 最近日层日志 → 了解上下文
├─ 第4层: 读 ~/self-improving/memory.md HOT → 注入惯用模式
├─ 第5层: mem.semantic_search("当前任务关键词") → 召回历史经验
├─ 第2层: 自动降级逻辑 → FTS5 if embedding unavailable
└─ proactivity: 读 working-buffer.md → 主动检查监控项
会话中
│
├─ 重要事实 → mem.remember() → 第5层 FTS5 即时写入
├─ 新教训 → mem.learn() → 第5层 lessons
├─ 新实体/关系 → JSONL append → 第3层 知识图谱
├─ 修正 → corrections.md → 第4层
└─ 操作日志 → 日层 MD → 第1层
会话结束
│
├─ 检查 Recent → 是否晋升 Active(3次确认)
├─ 检查 HOT → 是否超 100 行需要 compact
└─ 新增 facts → embedding-setup.py → 第2层向量化
五、核心设计原则
1. 精度衰减,搜索不变
日层是最精确的原始记录,语义层是最抽象的搜索索引。想知道"7月2日做了什么"→读日层 MD,想知道"之前怎么处理过类似问题"→语义搜索。
2. 渐进降级
semantic_search("如何优化网站")
→ 尝试: 向量相似度 (1536-dim cosine)
→ 失败: FTS5 关键词 (SQLite full-text)
→ 失败: 返回空列表(静默降级,不抛异常)
3. 追加优于覆盖
- 日层:新增日期文件,不修改历史
- 本体层:JSONL 行追加,不可变
- 语义层:facts 追加 + superseded_by 软删除
- 模式层:HOT → WARM → COLD 降级但不删除
4. 零配置启动
新 facts 写入后 FTS5 即时可用(不需重建索引)。向量生成可选:没有 embedding API 也能正常工作,只是语义搜索降级为关键词。
六、与本次 16 项优化的联动
本次优化过程中,五层记忆如何参与:
| 阶段 | 记忆层 | 作用 |
|---|---|---|
| 发现优化点 | 第5层 FTS5 | 搜索 nginx location → 召回"配置有 26 个重复块" |
| 避免重复踩坑 | 第5层 lessons | 搜索 gunicorn worker → 召回"gthread 在低内存 OOM" |
| 执行过程 | 第1层 + corrections | 每个修正实时写入 corrections.md |
| 架构结论 | 第3层 ontology | 16 项优化 → 15 个新实体 + 17 条关系 |
| 新经验 | 第5层 lessons | 5 条新教训(sync workers、安全头、连接复用等) |
| 后续监控 | proactivity | 写入 7 条监控项 → 下次会话自动加载 |
七、维护命令
# 语义搜索测试
python3 -c "
from src.memory import AgentMemory
m = AgentMemory()
for f, score in m.semantic_search('nginx 安全优化', limit=3):
print(f'{score:.4f} | {f.content[:80]}')
"
# 重新生成向量(新增 facts 后)
python3 ~/embeddings/embedding-setup.py
# 查看第4层热度分布
cat ~/self-improving/index.md
# 查看第3层实体关系
wc -l ~/memory/ontology/graph.jsonl
# 清理 COLD 归档(>30 天未用)
ls ~/self-improving/archive/
# 手动 compact HOT 层(超 100 行时)
# 自动由 heartbeat 脚本触发
说到底,五层记忆就是同一段历史的五种观察精度:想知道"7 月 2 日做了什么"就翻日层日志,想知道"以前怎么处理过类似的问题"就走语义搜索。它不让 Agent 变聪明,只是让它不必每次都从零开始。