Communitygithub.com

TerminallyLazy/树环记忆

框架无关、本地优先的AI代理记忆生命周期管理工具:Rust命令行、SQLite/FTS回忆、遗忘、审计、合并、DOX/Revolve适配器以及TUI界面。

树环记忆 是什么?

树环记忆是一个生命周期感知的记忆层,专为AI代理(如Claude Code、Cursor、Codex等)设计。它确保代理保留有意义的学习成果,而非无差别的对话转储。通过类似树环的结构,代理可以维护新鲜工作的详细记录、压缩旧知识、标记重要警告、保留持久真理以及存储未来想法。该工具基于Rust CLI构建,使用SQLite和全文搜索实现高效回忆,并提供遗忘、审计、合并等机制。它支持通过DOX和Revolve适配器与项目工件(如AGENTS.md)同步,并提供TUI界面用于事件流显示。代理主动负责决定何时调用记忆命令,确保隐私和安全,避免存储敏感数据。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add TerminallyLazy/Tree-Ring-Memory

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

树环记忆 是做什么的?

将树环记忆用作生命周期感知的记忆层,而非对话转储。

树环记忆像年轮一样保存代理有意义的学习:

  • 新鲜工作保持详细
  • 旧知识压缩成稳定环
  • 重要警告作为疤痕可见
  • 持久真相成为心材
  • 未来想法作为种子保存
  • 敏感数据默认被阻止、编辑或排除在外

何时回忆

在以下情况前回忆记忆:

  • 开始或恢复一个项目
  • 更改架构、存储、安全、隐私或发布行为
  • 重复一个可能存在先期失败的工作流程
  • 响应用户纠正
  • 做出依赖先前偏好或约束的决策
  • 编辑包含树环记忆或 AGENTS.md 约定的仓库中的文件
  • 完成有意义的工作并决定哪些内容应该被记住

尽量使用带有项目范围的窄查询。优先使用有源引用、高置信度、未被取代的结果。

何时记住

当信息可能有助于未来工作时存储记忆:

  • 用户声明了持久偏好
  • 用户纠正了代理
  • 做出了应超越当前会话的决策
  • 经过测试或生产行为验证的实施经验
  • 不应重复的失败方法
  • 出现安全、隐私、发布或数据丢失警告
  • 发现了有用的项目约定
  • 未来想法应稍后重新审视

保持记忆简洁。只存储经验、决策或警告,而非完整对话。

当经验来自评估、检查点、实验、分支、事件或已审查的运行产物时,使用 tree-ring evidence 而非简单的 remember。

当项目工件已经包含结构化指导或评估结果时,使用源适配器:

tree-ring dox sync --source-root . --dry-run
tree-ring revolve sync --source-root revolve --dry-run
tree-ring integrations scan --source-root .

先使用 --dry-run 运行适配器命令。只同步简洁的、有源引用的摘要;切勿将导入的记忆视为比源 AGENTS.md、Revolve 记录、评估、PR、问题或测试工件更具权威性。

使用本地安装暴露的确切CLI命令:

tree-ring --help
tree-ring dox sync --help
tree-ring revolve sync --help
tree-ring evidence --help

如果项目使用项目本地二进制文件初始化,优先使用生成的 .tree-ring/CLI.md 参考,并在需要时包含 --root .tree-ring。

如果此技能通过宿主原生桥接文件加载,请将该桥接文件仅视为指针。当存在项目本地的 .tree-ring/SKILL.md 和 .tree-ring/CLI.md 时,请读取它们以使命令与安装的项目根目录匹配。除非用户明确配置,否则不要假设全局树环设置适用于当前仓库。

证据结果映射:

  • promoted:来自支持证据的持久心材
  • rejected:可重用失败或回滚方法的疤痕
  • deferred:有前途但未解决的选项的种子
  • observed:外环评估结果

环的选择

使用这些环:

  • cambium:活跃或最近的任务上下文
  • outer:最近的决策和任务经验
  • inner:旧的压缩项目知识
  • heartwood:持久的、高置信度的真理和用户偏好
  • scar:重要的负面记忆、失败、回归、被拒绝的方法和警告
  • seed:未解决的想法、假设、后续工作和未来任务

不要从弱证据提升为 heartwood。优先使用 outer 或 seed,除非用户确认持久性或证据强有力。

事件类型

优先使用具体的事件类型:

  • user_preference
  • decision
  • lesson
  • warning
  • correction
  • file_change
  • tool_result
  • summary
  • hypothesis

如果宿主集成有更严格的事件类型名称,请使用最接近的本地等效类型。

不应存储的内容

不要存储:

  • 密码
  • 凭据
  • 令牌
  • 私钥
  • 原始思维链
  • 临时草稿笔记
  • 未经验证的声明视为持久真理
  • 未经明确用户指示的私人健康、财务、法律或个人标识符详细信息
  • 超出简短允许片段的受版权保护的源代码文本

如果有用的记忆包含敏感材料,请存储一个经过编辑的摘要,并保留足够的上下文以保持有用。

源和范围

有目的地设置项目和范围:

  • 使用项目范围处理特定于仓库的规则、决策、警告和经验
  • 使用代理范围处理代理配置文件行为
  • 仅对持久的用户偏好或跨项目指导使用全局范围
  • 包含源引用,如文件路径、问题ID、PR ID、运行ID或文档路径
  • 使用 tree-ring evidence ... --evidence-ref <ref> 处理评估结果
  • 使用 tree-ring dox sync 生成简洁的 AGENTS.md 摘要
  • 使用 tree-ring revolve sync 处理提升、拒绝、延迟或观察到的评估记录
  • 在配置新的代理宿主之前使用 tree-ring integrations scan

记忆不能替代源文档。如果仓库有 AGENTS.md、项目文档、测试、架构记录或宿主办指令文件,请直接读取这些源并将其视为权威。

当 DOX 或 Revolve 源记录更改时,使用 --dry-run 重新运行匹配的同步适配器,检查生成的记忆,然后仅在摘要有用且具有源引用时才执行写入命令。

代理介导的更新

树环记忆不会自动抓取聊天记录或在后台写入持久记忆。活动代理负责判断何时需要执行树环命令,然后有目的地调用CLI。

仅使用桥接文件来发现树环及其命令参考:

  • 项目级别的桥接应指向 .tree-ring/SKILL.md 和 .tree-ring/CLI.md
  • 全局桥接应视为选择性加入的用户配置
  • TUI 事件流脉冲是显示信号,而非持久记忆

在写入记忆之前,验证经验是持久的、有用的、隐私安全的,并且基于用户指令或源证据。

遗忘和纠正

如果记忆错误、隐私相关、过时或被取代:

  • 当持久形态有用但细节不安全时,编辑它
  • 当不应保留时,删除它
  • 当新决策取代它时,取代它
  • 对每次遗忘操作优先使用明确的原因

切勿仅仅因为之前回忆过就保留已知错误的记忆。

完成习惯

在完成有意义的工作后,询问:

  • 我们决定了什么?
  • 我们学到了什么?
  • 未来的代理应避免重复什么?
  • 用户是否声明了持久偏好?
  • 是否有值得重新审视的未来种子?
  • 是否有任何记忆敏感而最好不存储?

只记住那些能实质性改善未来工作的答案。

相关技能