Memory Storage Management

Hermes 记忆存储管理

核心原则：记忆空间的稀缺性是设计特征，不是缺陷——它强制信息蒸馏。扩容是最后手段，不是第一反应。

🔗 本 skill 的关联文件

scope-recall 运维细节（升级/补丁/journal recovery/embedder）已统一到 scope-recall-maintenance skill，不再在此重复维护。

快速入口

双存储架构

Hermes 内置记忆分为两个独立文件：

来源： 源码 hermes_cli/config.py 的 DEFAULT_CONFIG 中定义，agent_init.py 在 Agent 启动时读取，会话期间固定。

两个限额各自独立，互不占用。

适用边界（源码限定）

限额仅在一个入口生效：memory() 工具 → MemoryStore._char_limit()。 其他所有写入 USER.md / MEMORY.md 的路径都不受限额约束。

受限额约束的路径 ✅

不受限额约束的路径 ❌

对本 skill 的含义

• 本 skill 的溢出处理决策树、85% 阈值、3 次溢出规则只对走 memory() 工具的写入有效
• 自改进的写入行为不由本 skill 约束——它的溢出处理取决于自身的 LLM 推理，以及 write_file / patch 工具的固有特性（全量覆写、无原子批处理、无冲突检测）
• 这意味着：USER.md 的实际大小可能超过限额（如自改进写入时），但对话 LLM 通过 memory() 写入时仍然受限额约束

USER.md 单条目结构陷阱（2026-08-04 发现）

USER.md 磁盘上没有 \n§\n 条目分隔符（唯一的 § 在标题 ## § 行为约束 里，前后是空格）——按 _parse_entries（raw.split("\n§\n")）切分，整个 USER.md 是 1 个条目。MEMORY.md 是正常多条目（\n§\n 分隔），不受影响。含义：

正确用法：整文件修改用 replace（old_text="# USER.md" + 完整新全文），先 .bak 备份 + diff 审阅。不要对 USER.md 用 add / remove。

memory() 溢出时的行为（源码事实）

当写入超过上限时，memory() 工具不会静默失败或截断：

1. 返回 success: false
2. 同时返回 current_entries（现有全部条目，可供查看和压缩重试）
3. 错误信息明确告诉你当前占用 / 上限 / 溢出量
4. 你可以原地在同一轮中执行压缩后重试

批量模式（operations）额外优势：同一批中先 remove 再 add， 即使中间步骤超出上限也没关系——只检查最终净结果。

什么适合放

放 ✅：身份偏好、语言选择、兴趣领域、常用根路径、环境工具链 锚定条目 ✅（用户裁决）：允许祈使句（"必须/禁止/一律"）——祈使句是触发保障的一部分，规范本体在技能/RULES；锚定 = 触发信号+动作+流程 判据严格执行（审计修订）：① 触发认知只是必要不充分条件——"反直觉教训必存"受"高频 ∨ 未第一时间加载→重大事故"约束；② 低频排障经验（一次事故、可 session_search/技能查证）不常驻，写入前先 grep 技能库确认承载位置，已承载则不写（或只留指针）；③ 排障叙事 → ops-lessons-archive；④ 混合条目逐段判定：锚定条目可能混有机理/规范摘要段——逐段检查（锚定段=指向+触发信号，保留；机理摘要段已承载 → 删/指针），禁止用整体标签豁免局部冗余（实证：技能触发机制条目机理段冗余留存，整体标 anchor 被豁免） 判别类不等式 ✅（必须带实例）：如"信息需求 ≠ 执行授权"、"索引可见 ≠ 规范已加载"——价值在决策时刻的分类边界，可靠性来自反复实例化；不能用"能否命令化"否定（2026-08-05，详见 rule-enforcement/references/l1-failure-patterns.md） 不放 ❌：

条目标签体系

MEMORY.md 条目使用 4 个固定前缀标签：[base] / [env] / [ops] / [rule]。标签是注入层的索引前缀（认知分组 + 治理维度），不是分类学——分析框架是五维 M1-M5，标签只是条目的注意力引导。

系统设计五原则：

