Integrations

# Agent Skill And Project Contract

Tree Ring Memory ships two integration aids for agent workflows:

- `skills/tree-ring-memory/SKILL.md`: a portable agent skill that teaches an agent when to recall, remember, redact, forget, and avoid memory capture.
- `templates/dox/AGENTS.md`: a DOX-style project contract template for repos that want Tree Ring Memory guidance alongside source code.

`tree-ring init` creates canonical project guidance and safely configures
maintained project-local harness adapters where create-only publication is
possible. The resulting local guidance is:

- `.tree-ring/AGENTS.md`
- `.tree-ring/SKILL.md`
- `.tree-ring/CLI.md`

Existing bridge and activation-manifest entries are never overwritten or
removed. If an entry would need mutation, Tree Ring preserves it and reports
`needs-user-review`. A generated bridge is a pointer, not proof that a runtime
used Tree Ring; see
[the harness activation protocol](../protocol/harness-activation.md).

These generated files are the canonical project-local guidance. Harness-native
bridge files should point back to them rather than copying memory data or
duplicating long instructions.

## Skill Usage

Use the skill in agent runtimes that support local skills or instruction packs.
The skill is framework-agnostic and does not assume any single host runtime, model provider, CLI, or orchestration framework.

Recommended activation moments:

- project start or resume
- user says "remember this"
- user asks what was decided
- user corrects the agent
- a repeated mistake appears
- a durable decision is made
- a future idea should be tracked
- work is closing out

## Project Contract Usage

Use `templates/dox/AGENTS.md` when a repo wants local memory rules.
Copy it to the project root as `AGENTS.md`, or merge its sections into an existing project contract.

The contract intentionally says that Tree Ring Memory is not authoritative over source docs.
Agents should still read local project instructions and source evidence directly.

The CLI does not modify a project root `AGENTS.md` automatically. Merge the
generated `.tree-ring/AGENTS.md` guidance manually when you want DOX-aware
agents to encounter Tree Ring Memory instructions before entering `.tree-ring/`.

## Runtime Bootstrap And Updates

Agents must resolve the real project root before setup. If the user has already
authorized Tree Ring installation, download the official version-pinned
`v0.15.0/install.sh` installer to a temporary file, verify its SHA-256 is
`ef0d5eb8f09cbe2e4c3abe80ee9a98a56759c89ad4ddd103d6c68314cd653ade`, inspect
it, and only then run it from that root:

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

Agents must not pipe a network response directly to a shell; the installer
verifies the selected release archive against its published SHA-256. Without
existing setup authorization, the agent should explain that exact operation
and ask before downloading or installing software. It must not
initialize a plugin cache, package directory, home directory, or unrelated
working directory. Existing project-local installs should use
`.tree-ring/bin/tree-ring --root .tree-ring init`; global installs should use
`tree-ring --root .tree-ring init` from the project root.

`tree-ring update --check` checks for a release without changing files. With
update authorization, `tree-ring update` verifies official assets and preserves
the active project-local, direct-prefix, or Homebrew scope. Afterward, rerun
`init` in each project to backfill managed guidance. CLIs older than v0.15 must
first be upgraded through their existing package manager or install prefix.

## Minimal CLI Flow

```bash
tree-ring init
tree-ring recall "project startup warnings"
tree-ring remember "Use protocol-first design." --event-type decision --scope project --tag architecture
tree-ring evidence "Snapshot invalidation fixed stale unread chat state." --outcome promoted --evidence-ref evals/chat-state/run-042 --score 0.91
tree-ring dox sync --source-root . --dry-run
tree-ring revolve sync --source-root revolve --dry-run
tree-ring integrations scan --source-root .
tree-ring forget mem_example --mode redact --reason "remove sensitive detail"
tree-ring maintain
```

For a project-local install, use the generated quick reference in
`.tree-ring/CLI.md` and pass the project memory root explicitly when needed:

