memory-gardener

记忆园丁

持久化的 Agent 记忆默认会逐渐腐化。重复项不断累积，事实悄然过时，单条记忆膨胀成杂物抽屉，图谱节点变得孤立，而且从来没有任何内容得到归纳总结。大多数记忆系统都提供了用于维护的基本操作（重复项检查、失效处理、重新链接），但没有任何机制会实际运行这些操作。

这项技能就是园丁：一种有预算限制、幂等的维护流程，你可以定期运行它，整理当前环境所提供的各种记忆存储。它有意做到与存储无关——每次运行开始时都从工具界面发现可用能力，整理现有内容，跳过不具备的能力，并报告所有情况。用于判断高风险调用（去重和拆分膨胀内容）的提示词位于 prompts/，源自 Jeremy Scherer 在 EI 中经过实战验证的夜间维护流程（MIT）。

基本原则——安全约定

本节内容优先于本文档中的其他所有内容。

1. 变更模式。 默认模式是整理并提议：在报告中提议删除和不确定的合并，而不实际执行。如果操作者的运行指令明确授权使用自主模式，则直接执行明确无误的删除和合并——这与上游 EI 自身的维护流程一致，而提示词的保守策略（只有在核心含义有 85% 以上一致时才合并；默认保留两者）是关键的安全保障。无论哪种模式：如果存储支持失效处理、归档或过期，就优先采用这些方式，而不是删除；提示词标记为不确定的操作绝不执行——在整理并提议模式下提出建议，在自主模式下则推迟处理并附上说明。
2. 为每次运行设置预算。 默认值：每次运行最多进行 25 次变更和 50 次判断比较。预算用尽时，在当前阶段中途停止，在报告中记录恢复点，并让下次运行继续处理。按时间最久或最脏乱优先处理，自然便于后续恢复。
3. 幂等。 在一次干净的运行后立即重新运行，应该几乎找不到需要处理的内容。如果第二次运行仍不断发现同一个“问题”，说明修复方式有误——停止处理并改为提出建议。
4. 先创建快照。 如果环境提供备份能力：在整理并提议模式下，首次运行前创建备份；在自主模式下，每次运行前都创建备份——这是无人值守清理的撤销按钮。
5. 缺少能力 ⇒ 跳过该阶段并记录。 绝不要用破坏性的变通方法近似替代缺失的基本操作（例如，先删除再重新创建来伪装成更新）。

阶段 0 — 调查

不要假定工具名称；不同环境各不相同。扫描可用工具，并将其映射到相应能力：

能力	查找具备以下功能的工具……
记忆搜索	按相似度、文本或标签搜索或列出已存储的记忆
记忆修改	创建／更新记忆（可能也有删除功能；不要调用）
重复项检查	根据文本返回近似重复项——或通过带分数的相似度搜索来模拟
知识图谱	添加／查询事实；停用／作废链接或事实；查看时间线或历史
图结构	列出容器（集合、房间、抽屉）、链接／边，进行遍历和重新连接
日记／日志	追加带日期的自由文本条目
统计	项目数量、图谱统计——操作前后都要记录
备份	创建存储快照
工件／报告存储	保存文本文档

记录现有哪些存储。许多环境采用双层架构——快速向量存储和结构化知识图谱；两者都要维护。记录基线统计。确定“从何时开始”：查找先前的维护报告或日记条目，并维护从该时间起的内容；首次运行时，只检查最近的约 200 条，而非全部历史记录。

如果环境提供映射式工具发现功能，在判定某种能力缺失前，先发现并检查实际的修改操作。搜索相关意图（“使知识关系失效”“删除知识链接”“归档记忆”等），检查返回的架构，然后直接调用映射后的工具。不要要求工具名称必须恰好是 invalidate；许多系统会将图谱失效操作作为对链接资源执行的供应商无关的删除／停用操作。除非环境明确只公开底层供应商工具，否则应将其名称视为实现细节。

阶段 1 — 去重

首先，完成闭环：如果先前报告中有尚未处理的 Proposed 条目，且已获准执行——在“维护并提议”模式下由人工批准，或在自主模式下仍待处理——现在就使用 prompts/dedup-confirmed.md 执行这些合并，然后将相应报告标记为已执行，确保绝不重复运行。