1. 标签固定 4 个——不随知识类别扩展；新增类别 → 技能/archive，不是新标签（防标签膨胀与豁免面扩大）
2. 标签与承载状态正交——标签表示"条目性质"，不表示"是否已承载"（承载检查 = 判据①）
3. 标签与新鲜度正交——标签不表示"是否过时"（过期风险 = 判据④）
4. 标签是注入层专有概念——条目移出记忆（→技能/archive）时标签消亡
5. 混合条目取主导段——一条可含多段，按判据④逐段判定；锚定段与机理段并存且机理冗余 → 删机理段、标签不变

防豁免核心：标签决定"怎么读"（注意力分组），不决定"该不该存"（判据四问）——凡"贴签 = 合规"的用法都是豁免误用。 防豁免靠三联动：判据④逐段判定（流程）+ memory-audit cron（审计）+ 用户 diff 审阅（审批），标签定义本身是必要非充分。

记忆价值判据（什么该留、什么该删）

写入前自检清单（操作化，按序执行）

任何 memory() 写入前按序执行 5 步，任一步拦截即不写（判据细节见下）：

□ 1. 承载检查：grep -ril "<核心关键词>" "$HERMES_HOME/skills" --include="SKILL.md"
     命中 → skill_view 确认已覆盖 → 不写（或只留指针），停止
□ 2. 具体操作：影响哪个高频操作？写不出具体操作 = 排障知识 → 技能/archive，停止
□ 3. 频率门槛：操作 ≥2 次/月？或未第一时间加载会致重大事故？否则 → 技能/archive，停止
□ 4. 后果评估：不知道它 → 犯错后果可恢复？可恢复 → 技能；不可逆 → 通过
□ 5. 四问终检：触发认知 × 提及频率 × 时机敏感 − 过期风险；历史状态不写
□ 6. 粒度检查：含多个独立语义单元？各自服务什么决策时刻？不同决策/频率/过期 → 拆开；
     单条 >200 字符 → 检查是否该分流而非合并

粒度判定：决策时刻三问（聚合单位 = 决策时刻而非事件）：

默认策略：拆分优先——宁可多一条独立条目（可合并），不可过度合并（耦合难拆）。

2026-08-03 会话教训固化（来源 20260803_105311_eebf93）："可一步推断" ≠ "冗余"——Agent 是问题驱动（reactive），存在"未知的未知"（不知道要查 = 永远查不到）。判断一条环境事实是否值得占用记忆：

价值 = 触发认知 × 提及频率 × 时机敏感度 − 过期风险

写入前自检（⓪ 内容级查重 + 四问）：任何 memory() 写入前先执行 ⓪——对技能库做内容级 grep：grep -ril "<关键词>" "$HERMES_HOME/skills" --include="SKILL.md"，命中即 skill_view 确认是否已覆盖；已覆盖 → 不写入，改 patch 技能。名称/描述比对会漏"知识在内容里但描述不含关键词"的存量技能（2026-08-05 stash 教训；规范出处 hermes-agent-skill-authoring §258）。再输出四维对照执行——

四问过完才写；历史状态（已修复的过去式）一律不写。 符合高频使用、未在第一时间加载就会导致重大事故等任意一项条件的信息都必须加入MEMORY.md。经常未在预期时机加载的技能也可通过记忆来锚定。

四类处置：

实证（2026-08-03）：无 pwsh 记忆时 Agent 默认选 powershell.exe 5.1（"不会主动查询"活证据）；junction 条目防止"同一物理目录当两份"的错误推断。

分流正确出口（合并不是容量问题的解，分流才是）

命题：容量压力下"合并条目"是错误方向——省字符的代价是维护性（replace 难定位）、可读性（长条难秒读）、耦合性（频率/过期绑死）；真正的解是分流（不占注入层）。

与既有"压缩合并"的关系（术语区分）：

• "合并"的两义：① 精简合并（同归属层内去重/压缩——正面，既有"方案一：压缩合并"继续有效且优先）② 信息合并（跨归属层把应分流内容塞进 MEMORY——负面，本命题反对的）
• 操作序列：先分流（归属决策）→ 后精简（表述压缩）——互补非冲突
• "合并不是容量问题的解"仅指 ②；① 仍然有效且优先（压缩冗余零成本）

"全塞一条" = 不知道往哪分流的产物——分流四出口先行，注入层只留高频决策事实。

不够用时怎么办（优先级排序）

方案一：压缩合并（零成本，优先级最高）