```bash
.tree-ring/bin/tree-ring --root .tree-ring recall "project startup warnings"
.tree-ring/bin/tree-ring --root .tree-ring tui
```

## Multi-Agent Fan-Out And Fan-In

Tree Ring can coordinate multiple CLI workers that share one local memory root
on one host. The coordinator chooses one project, workflow ID, and session ID.
Every worker gets a unique agent profile and a stable operation ID for each
logical write:

```bash
tree-ring --root .tree-ring init

tree-ring --root .tree-ring remember "Storage worker validated WAL behavior." \
  --event-type lesson \
  --scope agent \
  --project example-service \
  --agent-profile worker-storage \
  --workflow-id release-readiness \
  --session-id attempt-1 \
  --operation-id validate-storage-v1 \
  --source-ref runs/release-readiness/worker-storage.json \
  --tag coordination
```

Repeat the worker command with a different `--agent-profile`,
`--operation-id`, and source reference. Keep `--workflow-id` and
`--session-id` shared across that fan-out. An exact retry of one logical write
reuses its original session and operation IDs. Rotate the session and assign new
operation IDs only when starting a genuinely new execution attempt.

Scope determines the required partition identity:

| Scope | Required identity | Intended use |
| --- | --- | --- |
| `agent` | `agent_profile` | One worker's partitioned task memory |
| `workflow` | `workflow_id` | Shared state for one fan-out/fan-in |
| `session` | `session_id` | State partitioned by execution attempt |
| `project` | None; `project` is recommended | Shared repository memory |
| `global` | None | Deliberate cross-project memory |

The CLI also reads `TREE_RING_AGENT_PROFILE`, `TREE_RING_WORKFLOW_ID`, and
`TREE_RING_SESSION_ID`. Explicit flags are easier to audit in retained worker
commands. If the coordinator uses environment defaults, clear the agent-profile
default before recalling all workers; otherwise it becomes an unintended recall
filter.

At fan-in, recall worker results through the shared dimensions:

```bash
tree-ring --root .tree-ring --json recall "release readiness" \
  --project example-service \
  --workflow-id release-readiness \
  --session-id attempt-1 \
  --scope agent \
  --limit 64
```

Inspect each memory's source reference before writing a coordinator-owned
summary. Use `scope=workflow` with the same workflow ID for shared workflow
state, or `scope=project` for a reviewed durable project conclusion:

```bash
tree-ring --root .tree-ring remember "Release readiness checks passed." \
  --event-type summary \
  --scope workflow \
  --project example-service \
  --agent-profile coordinator \
  --workflow-id release-readiness \
  --session-id attempt-1 \
  --operation-id fan-in-summary-v1 \
  --source-ref runs/release-readiness/fan-in.json
```

Consolidation accepts `--agent-profile`, `--workflow-id`, and `--session-id`
filters. Agent-, workflow-, and session-scoped inputs remain partitioned;
consolidation does not silently merge memories from different partition
identities. A coordinator that wants a shared conclusion should write the
explicit source-linked summary shown above.

### Idempotency

`operation_id` is an idempotency key inside the
`(project, workflow_id, agent_profile)` namespace:

- An exact retry with the same payload returns the existing memory ID and does
  not add a row.
- Reusing the key in that namespace for a different payload fails nonzero.
- `session_id` is retained context but is not part of the idempotency namespace;
  changing only the session makes the retry conflict.
- Omitting `operation_id` creates an ordinary new write.
- Consolidation-derived summaries do not inherit a source operation ID.
- Replacing an active memory ID preserves its old operation namespace as a
  one-way claim.
- Redaction keeps both the one-way operation claim and a memory-ID tombstone,
  so retries and replacement imports fail closed without restoring redacted
  content. Only hard deletion removes those claims.

