Tree Ring Memory
Overview
Use this skill to operate Tree Ring Memory as a lifecycle-aware memory layer for
AI agent work. Tree Ring Memory is for durable decisions, lessons, warnings,
project conventions, user preferences, and future seeds. It is not a transcript
dump or a background scraper.
The core idea is that agent memory should age deliberately:
- fresh work can stay detailed while it is still active
- older lessons should compress into stable summaries
- important failures and warnings should remain visible
- durable preferences and project truths should become high-confidence memory
- speculative follow-ups should stay separate from confirmed facts
- sensitive data should be blocked, redacted, or forgotten
When to Use
Use this skill when:
- The user asks the agent to remember, recall, consolidate, redact, or forget.
- A task depends on previous project decisions, preferences, or warnings.
- The agent is starting or resuming work in a repository with Tree Ring Memory
or a project-local
.tree-ring directory.
- A test, incident, PR, benchmark, or review produces a lesson that should help
future work.
- A source document such as
AGENTS.md, DOX, or Revolve contains durable
guidance that should be summarized into memory.
- The agent needs to audit stored memory before a risky change.
Do not use
Do not use this skill as the primary guide for:
- Short-lived scratch notes that should disappear after the task.
- Raw chain of thought or hidden reasoning.
- Secrets, credentials, tokens, private keys, payment details, or other
sensitive values.
- Saving entire conversations instead of concise lessons or decisions.
- Treating unverified claims as durable project truth.
- Replacing source documents, tests, issues, PRs, or release records.
Instructions
Follow the workflow below whenever Tree Ring Memory could improve continuity.
For small tasks, recall narrowly and only write memory when the lesson is
clearly durable. For higher-risk work, include source checks, evidence-linked
capture, and a closeout review.
Workflow
- Recall before acting when prior context could affect the task.
- Prefer narrow project-scoped queries over broad global recall.
- Read source documents directly when they exist; memory does not replace
AGENTS.md, project docs, tests, issues, PRs, or release records.
- Store only concise lessons, decisions, warnings, and preferences that will
materially improve future work.
- Use evidence-linked capture when a lesson comes from a reviewed run,
evaluation, checkpoint, incident, branch, PR, issue, or test artifact.
- Redact, supersede, or delete stale or sensitive memory instead of preserving
known-wrong context.
Command Reference
Start with local help so commands match the installed version:
tree-ring --help
tree-ring evidence --help
tree-ring dox sync --help
tree-ring revolve sync --help
If the project has a local Tree Ring setup, read .tree-ring/SKILL.md and
.tree-ring/CLI.md before assuming a global configuration. If a command needs
the project store explicitly, include the local root:
tree-ring --root .tree-ring recall --query "release decisions"
tree-ring --root .tree-ring evidence --help
Run source adapters in dry-run mode before writing imported summaries:
tree-ring dox sync --source-root . --dry-run
tree-ring revolve sync --source-root revolve --dry-run
tree-ring integrations scan --source-root .
Only write summaries that are concise, useful, source-linked, and privacy-safe.
Ring Model
Use the ring metaphor to decide retention strength:
cambium: active task contextouter: recent decisions and lessonsinner: older compressed project knowledgeheartwood: durable high-confidence truths and preferencesscar: important failures, regressions, rejected approaches, and warningsseed: unresolved ideas, hypotheses, and follow-ups
Do not promote weak evidence into heartwood. Use outer or seed until the
user confirms durability or the evidence is strong.
Privacy Guardrails
Never store:
- secrets, credentials, tokens, private keys, or payment details
- raw chain of thought
- temporary scratchpad notes
- unverified claims as durable truth
- sensitive health, financial, legal, or personal identifier details without
explicit user instruction
- copyrighted source text beyond short allowed excerpts
When useful memory contains sensitive material, keep only a redacted operational
summary with enough context to avoid repeating the same mistake.
Closeout Checklist
Before ending meaningful work, ask:
- What did we decide?
- What did we learn?
- What should future agents avoid repeating?
- Did the user state a durable preference?
- Is there a future seed worth revisiting?
- Is any memory wrong, stale, private, or better left unstored?
Only remember answers that are durable, useful, source-grounded, and safe.
1---
2name: tree-ring-memory
3description: Use when an AI agent needs local-first project memory recall, evidence-linked lessons, privacy-safe capture, audit, redaction, or intentional forgetting.
4---
5
6# Tree Ring Memory
7
8## Overview
9
10Use this skill to operate Tree Ring Memory as a lifecycle-aware memory layer for
11AI agent work. Tree Ring Memory is for durable decisions, lessons, warnings,
12project conventions, user preferences, and future seeds. It is not a transcript
13dump or a background scraper.
14
15The core idea is that agent memory should age deliberately:
16
17- fresh work can stay detailed while it is still active
18- older lessons should compress into stable summaries
19- important failures and warnings should remain visible
20- durable preferences and project truths should become high-confidence memory
21- speculative follow-ups should stay separate from confirmed facts
22- sensitive data should be blocked, redacted, or forgotten
23
24## When to Use
25
26Use this skill when:
27
28- The user asks the agent to remember, recall, consolidate, redact, or forget.
29- A task depends on previous project decisions, preferences, or warnings.
30- The agent is starting or resuming work in a repository with Tree Ring Memory
31 or a project-local `.tree-ring` directory.
32- A test, incident, PR, benchmark, or review produces a lesson that should help
33 future work.
34- A source document such as `AGENTS.md`, DOX, or Revolve contains durable
35 guidance that should be summarized into memory.
36- The agent needs to audit stored memory before a risky change.
37
38## Do not use
39
40Do not use this skill as the primary guide for:
41
42- Short-lived scratch notes that should disappear after the task.
43- Raw chain of thought or hidden reasoning.
44- Secrets, credentials, tokens, private keys, payment details, or other
45 sensitive values.
46- Saving entire conversations instead of concise lessons or decisions.
47- Treating unverified claims as durable project truth.
48- Replacing source documents, tests, issues, PRs, or release records.
49
50## Instructions
51
52Follow the workflow below whenever Tree Ring Memory could improve continuity.
53For small tasks, recall narrowly and only write memory when the lesson is
54clearly durable. For higher-risk work, include source checks, evidence-linked
55capture, and a closeout review.
56
57## Workflow
58
591. Recall before acting when prior context could affect the task.
602. Prefer narrow project-scoped queries over broad global recall.
613. Read source documents directly when they exist; memory does not replace
62 `AGENTS.md`, project docs, tests, issues, PRs, or release records.
634. Store only concise lessons, decisions, warnings, and preferences that will
64 materially improve future work.
655. Use evidence-linked capture when a lesson comes from a reviewed run,
66 evaluation, checkpoint, incident, branch, PR, issue, or test artifact.
676. Redact, supersede, or delete stale or sensitive memory instead of preserving
68 known-wrong context.
69
70## Command Reference
71
72Start with local help so commands match the installed version:
73
74```bash
75tree-ring --help
76tree-ring evidence --help
77tree-ring dox sync --help
78tree-ring revolve sync --help
79```
80
81If the project has a local Tree Ring setup, read `.tree-ring/SKILL.md` and
82`.tree-ring/CLI.md` before assuming a global configuration. If a command needs
83the project store explicitly, include the local root:
84
85```bash
86tree-ring --root .tree-ring recall --query "release decisions"
87tree-ring --root .tree-ring evidence --help
88```
89
90Run source adapters in dry-run mode before writing imported summaries:
91
92```bash
93tree-ring dox sync --source-root . --dry-run
94tree-ring revolve sync --source-root revolve --dry-run
95tree-ring integrations scan --source-root .
96```
97
98Only write summaries that are concise, useful, source-linked, and privacy-safe.
99
100## Ring Model
101
102Use the ring metaphor to decide retention strength:
103
104- `cambium`: active task context
105- `outer`: recent decisions and lessons
106- `inner`: older compressed project knowledge
107- `heartwood`: durable high-confidence truths and preferences
108- `scar`: important failures, regressions, rejected approaches, and warnings
109- `seed`: unresolved ideas, hypotheses, and follow-ups
110
111Do not promote weak evidence into `heartwood`. Use `outer` or `seed` until the
112user confirms durability or the evidence is strong.
113
114## Privacy Guardrails
115
116Never store:
117
118- secrets, credentials, tokens, private keys, or payment details
119- raw chain of thought
120- temporary scratchpad notes
121- unverified claims as durable truth
122- sensitive health, financial, legal, or personal identifier details without
123 explicit user instruction
124- copyrighted source text beyond short allowed excerpts
125
126When useful memory contains sensitive material, keep only a redacted operational
127summary with enough context to avoid repeating the same mistake.
128
129## Closeout Checklist
130
131Before ending meaningful work, ask:
132
133- What did we decide?
134- What did we learn?
135- What should future agents avoid repeating?
136- Did the user state a durable preference?
137- Is there a future seed worth revisiting?
138- Is any memory wrong, stale, private, or better left unstored?
139
140Only remember answers that are durable, useful, source-grounded, and safe.
yangsonhung