memory(target="user", operations=[
    {"action": "remove", "old_text": "第一条旧内容的唯一识别子串"},
    {"action": "remove", "old_text": "第二条旧内容的唯一识别子串"},
    {"action": "add", "content": "合并版：偏好A／项目B／工具C"}
])

⚠️ operations 数组中的多个操作是原子提交的——要么全成功，要么全不生效。不是三次独立调用。

典型效果：8 条（510 字符）→ 3 条（~350 字符），省 30%。

方案二：存为 Skill（过程性知识）

过程性知识 → skill_manage(action="create", name="xxx", category="xxx", content="...")，记忆只记引用名。

方案三：Scope Recall 分流

scope_recall_store(target="memory"|"project"|"ops") — 独立存储池，不占用记忆字符。需 scope-recall 插件已安装且启用（配置 memory.provider: scope-recall + plugins.enabled: [scope-recall]）。

⚠️ scope_recall_profile() 只能查看 scope-recall 插件中的记忆，不能 查看内置记忆内容。内置记忆的内容通过 memory() 工具直接管理。

方案四：定期清理（每 2~4 周）

memory(target="user", operations=[
    {"action": "remove", "old_text": "过期项目配置"},
])

溢出处理决策树

当 memory() 写入触发上限拒绝时，按此流程处理：

          memory() 操作溢出
               │
               ▼
        ┌──────────────┐
        │ 执行压缩     │
        │（去重/合并）  │
        └──────┬───────┘
               │
               ▼
        ┌──────────────────────────────┐
        │ 压缩后占用 < 上限×85%？      │
        └──────────┬───────────────────┘
                   │
      ┌────────────┼────────────┐
      ▼ 是          ▼ 否
  问题在冗余，      ┌────────────────┐
  压缩解决         │ 这是连续第几次？ │
  写入成功         └───────┬────────┘
                          │
               ┌──────────┼──────────┐
               ▼ 第1~2次   ▼ 第3+次
           注意观察       ┌────────────────────┐
                          │ 扩容信号触发       │
                          │ → 走扩容判定标准   │
                          └────────────────────┘

85% 阈值的来源： 压缩后如果仍 >85%，再写入新信息时几乎必然再次溢出——这本身就是"空间不够"的指标。以 1,375 为例，85% = ~1,169 字符。

压缩损失的两种类型

判断当前属于哪种损失

压缩省下的空间 > 30%  → 损失的主要是冗余（可接受）
压缩省下的空间 < 10%  → 接近实质损失边界（应评估扩容）
连续3次压缩收益递减   → 扩容信号

扩容的判定标准

触发扩容评估的条件（三个条件同时满足才触发）

1. 压缩收益持续递减： 第一次压缩省 80%，第二次省 30%，第三次省 5% —— 冗余已基本榨干
2. 压缩后仍接近上限： 占用持续 >85%（1,169/1,375）
3. 模式重复 3 次以上： 不是偶发事件

反例（不应扩容）： 一次溢出后，一次压缩就省了 90% 空间（如 1,513→130）——问题在表达方式，不在容量。

建议值的误区

此 skill 不提供通用的"场景→建议值"映射表，原因是：

• 你的实际占用取决于信息密度，不是语言数量或领域数量
• 双语言 + 多领域完全可能在 1,375 内（实际案例：中英文共 784 字符，仅占 57%）
• 错误建议值会导致"看表→直接扩容→跳过压缩"的非必要扩容

唯一可靠的扩容判定方式：走上面的溢出处理决策树。

扩容的操作方法

扩容（提高上限）

# config.yaml memory 段
memory:
  user_char_limit: 1375     # USER.md 上限
  memory_char_limit: 2200   # MEMORY.md 上限

hermes config set memory.user_char_limit 2000
# 或
hermes config set memory.memory_char_limit 5000

⚠️ 生效时机： 修改后需 /reset 或重启 Hermes。 原因： 限额在 Agent 启动时由 agent_init.py 一次性读入 MemoryStore，会话期间固定。/reset 新建 Agent 实例，重新读取配置。 注意： 修改配置不会删除超过新限额的已有内容——已有条目不受影响。

缩容（改回较低上限）

如果想改回默认或更低的值：

hermes config set memory.user_char_limit 1375  # 改回默认
# /reset 生效

