HOARD 历史组织与智能体召回库

它解决什么问题

Agent 在跨会话场景下会丢状态，HOARD 针对的是四类典型失效：

• 上下文窗口压缩：长对话被截断，不在当前窗口的内容直接消失。
• 会话超时：平台把空闲视为放弃，重启后 agent 变成白纸。
• 进程重启：网关重启、模型切换、崩溃，都会清掉工作记忆。
• 记忆投毒：被攻陷的工具或 prompt injection 写入对抗性条目，跨会话持久存在（MPBench 报告对无溯源机制的 OpenClaw agent 有 50.46% 攻击成功率）。

HOARD 的思路不是把上下文窗口加大，而是在窗口关闭前把关键事实写下来，并确保写下的内容可信。

三文件结构

MEMORY.md 是主索引，注入每次会话启动流程。规则很硬：每行一个事实、带日期戳、按时间而非主题分组、附来源元数据、链接到深度文件而不复制内容。临时状态不写入。

memory/*.md 存放不适合塞进索引的细节，按主题拆分文件。规则是「更新而非追加」——旧事实直接替换，不保留错误答案的历史。

HEARTBEAT.md 每次会话启动时刷新，承载当前系统状态，让 agent 快速建立情境感知，而不是在上下文窗口里重新摸索。

来源追踪与写入门禁

每个条目带 HTML 注释元数据：src（来源，五选一：user/agent/tool/web/dig）、ts（写入时间）、可选的 ttl。来源构成信任层级：user > agent > tool > web > dig，冲突时高信任覆盖低信任，同级则新条目胜出。没有元数据的条目默认 src:agent ts:unknown，视为低信任，整理时要打标记并补全来源。

写入门禁约定：只有 agent 可以写记忆，工具不可以。工具产出的持久化数据必须返回给 agent，由 agent 加上正确溯源后写入。这是防止被攻陷工具静默注入恶意条目的关键机制——目前靠 agent 自律，未来可能在网关层强制。

自动过期与后台整理

每条记忆可带 TTL，默认值按来源设定：user 永不过期、agent 和 tool 为 90 天、web 和 dig 为 30 天。整理流程定期跑四件事：过期清理（超期两倍的条目删除或归档）、去重（保留最新事实）、压缩（MEMORY.md 超过约 15KB 时把细节下沉到侧车文件，低于 12KB 停止下沉以避免边界抖动）、归档（可能仍有用但过期的条目移入 memory/archive/）。src:user 条目永不自动删除，整理脚本支持 --dry-run 先预览。

适用边界

• 这是单 agent 单机方案。规模化场景下 Vector DB 才是正解，HOARD 明确不做向量索引，只依赖平台原生的 memory_search 与 memory_get 工具。
• 整套机制的有效性依赖 agent 遵守写纪律：立即写入、只写关键事实、每条带溯源、永不存密钥、不让工具直接写记忆。纪律崩了，系统就退化成一堆带注释的 markdown。
• 源码中 npm 包名 hoard 已被无关时序库占用，需使用 scoped 包名。