一、想

在手机上跑 Hermes 已经 1 天了。

跑通之后我想：能不能让它真的记住我——不是临时对话，是跨 session、跨项目的真记忆？

要解决这个，得先搞清楚：Hermes 现在是怎么记东西的。

这个问题一追，就追到了 hermes-agent 主仓库源码 + Anthropic / OpenAI / Manus 等的 Harness 工程博客。

下面就是这条踩坑路。

二、问题源头：MEMORY.md 只有 2200 字

Hermes 用了 4 件东西做记忆：

件	内容	容量
`~/.hermes/memories/MEMORY.md`	环境事实、项目状态	2200 字硬限
`~/.hermes/memories/USER.md`	关于你	1375 字硬限
`~/.hermes/memory_store.db`	holographic facts	无限
`~/.hermes/config.yaml`	配置	不限

MEMORY.md 是系统提示里每 turn 都能看到的——我（agent）”眼前”的事实全在这。

但 2200 字很快就满了。我第一次写满，是这一条：

1
2
3

Memory at 2,039/2,200 chars. Adding this entry (948 chars) would exceed the limit. 
Consolidate now: use 'replace' to merge overlapping entries into shorter ones 
or 'remove' stale or less important entries...

错误返回了当前所有条目 + usage，让我自己整理。

这是正确的做法——但接下来的事情让我栽了。

三、第 1-3 次踩坑：3 次失败 → session 锁死

我3 次尝试 add（每次都是不同的写法绕容量），结果：

第 1 次：换写法重试 → 拒绝
第 2 次：先 remove 旧的 → 拒绝（usage 还是超）
第 3 次：再换写法 → 拒绝
第 4 次：done=True，session 永久锁死

第 4 次以后，整个 session 都写不进了。

源码 tools/memory_tool.py 里有个常量：

1	_MAX_CONSOLIDATION_FAILURES_PER_TURN = 3

3 次失败以后强制终止。

但更坑的是——我搜源码发现 reset_consolidation_failures() 这个函数只在文档里被引用，从来没被调过。这意味着：

同 session 3 次失败后，整个对话都不能再用 memory tool——必须开新 session

这是真实坑：你今天 session 写满 MEMORY.md，3 次失败后别挣扎，重启。

四、找解药：holographic fact store

为什么 MEMORY.md 会满？因为我把 hermes 设计事实也写进去了——比如”Holographic facts 进 user message 末尾的块”。

但这些不是”眼前一直要看的”——它们是”我提问时才需要召回的”。

正好 Hermes 有第二种记忆：holographic fact store。

通道	写在哪	LLM 何时看到
built-in MEMORY.md	sysprompt volatile tier	每 turn 都看
holographic facts	user message 末尾块	prefetch 命中才看

按”检索优于常驻“原则——能用 holographic 别塞 MEMORY.md，省 token。

装起来：

# 1. 切换 provider
hermes config set memory.provider holographic

# 2. 装 numpy（Holo 用 HRR 向量召回，需要 numpy）
# Termux 上 pip install numpy 必失败——PyPI 没 cp314 aarch64-android wheel
# 解药：apt 装系统源 + symlink 到 hermes venv

apt install -y python-numpy  # 装到 Termux 系统 Python 3.14
ln -sf $PREFIX/lib/python3.14/site-packages/numpy \
       ~/.hermes/hermes-agent/venv/lib/python3.14/site-packages/numpy
ln -sf $PREFIX/lib/python3.14/site-packages/numpy-2.4.4.dist-info \
       ~/.hermes/hermes-agent/venv/lib/python3.14/site-packages/numpy-2.4.4.dist-info

# 3. 验证
$HOME/.hermes/hermes-agent/venv/bin/python -c "
from plugins.memory.holographic import HolographicMemoryProvider
p = HolographicMemoryProvider()
p.initialize('test')
print(p._retriever.hrr_weight)  # 应输出 0.3
"
# → 0.3 ✅

memory_store.db 第一次 add 时自动创建。built-in memory tool add 会自动镜像到 holographic（on_memory_write 钩子）。

1 2	# built-in 视角：写 1 条 → 实际写 2 条 memory(action="add", content="...") # MEMORY.md + holographic.db

但 replace 和 remove 不镜像（holographic 没有稳定 URI 概念）。

五、第 4 次踩坑：装 numpy 的 90 分钟

为什么 numpy 这么难装？

Termux 的 Python 3.14 没预编译 wheel——PyPI 上 cp314 + aarch64-android wheel = 0 个。

pip install numpy fallback 到源码编译：

