Tree Ring Memory is a local-first memory lifecycle practice for Claude Code agents.
This plugin packages one Claude Code skill plus a few explicit slash commands that teach agents when to recall, write, audit, consolidate, and forget project memory using the open-source Tree Ring Memory CLI.
The plugin registers native startup recall and bounded stop checkpoints.
Automatic lifecycle hooks require CLI 0.15.6 or newer. It does not run a
background service, scrape chats, capture transcripts, or ship a networked MCP
server. The active agent evaluates durable outcomes before any capture.
- Recall before context-dependent project work.
- Concise memory writes for validated decisions, lessons, warnings, and user preferences.
- Evidence-backed outcomes through
tree-ring evidence. - Explicit forgetting, redaction, and supersession guidance.
- DOX and Revolve adapter usage with dry-run-first guardrails.
- Same-host multi-agent identity, idempotency, filtered fan-in, and optional coordinator write-policy guidance.
- Receipt-backed harness readiness that distinguishes configured bridges from observed use in a fresh Claude Code session.
- Verified project-local CLI bootstrap and scope-preserving update guidance.
From the actual project root, after the user has authorized Tree Ring setup:
Download the official version-pinned v0.15.0/install.sh to a temporary file,
verify its SHA-256 is
ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade, inspect
it, then run these commands from the project root:
sh <verified-installer-path> --project --init --release latest --no-animation
.tree-ring/bin/tree-ring --root .tree-ring integrations status --verboseDo not pipe a network response directly to a shell.
The plugin requires Tree Ring Memory v0.15.0 or newer:
tree-ring --version
tree-ring integrations status --helpBefore a current binary upgrades a pre-v0.13 store to schema v3, stop every Tree Ring process, checkpoint and back up the complete store, and upgrade every CLI, plugin, and bundled worker. Do not use a v0.12 writer against schema v3; all mixed-version operation is unsupported.
If the CLI is missing or older, the plugin may bootstrap or update it when the
user's request already authorizes Tree Ring setup. Otherwise it explains the
exact operation and asks before downloading or changing software. Use
tree-ring update --check for a read-only release check and, with update
authorization, tree-ring update to preserve the active install scope. It does
not edit shell configuration, change global scope, or claim that a memory
action ran without the required authorization and observed command output.
For other install paths, use the canonical project README: https://github.com/TerminallyLazy/Tree-Ring-Memory#install
Add this repository as a Claude Code plugin marketplace:
/plugin marketplace add TerminallyLazy/tree-ring-memory-claude-plugin
/plugin install tree-ring-memory@tree-ring-memory
After installation, Claude Code can use:
/tree-ring-memory:tree-ring-memory
/tree-ring-memory:tree-ring-recall
/tree-ring-memory:tree-ring-capture
/tree-ring-memory:tree-ring-audit
/tree-ring-memory:tree-ring-status
/tree-ring-memory:tree-ring-dox-sync
/tree-ring-memory:tree-ring-certify
/tree-ring-memory:tree-ring-update
Ask Claude Code:
Use Tree Ring Memory to recall durable project context before editing.
Use Tree Ring Memory to capture this validated lesson without storing a transcript.
Use Tree Ring Memory to audit stale or sensitive memory before closeout.
Preview DOX contract summaries and sync only concise, source-linked guidance.
Generate harness certification evidence without claiming full release certification.
The skill looks for project-local .tree-ring/SKILL.md and .tree-ring/CLI.md
first. If they are absent, it falls back to the public CLI commands documented
in the main framework repository.
For DOX projects, the plugin reads the applicable AGENTS.md chain before
edits and keeps those live contracts authoritative. /tree-ring-memory:tree-ring-dox-sync
previews the local adapter output before any persistence and never rewrites the
source contracts.
Before any DOX write, verify the selected project-local or PATH binary with
--version and require CLI 0.15.11 or newer. Older compatible runtimes may
preview with --dry-run, but must not persist DOX summaries. After an authorized
upgrade, rerun and review the preview. This DOX-only minimum adds atomic
source-root collision checks so a conflicting batch cannot overwrite another
project's guidance; general CLI and lifecycle-hook compatibility is unchanged.
/tree-ring-memory:tree-ring-certify uses the installed CLI for harness or
recall-quality evidence. The larger scripts/certify-tree-ring.sh suite remains
exclusive to a complete Tree Ring framework source checkout; it is not bundled
with this plugin.
For a new project, start with:
tree-ring init
tree-ring integrations statusConfiguration is not activation proof. A harness is active only after a
fresh, matching receipt shows scoped recall and safe context injection from a
new session. States such as configured-awaiting-proof, needs-trust,
needs-plugin, needs-project-mount, needs-user-review, and unsupported
remain explicitly non-active. The /tree-ring-memory:tree-ring-status command
reports the exact state without modifying trust, bridges, or receipts.
For fan-out/fan-in, the supported shared-root boundary is cooperative Tree Ring processes on one host and a local filesystem. Identity and scope route memory; they are not read access-control boundaries. Cross-host and network-filesystem workflows need per-host stores plus explicit, source-preserving fan-in.
- Framework repo: https://github.com/TerminallyLazy/Tree-Ring-Memory
- Launch page: https://terminallylazy.github.io/Tree-Ring-Memory/
- Homebrew tap: https://github.com/TerminallyLazy/homebrew-tree-ring
- v0.15 release: https://github.com/TerminallyLazy/Tree-Ring-Memory/releases/tag/v0.15.11
This plugin ships instructions only. It does not include remote MCP servers, webhooks, analytics, credentials, or networked runtime code.
Coordinated mode uses a one-time capability only through
TREE_RING_COORDINATOR_TOKEN. Keep it out of prompts, command arguments,
memory, logs, source references, and ordinary worker environments.
See PRIVACY.md, TERMS.md, and SECURITY.md for data handling, use terms, and disclosures.
The repository plugin registers exactly SessionStart, SubagentStart,
Stop, and SubagentStop. Each hook forwards its event JSON directly to the
local CLI and waits synchronously for at most 10 seconds. It does not register
prompt, tool, compaction, or SessionEnd hooks; run a background service;
scrape chats; or ship an MCP server.
Session start covers startup, resume, and compaction rehydration when the host reports those sources. Subagent start gives each worker an independent, receipt-backed preflight. Codex requires review and trust of the installed hook definition before it runs. Claude Code loads the hook with the enabled plugin.
Startup recall loads a bounded brief of shared project guidance and this agent's durable memories, including captures from earlier sessions. Workflow and session memories remain limited to their matching scope. It does not depend on memories containing special startup keywords. Use targeted recall when the task changes; the startup brief is not an exhaustive search.
Stop and subagent-stop enforce one agent-mediated memory checkpoint. The
lifecycle parser uses only stable harness identity and project fields; it never
inspects or persists transcript_path, last_assistant_message, prompts, or
transcript content. The checkpoint asks the active agent to evaluate its
already-grounded work. If and only if that evaluation yields a concise,
durable, normal-sensitivity candidate, the agent automatically runs the exact
strict tree-ring capture command template returned by the lifecycle handler.
Strict capture fixes agent scope, requires identity and provenance, adds an
automatic-capture tag, and rejects sensitive candidates. No candidate means no
memory write. This is one bounded checkpoint, not a recorder or automatic
summary of every turn.
The hook wrapper resolves the Git project root when available, prefers that
project's .tree-ring/bin/tree-ring, and otherwise uses tree-ring from
PATH. It then invokes the shared lifecycle entry point with the project-local
.tree-ring root. A project or linked worktree with no local .tree-ring entry
is skipped quietly without creating memory or using the primary checkout's
store. Existing roots, including dangling symlinks and roots with missing or
invalid activation metadata, still reach runtime diagnostics. An unavailable
or incompatible CLI is not active-harness proof and cannot be reported as a
successful checkpoint or capture.
When the host's effective project hook contains the managed lifecycle definition, that definition owns recall and stop checkpoints. The marketplace wrapper detects the exact managed marker and exits without invoking the CLI, preventing duplicate context, receipts, checkpoint continuations, or capture attempts.
For Codex's root .codex layer in a validated linked worktree, the wrapper
checks the corresponding primary-checkout .codex/hooks.json exclusively;
Codex ignores the worktree-local hook file in that case. The worktree must have
its own .codex directory for that layer to exist. Git metadata must prove the
reciprocal worktree and primary ownership; uncertain layouts dispatch normally.
This deduplication covers the root layer generated by Tree Ring, not custom
nested hook layers. Claude continues to check the local .claude/settings.json;
the wrapper does not assume that every Claude worktree inherits primary hooks.
Hook source selection never changes the current worktree's memory root.
integrations status --verbose reports the last validated recall's result
count and query class. A zero-result receipt proves the check ran; it does not
prove that useful context was found. Older skills-only packages omitted
automatic lifecycle hooks. Current Git and public upload packages include them. A newly configured Codex hook still needs
the host's trust flow and a new session before automatic execution can be
verified.
Installer onboarding requires CLI 0.15.7 or newer to create the activation
manifest and native project hooks in the same install action. On earlier 0.15
CLIs, run tree-ring init explicitly after the installer. Onboarding readiness
is configuration; a fresh host receipt is required to prove automatic recall.