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.
3. If no 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:

```bash
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 binary
that shadows the active one. After an update, return to each project root and
run `tree-ring --root .tree-ring init` (or the project-local equivalent) to
backfill managed agent 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 so an
older shadowing binary is not mistaken for the updated runtime. Do not edit a
shell profile or change global installation scope without separate user
authorization.

## 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
- a decision is made and should survive the current session
- an implementation lesson is validated by tests or production behavior
- a failed approach should not be repeated
- a security, privacy, release, or data-loss warning appears
- a useful project convention is discovered
- a future idea should be revisited later

Keep memory concise. Store the lesson, decision, or warning, not the full conversation.

Use `tree-ring evidence` instead of plain `remember` when the lesson comes from
an evaluation, checkpoint, experiment, branch, incident, or reviewed run
artifact.

Use source adapters when project artifacts already contain structured guidance
or evaluated outcomes:

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

Run adapter commands with `--dry-run` first. Sync only concise, source-linked
summaries; never treat imported memory as more authoritative than the source
`AGENTS.md`, Revolve record, evaluation, PR, issue, or test artifact.
In a Coordinated store, persisting an adapter result requires the coordinator
capability; dry-run discovery does not.

From TerminallyLazy/Tree-Ring-Memory, MIT.

More from TerminallyLazy/Tree-Ring-Memory