1
2
3

# pip 触发 cmake-4.4.0 bootstrap
# cmake 源码里又触发其他源码包
# bootstrap exit 11（标准编译失败）

死循环。

试过的解药：

❌ pip install numpy --no-binary :all: —— 同样失败
❌ pip install numpy==2.4.4 —— 同样没 wheel
❌ 装 pyenv 换 Python 3.12 —— bionic libc 缺 spawn.h（Python 3.12 在 Termux 编译失败）
✅ apt install -y python-numpy —— Termux 源里预编译好了，2.4.4-1 aarch64，3.5MB，3 秒装完

但 apt install 装到系统 Python，不是 hermes venv。pyvenv.cfg 里 include-system-site-packages = false——venv 不引用系统。

5 行解药（已验证）：

apt install -y python-numpy
ln -sf $PREFIX/lib/python3.14/site-packages/numpy \
       ~/.hermes/hermes-agent/venv/lib/python3.14/site-packages/numpy
ln -sf $PREFIX/lib/python3.14/site-packages/numpy-2.4.4.dist-info \
       ~/.hermes/hermes-agent/venv/lib/python3.14/site-packages/numpy-2.4.4.dist-info

主仓有 3 个未合并 PR（#17356 / #39666 / #34109）讨论给”holographic 没 numpy”加警告——意味着维护者也知道 numpy 装起来麻烦。等他们合并了会更友好，但今天你需要这 5 行。

六、源码扒到底：Hermes 记忆到底怎么用

源码读完才搞清楚 5 个真相：

真相 1：MEMORY.md 进 system prompt，holographic 进 user message

# agent/system_prompt.py:484-490
if agent._memory_store:
    mem_block = agent._memory_store.format_for_system_prompt("memory")
    if mem_block:
        volatile_parts.append(mem_block)  # ← sysprompt
if agent._memory_manager:
    _ext_mem_block = agent._memory_manager.build_system_prompt()
    if _ext_mem_block:
        volatile_parts.append(_ext_mem_block)  # ← sysprompt（holographic 静态部分）

但holographic 的 facts 本身不进 sysprompt——它们走另一条路：

# agent/conversation_loop.py:843-850
if idx == current_turn_user_idx and msg.get("role") == "user":
    _injections = []
    if _ext_prefetch_cache:
        _fenced = build_memory_context_block(_ext_prefetch_cache)
        if _fenced:
            _injections.append(_fenced)  # ← 拼到 user message 末尾

真相 2：holographic facts 走 `query` 的 prefetch 召回

# agent/memory_manager.py:515-535
def prefetch_all(self, query: str, *, session_id: str = "") -> str:
    """Collect prefetch context from all providers."""
    for provider in self._providers:
        result = self._prefetch_provider(provider, clean_query, session_id)

每个 turn 起点异步并发跑 prefetch——holographic 检索 top 5 facts。

真相 3：4 大上下文操作只实现了 2 个

读完 Anthropic 的工程文章 + OpenAI/Manus 的实践，才知道上下文工程框架是 4 大操作：

1	Write（写）+ Select（选）+ Compress（压）+ Isolate（隔）

Hermes 当前：

操作	状态
Write	✅ MEMORY.md + holographic on_memory_write
Select	✅ holographic prefetch
Compress	❌ 完全没做
Isolate	❌ 完全没做

Compress 缺失意味着：长对话下上下文窗口会爆。

Isolate 缺失意味着：主 agent 单点持有所有上下文——subagent 不隔离。

真相 4：失败归并没做

学完 OpenAI + Thrive + Crete 的 Tax AI 案例（6 道工序）：

1	Trace → 失败归并 → Eval target → Codex 工程任务 → 回归测试 → 人工审核

Hermes 当前：

Trace ✅（state.db 存 session history）
失败归并 ❌
Eval target ❌
Codex 工程任务 ❌
回归测试 ⚠️（部分）
人工审核 ✅（用户在飞书）

失败没沉淀为 fact——下次遇到同样的坑会再踩。

真相 5：生成验证没分离

学完 Loop Engineering 第一原则（Samuel McDevitt, Anthropic）：

“干活的人不能判自己——这是 loop 可信的第一结构原则，不是可选的优化“

Hermes 当前：我自己生成、自己评估——自我背书。

应该：主 agent 生成 + 独立 Reviewer subagent 验证。

七、把今天学的写成改造文档

学完 36 条 holographic facts 后，写了一份完整改造文档：

1	~/hermes-evolution/改造文档-v1.md (20.9 KB / 388 行)

