About

Imported from sickn33/agentic-awesome-skills (skills/tree-ring-memory/SKILL.md). Install upstream with npx skills add sickn33/agentic-awesome-skills --skill tree-ring-memory. Copyright stays with the author (MIT).

Tree Ring Memory

Name: tree-ring-memory
Author: sickn33

Overview

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.

When to Use This Skill

Use before resuming a project where prior decisions, warnings, preferences, or failed approaches may matter.
Use before changing architecture, storage, security, privacy, release, or agent-memory behavior.
Use when the user asks to remember, recall, audit, redact, forget, or consolidate agent memory.
Use after tests, reviews, incidents, or production behavior validate a lesson future agents should preserve.
Use when a project contains .tree-ring/SKILL.md, .tree-ring/CLI.md, or other Tree Ring bridge files.

How It Works

Step 1: Discover Local Guidance

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, resolve the actual project root and explain the exact project-local download before obtaining explicit approval to fetch it. Download the official, version-pinned v0.15.0/install.sh to a temporary file, verify its SHA-256 is ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade, inspect it, then run it. The pinned source is https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/v0.15.0/install.sh.

cd <project-root>
sh <verified-installer-path> --project --init --release v0.15.0 --no-animation

Do not pipe a network response directly to a shell. After verification and inspection, show the exact installer command and obtain explicit approval again before executing it. For an installed global CLI, initialize from the project root with tree-ring --root .tree-ring init; for a project-local CLI, use .tree-ring/bin/tree-ring --root .tree-ring init.

Check for a newer release without changing files using tree-ring update --check. Run tree-ring update only with user authorization, then rerun init in each project root to refresh managed guidance while preserving custom content.

Step 2: Recall Before Risky Work

Use narrow, project-scoped recall first:

tree-ring recall "release behavior" --project example-service
tree-ring recall "sqlite migration" --project example-service
tree-ring recall "user preference"

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.

Step 3: Write Only Durable Memory

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:

decision
lesson
warning
correction
user_preference
tool_result
summary
hypothesis

Store the durable lesson, decision, warning, or follow-up. Do not store the full conversation.

Step 4: Record Evidence for Evaluated Outcomes

Use evidence records for test runs, incidents, reviewed changes, or other evaluated outcomes:

tree-ring evidence \
  "Installer smoke test passed in an isolated HOME." \
  --outcome observed \
  --evidence-ref "ci/install-smoke/2026-07-08"

Outcome guidance:

promoted: durable truth backed by strong evidence
rejected: failed or rolled-back approach worth keeping visible
deferred: unresolved idea or future option
observed: normal evaluated result

Do not promote weak, stale, or unreviewed claims to durable truth.

Step 5: Use Source Adapters Carefully

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.

Ring Selection

Use the smallest durable ring that fits:

cambium: active or recent task context
outer: recent decisions and task lessons
inner: older compressed project knowledge
heartwood: durable high-confidence truths
scar: failures, regressions, rejected approaches, warnings
seed: unresolved ideas, hypotheses, follow-ups

Prefer outer or seed unless the user confirms durability or the evidence is strong.

Best Practices

Recall before risky or repeat work.
Keep project memory project-scoped unless it is a durable cross-project user preference.
Attach source references such as file paths, issue ids, PR ids, evaluation runs, or docs paths.
Re-check current source files and runtime state before acting on recalled memory.
Ask at closeout what future agents should remember, avoid, or revisit.
Use redaction, deletion, or supersession when memory is wrong, stale, sensitive, or replaced by a newer decision.

Security & Safety Notes

Never use Tree Ring Memory as a hidden recorder.
Do not store secrets, credentials, tokens, private keys, recovery codes, raw chain-of-thought, or temporary scratchpad content.
Do not store sensitive personal data unless the user explicitly asks and the retention boundary is safe.
Do not store copyrighted source text beyond short allowed excerpts.
Do not run installer, network, destructive, or mutation commands without explicit user approval and a clear target environment.
Treat all examples as commands to adapt after checking local --help, not as guaranteed command surfaces.

Limitations

Tree Ring Memory is not a replacement for source control, issue trackers, documentation, tests, logs, or live runtime verification.
Recalled memory can be stale or wrong. Always verify important claims against the current project before using them to make changes.
The CLI surface can change across releases. Prefer local .tree-ring guidance and tree-ring --help over copied command examples.
It should not be used for secret storage, comprehensive transcript archives, compliance retention, or unreviewed collection of sensitive personal data.
Cross-agent interoperability depends on each tool's ability to call the local CLI or read project-local guidance files.

Common Pitfalls

Problem: Recalled memory conflicts with current source. Solution: Treat source files, tests, docs, and runtime evidence as authoritative; supersede or forget stale memory.
Problem: Memory starts becoming transcript storage. Solution: Store only durable decisions, warnings, preferences, outcomes, and follow-ups.
Problem: A lesson is useful but contains sensitive detail. Solution: Store a redacted summary or do not store it.

Related Skills

@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.

Additional Resources

Tree Ring Memory repository: https://github.com/TerminallyLazy/Tree-Ring-Memory
Codex plugin wrapper: https://github.com/TerminallyLazy/tree-ring-memory-codex-plugin

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/sickn33-agentic-awesome-skills-tree-ring-memory/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

sickn33-agentic-awesome-skills-tree-ring-memory.ocm.jsonjson

{
  "ocm": "1",
  "id": "sickn33-agentic-awesome-skills-tree-ring-memory",
  "kind": "skill",
  "name": "tree-ring-memory",
  "description": "Use Tree Ring Memory for local-first AI-agent memory lifecycle work: recall, evidence, audit, forgetting, and consolidation without transcript dumping.",
  "publisher": "sickn33",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "agent-memory",
      "local-first",
      "recall",
      "privacy",
      "codex",
      "sqlite",
      "cli",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Use Tree Ring Memory for local-first AI-agent memory lifecycle work: recall, evidence, audit, forgetting, and consolidation without transcript dumping."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/sickn33/agentic-awesome-skills",
      "path": "skills/tree-ring-memory/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/sickn33/agentic-awesome-skills/blob/HEAD/skills/tree-ring-memory/SKILL.md",
      "key": "sickn33/agentic-awesome-skills/skills/tree-ring-memory/SKILL.md"
    },
    "license": "MIT"
  },
  "instructions": "# Tree Ring Memory\n\n## Overview\n\nTree Ring Memory is a framework-agnostic, local-first memory lifecycle layer for\nAI agents. Use this skill when an agent should recall, preserve, audit, or\nforget durable project memory without treating raw conversation transcripts as\nmemory.\n\nThe public runtime is a Rust CLI/TUI with local SQLite/FTS storage, scoped\nrecall, evidence records, audit, deterministic consolidation, maintenance,\nDOX/Revolve source adapters, framework discovery, redaction, and explicit\nforgetting.\n\n## When to Use This Skill\n\n- Use before resuming a project where prior decisions, warn",
  "cost": {
    "context_tokens": 2017
  }
}

Fetch it by URL: GET /api/v1/registry/sickn33-agentic-awesome-skills-tree-ring-memory/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.