⚠️ 超过新上限的内容不会被自动截断。 先手动压缩到低于新上限，然后改配置——或者先改配置再清理，系统都不会自动删除。

验证方法

hermes config show  # 查看 memory. 段的当前值

Token 税：扩容的真实成本

1,375 字符 ≈ 500 tokens（以 2.75 chars/token 估算），这个值写入每轮对话的系统提示词中。扩容的代价是每轮 × 每一字节：

从 1,375 扩到 2,000，50 轮多消耗 11,500 tokens——足够模型执行 510 次工具调用，或多回答 35 个复杂问题。

结论：扩容不是零成本——每扩一个字符，都在用未来的上下文窗口买单。

为什么不设计自动扩容（双向棘轮论证）

提议的方案

触及上限 → 压缩 → 自动扩容到 max(实际占用, 旧上限)
         ↑ 每次 / 固定N次 / 动态

反对论据

手动扩容的优势

推荐策略

记忆（memory）     → 高频稳定的偏好/事实
技能（Skill）      → 过程性知识（步骤/配置/工作流）
Scope Recall      → 笔记/日志/项目细节（不占记忆限额）
会话搜索          → 临时 TODO / 进度

条目长度：
  理想值：50~100 字符（方便单条替换和精确匹配）
  弹性：如果信息是关联偏好的连贯描述，
       单条 500~700 字符也是合理的——
       优先保证语义完整性，而非机械地切成碎片。
  判断标准：能拆成独立语义单元 → 拆开；
           拆开会丢失上下文关联 → 合并为一条

扩容优先顺序：
① 压缩合并（90% 的情况在此解决）
② 分流到 Skill / Scope Recall
③ 手动扩容（仅当压缩收益趋零 + 连续 3 次溢出后）

扩容走 hermes config set + /reset

记忆文件修改流程规范

修改 MEMORY.md / USER.md 必须按序执行：

1. 备份：cp <file> <file>.bak.$(date +%s)（修改前必做）
2. 通道：通过 memory() 工具写入（有 write_approval/限额/漂移检测），禁用 write_file/patch 直接写
3. 审阅：先给出完整 diff，等用户明确批准
4. 执行：批准后执行；变更后验证字符数 vs 限额

系统级保障（config.yaml）：

• memory.write_approval: true → memory() 写入先 staged，/memory approve 才提交
• approvals.smart_policy → 模型侧显式提示（"修改 memories/ 前必须备份+diff+批准"）

常见错误（反例）：

• 用 write_file 直接覆盖记忆文件（绕过备份/限额/审批）
• 把"同意方案方向"当作"授权跳过审阅"
• 修改前不备份

版本管理

数据版本仓库位于 F:\AI\Hermes\hermes-state-git\.git（hermes 目录内无 .git——避免 _is_repo_junk 把会话 git 探测拉回 Home；core.worktree=F:/AI/Hermes/hermes）。无 remote，禁止 push。跟踪 memories/ + skills/ + 身份文档 + config.yaml。.gitignore 排除敏感文件（auth.json / .env / *.db / .bak.）与框架数据目录。

批量 commit 约定（每次知识落盘/治理批次结束时，在 hermes 目录下执行）：

cd F:/AI/Hermes/hermes
git --git-dir=../hermes-state-git/.git --work-tree=. add memories/ skills/
git --git-dir=../hermes-state-git/.git --work-tree=. commit -m "desc (source session <会话ID>)"

陷阱：hermes 目录内直接 git add 报 not a git repository；git -C ../hermes-state-git add memories/ exit 0 但静默不生效（相对路径解析到仓库目录而非工作树）——前面成功 ≠ 安全。

禁止：git remote add / git push（本地私有是安全边界，push 即泄露面）；git add -A（纳入范围外文件）。

git 管理全景

受管范围（跟踪）：memories/（MEMORY.md/USER.md/USER - log.md）、skills/、config.yaml、scripts/、patches/、身份文档（SOUL.md/RULES.md/README.md/CAPABILITIES.md/CONSTITUTION.md）、.gitignore。 排除：*.bak / *.bak.*（watchdog 曾误纳 config.yaml.bak——白名单必须路径段级匹配）、auth.json、.env、*.db、hermes-agent/（源码）、运行产物（gateway.pid/hermes-setup.exe 等）。