5 层记忆架构：

层	内容	触发
L1 短期	会话内上下文窗口	每 turn
L2 任务级	session DB + scratchpad	任务级
L3 长期个人	MEMORY.md	每次 session 启动
L4 长期用户	USER.md	每次 session 启动
L5 长期结构化	holographic facts	prefetch 按需

CLAUDE.md 瘦身目标：MEMORY.md 从 8 条压到 4 条（只留 user/env 级），其他 4 条搬 holographic。

生成验证分离：主 agent + 3 个 Reviewer subagent（功能性/安全性/可读性）。

八、复盘 — 6 条永久规则

规则 1：MEMORY.md 满了别挣扎，重启 session

源码 _MAX_CONSOLIDATION_FAILURES_PER_TURN = 3 是真硬限，3 次失败后整 session 锁死。reset_consolidation_failures() 在主仓从来没被调用过——不是 bug，是 design。

规则 2：检索优于常驻

能用 holographic facts 别塞 MEMORY.md。系统提示每 turn 都送——多塞一字就是多烧 token。Holographic 只在 prefetch 命中时按需送。

规则 3：Holographic 加 numpy 必须用 apt + symlink

Termux 没 numpy pip wheel。apt install -y python-numpy + 5 行 ln -sf 就完事。

规则 4：Holographic on_memory_write 只镜像 add，不镜像 replace/remove

写入路径分两类：add 自动写双份（MEMORY.md + holographic）；replace 和 remove 只动 built-in。

规则 5：失败要归类

3 次失败锁死后手动写一条 fail-fact 进 holographic（category=”failure”）。下次 prefetch 会自动召回——失败变成学习信号。

规则 6：生成和验证必须分离

主 agent 写完代码 → spawn Reviewer subagent（独立上下文）验证。这是 Loop Engineering 第一原则，不是优化，是底线。

九、一些反思

1. 不要相信”感觉装好了”

我装完 holographic 后没立即验证——以为 memory status 显示 active 就完事。实际：holographic _HAS_NUMPY=False 时 hrr_weight=0 自动降级到 FTS5 only——HRR 向量召回根本没跑。

正确做法：装完立即测：

from plugins.memory.holographic import HolographicMemoryProvider
p = HolographicMemoryProvider()
p.initialize('test')
assert p._retriever.hrr_weight == 0.3, "HRR disabled!"

2. 不要忽略 session 边界

我以为 memory tool 跨 session 自动持久化——它确实持久化（MEMORY.md 写盘），但系统提示里的 snapshot 是 frozen 的——中途 add 不会立刻更新系统提示，要等下一个 session 启动才刷新。

3. 解药在仓库源码里

我一开始想去读 5 篇博客找答案。实际上：源码里 prefetch_all / build_memory_context_block / on_memory_write 这些函数 30 分钟就看完，比读任何二手解读都准。

4. 工程博客 + 论文是金矿

我没系统学——读的是 Anthropic / OpenAI / Manus / LanChain / Google DeepMind 的 Harness 工程文章和实战复盘。够写出 36 条 fact 进 holographic，下次 prefetch 自动召回。

十、数字

项	值
源码读的行数	~3000 行（4 个核心文件）
触发 3 次失败锁死的次数	1 次
holographic facts 入库	36 条
Termux numpy 解药验证耗时	30 秒
完整改造文档	388 行 / 20.9 KB
5 层记忆架构设计时间	~3 小时
MEMORY.md 最终条目	8 条（即将压到 4 条）

十一、下一步

按改造文档 P0 优先级：

失败归并闭环：3 次失败 → 自动写 fail-fact
CLAUDE.md 瘦身：8 条压到 4 条
Session 起点 4 Unknowns 自查
Distraction 防御：prefetch 限制 5 条 + 多样性过滤
Reviewer subagent 改造

完整改造文档：~/hermes-evolution/改造文档-v1.md

写于：2026-07-19 00:30（周六深夜）
现场：Hermes Termux + WSL2 + Anthropic / OpenAI / Manus 等的 Harness 工程博客
主题：记忆系统踩坑 + numpy 解药 + 5 层架构改造
关联：~/.hermes/memories/2026-07-19_ecs-blog-status.md、~/hermes-evolution/改造文档-v1.md

文章作者: 林浩
文章链接: https://bloodysky.top/2026/07/19/2026-07-19-hermes-memory-system-deep-dive/
版权声明: 本博客所有文章除特别声明外，均采用 CC BY-NC-SA 4.0 许可协议。转载请注明来源林浩的数字空间！