然后，针对自上次运行以来新增或更新的项目，使用重复项检查能力（或相似度搜索）查找近似重复项。将相似度 ≥ 0.90 的项目视为候选项，并使用随附的流程提示词进行判断：

• 包含 2 个或更多候选项的簇 → prompts/dedup-cluster.md — 策展流程：合并核心含义重合度达到 85% 以上的项目，首要原则是绝不丢失数据。
• 恰好两条记录，一条是新记录，另一条已存在 → prompts/dedup-validate.md — 把关流程：默认保留两条（“错误合并会永久销毁信息；错误保留则无妨”）。

应用每条提示词的 update 输出。其 remove 输出根据修改模式处理：在“维护并提议”模式下，将其放入报告的 Proposed 队列；在自主模式下，执行该操作（优先归档／作废，而非硬删除），并在报告中记录每次移除（参见 prompts/README.md）。合并规则速查：强度／置信度／曝光度等字段取较高值，情感类字段取平均值，描述详情取唯一内容的并集。

阶段 2 — 衰减

超过 30 天未被提及、检索或更新的项目视为陈旧（可根据存储的更新节奏调整）。对于陈旧项目：将重要性／优先级／曝光度降低一档，但绝不低于下限。如果存储支持过期设置，则为无关紧要的项目设置过期时间，而不要提议删除。绝不降低存储标记为已固定、关键或受保护的项目。

阶段 3 — 拆分臃肿内容

文本超过 约 750 个字符的条目，通常是多个事实共用一个 ID。优先处理最严重的条目，每次运行最多拆分 5 个：

1. 将不同的事实提取为新的、内容聚焦的条目。
2. 使用存储支持的任何方式，将子条目关联到父条目——边、隧道、标签，或元数据中的 parent: 引用。
3. 将父条目精简为其实际核心内容。

像 EI 那样分两步运行，并使用附带的提示词： prompts/bloat-scan.md 将埋藏的主题提取为搜索短语（扫描不会修改任何内容；对于类似人物的记录，使用咖啡店测试——六个月后偶遇时，这个细节仍然重要吗？）；搜索存储中的每个短语；然后由 prompts/bloat-split.md 精简原条目，并将内容重新分配到匹配的记录或新记录中。

这是成本最高的阶段；少拆分一些、但拆分得更好，完全可以接受。

阶段 4 — 使已被取代的内容失效

仅适用于知识图谱存储。查询自上次运行以来变动的事实，并查找矛盾：主体和谓词相同，但宾语不同、时间也不同。较早的事实已被取代——应将其标记为失效（以保留时间线），绝不要硬删除。

保持对存储方式无关，但要准确区分操作类型：

1. 如果检查过的模式提供原生的失效、归档或退役操作，优先使用该操作。
2. 如果模式将失效建模为删除链接或事实资源，这仍然是正确的失效能力。若工具描述或提供方行为表明此操作会退役图谱断言，而不是销毁所有历史记录，就使用它。
3. 如果过时的断言已通过主体 + 谓词 + 宾语识别出来，但变更模式要求不透明的链接/事实 ID，则先使用图查询、邻居、路径、时间线或搜索能力找回确切 ID。不要仅仅因为起初只有三元组，就声称无法使其失效。
4. 在“维护并提议”模式下，除非操作员已批准该过时断言，否则应提议将其标记为失效。在自主模式下，只执行明确无疑的取代操作，并记录确切退役的断言。

如果存储确实不支持失效，则将更正内容添加为新事实，并在待提议项下列出过时的事实。

阶段 5 — 重新连接孤立项

对于图存储：查找没有链接的节点，或被归入明显错误容器的条目。重新归档这些条目，添加唯一明确缺失的链接；如果存储提供重新连接辅助工具，也应使用。**每次运行最多重新连接 10 项。**如果某个条目的正确归属不明确，就保留原状并注明——错误链接比缺少链接更糟。

阶段 6 — 总结这段时间的情况

