SuperAPI AI 工具集

memory-hygiene

编程与开发

查看项目

更新于 10-29 18:03

技能介绍

memory-hygiene 是一个项目级技能实例,改编自 canon 全局技能,用于检查并修复项目记忆库(memory store)的健康状况。其核心动机是:除了加载器之外,没有任何东西会读取记忆库,因此索引漂移是静默的,并且会不断累积。资料记录了 2026-08-12 对 14 个记忆库、341 条记忆的测量:其中一个记忆库在六个月内将所有内容内联在 MEMORY.md 中,没有任何记忆文件;另外三个存在链接或膨胀缺陷,均未被发现。

用途: 对指定记忆库执行只读检查或确定性修复,识别索引与文件不一致、链接失效、标题不规范、钩子文本过长、内容误置和索引缺失等问题。

主要能力: 检查项包括:MEMORY.md 应作为索引(出现散文、表格或代码而非单行指针);索引存在性(磁盘上有记忆文件但无 MEMORY.md);索引与文件 1:1 对应(孤儿文件、过期指针、重复项);[[链接]] 可解析(悬空 wiki 链接,无歧义者可自动修复);name 字段等于文件名词干;无 slug 标题(索引标题是文件名而非散文);钩子文本不超过 300 字符。

使用方式: 解析记忆库路径:SLUG=$(printf '%s' "$PWD" | sed 's#[/.]#-#g'),MEMDIR=<repo-declared-memory-store>。slug 将 /、 和 . 映射为 -,大小写保留。若 $MEMDIR 不存在,应列出 <repo-declared-memory-stores>/ 并查找匹配 slug 的库,不能将“无法解析路径”与“项目没有记忆”混为一谈。运行命令: python3 <skills-root>/memory-hygiene/lint.py "$MEMDIR" --brief # 单行只读 python3 <skills-root>/memory-hygiene/lint.py "$MEMDIR" # 完整报告,违规时退出 1 python3 <skills-root>/memory-hygiene/lint.py "$MEMDIR" --fix # 仅确定性修复

修复门控: --fix 只做两件事:将 name: 字段重写为与文件名匹配,以及重新指向无歧义的 [[链接]]。写文件前会先将所有待写文件打包到 .backups/lint-fix-<ts>.tar.gz。它绝不能作用于“内容在索引中”和“索引缺失”检查,也不应这样做,因为拆分承载内容的 MEMORY.md 是判断问题,且该文件常是唯一副本。在运行 --fix 前应先阅读 --brief 报告。

适用场景: 项目记忆库的定期健康检查;作为 SessionStart 钩子运行 --brief(只读、单行、|| true)是安全的。SessionEnd 钩子运行 --fix 属于跨所有记忆库的自主写入,按审批门控应归为高风险,需经审批流程,且应先阅读每个记忆库的 --brief 报告。两者都存放在引擎设置文件中,该文件通常不被版本跟踪,移除技能目录并不会移除钩子,需显式注销。

限制: --fix 无法修复最重要的两类缺陷(内容误置、索引缺失),需人工处理。检查通过仅表示这些不变量成立。路径解析错误可能被误判为“没有记忆”。索引可能承载唯一数据,丢失即丢失数据。