diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 4627c61..6a16835 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "tree-ring-memory", - "version": "0.2.0", - "description": "Lifecycle-aware local and same-host multi-agent memory guidance for Codex using Tree Ring Memory v0.13+.", + "version": "0.3.0", + "description": "Local-first memory lifecycle and receipt-backed harness guidance for coding agents using Tree Ring Memory v0.14+.", "author": { "name": "TerminallyLazy", "url": "https://github.com/TerminallyLazy" @@ -14,6 +14,7 @@ "memory", "agent-memory", "multi-agent", + "harness-activation", "idempotency", "local-first", "recall", @@ -24,7 +25,7 @@ "interface": { "displayName": "Tree Ring Memory", "shortDescription": "Local-first memory lifecycle guidance for Codex agents.", - "longDescription": "Tree Ring Memory gives Codex a lifecycle-aware memory practice for project recall, durable decisions, same-host fan-out/fan-in, idempotent worker writes, coordinator-authorized shared publication, explicit forgetting, and privacy-safe memory capture using Tree Ring Memory v0.13 or newer.", + "longDescription": "Tree Ring Memory gives coding agents a lifecycle-aware practice for project recall, durable decisions, receipt-backed harness readiness, same-host fan-out/fan-in, idempotent worker writes, coordinator-authorized shared publication, explicit forgetting, and privacy-safe memory capture using Tree Ring Memory v0.14 or newer.", "developerName": "TerminallyLazy", "category": "Developer Tools", "capabilities": [ @@ -32,18 +33,21 @@ "Write", "Interactive" ], - "websiteURL": "https://github.com/TerminallyLazy/Tree-Ring-Memory", - "privacyPolicyURL": "https://github.com/TerminallyLazy/tree-ring-memory-codex-plugin/blob/main/SECURITY.md", - "termsOfServiceURL": "https://github.com/TerminallyLazy/tree-ring-memory-codex-plugin/blob/main/LICENSE", + "websiteURL": "https://terminallylazy.github.io/Tree-Ring-Memory/", + "privacyPolicyURL": "https://github.com/TerminallyLazy/tree-ring-memory-codex-plugin/blob/main/PRIVACY.md", + "termsOfServiceURL": "https://github.com/TerminallyLazy/tree-ring-memory-codex-plugin/blob/main/TERMS.md", "defaultPrompt": [ - "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.", - "Use Tree Ring Memory v0.13 coordinated policy for this same-host fan-out and fan-in." + "Recall durable project context before changing release behavior.", + "Capture this validated lesson without storing a transcript.", + "Check Tree Ring harness readiness and explain any non-active state." ], "brandColor": "#2F7D5C", - "composerIcon": "./assets/icon.svg", - "logo": "./assets/icon.svg", - "screenshots": [] + "composerIcon": "./assets/tree-ring-memory-logo.png", + "logo": "./assets/tree-ring-memory-logo.png", + "screenshots": [ + "./assets/screenshot-dashboard.png", + "./assets/screenshot-recall.png", + "./assets/screenshot-evidence.png" + ] } } diff --git a/.github/workflows/hol-plugin-scanner.yml b/.github/workflows/hol-plugin-scanner.yml index 6ab9dff..5912c39 100644 --- a/.github/workflows/hol-plugin-scanner.yml +++ b/.github/workflows/hol-plugin-scanner.yml @@ -16,7 +16,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 - - name: Validate v0.13 wrapper contract + - name: Validate v0.14 wrapper contract run: sh scripts/validate-plugin.sh - name: HOL Plugin Scanner uses: hashgraph-online/ai-plugin-scanner-action@d38d84308e670972f6534739dbc193b2c2dcc163 diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..afc1fbc --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,63 @@ +name: Validate + +on: + pull_request: + push: + branches: + - main + +permissions: + contents: read + +env: + TREE_RING_VERSION: "0.14.0" + TREE_RING_LINUX_X86_64_SHA256: "c72191aca81f195472272a1962df354fe0af04a08b01a7472a1faf987cd177fa" + +jobs: + validate: + runs-on: ubuntu-24.04 + steps: + - uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1 + + - name: Install checksum-pinned Tree Ring v0.14 + shell: bash + run: | + set -euo pipefail + archive_name="tree-ring-memory-${TREE_RING_VERSION}-linux-x86_64.tar.gz" + archive_path="${RUNNER_TEMP}/${archive_name}" + release_url="https://github.com/TerminallyLazy/Tree-Ring-Memory/releases/download/v${TREE_RING_VERSION}/${archive_name}" + extract_root="${RUNNER_TEMP}/tree-ring-${TREE_RING_VERSION}" + + curl \ + --proto '=https' \ + --tlsv1.2 \ + --fail \ + --location \ + --silent \ + --show-error \ + --output "${archive_path}" \ + "${release_url}" + printf '%s %s\n' \ + "${TREE_RING_LINUX_X86_64_SHA256}" \ + "${archive_path}" \ + | sha256sum --check --status + + while IFS= read -r entry; do + case "${entry}" in + /*|../*|*/../*|*/..) exit 1 ;; + esac + done < <(tar -tzf "${archive_path}") + + mkdir -p "${extract_root}" + tar -xzf "${archive_path}" -C "${extract_root}" + binary_path="${extract_root}/tree-ring-memory-${TREE_RING_VERSION}-linux-x86_64/tree-ring" + test -x "${binary_path}" + test "$("${binary_path}" --version)" = "tree-ring ${TREE_RING_VERSION}" + printf 'TREE_RING_BIN=%s\n' "${binary_path}" >> "${GITHUB_ENV}" + + - name: Validate plugin package + run: sh scripts/validate-plugin.sh + + - name: Smoke Tree Ring v0.14 integration + shell: bash + run: bash scripts/smoke_v014.sh diff --git a/PRIVACY.md b/PRIVACY.md new file mode 100644 index 0000000..5e67fbe --- /dev/null +++ b/PRIVACY.md @@ -0,0 +1,24 @@ +# Tree Ring Memory Plugin Privacy Notice + +Effective August 23, 2026 + +The Tree Ring Memory plugin is an instruction package for AI coding agents. It +does not operate a hosted service, create a user account, collect analytics, +send telemetry, or include a remote MCP server. + +When an agent runs the separately installed Tree Ring Memory CLI, the CLI stores +the memory content the user chooses in a local SQLite database under the +configured Tree Ring root. The project does not receive that database or its +contents. Data leaves the local environment only when the user or another tool +explicitly exports, syncs, publishes, or otherwise transmits it. + +The plugin instructs agents to avoid transcripts, credentials, secrets, private +keys, raw chain-of-thought, and unnecessary sensitive personal data. It also +provides explicit redaction, deletion, supersession, audit, and consolidation +workflows. These safeguards do not replace the privacy and data-use terms of the +AI host, operating system, source-control provider, or any other tool the user +chooses to invoke. + +Support and privacy questions may be filed at +. +Do not include secrets or private memory content in a public issue. diff --git a/README.md b/README.md index 61abac0..1de2bf1 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,9 @@ This plugin packages one Codex skill that teaches agents when to recall, write, audit, consolidate, and forget project memory using the open-source [Tree Ring Memory](https://github.com/TerminallyLazy/Tree-Ring-Memory) CLI. -Plugin `0.2.0` requires Tree Ring Memory CLI **>= 0.13.0**. The minimum is -intentional: v0.13 adds schema v3, coordinated-write authorization, and the -writer-protocol fence used by this guidance. +Plugin `0.3.0` requires Tree Ring Memory CLI **>= 0.14.0**. The minimum is +intentional: v0.14 adds receipt-backed harness readiness on top of the v0.13 +schema-v3, coordinated-write, and idempotency contracts used by this guidance. It does not run a background service, scrape chats, or capture transcripts. The active agent chooses when a memory action is useful, source-linked, and @@ -23,6 +23,8 @@ privacy-safe. - Same-host worker identity, scoped fan-out/fan-in, and idempotent retries. - Optional coordinator-authorized shared publication and protected lifecycle writes. +- Receipt-backed harness readiness that distinguishes configured bridges from + observed use in a fresh agent session. - Explicit forgetting, redaction, and supersession guidance. - DOX and Revolve adapter usage with dry-run-first guardrails. @@ -44,7 +46,11 @@ Verify the installed core before using this wrapper: tree-ring --version ``` -The result must be `tree-ring 0.13.0` or newer. +The result must be `tree-ring 0.14.0` or newer. + +If the CLI is absent or older, the plugin reports the limitation. It does not +install or upgrade software, edit shell configuration, or claim a memory action +ran without explicit user permission and observed command output. ## Use @@ -54,12 +60,42 @@ After installing this plugin in Codex, ask: 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. +Use Tree Ring Memory to preview DOX contract summaries before syncing them. ``` The skill will look for project-local `.tree-ring/SKILL.md` and `.tree-ring/CLI.md` files first. If they are absent, it falls back to the public CLI commands documented in the main framework repository. +For DOX projects, it reads the applicable `AGENTS.md` chain before edits and +keeps the live contracts authoritative. DOX sync is dry-run-first, persists only +concise source-linked summaries, and never rewrites the source contracts. + +For installed-runtime evidence, use `tree-ring integrations certify` or +`tree-ring recall-quality`. The full `scripts/certify-tree-ring.sh` release suite +requires a complete Tree Ring framework source checkout and is intentionally not +bundled in this plugin. + +On a host without local shell and project-file access, the skill remains useful +as memory-lifecycle guidance but cannot perform Tree Ring recall, capture, +audit, activation, or forgetting. + +## Receipt-Backed Harness Readiness + +For a new project, start with: + +```bash +tree-ring init +tree-ring integrations status +``` + +Configuration 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. Use `tree-ring integrations status --verbose` +for diagnosis; do not manufacture bridge files or receipts. + ## Same-Host Multi-Agent Contract Tree Ring supports concurrent workers sharing one root only when they run on @@ -115,14 +151,14 @@ maintenance with apply or repair flags. Recall, export, policy status/audit, adapter and consolidation dry-runs, and report-only maintenance remain read-only. -## v0.13 Schema-v3 Upgrade Fence +## Schema-v3 Upgrade Fence -Before opening an existing store with v0.13: +Before opening a pre-v0.13 store with a current release: 1. Stop every Tree Ring CLI, TUI, plugin, and bundled worker using the root. 2. Checkpoint SQLite WAL state and make a verified backup. 3. Upgrade every CLI, plugin, and bundled worker. -4. Reopen with v0.13 to migrate the store to schema v3. +4. Reopen with the current release to migrate the store to schema v3. Do not reopen the upgraded root with v0.12. Schema v3 fences old memory inserts, updates, and deletes, and all mixed-version operation is unsupported. @@ -132,7 +168,8 @@ backup. ## Canonical Project - Framework repo: -- Canonical v0.13 skill: +- Canonical v0.14 skill: +- v0.14 release: - Launch page: - Homebrew tap: @@ -141,4 +178,5 @@ backup. This plugin ships instructions only. It does not include remote MCP servers, webhooks, analytics, credentials, or networked runtime code. -See [SECURITY.md](SECURITY.md) for disclosure and privacy guidance. +See [PRIVACY.md](PRIVACY.md), [TERMS.md](TERMS.md), and +[SECURITY.md](SECURITY.md) for data handling, use terms, and disclosures. diff --git a/SUBMISSION.md b/SUBMISSION.md new file mode 100644 index 0000000..2e3c640 --- /dev/null +++ b/SUBMISSION.md @@ -0,0 +1,93 @@ +# OpenAI Plugin Submission Dossier + +## Listing + +- Name: Tree Ring Memory +- Type: Skills only +- Category: Developer Tools +- Short description: Local-first memory lifecycle guidance for coding agents. +- Website: +- Support: +- Privacy: +- Terms: +- Source: + +Long description: + +> Tree Ring Memory gives coding agents a lifecycle-aware practice for project +> recall, durable decisions, receipt-backed harness readiness, same-host +> fan-out/fan-in, idempotent worker writes, coordinator-authorized shared +> publication, explicit forgetting, and privacy-safe memory capture using the +> open-source Tree Ring Memory 0.14 CLI. + +## Starter Prompts + +1. Recall durable project context before changing release behavior. +2. Capture this validated lesson without storing a transcript. +3. Check Tree Ring harness readiness and explain any non-active state. + +## Positive Review Cases + +1. Prompt: "Recall what we decided about release behavior in this project." + Expected behavior: check the local runtime and project guidance, run scoped + recall, and summarize source-linked results. Expected shape: concise memories + with confidence or source context. Fixture: an initialized v0.14 store with a + project-scoped release decision. +2. Prompt: "Remember that the signed archive must be inspected before release." + Expected behavior: confirm the lesson is durable and privacy-safe, then create + one concise source-linked memory. Expected shape: the observed CLI result and + stored memory identifier. Fixture: an initialized writable v0.14 store. +3. Prompt: "Audit this store for stale or sensitive memory without changing it." + Expected behavior: use report-only audit and maintenance commands. Expected + shape: grouped findings and recommended follow-up, with no mutation claim. + Fixture: an initialized store with synthetic stale and sensitive candidates. +4. Prompt: "Fan in the storage and release workers from attempt 2." + Expected behavior: recall the shared workflow and session without an + agent-profile filter, inspect source references, and avoid a shared write + unless coordinator authority is present. Expected shape: one attributed + synthesis. Fixture: two agent-scoped memories sharing workflow and session. +5. Prompt: "Is Tree Ring active for this Codex project?" + Expected behavior: run verbose integration status and report its exact state; + configuration alone must not be called active. Expected shape: harness name, + state, capability, and next step. Fixture: a configured v0.14 project without + a fresh matching receipt. +6. Prompt: "Preview the DOX contracts in this repository before syncing them." + Expected behavior: read the applicable `AGENTS.md` chain, run DOX sync in + dry-run mode, and treat live contracts as authoritative. Expected shape: + concise proposed summaries with source references and no write claim. + Fixture: nested synthetic `AGENTS.md` contracts with a child refinement. +7. Prompt: "Certify this project's Tree Ring harnesses." + Expected behavior: run the installed CLI harness certification, report the + observed evidence, and keep activation status as a separate receipt-backed + gate. Expected shape: pass/fail/skip counts and evidence paths, without a + full framework release-certification claim. Fixture: a project with synthetic + harness markers and no Tree Ring source checkout. + +## Negative Review Cases + +1. Scenario: the host has no local shell or `tree-ring` executable. Expected + fallback: explain the limitation, provide installation guidance, and do not + fabricate recall or install software without permission. +2. Prompt: "Remember this private API credential." Expected refusal: do not + request, store, or repeat the secret; offer a redacted warning that it needs + rotation. Reason: credentials and secrets are excluded from memory. +3. Prompt: "Forget the bad memory." Expected clarification: ask for the exact + memory identifier and whether redaction or deletion is intended. Reason: + ambiguous destructive lifecycle actions must not run. + +## Release Notes + +Initial OpenAI submission of the v0.14-compatible skills-only package. It adds +runtime preflight, receipt-backed harness readiness, exact non-active states, +same-host coordination rules, and explicit privacy-safe fallback when local +execution is unavailable. The plugin has no MCP server, hosted service, +credentials, telemetry, or reviewer account requirement. + +## Review Note + +The core workflow invokes a separately installed local CLI and reads project +files when the host supports those capabilities. On hosts without them, the +skill remains guidance-only and explicitly forbids claims that a command ran. +OpenAI's Claude-plugin migration guide asks local-execution plugins to contact +their OpenAI partner; disclose this boundary in the submission rather than +representing the package as a hosted integration. diff --git a/TERMS.md b/TERMS.md new file mode 100644 index 0000000..63add90 --- /dev/null +++ b/TERMS.md @@ -0,0 +1,20 @@ +# Tree Ring Memory Plugin Terms of Use + +Effective August 23, 2026 + +The Tree Ring Memory plugin is open-source software distributed under the MIT +License. By using it, you agree to the license and these operational terms. + +The plugin provides agent instructions only. It is not a hosted memory service, +backup service, access-control system, medical or legal record system, or +guarantee that an AI host will follow every instruction. The user is responsible +for choosing what to store, maintaining backups, controlling local filesystem +access, reviewing agent actions, and complying with applicable policies and +law. + +Tree Ring Memory is provided without warranty, including warranties of fitness, +availability, accuracy, non-infringement, or data durability, to the maximum +extent permitted by law. The limitations in the included MIT License apply. + +Questions may be filed at +. diff --git a/assets/screenshot-dashboard.png b/assets/screenshot-dashboard.png new file mode 100644 index 0000000..500a907 Binary files /dev/null and b/assets/screenshot-dashboard.png differ diff --git a/assets/screenshot-evidence.png b/assets/screenshot-evidence.png new file mode 100644 index 0000000..9863f34 Binary files /dev/null and b/assets/screenshot-evidence.png differ diff --git a/assets/screenshot-recall.png b/assets/screenshot-recall.png new file mode 100644 index 0000000..52da30e Binary files /dev/null and b/assets/screenshot-recall.png differ diff --git a/assets/tree-ring-memory-logo.png b/assets/tree-ring-memory-logo.png new file mode 100644 index 0000000..530360c Binary files /dev/null and b/assets/tree-ring-memory-logo.png differ diff --git a/scripts/smoke_v014.sh b/scripts/smoke_v014.sh new file mode 100755 index 0000000..8b711ac --- /dev/null +++ b/scripts/smoke_v014.sh @@ -0,0 +1,258 @@ +#!/usr/bin/env bash +set -euo pipefail + +tree_ring_bin="${TREE_RING_BIN:-tree-ring}" +if [[ "${tree_ring_bin}" == */* ]]; then + test -x "${tree_ring_bin}" +else + command -v "${tree_ring_bin}" >/dev/null +fi +test "$("${tree_ring_bin}" --version)" = "tree-ring 0.14.0" + +smoke_base="${RUNNER_TEMP:-${TMPDIR:-/tmp}}" +smoke_base="${smoke_base%/}" +smoke_dir=$(mktemp -d "${smoke_base}/tree-ring-codex-smoke.XXXXXX") +case "${smoke_dir}" in + "${smoke_base}"/tree-ring-codex-smoke.*) ;; + *) exit 91 ;; +esac + +cleanup() { + find "${smoke_dir}" -depth -delete +} +trap cleanup EXIT + +# A fresh project may be configured, but cannot be active without a matching +# new-session preflight receipt. +harness_project="${smoke_dir}/harness-project" +mkdir -p "${harness_project}" +( + cd "${harness_project}" + "${tree_ring_bin}" --root .tree-ring --json init \ + > "${smoke_dir}/harness-init.json" + "${tree_ring_bin}" --root .tree-ring integrations status --json --verbose \ + > "${smoke_dir}/harness-status.json" +) +TREE_RING_HARNESS_STATUS="${smoke_dir}/harness-status.json" python3 - <<'PY' +import json +import os + +with open(os.environ["TREE_RING_HARNESS_STATUS"], encoding="utf-8") as stream: + status = json.load(stream) +integrations = status.get("integrations") +if not isinstance(integrations, list) or not integrations: + raise SystemExit("expected integration status entries") +if any(item.get("state") == "active" for item in integrations): + raise SystemExit("fresh configuration must not report active without a receipt") +PY + +hash_file() { + local file_path=$1 + if command -v sha256sum >/dev/null; then + sha256sum "${file_path}" | awk '{print $1}' + else + shasum -a 256 "${file_path}" | awk '{print $1}' + fi +} + +snapshot_tree() { + local root_path=$1 + find "${root_path}" -type f | LC_ALL=C sort | while IFS= read -r file_path; do + printf '%s %s\n' \ + "$(hash_file "${file_path}")" \ + "${file_path#"${root_path}"/}" + done +} + +# Policy inspection must not initialize a missing root. +missing_root="${smoke_dir}/missing-store" +if "${tree_ring_bin}" --root "${missing_root}" policy status >/dev/null 2>&1; then + exit 92 +fi +if "${tree_ring_bin}" --root "${missing_root}" policy audit --limit 100 \ + >/dev/null 2>&1; then + exit 93 +fi +test ! -e "${missing_root}" + +# Policy inspection must not migrate or add sidecars to a legacy schema-v2 DB. +legacy_root="${smoke_dir}/legacy-v2" +legacy_db="${legacy_root}/memory.sqlite3" +mkdir -p "${legacy_root}" +TREE_RING_SMOKE_LEGACY_DB="${legacy_db}" python3 - <<'PY' +import os +import sqlite3 + +database = os.environ["TREE_RING_SMOKE_LEGACY_DB"] +connection = sqlite3.connect(database) +connection.execute("CREATE TABLE sentinel (value TEXT NOT NULL)") +connection.execute("INSERT INTO sentinel(value) VALUES ('unchanged')") +connection.execute("PRAGMA user_version = 2") +connection.commit() +connection.close() +PY +snapshot_tree "${legacy_root}" > "${smoke_dir}/legacy-before.sha256" +"${tree_ring_bin}" --root "${legacy_root}" policy status >/dev/null 2>&1 || true +"${tree_ring_bin}" --root "${legacy_root}" policy audit --limit 100 \ + >/dev/null 2>&1 || true +snapshot_tree "${legacy_root}" > "${smoke_dir}/legacy-after.sha256" +cmp "${smoke_dir}/legacy-before.sha256" "${smoke_dir}/legacy-after.sha256" + +# Exercise the documented same-host Coordinated-mode workflow. +store_root="${smoke_dir}/coordinated-project/.tree-ring" +"${tree_ring_bin}" --root "${store_root}" init >/dev/null +grant_json=$( + "${tree_ring_bin}" \ + --root "${store_root}" \ + --json \ + policy enable \ + --coordinator smoke-coordinator +) +coordinator_capability=$( + python3 -c \ + 'import json, sys; print(json.load(sys.stdin)["capability"])' \ + <<<"${grant_json}" +) +test "${#coordinator_capability}" -gt 20 + +worker_env=( + env + -u TREE_RING_COORDINATOR_TOKEN + TREE_RING_AGENT_PROFILE=worker-storage + TREE_RING_WORKFLOW_ID=release-smoke + TREE_RING_SESSION_ID=attempt-1 +) +first_write=$( + "${worker_env[@]}" "${tree_ring_bin}" \ + --root "${store_root}" \ + --json \ + remember "Storage validation completed." \ + --event-type lesson \ + --scope agent \ + --operation-id validate-storage-v1 \ + --source-ref runs/release-smoke/worker-storage.json +) +retry_write=$( + "${worker_env[@]}" "${tree_ring_bin}" \ + --root "${store_root}" \ + --json \ + remember "Storage validation completed." \ + --event-type lesson \ + --scope agent \ + --operation-id validate-storage-v1 \ + --source-ref runs/release-smoke/worker-storage.json +) +first_id=$( + python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])' \ + <<<"${first_write}" +) +retry_id=$( + python3 -c 'import json, sys; print(json.load(sys.stdin)["id"])' \ + <<<"${retry_write}" +) +test "${first_id}" = "${retry_id}" + +if "${worker_env[@]}" "${tree_ring_bin}" \ + --root "${store_root}" \ + remember "Conflicting retry." \ + --event-type lesson \ + --scope agent \ + --operation-id validate-storage-v1 \ + --source-ref runs/release-smoke/worker-storage.json \ + >/dev/null 2>&1; then + exit 94 +fi +if "${worker_env[@]}" "${tree_ring_bin}" \ + --root "${store_root}" \ + remember "Unauthorized shared result." \ + --event-type lesson \ + --scope project \ + --operation-id worker-shared-v1 \ + --source-ref runs/release-smoke/worker-shared.json \ + >/dev/null 2>&1; then + exit 95 +fi + +fan_in=$( + env \ + -u TREE_RING_AGENT_PROFILE \ + -u TREE_RING_COORDINATOR_TOKEN \ + TREE_RING_WORKFLOW_ID=release-smoke \ + TREE_RING_SESSION_ID=attempt-1 \ + "${tree_ring_bin}" \ + --root "${store_root}" \ + --json \ + recall "storage validation" \ + --scope agent +) +python3 -c \ + 'import json, sys +value = json.load(sys.stdin) +results = value if isinstance(value, list) else value["results"] +raise SystemExit(0 if len(results) == 1 else 1)' \ + <<<"${fan_in}" + +printf '%s' "${coordinator_capability}" | \ + TREE_RING_TEST_BINARY="${tree_ring_bin}" \ + TREE_RING_TEST_ROOT="${store_root}" \ + python3 -c ' +import os +import subprocess +import sys + +environment = os.environ.copy() +environment["TREE_RING_COORDINATOR" + "_TOKEN"] = sys.stdin.read() +environment["TREE_RING_AGENT_PROFILE"] = "coordinator" +environment["TREE_RING_WORKFLOW_ID"] = "release-smoke" +environment["TREE_RING_SESSION_ID"] = "attempt-1" +subprocess.run( + [ + environment["TREE_RING_TEST_BINARY"], + "--root", + environment["TREE_RING_TEST_ROOT"], + "remember", + "Coordinator-approved shared result.", + "--event-type", + "lesson", + "--scope", + "project", + "--operation-id", + "coordinator-shared-v1", + "--source-ref", + "runs/release-smoke/coordinator.json", + ], + check=True, + env=environment, + stdout=subprocess.DEVNULL, +) +' + +status_output=$( + "${tree_ring_bin}" --root "${store_root}" policy status +) +audit_output=$( + "${tree_ring_bin}" --root "${store_root}" policy audit --limit 100 +) +if [[ "${status_output}${audit_output}" == *"${coordinator_capability}"* ]]; then + exit 96 +fi +if grep -R -a -F -- "${coordinator_capability}" "${store_root}" >/dev/null; then + exit 97 +fi + +# Inspection on an upgraded store must leave every tracked store byte unchanged. +snapshot_tree "${store_root}" > "${smoke_dir}/upgraded-before.sha256" +"${tree_ring_bin}" --root "${store_root}" policy status >/dev/null +"${tree_ring_bin}" --root "${store_root}" policy audit --limit 100 >/dev/null +"${tree_ring_bin}" --root "${store_root}" audit --audit-type sensitive >/dev/null +"${tree_ring_bin}" \ + --root "${store_root}" \ + consolidate \ + --period-type manual \ + --dry-run \ + >/dev/null +"${tree_ring_bin}" --root "${store_root}" maintain >/dev/null +snapshot_tree "${store_root}" > "${smoke_dir}/upgraded-after.sha256" +cmp "${smoke_dir}/upgraded-before.sha256" "${smoke_dir}/upgraded-after.sha256" + +printf 'Tree Ring v0.14 integration smoke passed\n' diff --git a/scripts/validate-plugin.sh b/scripts/validate-plugin.sh index 5e56933..e6a1bf1 100755 --- a/scripts/validate-plugin.sh +++ b/scripts/validate-plugin.sh @@ -10,22 +10,68 @@ python3 -m json.tool "$PLUGIN" >/dev/null assert_contains() { file=$1 expected=$2 - grep -F -- "$expected" "$file" >/dev/null || { - printf 'missing required contract in %s: %s\n' "$file" "$expected" >&2 - exit 1 - } + python3 - "$file" "$expected" <<'PY' +import sys +from pathlib import Path + +path = Path(sys.argv[1]) +expected = " ".join(sys.argv[2].split()) +actual = " ".join(path.read_text(encoding="utf-8").split()) +if expected not in actual: + raise SystemExit(f"missing required contract in {path}: {sys.argv[2]}") +PY } -assert_contains "$PLUGIN" '"version": "0.2.0"' -assert_contains "$README" 'CLI **>= 0.13.0**' -assert_contains "$SKILL" 'version: 0.13.0' +python3 - <<'PY' +import json +from pathlib import Path + +root = Path(".") +manifest = json.loads((root / ".codex-plugin/plugin.json").read_text()) +if manifest.get("name") != "tree-ring-memory": + raise SystemExit("plugin name must remain tree-ring-memory") +if manifest.get("version") != "0.3.0": + raise SystemExit("wrapper version must be 0.3.0") + +interface = manifest.get("interface", {}) +prompts = interface.get("defaultPrompt", []) +if not 1 <= len(prompts) <= 3: + raise SystemExit("defaultPrompt must contain one to three prompts") +if any(len(prompt) > 128 for prompt in prompts): + raise SystemExit("defaultPrompt entries must be at most 128 characters") + +for key in ("composerIcon", "logo"): + path = interface.get(key) + if not path or not (root / path).is_file(): + raise SystemExit(f"missing interface asset: {key}") + +screenshots = interface.get("screenshots", []) +if len(screenshots) != 3 or any(not (root / path).is_file() for path in screenshots): + raise SystemExit("three real screenshots are required") + +for required in ("PRIVACY.md", "TERMS.md", "SUBMISSION.md"): + if not (root / required).is_file(): + raise SystemExit(f"missing publication material: {required}") +PY + +assert_contains "$README" 'CLI **>= 0.14.0**' +assert_contains "$README" 'Receipt-Backed Harness Readiness' +assert_contains "$SKILL" 'version: 0.14.0' +assert_contains "$SKILL" 'Runtime Preflight' +assert_contains "$SKILL" 'DOX Contract Flow' +assert_contains "$SKILL" 'tree-ring dox sync --source-root --dry-run' +assert_contains "$SKILL" 'Certification Boundary' +assert_contains "$SKILL" 'tree-ring integrations certify --source-root .' +assert_contains "$SKILL" 'tree-ring recall-quality --source-root .' +assert_contains "$SKILL" 'full framework release suite' +assert_contains "$SKILL" 'tree-ring integrations status' +assert_contains "$SKILL" 'configured-awaiting-proof' assert_contains "$SKILL" '--operation-id' assert_contains "$SKILL" 'TREE_RING_COORDINATOR_TOKEN' -assert_contains "$SKILL" 'one host using a local' -assert_contains "$SKILL" 'does not claim safe' -assert_contains "$SKILL" 'schema-v3 upgrade' -assert_contains "$SKILL" 'mixed-version operation is unsupported' +assert_contains "$SKILL" 'same-host local-filesystem processes' +assert_contains "$SKILL" 'schema v3 fences' +assert_contains "$SKILL" 'operation is unsupported' assert_contains "$SKILL" 'maintenance with apply or repair flags' -assert_contains "$SKILL" 'ordinary worker with `TREE_RING_COORDINATOR_TOKEN` unset' +assert_contains "$SKILL" 'launch every ordinary worker with `TREE_RING_COORDINATOR_TOKEN` unset' printf 'Tree Ring Memory Codex wrapper contract is valid.\n' diff --git a/skills/tree-ring-memory/SKILL.md b/skills/tree-ring-memory/SKILL.md index ea0fa91..f12d071 100644 --- a/skills/tree-ring-memory/SKILL.md +++ b/skills/tree-ring-memory/SKILL.md @@ -1,25 +1,28 @@ --- name: tree-ring-memory -description: Use when Codex needs local-first recall, durable project decisions, same-host multi-agent coordination, privacy-safe memory capture, evidence records, audit, consolidation, or explicit forgetting through Tree Ring Memory v0.13+. -version: 0.13.0 -tags: ["memory", "agents", "recall", "privacy", "projects", "multi-agent", "idempotency", "coordinator-policy", "cli"] +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. +version: 0.14.0 +license: MIT +tags: ["memory", "agents", "recall", "privacy", "projects", "dox", "revolve", "skills", "cli"] triggers: - "remember this" - "recall what we decided" + - "what did we learn" - "tree ring memory" - - "multi-agent memory" - - "fan-in memory" - - "coordinator policy" - - "upgrade tree ring" + - "consolidate memory" - "forget this" + - "project memory" + - "sync DOX" + - "sync Revolve" + - "evidence loop" + - "multi-agent memory" --- # Tree Ring Memory -Use Tree Ring Memory as a lifecycle-aware memory layer, not as a transcript -dump. +Use Tree Ring Memory as a lifecycle-aware memory layer, not as a transcript dump. -Tree Ring Memory preserves meaningful agent learning: +Tree Ring Memory preserves meaningful agent learning like tree rings: - fresh work stays detailed - older learning compresses into stable rings @@ -28,88 +31,209 @@ Tree Ring Memory preserves meaningful agent learning: - speculative future work stays as seeds - sensitive data is blocked, redacted, or kept out by default -## First Check +## Runtime Preflight -If the current project contains Tree Ring files, read them before using global -assumptions: +Before running a Tree Ring command: -```bash -.tree-ring/SKILL.md -.tree-ring/CLI.md -``` +1. Read project-local `.tree-ring/SKILL.md` and `.tree-ring/CLI.md` when they + exist. They describe the configured root and exact installed commands. +2. Confirm that the local runtime is available: -If the CLI is not installed, use the canonical project install guide: - + ```bash + tree-ring --version + ``` -This wrapper requires Tree Ring Memory CLI >= 0.13.0. Check before using a -shared store or v0.13 policy commands: +3. This package targets Tree Ring Memory CLI 0.14.0 or newer. If the command is + missing or older, do not invent results, edit shell configuration, or install + or upgrade software without the user's explicit permission. Explain the + limitation and point to the canonical install guide: + -```bash -tree-ring --version -``` +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. -On macOS ARM64: +## Agent Operating Loop -```bash -brew tap TerminallyLazy/tree-ring -brew install tree-ring -``` +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, or future seeds. Never store raw + transcripts, secrets, or sensitive data. +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 before: +Recall memory before: - starting or resuming a project - changing architecture, storage, security, privacy, or release behavior -- opening or upgrading a memory root shared by multiple workers -- coordinating same-host fan-out/fan-in or retrying a worker write - repeating a workflow where prior failures may matter - responding to a user correction - making a decision that depends on previous preferences or constraints -- closing meaningful work and deciding what should be remembered +- 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. - -```bash -tree-ring recall "release behavior" --project example-service -``` +Use narrow queries with project scope when possible. Prefer source-linked, high-confidence, non-superseded results. ## When To Remember -Store a memory only when the information is likely to help future work: +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 -- a lesson is validated by tests, review, or production behavior +- 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, warning, or evidence summary, -not the full conversation. +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 remember "Use project-scoped recall before changing release behavior." \ - --event-type lesson \ - --scope project \ - --project example-service \ - --tag release \ - --tag workflow +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. + +Use the exact CLI commands exposed by the local install: + +```bash +tree-ring --help +tree-ring dox sync --help +tree-ring revolve sync --help +tree-ring evidence --help +``` + +If the project was initialized with a project-local binary, prefer the generated +`.tree-ring/CLI.md` reference and include `--root .tree-ring` when needed. + +If this skill was loaded through a harness-native bridge file, treat that bridge +as a pointer only. Read the project-local `.tree-ring/SKILL.md` and +`.tree-ring/CLI.md` when present so commands match the installed project root. +Do not assume a global Tree Ring setup applies to the current repo unless the +user explicitly configured it. + +## DOX Contract Flow + +When a project uses DOX-style `AGENTS.md` contracts: + +1. Read the applicable contract chain from the project root down to the working + directory before editing files. More specific child contracts may refine the + parent contract. +2. Treat those current source files as authoritative. A recalled DOX summary is + only a navigation and continuity aid; it never overrides the live contract. +3. Preview the adapter output first with + `tree-ring dox sync --source-root --dry-run` and inspect every summary + and source reference. +4. Persist only concise, useful summaries. In a Coordinated store, persistence + requires coordinator authority; dry-run discovery does not. +5. Never use the adapter to rewrite a root or child `AGENTS.md`, copy whole + contract trees into memory, or weaken child instructions. Re-run the dry run + after a source contract changes and re-read the chain before the next edit. + +## Harness Activation + +For a new project, begin with the safe, project-local default: + +```bash +tree-ring init +tree-ring integrations status ``` -Use `tree-ring evidence` when the lesson comes from an evaluation, checkpoint, -experiment, branch, incident, or reviewed run artifact. +Do not ask the user to copy a bridge or run `integrations link` for ordinary +setup. `init` configures only safe project-local adapter material by creating +absent final bridge and manifest paths. It never replaces or removes an existing +entry, including during deactivation; contested entries stay untouched and +report `needs-user-review`. A bridge, marker, generated skill, or successful +`init` is not activation proof: `active` requires a fresh, matching receipt from +a new session's scoped recall and safe context injection. +Treat `configured-awaiting-proof`, `active-isolated`, `needs-trust`, +`needs-project-mount`, `needs-plugin`, `needs-user-review`, `unsupported`, +and `failed` as their exact non-active outcomes. Never say Hermes or another +unverified runtime is active. + +If publication durability becomes indeterminate, do not delete or rewrite the +published path. Preserve disk material, keep changed harnesses marked +`needs-user-review` in the returned in-memory manifest, and leave any activation +manifest already published on disk intact for explicit reconciliation. + +Pi trust is the user's decision: report `needs-trust` rather than changing +global trust. Agent Zero is separate: `tree-ring init` writes only Tree Ring's +passive Agent Zero binding with `needs-plugin`. The user installs/enables the +compatible `tree_ring_memory` plugin and selects the mounted project; the plugin +then owns its absolute, non-project `activation-capability.json` descriptor and +passes it internally. Only descriptor-scoped plugin status can derive +`configured-awaiting-proof`, and only its new-session preflight receipt can +make the runtime `active`. + +Never create a generic marker, copy or hand-author that descriptor, set its +internal transport, modify Agent Zero core, or call a different plugin store +shared. A missing, invalid, disabled, or release-incompatible descriptor stays +`needs-plugin`; a different reachable store is `active-isolated`; an +unavailable root is `needs-project-mount`. A passive binding, source checkout, +or stale bundled CLI is not installed capability. + +Receipts prove a privacy-safe preflight check, not durable memory creation or a +security boundary. They exclude raw prompts, recalled content, secrets, +sensitive values, paths, and coordinator capabilities. Shared-store claims are +limited to same-host local-filesystem processes whose receipts match the +canonical project `store_id`; they do not apply across hosts or network +filesystems. For diagnostics use `tree-ring integrations status --verbose`; +for advanced controlled work use `integrations activate --harness +--dry-run`, `integrations certify`, or `integrations deactivate --harness +`. + +## Certification Boundary + +For an installed Tree Ring runtime, use the self-contained CLI evidence paths: ```bash -tree-ring evidence "Migration smoke test passed with project-local memory." \ - --outcome promoted \ - --evidence-ref "runs/migration-smoke-001" \ - --score 0.91 +tree-ring integrations certify --source-root . +tree-ring recall-quality --source-root . ``` +Harness certification is non-mutating and writes JSON/Markdown evidence under +`target/tree-ring-certification/`; it does not activate a harness or prove that +an agent used recalled context. Keep receipt-backed status as a separate gate. + +`sh scripts/certify-tree-ring.sh` is the full framework release suite. Run it +only from a canonical Tree Ring Memory source checkout where that file, the Rust +workspace, `install.sh`, fixtures, and build tooling are all present. Do not +copy it into another project, download it automatically, or claim full release +certification from the smaller installed-CLI checks. In the TUI, `/evidence +refresh` only displays this external source-checkout command; it does not run +certification. If the script is absent, report that boundary and use the +self-contained CLI commands above when they fit the user's request. + Evidence outcome mapping: - `promoted`: durable heartwood from supported evidence @@ -117,19 +241,96 @@ Evidence outcome mapping: - `deferred`: seed for promising unresolved options - `observed`: outer-ring evaluation result +## Memory Quality Gates + +Use these gates before relying on or writing memory. + +Recall gates: + +- Before substantial project work, recall project constraints, scars, user preferences, and unresolved seeds. +- Before risky changes, recall warnings and evidence-linked prior failures. +- Before repeating a workflow, recall prior errors and accepted procedures. +- Before closeout, recall recent decisions so memory updates do not contradict already-stored lessons. + +Trust gates: + +- Prefer source-linked, non-superseded, high-confidence memories. +- Treat heartwood as durable only when source evidence or user confirmation supports it. +- Re-read source files, tests, explicit user instructions, DOX contracts, or Revolve evidence when memory conflicts with current sources. +- Do not treat sensitive or hidden-by-default memory as ordinary recall context. + +Write gates: + +- Remember only durable decisions, validated lessons, reusable warnings, corrections, future seeds, and evidence-backed outcomes. +- Reject transient planning chatter, duplicate wording, tool noise, and unsupported claims. +- Require evidence refs for promoted or rejected evaluated outcomes. +- Require user confirmation before creating or promoting broad cross-project heartwood. + +## Ring Selection + +Use these rings: + +- `cambium`: active or recent task context +- `outer`: recent decisions and task lessons +- `inner`: older compressed project knowledge +- `heartwood`: durable, high-confidence truths and user preferences +- `scar`: important negative memory, failures, regressions, rejected approaches, and warnings +- `seed`: unresolved ideas, hypotheses, follow-ups, and future work + +Do not promote to `heartwood` from weak evidence. Prefer `outer` or `seed` unless the user confirms durability or the evidence is strong. + +## Event Types + +Prefer specific event types: + +- `user_preference` +- `decision` +- `lesson` +- `warning` +- `correction` +- `file_change` +- `tool_result` +- `summary` +- `hypothesis` + +If a host integration has stricter event type names, use the closest local equivalent. + +## What Not To Store + +Do not store: + +- secrets +- credentials +- tokens +- private keys +- raw chain-of-thought +- temporary scratchpad notes +- unverified claims as durable truth +- private health, financial, legal, or personal identifier details without explicit user instruction +- copyrighted source text beyond short allowed snippets + +If a useful memory contains sensitive material, store a redacted summary with enough context to be useful. + ## Source And Scope Set project and scope deliberately: -- use project scope for repo-specific shared rules and reviewed conclusions -- use agent scope for worker-partitioned memory and always set `agent_profile` -- use workflow scope for shared fan-out/fan-in state and always set `workflow_id` +- use project scope for repo-specific rules, decisions, warnings, and lessons +- use agent scope for agent-partitioned behavior and always set `agent_profile` +- use workflow scope for one coordinated fan-out/fan-in and always set `workflow_id` - use session scope for one execution attempt and always set `session_id` -- use global scope only for durable cross-project guidance -- include a source reference for worker results and coordinator summaries +- use global scope only for durable user preferences or cross-project guidance +- include source references such as file paths, issue ids, PR ids, run ids, or docs paths +- use `tree-ring evidence ... --evidence-ref ` for evaluated outcomes +- use `tree-ring dox sync` for concise `AGENTS.md` summaries +- use `tree-ring revolve sync` for promoted, rejected, deferred, or observed evaluation records +- use `tree-ring integrations scan` before configuring a new agent harness + +Memory 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. -Scope and identity fields are routing partitions, not a read ACL. A same-user -coordinator with filesystem access can recall across worker profiles. +When DOX or Revolve source records change, re-run the matching sync adapter with +`--dry-run`, inspect the generated memories, then run the write command only +when the summaries are useful and source-linked. ## Multi-Agent Coordination @@ -149,40 +350,45 @@ tree-ring --root .tree-ring remember "Worker validated the storage boundary." \ ``` Use a unique `agent_profile` per worker, one shared `workflow_id` for the -fan-out/fan-in, one `session_id` for each genuine execution attempt, and a -stable unique `operation_id` for each logical write. An exact retry reuses both -the original session ID and operation ID with the same metadata and payload. -Changing only the session or content under the same operation key is a -conflicting reuse and fails closed. New attempts use a new session and new -operation IDs. Replaced operation namespaces and redacted memory IDs remain -claimed until explicit hard deletion. - -At fan-in, omit the agent-profile filter so the coordinator sees every worker, -inspect each source reference, then publish an explicit source-linked workflow -or project summary: +fan-out/fan-in, one `session_id` for each genuine execution attempt, and a stable +unique `operation_id` for each logical write. An exact retry reuses both the +original session ID and operation ID; changing only the session is a conflicting +reuse. Start a new session and use new operation IDs only for a genuinely new +attempt. Exact retries with the same operation metadata and payload return the +original memory. Reusing that operation key for a different payload fails +closed. Replacing a stored memory keeps its old operation namespace claimed. +Redaction also tombstones the memory ID; only an explicit hard delete releases +those claims. + +At fan-in, recall the shared workflow and session without an agent-profile +filter, inspect the source refs, then write a source-linked workflow or project +summary: ```bash -tree-ring --root .tree-ring --json recall "release readiness" \ +tree-ring --root .tree-ring recall "release readiness" \ --project example-service \ --workflow-id release-readiness \ --session-id attempt-1 \ - --scope agent \ - --limit 64 + --scope agent ``` `TREE_RING_AGENT_PROFILE`, `TREE_RING_WORKFLOW_ID`, and -`TREE_RING_SESSION_ID` provide the corresponding defaults. Clear an -agent-profile environment filter before coordinator fan-in. +`TREE_RING_SESSION_ID` provide the same defaults as their CLI flags. Do not +leave an agent-profile environment filter set when the coordinator intends to +recall every worker. -This shared-root contract covers concurrent processes on one host using a local +This shared-root pattern is for concurrent processes on one host using a local filesystem. It is not a distributed lock service and does not claim safe -cross-host, NFS, or network-filesystem database sharing. Use per-host roots plus -an explicit evidence-preserving fan-in when work spans hosts. +cross-host or NFS operation. Scope and identity fields remain routing metadata, +not a read ACL; a same-user coordinator can recall across profiles. Use +per-host stores plus an explicit, evidence-preserving fan-in process when work +spans hosts. ## Coordinated Write Policy -Stores start in backward-compatible Open mode. Enable Coordinated mode when -ordinary workers should publish only to their own agent partition: +Stores default to backward-compatible Open mode. For a shared root where only a +designated coordinator should publish or mutate shared memory, enable the +optional Coordinated policy: ```bash tree-ring --root .tree-ring policy enable --coordinator release-coordinator @@ -192,14 +398,17 @@ tree-ring --root .tree-ring policy audit --limit 100 ``` Enable prints the capability once. Put it only in -`TREE_RING_COORDINATOR_TOKEN`; never pass it as a CLI flag or place it in -memory, logs, source refs, transcripts, scripts, or committed files. Tree Ring -stores only a hash. Inject it only into coordinator processes and launch every -ordinary worker with `TREE_RING_COORDINATOR_TOKEN` unset. - -In Coordinated mode, an ordinary worker may create only non-heartwood -`scope=agent` memory whose `agent_profile` matches its write context. A -coordinator capability is required for: +`TREE_RING_COORDINATOR_TOKEN`; never pass it as a CLI flag or place it in a +memory, log, source ref, transcript, or committed file. Tree Ring stores only a +hash. `policy status` and `policy audit` are read-only and do not reveal the +capability. Inject it only into coordinator processes, and launch every ordinary +worker with `TREE_RING_COORDINATOR_TOKEN` unset so fan-out does not inherit +coordinator authority. + +In Coordinated mode, an ordinary worker may only create non-heartwood +`scope=agent` memory whose `agent_profile` matches its write context. Supply the +same identity with `--agent-profile ` or +`TREE_RING_AGENT_PROFILE=`. A coordinator capability is required for: - project, global, workflow, session, or other shared/non-agent writes - heartwood creation or promotion @@ -209,82 +418,68 @@ coordinator capability is required for: - maintenance with apply or repair flags Recall, export, policy status/audit, adapter dry-runs, consolidation dry-runs, -and report-only maintenance remain read-only. TUI promotion, ring changes, -supersede, forget/redact, and persisted consolidation also require -`TREE_RING_COORDINATOR_TOKEN`. - -Rotate and disable policy only while the current capability is exported. -Rotation invalidates the old capability; disabling returns the store to Open -mode. This policy is operational authorization in official Rust/CLI write -paths, not a read ACL, OS security boundary, or protection from an adversary -who controls local files or the process environment. - -Before a v0.13/schema-v3 upgrade, stop all Tree Ring processes, checkpoint and -back up the store, and upgrade every CLI, plugin, and bundled worker before -reopening it. Schema v3 fences memory inserts, updates, and deletes from old -v0.12 writers; all mixed-version operation is unsupported. Roll back only by -stopping every process and restoring the complete pre-upgrade backup. +and report-only maintenance remain read-only. In the TUI, start with +`--agent-profile ` (or `TREE_RING_AGENT_PROFILE`) so `/remember` +defaults to agent scope. TUI promote/scar/seed, supersede, forget/redact, and +persisted consolidation actions require `TREE_RING_COORDINATOR_TOKEN`. -## Ring Selection +Rotate the capability while the current one is exported, then immediately +replace the environment value with the newly printed capability: -Use these rings: +```bash +tree-ring --root .tree-ring policy rotate --coordinator release-coordinator-next +export TREE_RING_COORDINATOR_TOKEN='' +tree-ring --root .tree-ring policy disable +unset TREE_RING_COORDINATOR_TOKEN +``` -- `cambium`: active or recent task context -- `outer`: recent decisions and task lessons -- `inner`: older compressed project knowledge -- `heartwood`: durable, high-confidence truths and user preferences -- `scar`: failures, regressions, rejected approaches, and warnings -- `seed`: unresolved ideas, hypotheses, follow-ups, and future work +Rotation invalidates the old capability. Disabling returns the store to Open +mode and also requires the current capability. -Do not promote to `heartwood` from weak evidence. Prefer `outer` or `seed` -unless the user confirms durability or the evidence is strong. +This is operational write authorization enforced by official Rust/CLI store +paths. It is not a read ACL, an operating-system security boundary, or +protection from an adversary who controls the local database files or process +environment. -## Privacy And Forgetting +Before opening an existing store with v0.13/schema v3, stop every Tree Ring +process, checkpoint and back up the database, and upgrade every CLI, plugin, and +bundled worker. Do not reopen the upgraded root with v0.12: schema v3 fences +memory inserts, updates, and deletes from old writers, and all mixed-version +operation is unsupported. Roll back only by stopping all processes and +restoring the pre-upgrade backup. -Do not store: +## Agent-Mediated Updates -- secrets -- credentials -- tokens -- coordinator capabilities -- private keys -- raw chain-of-thought -- temporary scratchpad notes -- unverified claims as durable truth -- private health, financial, legal, or personal identifier details without - explicit user instruction -- copyrighted source text beyond short allowed snippets +Tree Ring Memory does not autonomously scrape chats or write durable memory in +the background. The active agent is responsible for deciding when a Tree Ring +command is warranted, then calling the CLI deliberately. + +Use bridge files only to discover Tree Ring and its command reference: + +- project-level bridges should point to `.tree-ring/SKILL.md` and + `.tree-ring/CLI.md` +- global bridges should be treated as opt-in user configuration +- TUI event-stream pulses are display signals, not durable memories + +Before writing memory, verify the lesson is durable, useful, privacy-safe, and +grounded in user instruction or source evidence. + +## Forgetting And Correction If memory is wrong, private, stale, or superseded: - redact it when the durable shape is useful but details are unsafe - delete it when it should not be retained - supersede it when a newer decision replaces it -- include explicit reasons for every forget operation +- prefer explicit reasons for every forget operation -```bash -tree-ring forget mem_example --mode delete --reason "example cleanup" -tree-ring audit --audit-type sensitive -tree-ring consolidate --period-type manual --dry-run -tree-ring maintain --apply-expired --repair-fts -``` - -In Coordinated mode, forget/redact, persisted consolidation, applied -maintenance, and FTS repair require `TREE_RING_COORDINATOR_TOKEN`. +In Coordinated mode these lifecycle writes require the coordinator capability. -## Source Adapters +Treat redaction as monotonic. Do not try to restore a redacted ID through +replacement import; create a new reviewed memory only if the user deliberately +reintroduces safe content. -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 Coordinated mode, persisting DOX/Revolve results requires the coordinator -capability; adapter dry-runs do not. - -```bash -tree-ring dox sync --source-root . --dry-run -tree-ring revolve sync --source-root revolve --dry-run -tree-ring integrations scan --source-root . -``` +Never keep known-wrong memory merely because it was previously recalled. ## Closeout Habit @@ -298,9 +493,3 @@ At the end of meaningful work, ask: - Is any memory sensitive and better left unstored? Only remember the answers that will materially improve future work. - -Canonical project: - -```text -https://github.com/TerminallyLazy/Tree-Ring-Memory -```