Hermes Memory 源码深潜：受限自管理、快照隔离与事务化巩固

0.1 十一个研究问题#

1. 为什么把 User Profile 与 Agent Experience 分开？
2. Frozen Snapshot 和 Live State 为什么必须并存？
3. 为什么预算使用字符而不是 Token？
4. 容量满时为什么拒绝 Add，而不是后台静默摘要？
5. add 为什么可以跳过一部分 Drift Guard？
6. replace/remove 为什么必须在锁内重读？
7. Atomic Rename 解决了哪一个并发窗口？
8. apply_batch 为什么只检查最终状态预算？
9. Threat Scan 为什么既发生在写入时，也发生在启动加载时？
10. Write Approval 如何把“Agent 想写”与“系统允许写”分开？
11. 为什么 Memory 失败不能阻塞用户主任务？

1.1 两个 Target：User Model 与 Agent Experience#

MEMORY_SCHEMA 的描述还给出一条重要分类规则：[H2]

1
user preference / correction
2
    > environment fact
3
    > procedure

同时明确：可复用 Procedure 更适合进入 Skill，临时任务进度更适合 Session Search，而不是长期 Memory。

这说明 Hermes 并不是只有一个长期文本框，而是隐含了一个写入 Router：

1
Candidate
2
├── Who the user is             → USER.md
3
├── Stable environment lesson   → MEMORY.md
4
├── Reusable procedure          → Skill
5
├── Temporary task progress     → Session state / search
6
└── Trivial rediscoverable fact → Drop

1.2 为什么 Scope Separation 很重要#

如果把用户偏好和 Agent 技术经验混在一个列表中，会出现：

• 用户隐私和工程经验共享同一保留策略；
• “回答风格”与“构建命令”竞争同一个预算；
• 删除用户 Profile 可能误删 Agent 经验；
• Prompt Builder 无法给两类信息不同标签。

两个文件并不是完美的数据模型，但它至少让 Ownership 和用途显式化。

2.1 为什么写成功后当前 Agent 仍不应该“假装已经看到”#

如果同一 Turn 修改系统提示词前缀：

1
Turn 1 Prefix = P1
2
Turn 2 Prefix = P2
3
Turn 3 Prefix = P3

会破坏 Prefix Cache 稳定性，也会让同一 Session 的行为规则悄然变化。

Hermes 选择：

1
Session Start
2
→ Capture Frozen Snapshot S0
3

4
Memory Tool writes S1, S2...
5
→ Persist for future sessions
6
→ Current system prompt remains S0

这接近数据库 Snapshot Isolation：当前会话读取一个稳定快照，写入对未来会话可见。

2.2 Read-your-own-write 的语义被拆开#

Hermes 不是完全没有 Read-your-own-write：成功响应会返回 Live State 计算出的 Usage、Entry Count 和完成标记；需要模型修复调用的失败响应才会按需返回 current_entries。Agent 因此知道修改是否落盘以及剩余预算，但系统提示词注入不会随写入重建。

因此应区分：

1
Tool-level visibility
2
≠
3
System-prompt snapshot visibility

这是一个很成熟的 Context Engineering 取舍：一致的 Prompt Prefix 优先于“每次写完立刻改系统提示词”。

2.3 状态转换图#

1
stateDiagram-v2
2
    [*] --> LoadDisk
3
    LoadDisk --> Sanitize
4
    Sanitize --> FrozenSnapshot
5
    LoadDisk --> LiveState
6
    LiveState --> LockedReload: memory tool mutation
7
    LockedReload --> Reject: threat / drift / budget / match failure
8
    LockedReload --> Commit: validation success
9
    Commit --> LiveState: atomic replace
10
    FrozenSnapshot --> [*]: session ends
11
    LiveState --> LoadDisk: next session

3.1 为什么 Threat Hit 不直接从磁盘删除#

命中威胁模式的 Entry 在 Snapshot 中会被替换为类似：