Pre-0.12 `agent`, `workflow`, or `session` records that lack the now-required
identity are assigned a deterministic, per-record `legacy-*` identity during
migration/import and marked for review. They remain privately partitioned and
portable instead of being widened into project/global scope.

The identifiers must be nonblank, contain no control characters, and stay at or
below 256 characters. These fields are routing and correlation metadata, not a
read-authorization boundary. A process with filesystem access to the SQLite
store can read it, so host permissions still control access.

### Coordinated Write Authorization

Stores remain in backward-compatible Open mode unless a coordinator explicitly
opts in. Enable Coordinated mode for a shared root when ordinary fan-out workers
should publish only to their own agent partitions:

```bash
tree-ring --root .tree-ring policy enable --coordinator release-coordinator
# Set and export TREE_RING_COORDINATOR_TOKEN with a history-safe, no-echo prompt
# supported by your shell, or inject it through an approved secret manager.
tree-ring --root .tree-ring policy status
tree-ring --root .tree-ring policy audit --limit 100
```

Enable prints the capability exactly once. Supply it only through
`TREE_RING_COORDINATOR_TOKEN`; there is no token CLI flag. Do not put the token
in memory, a source ref, a log, a retained command, or a committed file. Do not
paste it into an `export` command; use a history-safe, no-echo prompt supported
by the current shell or approved secret-manager injection. The store keeps only
its hash, and policy status/audit never reveal it.
Inject the variable only into coordinator processes. Ensure every ordinary
worker is launched with `TREE_RING_COORDINATOR_TOKEN` unset so authority is not
inherited through fan-out.

In Coordinated mode, an ordinary worker may only create a non-heartwood
`scope=agent` event whose `agent_profile` matches the `WriteContext` actor. The
CLI constructs that actor from `--agent-profile` or
`TREE_RING_AGENT_PROFILE`. Everything else that can publish shared state or
mutate lifecycle state requires the coordinator capability:

- project, global, workflow, session, or other non-agent creates
- all heartwood creates and promotions
- JSONL import and persisted DOX/Revolve sync
- persisted consolidation
- ring changes, supersede, delete, and redact
- applied expiry/secret maintenance and FTS repair

Recall, export, policy status/audit, adapter dry-runs, consolidation dry-runs,
and report-only maintenance remain read-only. Protected allow and deny
decisions are written to the policy audit trail without the plaintext token.

Rotate the capability while the current token is in the environment, then
replace it immediately with the newly printed capability:

```bash
tree-ring --root .tree-ring policy rotate --coordinator release-coordinator-next
# Replace TREE_RING_COORDINATOR_TOKEN through the same history-safe, no-echo
# input path before using the new capability.
tree-ring --root .tree-ring policy disable
unset TREE_RING_COORDINATOR_TOKEN
```

The old capability stops authorizing writes after rotation. Disabling also
requires the current capability and returns the store to Open mode.

For TUI workers, pass `--agent-profile <worker>` to
`tree-ring --root .tree-ring tui` or set `TREE_RING_AGENT_PROFILE`.
`/remember` then defaults to `scope=agent` for that worker. Without a profile,
`/remember` keeps its Open-mode global default and an unprivileged
Coordinated-mode write is denied. Promote/scar/seed, supersede, forget/redact,
and persisted consolidation actions require `TREE_RING_COORDINATOR_TOKEN`.

This is operational authorization in official Rust/CLI write paths. It is not
a read ACL, an OS security boundary, or protection from an adversary who
controls the local files or process environment.

### Runtime Boundary And Evidence

The supported shared-root pattern is concurrent processes on the same host
using a local filesystem. SQLite WAL, bounded lock retries, and a busy timeout
handle local contention. Tree Ring is not a distributed database or lock
service, and this evidence does not establish safe shared-database operation
over NFS, network filesystems, containers on different hosts, or multiple
machines. Use per-host roots and an explicit export/import or other
evidence-preserving coordinator when work spans hosts.

