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 变聪明,只是让它不必每次都从零开始。