1
[BLOCKED: MEMORY.md entry contained threat pattern(s): ...]

但原始 Entry 保留在 Live State 和磁盘中，用户仍可以检查并删除。[H3]

这是一个值得学习的安全设计：

1
Prevent execution
2
but preserve evidence

如果安全过滤器静默删除原文：

• 用户不知道发生过投毒；
• 无法复盘来源；
• 误报时无法恢复；
• 攻击证据被防线自己破坏。

3.2 Snapshot Sanitization 与 Write-time Scan 是两道不同防线#

写入时扫描防止当前 Tool 把危险文本持久化；启动时扫描防止以下旁路：[H3][H4][H13]

• 用户手工编辑；
• Sister Session 写入；
• Patch / Shell 直接修改；
• Supply-chain 文件替换；
• 旧版本留下的危险内容。

只做 Write-time Scan 无法覆盖外部 Writer；只做 Load-time Scan 又会让危险内容长期留存。两者共同形成：

1
Mutation Gate
2
+
3
Consumption Gate

4.1 为什么用 Character Budget#

字符预算并不精确等于模型 Token，但它有四个工程优势：

• 与 Provider / Tokenizer 解耦；
• 文件长度可直接计算；
• 错误信息对人可读；
• 不需要在每次 Mutation 中加载 Tokenizer。

代价是不同语言的 Token Ratio 不同：2,200 个 ASCII 字符与 2,200 个中文字符的 Token 成本并不相同。

生产系统可以在保持字符 Hard Limit 的同时补充 Token Estimate：

1
hard_char_limit
2
+ soft_token_warning
3
+ measured_prompt_tokens

4.2 容量满时故意 Fail Closed#

add() 会先计算加入后的完整最终字符数。超过预算时不写入，而是返回当前 Entries、Usage 和巩固建议。[H6]

这比后台静默摘要更诚实：

1
Memory Full
2
→ Agent must choose what to replace or remove
3
→ Information loss becomes an explicit decision

自动压缩如果没有可验证策略，可能把用户纠正、关键环境限制或少见但高风险经验一起删掉。

4.3 Capacity Pressure 是 Agent 的认知压力#

当预算接近上限，Agent 应执行：

1
Deduplicate
2
→ Merge overlapping lessons
3
→ Remove stale entries
4
→ Promote reusable procedure to Skill
5
→ Add new high-value fact

容量限制迫使 Agent 从“日志追加器”转向 Curator。

5.1 add：Append Semantics#

add() 在进入锁之前完成空内容与 Threat Scan；进入锁后重新读取磁盘，Exact Duplicate 直接返回成功，不重复写入。[H6]

关键点是：

1
_reload_target(target, skip_drift=True)

为什么可以弱化 Drift Guard？

因为 Add 的逻辑是：

1
Re-read latest entries
2
→ append one new entry
3
→ preserve all existing parsed entries

它不需要定位并重写某一条旧 Entry，因此外部内容被覆盖的风险低于 Replace/Remove。

但“低于”不等于“没有”。如果外部文件完全不符合 Entry Delimiter 结构，重新序列化仍可能改变格式。Hermes 当前策略是针对已知事故窗口做务实取舍，而不是通用无损文本编辑器。

5.2 replace：Targeted Rewrite#

Replace 要求：

• old_text 非空；
• new_content 非空；
• 新内容通过 Threat Scan；
• 锁内 Drift Check 通过；
• old_text 命中至少一条；
• 多个不同 Entry 命中时拒绝歧义；
• 替换后的最终状态不超预算。

如果 Structured-output Client 漏掉 old_text，Tool 不只返回“参数缺失”，还回传当前 Entries 和明确的重试说明，让模型能选择唯一子串再次调用。[H7]

这是 Tool Protocol 的一个重要原则：

错误响应应该携带完成修复所需的最小状态，而不是只给一个死胡同错误码。

5.3 remove：Deletion 也需要唯一定位#