`crates/tree-ring-memory-cli/tests/multi_agent_acceptance.rs` is a bounded
process-level acceptance test. It launches eight real CLI writers against one
root, exercises profile/workflow/session/scope recall filters, verifies exact
retry and conflicting-key behavior, and checks memory-row/FTS parity through
the JSON maintenance report. Its policy phase races concurrent unauthorized
shared writes, proves ordinary agent-partitioned creates still work, verifies a
coordinator can publish and promote, rotates the capability, and checks allowed
and denied audit records. It is evidence for the same-host contract only; it is
not a sustained-load, crash-recovery, fairness, adversarial-local-user, or
distributed-storage certification.

### v0.13 Schema-v3 Upgrade

Before any v0.13 process opens an existing root:

1. Stop every Tree Ring CLI, TUI, plugin, and bundled worker using it.
2. Checkpoint SQLite WAL state and make a verified backup of the store.
3. Upgrade every CLI, plugin, and bundled worker.
4. Reopen with v0.13 to migrate the root to schema v3.

Schema v3 fences memory inserts, updates, and deletes from old writers. Do not
use v0.12 on that root: all mixed-version operation is unsupported even if an
older read or maintenance command appears to work. Roll back only by stopping
all processes and restoring the complete pre-upgrade backup.

## Evidence-Driven Improvement

Use `tree-ring evidence` when a lesson comes from an evaluation, checkpoint,
experiment, branch, incident, or reviewed run artifact.

Outcome mapping:

- `promoted` creates durable heartwood from supported evidence.
- `rejected` creates a scar when a failed or rolled-back approach has reusable warning value.
- `deferred` creates a seed for a promising but unresolved option.
- `observed` creates an outer-ring evaluation result.

Plain `remember` is still appropriate for user preferences, explicit decisions,
and project lessons that do not come from a formal evaluated outcome.

## Memory Quality Gates

Tree Ring guidance is meant to improve agent behavior, not increase memory volume.
Use these gates when wiring Tree Ring into an agent harness:

- Recall gates: before substantial or risky work, recall constraints, scars, preferences, and unresolved seeds.
- Trust gates: prefer source-linked, non-superseded, high-confidence memories and re-read authoritative sources when memory conflicts with source files or user instructions.
- Write gates: reject transient planning chatter, duplicate wording, tool noise, and unsupported claims; require evidence refs for promoted or rejected evaluated outcomes.

The certification suite includes quality scenarios that exercise missed constraints, memory spam, stale truth suppression, and behavior proof.
Quality artifacts are written to
`target/tree-ring-certification/quality/quality-report.json` and
`target/tree-ring-certification/quality/quality-summary.md`.

## Source Adapter Flow

Use DOX and Revolve adapters when the source artifacts already exist locally:

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

The adapters are Rust-native and local-only. They create concise, source-linked
memory events through the same SQLite store as manual memories. They do not
modify root `AGENTS.md` files, rewrite DOX contracts, mutate Revolve records,
or import raw run-log bloat.

DOX adapter rules:

- Scan a project root or a single `AGENTS.md` file.
- Store concise summaries and source refs.
- Treat source `AGENTS.md` files as authoritative.
- Re-read the DOX chain before editing files.

Revolve adapter rules:

- Scan a Revolve root or an evidence file.
- Import promoted outcomes as heartwood.
- Import reusable rejected outcomes as scars.
- Import deferred hypotheses as seeds.
- Import observed results as outer-ring evidence.
- Ignore outcome-free files as durable truth.

Run `--dry-run` first, inspect the generated memories, then rerun without
`--dry-run` only when the summaries are useful and source-linked. In
Coordinated mode, that persisted rerun requires
`TREE_RING_COORDINATOR_TOKEN`; the dry-run does not.

## Agent Harness Notes

Tree Ring Memory is framework-agnostic. The default is `tree-ring init`, not a
manual bridge-copying workflow. It installs only owned project-local material
that a maintained adapter can publish to an absent final path. It never replaces
or removes an existing bridge or activation manifest, including during
deactivation. Then run:

