Update to Tree Ring Memory

{
  "description": "Guides AI agents in using Tree Ring Memory for durable recall, project decisions, user preferences, warnings, future seeds, privacy-safe memory capture, and lifecycle-aware forgetting.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 238
    }
  ],
  "name": "tree-ring-memory",
  "skill_md_contents": "---\nname: tree-ring-memory\ndescription: Guides AI agents in using Tree Ring Memory for durable recall, project decisions, user preferences, warnings, future seeds, privacy-safe memory capture, and lifecycle-aware forgetting.\nlicense: MIT\n---\n\n# Tree Ring Memory\n\nUse Tree Ring Memory as a lifecycle-aware memory layer, not as a transcript dump.\n\nTree Ring Memory preserves meaningful agent learning like tree rings:\n\n- fresh work stays detailed\n- older learning compresses into stable rings\n- important warnings remain visible as scars\n- durable truths become heartwood\n- speculative future work stays as seeds\n- sensitive data is blocked, redacted, or kept out by default\n\n## Runtime Bootstrap And Updates\n\nResolve the actual project root before running Tree Ring. Never initialize a\nplugin cache, downloaded package directory, home directory, or arbitrary\nworking directory by accident.\n\n1. If `<project-root>/.tree-ring/bin/tree-ring` exists, prefer that binary for\n   this project. Otherwise check `command -v tree-ring` and run\n   `tree-ring --version`.\n2. Read existing `<project-root>/.tree-ring/SKILL.md` and `CLI.md` when present.\n   Lifecycle hooks need CLI 0.15.6 or newer; older packages may omit\n   automatic hooks. Current Codex packages include them, including the public upload. Use `integrations status --verbose` to inspect the last\n   recall count and query class, and distinguish no receipt from zero results.\n3. This package targets Tree Ring Memory CLI 0.15.0 or newer. If no compatible\n   CLI is available and the user's request already authorizes Tree Ring setup,\n   install the verified current release project-locally from the project root.\n   Otherwise explain the exact operation and obtain permission before the\n   network download or software installation. Download the official,\n   version-pinned `v0.15.0/install.sh` installer to a temporary file, verify its\n   SHA-256 is\n   `ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade`,\n   inspect it, and only then run:\n\n   ```bash\n   cd <project-root>\n   sh <verified-installer-path> --project --init --release latest --no-animation\n   ```\n\n   Do not pipe a network response directly to a shell. The installer verifies\n   the selected release archive against its published SHA-256 before placing\n   the binary at `<project-root>/.tree-ring/bin/tree-ring`.\n\n4. For an existing global CLI, initialize from the project root with\n   `tree-ring --root .tree-ring init`. For a project-local CLI, use\n   `.tree-ring/bin/tree-ring --root .tree-ring init`. This must place\n   `memory.sqlite`, `AGENTS.md`, `SKILL.md`, and `CLI.md` under that project's\n   `.tree-ring/` directory.\n5. Verify the created paths and run the same binary with\n   `--root .tree-ring integrations status`. Initialization creates safe local\n   guidance and bridge material; it is not receipt-backed activation proof.\n\nCheck for releases without changing files with `tree-ring update --check`. Run\n`tree-ring update` only when the user has authorized an update. It updates the\nactive binary in its existing project-local, direct, or Homebrew-managed scope,\nverifies official release assets, and must not create a second shadowing binary.\nAfter an update, return to each project root and rerun `tree-ring --root\n.tree-ring init` (or the project-local equivalent) to backfill managed guidance\nwithout replacing custom files.\n\nCLIs older than 0.15.0 do not have `tree-ring update`. Upgrade those with the\nsame manager or prefix that installed them: `brew upgrade tree-ring` for\nHomebrew, `--project --release latest` for an existing project-local install,\nor `--install-dir <existing-prefix> --release latest` for another direct\ninstall. Check `command -v tree-ring` and `which -a tree-ring` afterward. Do not\nedit a shell profile or change global installation scope without separate user\nauthorization.\n\nIf the current host cannot execute a local shell or access project files, use\nthis skill only as memory-lifecycle guidance. Do not claim that recall, capture,\naudit, activation, or forgetting occurred unless the corresponding command ran\nand its result was observed.\n\n## Agent Operating Loop\n\nUse this sequence for meaningful project work:\n\n1. Resolve the project root and read its local Tree Ring contract when present.\n2. Run the runtime preflight, then recall narrowly scoped, source-linked memory\n   before making a material decision or repeating a failure-prone workflow.\n3. Treat recalled memory as context, not authority. Recheck facts that may have\n   changed and defer to current source files, tests, policies, and user input.\n4. Do the work. Do not write memory merely because a session is active.\n5. At a natural checkpoint or closeout, capture only durable decisions,\n   corrections, validated lessons, warnings, preferences, or future seeds.\n   Never store raw transcripts, secrets, or sensitive data. Repository\n   lifecycle integrations enforce one agent-mediated checkpoint at `Stop` or\n   `SubagentStop`; they do not derive memory from hook payloads.\n6. Observe the command result and report the actual outcome. A proposed memory,\n   dry run, bridge file, or generated marker is not proof that a durable write,\n   sync, activation, correction, or deletion occurred.\n\nIn a Coordinated store, do not attempt persistent writes without the required\ncoordinator capability. If the capability is unavailable, provide a concise\ncandidate memory for an authorized coordinator instead of claiming it was\nstored.\n\n## When To Recall\n\nRecall memory before:\n\n- starting or resuming a project\n- changing architecture, storage, security, privacy, or release behavior\n- repeating a workflow where prior failures may matter\n- responding to a user correction\n- making a decision that depends on previous preferences or constraints\n- editing files in a repo that has a Tree Ring Memory or `AGENTS.md` contract\n- closing out meaningful work and deciding what should be remembered\n\nUse narrow queries with project scope when possible. Prefer source-linked, high-confidence, non-superseded results.\n\n## When To Remember\n\nStore a memory when the information is likely to help future work:\n\n- the user states a durable preference\n- the user corrects the agent\n- a decision is made and should survive the current session\n- an implementation lesson is validated by tests or production behavior\n- a failed approach should not be repeated\n- a security, privacy, release, or data-loss warning appears\n- a useful project convention is discovered\n- a future idea should be revisited later\n\nKeep memory concise. Store the lesson, decision, or warning, not the full conversation.\n\nUse `tree-ring evidence` instead of plain `remember` when the lesson comes from\nan evaluation, checkpoint, experiment, branch, incident, or reviewed run\nartifact.\n\nUse source adapters when project artifacts already contain structured guidance\nor evaluated outcomes:\n\n```bash\ntree-ring dox sync --source-root . --dry-run\ntree-ring revolve sync --source-root revolve --dry-run\ntree-ring integrations scan --source-root .\n```\n\nRun adapter commands with `--dry-run` first. Sync only concise, source-linked\nsummaries; never treat imported memory as more authoritative than the source\n`AGENTS.md`, Revolve record, evaluation, PR, issue, or test artifact.\nIn a Coordinated store, persisting an adapter result requires the coordinator\ncapability; dry-run discovery does not.\n\nUse the exact CLI commands exposed by the local install:\n\n```bash\ntree-ring --help\ntree-ring dox sync --help\ntree-ring revolve sync --help\ntree-ring evidence --help\n```\n\nIf the project was initialized with a project-local binary, prefer the generated\n`.tree-ring/CLI.md` reference and include `--root .tree-ring` when needed.\n\nIf this skill was loaded through a harness-native bridge file, treat that bridge\nas a pointer only. Read the project-local `.tree-ring/SKILL.md` and\n`.tree-ring/CLI.md` when present so commands match the installed project root.\nDo not assume a global Tree Ring setup applies to the current repo unless the\nuser explicitly configured it.\n\n## DOX Contract Flow\n\nWhen a project uses DOX-style `AGENTS.md` contracts:\n\n1. Read the applicable contract chain from the project root down to the working\n   directory before editing files. More specific child contracts may refine the\n   parent contract.\n2. Treat those current source files as authoritative. A recalled DOX summary is\n   only a navigation and continuity aid; it never overrides the live contract.\n3. Preview the adapter output first with\n   `tree-ring dox sync --source-root <path> --dry-run` and inspect every summary\n   and source reference.\n4. Before persisting, verify the selected CLI is 0.15.11 or newer using\n   `--version`; older runtimes are preview-only for DOX. After an authorized\n   upgrade, rerun and review the preview. Persist only concise, useful summaries.\n   In a Coordinated store, persistence requires coordinator authority; dry-run\n   discovery does not.\n5. Never use the adapter to rewrite a root or child `AGENTS.md`, copy whole\n   contract trees into memory, or weaken child instructions. Re-run the dry run\n   after a source contract changes and re-read the chain before the next edit.\n\n## DOX Persistence Compatibility\n\nDOX persistence requires Tree Ring CLI 0.15.11 or newer. Check the selected\nproject-local or PATH binary with `--version` before any DOX write. Older\nruntimes may preview with `--dry-run`, but must not persist DOX summaries.\nUpgrade through the existing installation scope when authorized, then rerun\nand review the preview with the updated binary. This minimum applies only to\nDOX persistence: 0.15.11 adds source-root collision checks that reject the\nentire conflicting batch instead of overwriting another project's guidance.\n\n## Harness Activation\n\nFor a new project, begin with the safe, project-local default:\n\n```bash\ntree-ring init\ntree-ring integrations status\n```\n\nDo not ask the user to copy a bridge or run `integrations link` for ordinary\nsetup. `init` configures only safe project-local adapter material by creating\nabsent final bridge and manifest paths. It never replaces or removes an existing\nentry, including during deactivation; contested entries stay untouched and\nreport `needs-user-review`. A bridge, marker, generated skill, or successful\n`init` is not activation proof: `active` requires a fresh, matching receipt from\na new session's scoped recall and safe context injection.\nTreat `configured-awaiting-proof`, `active-isolated`, `needs-trust`,\n`needs-project-mount`, `needs-plugin`, `needs-user-review`, `unsupported`,\nand `failed` as their exact non-active outcomes. Never say Hermes or another\nunverified runtime is active.\n\nIf publication durability becomes indeterminate, do not delete or rewrite the\npublished path. Preserve disk material, keep changed harnesses marked\n`needs-user-review` in the returned in-memory manifest, and leave any activation\nmanifest already published on disk intact for explicit reconciliation.\n\nPi trust is the user's decision: report `needs-trust` rather than changing\nglobal trust. Agent Zero is separate: `tree-ring init` writes only Tree Ring's\npassive Agent Zero binding with `needs-plugin`. The user installs/enables the\ncompatible `tree_ring_memory` plugin and selects the mounted project; the plugin\nthen owns its absolute, non-project `activation-capability.json` descriptor and\npasses it internally. Only descriptor-scoped plugin status can derive\n`configured-awaiting-proof`, and only its new-session preflight receipt can\nmake the runtime `active`.\n\nNever create a generic marker, copy or hand-author that descriptor, set its\ninternal transport, modify Agent Zero core, or call a different plugin store\nshared. A missing, invalid, disabled, or release-incompatible descriptor stays\n`needs-plugin`; a different reachable store is `active-isolated`; an\nunavailable root is `needs-project-mount`. A passive binding, source checkout,\nor stale bundled CLI is not installed capability.\n\nReceipts prove a privacy-safe preflight check, not durable memory creation or a\nsecurity boundary. They exclude raw prompts, recalled content, secrets,\nsensitive values, paths, and coordinator capabilities. Shared-store claims are\nlimited to same-host local-filesystem processes whose receipts match the\ncanonical project `store_id`; they do not apply across hosts or network\nfilesystems. For diagnostics use `tree-ring integrations status --verbose`;\nfor advanced controlled work use `integrations activate --harness <id>\n--dry-run`, `integrations certify`, or `integrations deactivate --harness\n<id>`.\n\n## Certification Boundary\n\nFor an installed Tree Ring runtime, use the self-contained CLI evidence paths:\n\n```bash\ntree-ring integrations certify --source-root .\ntree-ring recall-quality --source-root .\n```\n\nHarness certification is non-mutating and writes JSON/Markdown evidence under\n`target/tree-ring-certification/`; it does not activate a harness or prove that\nan agent used recalled context. Keep receipt-backed status as a separate gate.\n\n`sh scripts/certify-tree-ring.sh` is the full framework release suite. Run it\nonly from a canonical Tree Ring Memory source checkout where that file, the Rust\nworkspace, `install.sh`, fixtures, and build tooling are all present. Do not\ncopy it into another project, download it automatically, or claim full release\ncertification from the smaller installed-CLI checks. In the TUI, `/evidence\nrefresh` only displays this external source-checkout command; it does not run\ncertification. If the script is absent, report that boundary and use the\nself-contained CLI commands above when they fit the user's request.\n\nEvidence outcome mapping:\n\n- `promoted`: durable heartwood from supported evidence\n- `rejected`: scar for reusable failed or rolled-back approaches\n- `deferred`: seed for promising unresolved options\n- `observed`: outer-ring evaluation result\n\n## Memory Quality Gates\n\nUse these gates before relying on or writing memory.\n\nRecall gates:\n\n- Before substantial project work, recall project constraints, scars, user preferences, and unresolved seeds.\n- Before risky changes, recall warnings and evidence-linked prior failures.\n- Before repeating a workflow, recall prior errors and accepted procedures.\n- Before closeout, recall recent decisions so memory updates do not contradict already-stored lessons.\n\nTrust gates:\n\n- Prefer source-linked, non-superseded, high-confidence memories.\n- Treat heartwood as durable only when source evidence or user confirmation supports it.\n- Re-read source files, tests, explicit user instructions, DOX contracts, or Revolve evidence when memory conflicts with current sources.\n- Do not treat sensitive or hidden-by-default memory as ordinary recall context.\n\nWrite gates:\n\n- Remember only durable decisions, validated lessons, reusable warnings, corrections, future seeds, and evidence-backed outcomes.\n- Reject transient planning chatter, duplicate wording, tool noise, and unsupported claims.\n- Require evidence refs for promoted or rejected evaluated outcomes.\n- Require user confirmation before creating or promoting broad cross-project heartwood.\n\n## Ring Selection\n\nUse these rings:\n\n- `cambium`: active or recent task context\n- `outer`: recent decisions and task lessons\n- `inner`: older compressed project knowledge\n- `heartwood`: durable, high-confidence truths and user preferences\n- `scar`: important negative memory, failures, regressions, rejected approaches, and warnings\n- `seed`: unresolved ideas, hypotheses, follow-ups, and future work\n\nDo not promote to `heartwood` from weak evidence. Prefer `outer` or `seed` unless the user confirms durability or the evidence is strong.\n\n## Event Types\n\nPrefer specific event types:\n\n- `user_preference`\n- `decision`\n- `lesson`\n- `warning`\n- `correction`\n- `file_change`\n- `tool_result`\n- `summary`\n- `hypothesis`\n\nIf a host integration has stricter event type names, use the closest local equivalent.\n\n## What Not To Store\n\nDo not store:\n\n- secrets\n- credentials\n- tokens\n- private keys\n- raw chain-of-thought\n- temporary scratchpad notes\n- unverified claims as durable truth\n- private health, financial, legal, or personal identifier details without explicit user instruction\n- copyrighted source text beyond short allowed snippets\n\nIf a useful memory contains sensitive material, store a redacted summary with enough context to be useful.\n\n## Source And Scope\n\nSet project and scope deliberately:\n\n- use project scope for repo-specific rules, decisions, warnings, and lessons\n- use agent scope for agent-partitioned behavior and always set `agent_profile`\n- use workflow scope for one coordinated fan-out/fan-in and always set `workflow_id`\n- use session scope for one execution attempt and always set `session_id`\n- use global scope only for durable user preferences or cross-project guidance\n- include source references such as file paths, issue ids, PR ids, run ids, or docs paths\n- use `tree-ring evidence ... --evidence-ref <ref>` for evaluated outcomes\n- use `tree-ring dox sync` for concise `AGENTS.md` summaries\n- use `tree-ring revolve sync` for promoted, rejected, deferred, or observed evaluation records\n- use `tree-ring integrations scan` before configuring a new agent harness\n\nMemory does not replace source documents. If a repo has `AGENTS.md`, project docs, tests, architectural records, or host-specific instruction files, read those sources directly and treat them as authoritative.\n\nWhen DOX or Revolve source records change, re-run the matching sync adapter with\n`--dry-run`, inspect the generated memories, then run the write command only\nwhen the summaries are useful and source-linked.\n\n## Multi-Agent Coordination\n\nFor workers sharing one local Tree Ring root, give every write explicit\ncoordination metadata:\n\n```bash\ntree-ring --root .tree-ring remember \"Worker validated the storage boundary.\" \\\n  --event-type lesson \\\n  --scope agent \\\n  --project example-service \\\n  --agent-profile worker-storage \\\n  --workflow-id release-readiness \\\n  --session-id attempt-1 \\\n  --operation-id validate-storage-v1 \\\n  --source-ref runs/release-readiness/worker-storage.json\n```\n\nUse a unique `agent_profile` per worker, one shared `workflow_id` for the\nfan-out/fan-in, one `session_id` for each genuine execution attempt, and a stable\nunique `operation_id` for each logical write. An exact retry reuses both the\noriginal session ID and operation ID; changing only the session is a conflicting\nreuse. Start a new session and use new operation IDs only for a genuinely new\nattempt. Exact retries with the same operation metadata and payload return the\noriginal memory. Reusing that operation key for a different payload fails\nclosed. Replacing a stored memory keeps its old operation namespace claimed.\nRedaction also tombstones the memory ID; only an explicit hard delete releases\nthose claims.\n\nAt fan-in, recall the shared workflow and session without an agent-profile\nfilter, inspect the source refs, then write a source-linked workflow or project\nsummary:\n\n```bash\ntree-ring --root .tree-ring recall \"release readiness\" \\\n  --project example-service \\\n  --workflow-id release-readiness \\\n  --session-id attempt-1 \\\n  --scope agent\n```\n\n`TREE_RING_AGENT_PROFILE`, `TREE_RING_WORKFLOW_ID`, and\n`TREE_RING_SESSION_ID` provide the same defaults as their CLI flags. Do not\nleave an agent-profile environment filter set when the coordinator intends to\nrecall every worker.\n\nThis shared-root pattern is for concurrent processes on one host using a local\nfilesystem. It is not a distributed lock service and does not claim safe\ncross-host or NFS operation. Scope and identity fields remain routing metadata,\nnot a read ACL; a same-user coordinator can recall across profiles. Use\nper-host stores plus an explicit, evidence-preserving fan-in process when work\nspans hosts.\n\n## Coordinated Write Policy\n\nStores default to backward-compatible Open mode. For a shared root where only a\ndesignated coordinator should publish or mutate shared memory, enable the\noptional Coordinated policy:\n\n```bash\ntree-ring --root .tree-ring policy enable --coordinator release-coordinator\n# Set and export TREE_RING_COORDINATOR_TOKEN with a history-safe, no-echo prompt\n# supported by your shell, or inject it through an approved secret manager.\ntree-ring --root .tree-ring policy status\ntree-ring --root .tree-ring policy audit --limit 100\n```\n\nEnable prints the capability once. Put it only in\n`TREE_RING_COORDINATOR_TOKEN`; never pass it as a CLI flag or place it in a\nmemory, log, source ref, transcript, or committed file. Tree Ring stores only a\nhash. `policy status` and `policy audit` are read-only and do not reveal the\ncapability. Do not paste it into an `export` command; use a history-safe,\nno-echo prompt supported by the current shell or approved secret-manager\ninjection. Inject it only into coordinator processes, and launch every ordinary\nworker with `TREE_RING_COORDINATOR_TOKEN` unset so fan-out does not inherit\ncoordinator authority.\n\nIn Coordinated mode, an ordinary worker may only create non-heartwood\n`scope=agent` memory whose `agent_profile` matches its write context. Supply the\nsame identity with `--agent-profile <worker>` or\n`TREE_RING_AGENT_PROFILE=<worker>`. A coordinator capability is required for:\n\n- project, global, workflow, session, or other shared/non-agent writes\n- heartwood creation or promotion\n- JSONL import and persisted DOX/Revolve sync\n- persisted consolidation\n- ring changes and supersede/delete/redact lifecycle operations\n- maintenance with apply or repair flags\n\nRecall, export, policy status/audit, adapter dry-runs, consolidation dry-runs,\nand report-only maintenance remain read-only. In the TUI, start with\n`--agent-profile <worker>` (or `TREE_RING_AGENT_PROFILE`) so `/remember`\ndefaults to agent scope. TUI promote/scar/seed, supersede, forget/redact, and\npersisted consolidation actions require `TREE_RING_COORDINATOR_TOKEN`.\n\nRotate the capability while the current one is exported, then immediately\nreplace the environment value with the newly printed capability:\n\n```bash\ntree-ring --root .tree-ring policy rotate --coordinator release-coordinator-next\n# Replace TREE_RING_COORDINATOR_TOKEN through the same history-safe, no-echo\n# input path before using the new capability.\ntree-ring --root .tree-ring policy disable\nunset TREE_RING_COORDINATOR_TOKEN\n```\n\nRotation invalidates the old capability. Disabling returns the store to Open\nmode and also requires the current capability.\n\nThis is operational write authorization enforced by official Rust/CLI store\npaths. It is not a read ACL, an operating-system security boundary, or\nprotection from an adversary who controls the local database files or process\nenvironment.\n\nBefore opening an existing store with v0.13/schema v3, stop every Tree Ring\nprocess, checkpoint and back up the database, and upgrade every CLI, plugin, and\nbundled worker. Do not reopen the upgraded root with v0.12: schema v3 fences\nmemory inserts, updates, and deletes from old writers, and all mixed-version\noperation is unsupported. Roll back only by stopping all processes and\nrestoring the pre-upgrade backup.\n\n## Agent-Mediated Updates\n\nTree Ring Memory does not autonomously scrape chats or write durable memory in\nthe background. The active agent is responsible for deciding when a Tree Ring\ncommand is warranted, then calling the CLI deliberately.\n\nRepository lifecycle integrations register exactly `SessionStart`,\n`SubagentStart`, `Stop`, and `SubagentStop`. Start events perform bounded recall.\nEach stop event enforces one synchronous, agent-mediated memory checkpoint. The\nhook parser uses stable harness identity and project fields only; it never\ninspects or persists `transcript_path`, `last_assistant_message`, prompts, or\ntranscript content. It does not register a prompt, tool, or `SessionEnd` hook.\n\nAt the checkpoint, evaluate the grounded work already in your context. If there\nare no durable candidates, finish without a memory write. For up to three\nconcise candidates that are durable, source-grounded, and normal sensitivity,\nautomatically run the exact strict `tree-ring capture` command template supplied\nby the lifecycle handler. Do not edit its project, agent, workflow, session,\ncheckpoint, operation, or source identity fields. Strict capture fixes\n`scope=agent`, adds the automatic-capture tag, and rejects sensitive content.\nNever substitute `remember`, `evidence`, an import, or a transcript summary for\nthat checkpoint command.\n\nUse bridge files only to discover Tree Ring and its command reference:\n\n- project-level bridges should point to `.tree-ring/SKILL.md` and\n  `.tree-ring/CLI.md`\n- global bridges should be treated as opt-in user configuration\n- TUI event-stream pulses are display signals, not durable memories\n\nBefore writing memory, verify the lesson is durable, useful, privacy-safe, and\ngrounded in user instruction or source evidence.\n\n## Forgetting And Correction\n\nIf memory is wrong, private, stale, or superseded:\n\n- redact it when the durable shape is useful but details are unsafe\n- delete it when it should not be retained\n- supersede it when a newer decision replaces it\n- prefer explicit reasons for every forget operation\n\nIn Coordinated mode these lifecycle writes require the coordinator capability.\n\nTreat redaction as monotonic. Do not try to restore a redacted ID through\nreplacement import; create a new reviewed memory only if the user deliberately\nreintroduces safe content.\n\nNever keep known-wrong memory merely because it was previously recalled.\n\n## Closeout Habit\n\nAt the end of meaningful work, or when a stop hook requests the single\nagent-mediated checkpoint, ask:\n\n- What did we decide?\n- What did we learn?\n- What should future agents avoid repeating?\n- Did the user state a durable preference?\n- Is there a future seed worth revisiting?\n- Is any memory sensitive and better left unstored?\n\nOnly remember the answers that will materially improve future work and pass the\nnormal-sensitivity gate. During a lifecycle checkpoint, use only the supplied\nstrict `tree-ring capture` template.\n"
}