Remove 同样使用子串匹配。如果一个子串命中多个不同 Entry，则拒绝删除并返回 Preview，防止一个含糊的 old_text 批量破坏 Memory。[H6]

这相当于乐观的人机协议：Agent 必须先观察当前状态，再给出足够精确的 Mutation Selector。

6.1 为什么锁必须覆盖 Re-read#

错误方式：

1
Read v1
2
→ wait for lock
3
→ write mutation(v1)

在等待期间其他 Session 可能已经写入 v2，当前 Writer 仍会覆盖它。

正确方式：

1
Acquire lock
2
→ Read latest v2
3
→ Mutate v2
4
→ Commit v3

6.2 为什么不用 open("w") + flock#

源码注释指出，旧式 open("w") 会在获取锁之前截断文件，读者可能看到短暂空文件。[H8]

Temp File + Atomic Rename 保证无锁 Reader 看到：

1
old complete file
2
or
3
new complete file

而不是半写入或空文件。

6.3 Atomic Rename 不等于跨进程完整事务#

它保证单文件替换原子性，但不自动保证：

• 跨两个 Target 的事务；
• Network Filesystem 上完全一致的语义；
• 进程 Crash 后所有目录元数据已持久化；
• 多机器共享目录中的分布式锁；
• Mutation Audit 与文件提交原子一致。

这些属于生产部署时必须重新验证的 Filesystem Contract。

7.1 Drift 时为什么先 Backup 再 Abort#

检测到 Drift 后：

1
Read raw text
2
→ write timestamped .bak
3
→ return backup path
4
→ reject replace/remove

这体现：

Potential Data Loss 时 Fail Closed，并保留恢复副本。

如果 Backup 自身失败，返回值会明确标记 BACKUP FAILED，而不是假装已经安全保存。

7.2 Drift Guard 的边界#

Round-trip 相等只能证明格式可往返，不证明内容语义正确；Entry 未超长也不能证明它来自可信 Writer。

因此还需要：

1
format drift detection
2
+ source provenance
3
+ content threat scan
4
+ mutation audit

8.1 为什么只检查 Final Budget#

假设当前已满：

1
Current = 2,200 / 2,200

计划：

1
Remove stale 500 chars
2
Add valuable 300 chars
3
Final = 2,000

逐操作提交会先失败或暴露中间状态。Batch 在 Working Copy 上执行全部 Operation，只对最终状态检查预算：

1
working = copy(current_entries)
2
for op in operations:
3
    validate_and_apply(working, op)
4

5
if chars(working) > limit:
6
    abort()
7
else:
8
    atomic_write(working)

8.2 Transaction Boundary#

Batch 保证的是：

1
One Target
2
+ One Lock
3
+ One Working Copy
4
+ One Final Budget Check
5
+ One Atomic File Replace

它不保证 USER.md 与 MEMORY.md 跨文件原子，也不包含外部 Skill Store。

这里的事务边界还不包括进程内状态回滚：固定版本先用 _set_entries() 更新 Live State，再调用 save_to_disk()。如果文件写入抛出异常，正式文件仍受 Atomic Replace 保护而保持旧完整版本，但当前 MemoryStore 对象可能短暂领先于磁盘，直到下一次锁内 Reload。因而它是单文件提交协议，不是涵盖 RAM、磁盘与 Crash Recovery 的数据库事务。

8.3 幂等与歧义#

• Batch Add 遇到 Exact Duplicate 会跳过；
• Replace/Remove 无命中时整个 Batch 失败；
• 一个 Selector 命中多个不同 Entry 时整个 Batch 失败；
• 任一新内容命中 Threat Pattern，MemoryStore.apply_batch() 会在触碰 USER.md / MEMORY.md 目标文件前拒绝整个 Batch。

这让 Memory Mutation 更接近事务命令，而不是一串 Best-effort Tool Calls。

9.1 为什么审批必须位于 Store 之前#

