Tree Ring Memory is a framework-agnostic, local-first memory lifecycle layer for
AI agents. Use this skill when an agent should recall, preserve, audit, or
forget durable project memory without treating raw conversation transcripts as
memory.
The public runtime is a Rust CLI/TUI with local SQLite/FTS storage, scoped
recall, evidence records, audit, deterministic consolidation, maintenance,
DOX/Revolve source adapters, framework discovery, redaction, and explicit
forgetting.
or failed approaches may matter.
agent-memory behavior.
consolidate agent memory.
future agents should preserve.
.tree-ring/SKILL.md, .tree-ring/CLI.md, orother Tree Ring bridge files.
Check whether the current project already has Tree Ring guidance:
test -f .tree-ring/SKILL.md && sed -n '1,220p' .tree-ring/SKILL.md
test -f .tree-ring/CLI.md && sed -n '1,220p' .tree-ring/CLI.md
Treat project-local .tree-ring files as more authoritative than generic
examples in this skill. If the CLI is installed, inspect the current command
surface before assuming flags:
tree-ring --help
tree-ring recall --help
tree-ring remember --help
tree-ring evidence --help
tree-ring audit --help
tree-ring forget --help
If Tree Ring is not installed, do not run remote installer commands
automatically. Point the user to the project repository or install docs and ask
whether they want installation help.
Use narrow, project-scoped recall first:
tree-ring recall "release behavior" --scope project
tree-ring recall "sqlite migration" --scope project
tree-ring recall "user preference" --scope global
Use recalled memory as context, not authority. Verify it against current source
files, tests, docs, issues, pull requests, logs, and runtime state before making
changes.
Write concise memory only when it is likely to help future agents:
tree-ring remember "Run project-scoped recall before release changes." --event-type lesson --scope project
Prefer specific event types when supported locally:
decisionlessonwarningcorrectionuser_preferencetool_resultsummaryhypothesisStore the durable lesson, decision, warning, or follow-up. Do not store the
full conversation.
Use evidence records for test runs, incidents, reviewed changes, or other
evaluated outcomes:
tree-ring evidence \
--outcome observed \
--summary "Installer smoke test passed in an isolated HOME." \
--evidence-ref "ci/install-smoke/2026-07-08"
Outcome guidance:
promoted: durable truth backed by strong evidencerejected: failed or rolled-back approach worth keeping visibledeferred: unresolved idea or future optionobserved: normal evaluated resultDo not promote weak, stale, or unreviewed claims to durable truth.
When a repo has structured source records, run dry runs first:
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 adapter summaries when they are concise, source-linked, useful, and
privacy-safe. Imported memory does not replace the underlying AGENTS.md,
Revolve record, test, pull request, issue, or documentation.
Use the smallest durable ring that fits:
cambium: active or recent task contextouter: recent decisions and task lessonsinner: older compressed project knowledgeheartwood: durable high-confidence truthsscar: failures, regressions, rejected approaches, warningsseed: unresolved ideas, hypotheses, follow-upsPrefer outer or seed unless the user confirms durability or the evidence is
strong.
preference.
runs, or docs paths.
memory.
sensitive, or replaced by a newer decision.
chain-of-thought, or temporary scratchpad content.
retention boundary is safe.
explicit user approval and a clear target environment.
--help, not asguaranteed command surfaces.
documentation, tests, logs, or live runtime verification.
the current project before using them to make changes.
.tree-ringguidance and tree-ring --help over copied command examples.
compliance retention, or unreviewed collection of sensitive personal data.
CLI or read project-local guidance files.
Solution: Treat source files, tests, docs, and runtime evidence as
authoritative; supersede or forget stale memory.
Solution: Store only durable decisions, warnings, preferences, outcomes,
and follow-ups.
Solution: Store a redacted summary or do not store it.
@agent-memory-systems - Use for broad agent-memory architecture choices.@agent-memory - Use for the listed hybrid memory MCP system.@planning-with-files - Use when simple persistent files are enough.