tree-ring-memory

Files (1)

• SKILL.md

SKILL.md (first lines)

# Tree Ring Memory

Use Tree Ring Memory as a lifecycle-aware memory layer, not as a transcript dump.

Tree Ring Memory preserves meaningful agent learning like tree rings:

- fresh work stays detailed
- older learning compresses into stable rings
- important warnings remain visible as scars
- durable truths become heartwood
- speculative future work stays as seeds
- sensitive data is blocked, redacted, or kept out by default

## Runtime Bootstrap And Updates

Resolve the actual project root before running Tree Ring. Never initialize a
plugin cache, downloaded package directory, home directory, or arbitrary
working directory by accident.

1. If `<project-root>/.tree-ring/bin/tree-ring` exists, prefer that binary for
   this project. Otherwise check `command -v tree-ring` and run
   `tree-ring --version`.
2. Read existing `<project-root>/.tree-ring/SKILL.md` and `CLI.md` when present.
   Lifecycle hooks need CLI 0.15.6 or newer; older packages may omit
   automatic hooks. Current Codex packages include them, including the public upload. Use `integrations status --verbose` to inspect the last
   recall count and query class, and distinguish no receipt from zero results.
3. This package targets Tree Ring Memory CLI 0.15.0 or newer. If no compatible
   CLI is available and the user's request already authorizes Tree Ring setup,
   install the verified current release project-locally from the project root.
   Otherwise explain the exact operation and obtain permission before the
   network download or software installation. Download the official,
   version-pinned `v0.15.0/install.sh` installer to a temporary file, verify its
   SHA-256 is
   `ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade`,
   inspect it, and only then run:

   ```bash
   cd <project-root>
   sh <verified-installer-path> --project --init --release latest --no-animation
   ```

   Do not pipe a network response directly to a shell. The installer verifies
   the selected release archive against its published SHA-256 before placing
   the binary at `<project-root>/.tree-ring/bin/tree-ring`.

4. For an existing 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`. This must place
   `memory.sqlite`, `AGENTS.md`, `SKILL.md`, and `CLI.md` under that project's
   `.tree-ring/` directory.
5. Verify the created paths and run the same binary with
   `--root .tree-ring integrations status`. Initialization creates safe local
   guidance and bridge material; it is not receipt-backed activation proof.

Check for releases without changing files with `tree-ring update --check`. Run
`tree-ring update` only when the user has authorized an update. It updates the
active binary in its existing project-local, direct, or Homebrew-managed scope,
verifies official release assets, and must not create a second shadowing binary.
After an update, return to each project root and rerun `tree-ring --root
.tree-ring init` (or the project-local equivalent) to backfill managed guidance
without replacing custom files.

CLIs older than 0.15.0 do not have `tree-ring update`. Upgrade those with the
same manager or prefix that installed them: `brew upgrade tree-ring` for
Homebrew, `--project --release latest` for an existing project-local install,
or `--install-dir <existing-prefix> --release latest` for another direct
install. Check `command -v tree-ring` and `which -a tree-ring` afterward. Do not
edit a shell profile or change global installation scope without separate user
authorization.

If the current host cannot execute a local shell or access project files, use
this skill only as memory-lifecycle guidance. Do not claim that recall, capture,
audit, activation, or forgetting occurred unless the corresponding command ran
and its result was observed.

## Agent Operating Loop

Use this sequence for meaningful project work:

1. Resolve the project root and read its local Tree Ring contract when present.
2. Run the runtime preflight, then recall narrowly scoped, source-linked memory
   before making a material decision or repeating a failure-prone workflow.
3. Treat recalled memory as context, not authority. Recheck facts that may have
   changed and defer to current source files, tests, policies, and user input.
4. Do the work. Do not write memory merely because a session is active.
5. At a natural checkpoint or closeout, capture only durable decisions,
   corrections, validated lessons, warnings, preferences, or future seeds.
   Never store raw transcripts, secrets, or sensitive data. Repository
   lifecycle integrations enforce one agent-mediated checkpoint at `Stop` or
   `SubagentStop`; they do not derive memory from hook payloads.
6. Observe the command result and report the actual outcome. A proposed memory,
   dry run, bridge file, or generated marker is not proof that a durable write,
   sync, activation, correction, or deletion occurred.

In a Coordinated store, do not attempt persistent writes without the required
coordinator capability. If the capability is unavailable, provide a concise
candidate memory for an authorized coordinator instead of claiming it was
stored.

## When To Recall

Recall memory before:

- starting or resuming a project
- changing architecture, storage, security, privacy, or release behavior
- repeating a workflow where prior failures may matter
- responding to a user correction
- making a decision that depends on previous preferences or constraints
- editing files in a repo that has a Tree Ring Memory or `AGENTS.md` contract
- closing out meaningful work and deciding what should be remembered

Use narrow queries with project scope when possible. Prefer source-linked, high-confidence, non-superseded results.

## When To Remember

Store a memory when the information is likely to help future work:

- the user states a durable preference
- the user corrects the agent

From TerminallyLazy/Tree-Ring-Memory, MIT.