撰写一篇日记/日志：用 2–6 个句子记录自上次运行以来新增的重要知识，再用一行说明知识库的健康状况（例如：“主题 X 中的重复压力正在上升。”）。如果没有日记功能，则改为写入一条标记为 garden-summary 的记忆条目。

阶段 7 — 报告（绝不跳过）

即使跳过了所有其他阶段，也要生成报告。如果存在工件/报告功能，通过它保存报告；同时始终将报告作为最终输出发送。

# Gardening report — <ISO timestamp>
Stores tended: <store: capability summary, per store>
Stats: <counts before → after, per store>
Actions: merges N · decays N · splits N · invalidations N · reconnects N
Destructive ops (mode: tend-and-propose | autonomous):
  - PROPOSED DELETE <id> "<short preview>" — duplicate of <id>   (tend-and-propose)
  - EXECUTED MERGE <id> ← <id> — "<short preview>"               (autonomous)
Deferred (uncertain): <pairs the prompts declined to merge, one line each>
Skipped: <phase> — <missing capability>
Budget: <used>/<max> mutations · resume point: <store / cursor or "clean">

在“维护并提议”模式下，破坏性操作部分就是供人工审核的队列——**维护者负责照料；人类负责修剪。**在自主模式下，维护者也负责修剪，而报告就是审计日志：每项移除都有据可查，每个不确定之处都延后处理，而非强行定论。

Substrate 语义完成

当此技能作为 Substrate runner 或工作流任务运行时，园艺报告仍是面向人类的输出，但它不是机器成功信号。在报告和任何工作流特定状态字段之后，将最后一条非空助手消息严格设为一条 SUBSTRATE_OUTCOME_V1= 声明。

仅当仪式在预算内完成、所有不可用阶段都如实记录为已跳过、每项已执行的变更都经过审计，并且在存在制品能力时报告已持久化并读回，才声明 outcome: "succeeded"。自主模式下所需备份失败、未报告的部分变更，或未能持久化所需报告，均属于 outcome: "failed"；受阻或需要人工处理的工作也属于失败。记忆和知识变更不是 Git 更改，因此使用 changes.status: "notApplicable"。

成功行示例（将占位符替换为真实证据）：

SUBSTRATE_OUTCOME_V1={"version":1,"outcome":"succeeded","summary":"Completed memory gardening and persisted report <artifact-id>","evidence":{"changes":{"status":"notApplicable","reason":"Memory-store mutations are not Git changes"},"verification":{"status":"passed","commands":["read back report artifact <artifact-id>"]}}}

不要输出第二条声明，也不要在其后输出任何内容。在 Substrate 任务之外，不要添加这条平台专用行。

定期运行

适用于任何能够调用带有此技能的 Agent 的主机进行近乎每日的无人值守运行——例如启动 Agent 任务的调度器、Agent 框架自带的 cron，或普通的 crontab 条目。活跃的存储库适合每日运行；不活跃的存储库适合每周运行。每次运行都有预算上限，因此采用较短的运行间隔也是安全的——最坏的情况只是报告显示“干净”。

与 memory-collector 配合使用

memory-collector 是配套的另一半：它会收集编码 Agent 会话的转录内容（Claude Code、Codex、OpenCode、Cursor、Pi），并将主题、人物、事件和引语写入此技能维护的同一批存储库。收集过程有意容忍近似重复和内容膨胀——验证关卡、去重整理器和膨胀拆分机制正是为应对这些流入内容而存在。收集器负责写入；园丁负责修剪。良好的节奏是：收集器每天运行，园丁在之后的夜间运行。

来源与致谢

仪式结构（去重 → 衰减 → 重写 → 反思）、工作阈值（重复候选项为 0.90、核心含义合并率为 85%+、膨胀行约为 750 个字符），以及 prompts/ 中的判断提示词，均源自 Jeremy Scherer 编写的 Flare576/ei 中的夜间仪式（MIT，© 2026 Jeremy Scherer）。Jeremy 根据真实的个人记忆撰写并调整了这些提示词；此技能只将其周边流程泛化，使其不依赖特定存储方式。如果园丁证明了自身价值，不妨了解一下上游项目——一个本地优先的 AI 记忆层，并在其上搭建了人格伴侣系统。