```bash
tree-ring integrations status
```

`active` needs a fresh matching receipt from a new session's scoped recall and
safe context injection. `configured-awaiting-proof`, `active-isolated`,
`needs-trust`, `needs-project-mount`, `needs-plugin`, and
`needs-user-review` are deliberately non-active states.

If an entry is already present or has changed, leave it untouched and follow the
reported `needs-user-review` reconciliation step. If durability becomes
indeterminate after publication, preserve the published disk material; Tree
Ring keeps changed harnesses in the returned in-memory manifest marked for
review and leaves any manifest already published on disk intact.

Recommended project-level bridge targets:

- Codex and Gemini-style skill loaders: `.agents/skills/tree-ring-memory/SKILL.md`
  pointing to `.tree-ring/SKILL.md` and `.tree-ring/CLI.md`.
- Claude Code: `.claude/skills/tree-ring-memory/SKILL.md` plus a `CLAUDE.md`
  reference to `.tree-ring/AGENTS.md` and `.tree-ring/CLI.md`.
- OpenCode and DOX-style agents: a root `AGENTS.md` managed block or manual
  section that tells the agent to read `.tree-ring/AGENTS.md`,
  `.tree-ring/SKILL.md`, and `.tree-ring/CLI.md`.
- Pi: a `.pi/settings.json` resource path that points at the Tree Ring skill or
  CLI guidance.

Project bridge files are preferred because they stay scoped to the current
repo. Global bridge files under `~/.agents`, `~/.codex`, `~/.claude`,
`~/.gemini`, or `~/.pi` affect every project and should be written only through
an explicit global opt-in flow.

The bridge-linking design is agent-mediated: start hooks perform receipt-backed
recall, and maintained stop hooks require the active agent to evaluate zero to
three structured automatic-capture candidates. Accepted candidates still cross
the strict CLI write boundary with lifecycle identity, idempotency, provenance,
sensitivity filtering, and coordinated-policy enforcement. Tree Ring does not
run a background recorder or autonomously persist chat transcripts.

`integrations link` is an advanced alias for controlled bridge work; it is not
required after default initialization. `tree-ring integrations activate --harness
<id> --dry-run`, `integrations certify`, and `integrations deactivate --harness
<id>` are advanced operations. Certification creates JSON and Markdown evidence;
a marker-only result cannot pass.

Pi trust is the user's platform decision: report `needs-trust` rather than
changing global trust. Agent Zero uses only its separate `tree_ring_memory`
plugin. `tree-ring init` creation-publishes Tree Ring's passive Agent Zero
binding with `needs-plugin`; that is configuration, not a claim that the plugin
or project mount is available. After the user installs/enables the matching
plugin release and selects the mounted project, the plugin owns an absolute,
non-project `activation-capability.json` descriptor and passes it internally.
Only its descriptor-scoped status and new-session preflight can report
`configured-awaiting-proof` and then receipt-backed `active`.

Do not create a generic `.a0` marker, copy the descriptor into the project, or
try to invoke a descriptor command. Tree Ring does not modify Agent Zero core or
create another store to imply sharing. A missing, invalid, disabled, or
release-incompatible plugin descriptor remains `needs-plugin`; an inaccessible
canonical root is `needs-project-mount`, and a different store is
`active-isolated`. Hermes and any unverified runtime remain non-active.

Receipts are privacy-redacted operational evidence, not raw prompts, recalled
content, secrets, sensitive values, paths, or coordinator capabilities. They
prove preflight usage, not a security boundary. Shared status is limited to
same-host processes on a local filesystem with the same project `store_id`;
it does not apply across hosts or network filesystems.

## Safety Rule

When in doubt, do not store the memory.
Prefer a short, redacted, source-linked lesson over detailed sensitive capture.