如果先写磁盘再审批，就只剩撤销，不是批准；持久化 Prompt Injection 已经可能影响其他 Session。

正确顺序：

1
Agent proposes mutation
2
→ Policy evaluates
3
→ Optional human approval
4
→ Store validates current state
5
→ Commit

9.2 当前 Fail-open 取舍#

固定版本源码中，如果 Write Approval Module 无法 Import，Gate 会 Fail Open，以避免所有 Memory 写入被基础设施故障阻塞。[H11]

这是可用性取舍，不是普适安全答案。高合规环境更可能要求：

1
approval infrastructure unavailable
2
→ fail closed for sensitive targets
3
→ allow only low-risk local target

策略应由 Risk Tier 决定，而不是所有环境共享一个默认值。

10.1 Side-effect Priority#

1
Primary effect: answer user / complete task
2
Secondary effect: improve future memory

除非用户请求本身就是管理 Memory，否则 Secondary Effect 失败不应取消 Primary Effect。

10.2 重置边界#

计数器在 Turn 开始时通过 reset_consolidation_failures() 清零，任意一次成功写入也会将其清零。[H3][H7] 因此它限制的是同一 Turn 中没有取得进展的连续失败，不会把间歇性错误或历史失败累积成永久不可写。

11.1 Schema Description 是 Policy Prompt#

MEMORY_SCHEMA.description 包含：

• 何时保存；
• 优先级；
• 什么不保存；
• Target 如何选择；
• 满容量时使用 Batch；
• Procedure 应进入 Skill。

也就是说，Tool Schema 同时承载：

1
API Contract
2
+ Memory Write Policy
3
+ Recovery Playbook

这提高模型自主性，但也意味着 Schema 改动属于行为变更，应该像 Prompt 与 API 一样做 Regression Eval。

12.1 Process Crash#

Temp File 写入后、Atomic Replace 前 Crash，会留下临时文件，但正式文件保持旧完整版本。需要周期清理 .mem_*.tmp。

12.2 Backup Accumulation#

外部 Drift 每次都可能生成 Timestamped Backup。没有 Retention Policy 时，恢复文件会无限增长，也可能长期保留用户敏感内容。

12.3 Cross-target Transaction#

同时修改 USER 与 MEMORY 时没有跨文件事务。可以通过：

1
Mutation Journal
2
→ target A commit
3
→ target B commit
4
→ mark journal committed
5
→ recover incomplete journal

补强，但这不是固定版本已提供能力。

12.4 Audit Log#

建议记录：

1
{
2
  "mutation_id": "...",
3
  "session_id": "...",
4
  "target": "memory",
5
  "action": "batch",
6
  "before_hash": "...",
7
  "after_hash": "...",
8
  "origin": "agent|user|approval",
9
  "policy_decision": "allow|stage|block",
10
  "committed_at": "..."
11
}

文件 Diff 很透明，但没有 Immutable Audit 时无法证明谁在何时通过哪条路径修改。

12.5 Privacy#

USER.md 可能包含身份、偏好和个人信息。需要独立考虑：

• 存储权限；
• Backup Retention；
• 日志脱敏；
• 用户删除请求；
• Snapshot、缓存、Pending Record 与临时文件同步删除；
• 多用户机器隔离。

13.1 必测状态机#

1
Empty → Add → Duplicate Add
2
Full → Add Rejected → Batch Consolidate
3
External Drift → Replace Rejected + Backup
4
Threat Write → Rejected Before Lock
5
Poisoned Disk → Snapshot Placeholder + Raw Preserved
6
Concurrent Sessions → No Lost Update
7
Four Consecutive Failures → Terminal done=true
8
Staged Write → Approve → Store Validation → Commit

13.2 Crash Test#

在以下位置注入进程终止：

• Temp File 创建后；
• fsync 前后；
• Atomic Replace 前后；
• Backup 写入期间；
• Pending Approval 重放期间。