机制特征（事实）：无 git hooks、无 watcher、无自动提交——git 只记录"执行 add+commit 的时点"，用户/任何进程手动编辑文件不触发任何 git 记录（变更静默悬空直到批次 commit 碰巧带上）。"git 已记录时间线"指 commit 时点，非编辑时点。

看门狗：~/AppData/Local/hermes/scripts/git-watchdog.py + cron git-state-watchdog（每日 23:55，no_agent 零 token）。白名单路径段级匹配 + 敏感路径拒绝 + 干净静默；未提交变更自动快照 commit。手工批次 commit 仍是首选（有意义的 message），看门狗是兜底（防悬空丢失），不是替代。

执行纪律（防 L1 遗忘）：

1. 任何受管文件变更（含 config.yaml 配置、scripts/ 补丁）变更完成即 commit，不等批次
2. 手动编辑记忆/技能后，下次会话主动检查 git status 并补 commit
3. 看门狗日志：cronjob(action='list') 查 git-state-watchdog last_status

风险备忘：A2A 配置（gateway.platforms.a2a）、fvm repo_scan 排除、0.20.0 升级路径曾悬空 21h+ 未提交（2026-08-05 发现）——配置变更是最易漏 commit 的类型。

与既有流程的关系：步骤①的 .bak 快照仍保留——git 历史提供"逐次 diff 追溯 + 精确回滚"，.bak 提供"修改前瞬间快照"，两者互补；hermes backup 全量与云备份（gpg+rclone 123pan，已含 hermes-state-git）为第三、四层。保护链：① .bak 快照 → ② git 历史 → ③ hermes backup → ④ 云备份。

备份保留策略

.bak 快照无上限累积——实测 MEMORY.md.bak 55 份、单技能 SKILL.md.bak 10 份（每次写前备份从不清理）。策略：

• 保留量：每个文件保留最近 2 份（MEMORY.md / USER.md / SKILL.md 同理）——第 1 份回滚当前修改，第 2 份兜底上一版本；更早版本由 git 历史（hermes-state-git）与 hermes backup 全量兜底，.bak 无需多存
• 清理时机：每次写前备份时顺手清（超过 2 份即删最旧）；或每月治理批次（与 hermes-state-git 批量 commit 同批）
• 清理方式：memories/ 与 skills/ 是受保护路径——裸 rm 会被 block-hermes-assets hook 拦截；一律用 safe-rm（转 F:/AI/Hermes/trash/，可恢复，cron trash-cleanup 30 天自动清）：

  PY="$HERMES_HOME/hermes-agent/venv/Scripts/python.exe"
  SRM="$HERMES_HOME/scripts/safe-rm.py"
  "$PY" "$SRM" <memories|skills>/.../FILE.bak.<ts>   # 每文件保留最新 2 份，其余删除
  

• 实证：一次清理 55 份 MEMORY.md.bak + 29 份 SKILL.md.bak（memory-storage-management 独占 10 份、rule-enforcement 3 份）→ 释放 ~800KB；备份机制本身的累积不产生价值，只产生索引噪音

Scope-Recall 运维

编排式运维 — scope-recall 的完整运维手册已统一到 scope-recall-maintenance skill（安装/升级/补丁/journal recovery/embedder 配置/doctor 解读）。此处仅保留与记忆治理相关的要点，避免双份维护。

与记忆治理相关要点

1. scope_recall 与内置记忆分工：scope_recall_store(target="memory"|"project"|"ops") 是独立存储池，不占用记忆字符；scope_recall_profile() 只能看 scope-recall 记忆，不能看内置 USER.md/MEMORY.md
2. 升级/维护操作 → 加载 scope-recall-maintenance skill 执行（含 1.8.7 升级前置条件、5 个补丁、doctor 全绿红线）
3. journal 积压消化 → 见 scope-recall-maintenance 的 references/journal-recovery.md（heuristic 快速消化法）
4. UA 修复 → scope-recall-maintenance 的 nightly-llm-ua.patch（浏览器 UA，非自定义字符串）

Schema 迁移

• 自动时机：provider 初始化（Hermes 完整重启）
• 验证：doctor 输出 sqlite.schema_migrations.current: true
• 注意：/new / /reset 不足，需完整重启 Hermes