验证正式文件始终是旧完整版本或新完整版本，不能出现空文件与半 Entry。

13.3 指标#

1
memory_usage_ratio{target}
2
memory_mutation_total{action,result}
3
memory_consolidation_failure_total
4
memory_terminal_skip_total
5
memory_drift_detected_total
6
memory_threat_block_total{pattern}
7
memory_pending_total{decision}
8
memory_lock_wait_ms
9
memory_write_latency_ms
10
memory_backup_count

13.4 Eval 不能只测“记住了吗”#

至少拆成：

14.1 优势#

• Memory Mutation 进入 Agent Action Space；
• 强制容量使 Agent 主动 Curate；
• Frozen Snapshot 保持 Session Prefix 稳定；
• Live State 与未来会话持久化分离；
• 锁内重读、Atomic Replace 和 Drift Backup 降低数据损失；
• Batch 提供单 Target All-or-nothing Consolidation；
• Threat Scan 覆盖写入与消费两条路径；
• Terminal Failure 保护用户主回复。

14.2 边界#

• Character Limit 对不同语言 Token 成本不一致；
• 两个文件无法表达复杂时间冲突与实体关系；
• 单机 File Lock 不等于分布式一致性；
• 缺少跨 Target Transaction；
• Snapshot 中的 Memory 默认 Always-on，会持续占用 Context；
• 自动写入质量仍受模型判断影响；
• Threat Pattern 是规则检测，无法证明语义无害；
• Backup、临时文件与审计需要额外治理。

14.3 最准确的架构定义#

Hermes Memory 不是：

1
Agent can edit MEMORY.md

而是：

1
Bounded Agent-controlled Store
2
+ Frozen Prompt Snapshot
3
+ Live Mutation State
4
+ Lock + Reload + Drift Guard
5
+ Atomic Single-file Commit
6
+ Transactional Batch Consolidation
7
+ Write / Load Threat Gates
8
+ Optional Approval Control Plane
9
+ Turn-level Failure Circuit Breaker

它最值得学习的结论是：

当 Memory 写入交给 Agent 后，系统必须把容量、失败、并发、安全和权限变成 Tool 的显式协议，而不能只依赖模型“谨慎一点”。

[H1] Hermes Agent 固定版本源码#

• Repository：NousResearch/hermes-agent @ 77d5b2d
• 核心文件：tools/memory_tool.py

[H2] Memory Tool Schema 与路由策略#

• MEMORY_SCHEMA
• 核对内容：Target、Batch 建议、Write Priority、Skip 条件、Skill 与 Session State 边界。

[H3] MemoryStore、冻结快照与失败上限#

• MemoryStore
• 核对内容：双状态、2,200 / 1,375 字符预算、前三次连续失败可重试、第四次后 Terminal、加载时去重与 Snapshot Sanitization。

[H4] Threat Pattern Library#

• tools/threat_patterns.py
• 核对内容：Strict Scope 扫描与 Pattern ID。

[H5] 无 Live Agent 的 Store 构造#

• load_on_disk_store

[H6] Single Mutation#

• add
• replace
• remove

[H7] Tool Dispatcher 与可恢复错误#

• memory_tool
• _missing_old_text_error
• _success_response

[H8] File Lock 与 Atomic Write#

• _file_lock
• _write_file

[H9] External Drift Detection#

• _detect_external_drift

[H10] Atomic Batch Consolidation#

• apply_batch

[H11] Write Approval Gate#

• _apply_write_gate
• _apply_batch_write_gate
• apply_memory_pending
• stage_write

[H12] 官方 Persistent Memory 文档#

• Persistent Memory
• 核对内容：Bounded Curated Memory、MEMORY.md / USER.md、容量与 Agent-managed Mutation。

[H13] OWASP Agent Memory Security#

• OWASP Agent Memory Guard
• AI Agent Security Cheat Sheet

上一篇：Claude Code Memory 深潜 · 下一篇：Mem0 Memory Pipeline 源码深潜