Tree Ring Memory｜本地优先的AI Agent记忆生命周期管理

access：来源确认 · curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --release latest

project_type：来源确认 · Tree Ring Memory is a framework-agnostic, local-first memory lifecycle layer for

# Tree Ring Memory

![Tree Ring Memory retro roller-rink banner](assets/tree-ring-memory-banner.png)

Tree Ring Memory is a framework-agnostic, local-first memory lifecycle layer for
AI agents. It helps agents remember useful decisions, warnings, preferences,
and lessons without turning memory into a transcript dump. Fresh memory stays
detailed, older memory compresses into rings, important scars remain visible,
and durable truths become heartwood.

Tree Ring Memory is inspired by the spatial project-memory patterns in
[DOX](https://github.com/agent0ai/dox) and the evidence-driven improvement loop
in [Revolve](https://github.com/agent0ai/revolve), with a deliberate nod to
their original creator, [Jan Tomášek](https://github.com/frdel). This project is
framework-agnostic and does not replace either protocol.

Tree Ring Memory is in protocol-preview status. Current launch links:

- Launch page: <https://terminallylazy.github.io/Tree-Ring-Memory/>
- Launch release: <https://github.com/TerminallyLazy/Tree-Ring-Memory/releases/tag/v0.15.3>
- Launch discussion: <https://github.com/TerminallyLazy/Tree-Ring-Memory/discussions/27>
- Rust-native CLI article: <https://terminallylazy.github.io/Tree-Ring-Memory/launch/rust-native-agent-memory-cli.md>
- Feedback issue: <https://github.com/TerminallyLazy/Tree-Ring-Memory/issues/26>
- Homebrew tap: <https://github.com/TerminallyLazy/homebrew-tree-ring>

<details>
<summary>Protocol preview history</summary>

- v0.1 provided the initial local reference implementation with SQLite storage and no required cloud services.
- v0.2 moved durable behavior into a Rust core.
- v0.3 explored host bindings during the Rust migration.
- v0.4 added Rust-owned JSONL import/export with privacy-preserving defaults across the CLI.
- v0.5 added Rust-owned audit checks for stale, sensitive, low-confidence, supersession, and contradiction candidates.
- v0.6 added Rust-owned deterministic consolidation with idempotent summary records and cautious sensitive-memory handling.
- v0.7 made the public facade Rust-native only and added Rust-owned maintenance for expiry, secret redaction, and FTS repair.
- v0.8 removed Python-owned runtime behavior.
- v0.9 removed tracked Python source, tests, smoke scripts, and the optional CPython extension from the canonical repo.
- v0.10 added a one-line installer plus Rust-native terminal onboarding with animated terminal tree rings.
- v0.11 made the repo fully Rust-native, wired TUI export/consolidation actions, added DOX/Revolve sync adapters, and added agent-framework discovery.
- v0.12 adds a controlled, retained agent-workflow proof with explicit model identity and exact structured-output checks; it reports observed outcomes without claiming a universal memory advantage.
- v0.13 adds same-host multi-agent identities and idempotency, opt-in coordinator authorization for shared writes, a protected-write audit, and a schema-v3 fence for old memory inserts, updates, and deletes.
- v0.14 adds project-local harness activation with receipt-backed readiness, so configured bridges do not imply that an agent has used memory.
- v0.15 adds verified release bootstrap, project-root-aware agent guidance, and scope-preserving CLI updates.

</details>

## What It Gives Agents

- Explicit local recall with SQLite/FTS storage and no required cloud service.
- Source-linked memories for decisions, scars, lessons, evidence, and durable
  project truths.
- Rust-native import/export, audit, consolidation, maintenance, DOX/Revolve
  adapters, harness discovery, and terminal UI.
- Same-host multi-agent correlation, scoped recall filters, and idempotent
  worker writes through the public CLI.
- Optional coordinator capability enforcement for shared publication and
  lifecycle mutations while ordinary workers stay agent-partitioned.
- Evidence artifacts for install size, recall speed, harness readiness, and
  recall quality.
- Privacy defaults that block secret-like memory, hide sensitive details, and
  keep transcript capture out of scope.

The Rust workspace currently includes:

- `crates/tree-ring-memory-core`: models, validation, sensitivity checks, and recall scoring.
- `crates/tree-ring-memory-sqlite`: schema-compatible SQLite/FTS storage and recall filtering.
- `crates/tree-ring-memory-cli`: native `tree-ring` CLI.

The public runtime is Rust-native. The Rust CLI and Rust crates own storage,
recall, import/export, audit, consolidation, maintenance, and terminal UI
behavior. There is no tracked root Python package, Python wrapper layer, pytest
suite, Python smoke script, PyO3 crate, or CPython extension.

## Screenshots

These are captured from the actual `tree-ring tui` app running against a local
`.tree-ring` store populated through the public CLI with 47 memories across
all rings, plus the current certification artifacts.

![Tree Ring TUI dashboard showing ring activity, ambient rings, memories, and detail panels](docs/assets/readme-tui-dashboard.png)

Dashboard view with populated cambium, outer, inner, heartwood, scar, and seed
rings. Ambient layers are duller at lower relative fullness and lighter as their
share of stored memories grows; activity pulses are temporary.

![Tree Ring TUI search mode showing ranked recall results from a populated store](docs/assets/readme-tui-search.png)

Search mode with ranked recall results and selected-memory details.

![Tree Ring TUI evidence browser showing certification metrics, harness records, and recall-quality checks](docs/assets/readme-tui-evidence.png)

Evidence browser with install size, recall speed, harness records, and
recall-quality checks loaded from `target/tree-ring-certification/`.

![Tree Ring TUI integrations view showing detected agent frameworks and setup guidance](docs/assets/readme-tui-integrations.png)

Integrations view showing detected local agent framework markers and next-step
guidance.

## Quick Start

### Activate project-local harnesses

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

If memory seems silent, run `tree-ring integrations status --verbose`. The last
recall result count distinguishes a successful empty recall from a hook that
has never run. CLI 0.15.6 repairs cross-session startup recall and generated
hooks for project-local installs; see the
[recall visibility and startup brief contract](docs/protocol/harness-activation.md#recall-visibility-and-startup-briefs).
The current public-directory upload also includes native Codex lifecycle hooks;
ordinary Chat hosts without the Codex hook runtime remain guidance-only.

CLI 0.15.13 and the Codex 0.3.10 / Claude 0.3.7 plugins quietly skip lifecycle
hooks in uninitialized projects and linked worktrees. Each checkout keeps its
own memory root; inherited hooks never initialize it or reuse another
checkout's store. Existing roots with broken activation still report errors.

Default `init` creates the canonical project-local store and configures
maintained adapters where new project-local bridge and manifest entries can be
created safely. It does not require copying a skill or manually running
`integrations link`. Existing entries are never overwritten or removed; a
contested bridge or manifest reports `needs-user-review`. A harness is `active`
only after a fresh matching receipt shows a new session completed scoped recall
and safe context injection; `init`, markers, and generated guidance establish
configuration, not activation. See the [harness activation
protocol](docs/protocol/harness-activation.md) for states, receipts, advanced
commands, and runtime boundaries.

Shared Tree Ring activation is supported only for concurrent processes on the
same-host local filesystem with matching project-store identity. It does not
claim safe SQLite sharing across hosts, NFS/network filesystems, or containers
on different hosts.

### Install the agent guidance plugin (optional)

The repository includes an instruction-only package for ChatGPT/Codex and
Claude Code under `plugins/tree-ring-memory/`. It adds the reviewed Tree Ring
workflow, DOX dry-run guidance, and installed-runtime certification commands;
it does not bundle the CLI, the full source certification script, or an MCP
server.

Add the marketplace to Codex:

```bash
codex plugin marketplace add TerminallyLazy/Tree-Ring-Memory
```

Then restart the ChatGPT desktop app and install Tree Ring Memory from the
Plugins Directory. The repo-local `.agents/plugins/marketplace.json` is also
available automatically when this repository is open in a supported Work or
Codex surface.

Add and install the same package in Claude Code:

```text
/plugin marketplace add TerminallyLazy/Tree-Ring-Memory
/plugin install tree-ring-memory@tree-ring-memory
```

The plugin requires Tree Ring Memory CLI v0.15.0 or newer and teaches agents how
to install a verified project-local runtime when setup is already authorized.
See the
[plugin README](plugins/tree-ring-memory/README.md) for the platform manifests,
commands, DOX contract flow, and certification boundary.

### Agent Zero uses its separate plugin

Agent Zero is intentionally a two-part setup. `tree-ring init` creates the
project-local, passive Agent Zero binding and records `needs-plugin`; that
proves only that Tree Ring owns the project-side configuration. It does not
claim that Agent Zero is installed, that the project is mounted there, or that
an agent has used memory.

For a project that will use Agent Zero, install or update the separate
`tree_ring_memory` plugin, then configure it for the same mounted project root.
That is the only extra user setup. The plugin owns its fixed,
absolute `activation-capability.json` descriptor outside the project and passes
it to Tree Ring internally. Do not copy that file into the repository, create a
generic `.a0` marker, or try to invoke a descriptor command yourself.

The plugin's descriptor-scoped status check can report
`configured-awaiting-proof`; a new Agent Zero session's descriptor-scoped
preflight writes the receipt required for `active`. A normal host-shell status
without the installed plugin descriptor intentionally remains `needs-plugin`.
The matching Tree Ring core and Agent Zero plugin release must both be
installed; a source checkout, a passive binding, or an older bundled CLI is not
an installed-capability claim.

Verified prebuilt install for macOS ARM64 or Linux x86_64:

```bash
curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --release latest
```

Recommended project-local install with first-run initialization:

```bash
cd <project-root>
curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init --release latest --no-animation
```

macOS ARM64 install with Homebrew:

```bash
brew tap TerminallyLazy/tree-ring
brew install tree-ring
```

Source install (requires Rust and Cargo):

```bash
curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh
```

Store the first project memory:

```bash
tree-ring init
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 recall "release behavior" --project example-service
```

Open the terminal console:

```bash
tree-ring tui
```

## Install Details

With `--release latest`, the installer downloads the official platform archive,
downloads its published SHA-256, verifies it, and installs `tree-ring` without
requiring Rust. Without `--release`, it builds the Rust CLI with `cargo`. It then
shows one terminal onboarding screen with a branded terminal ring and useful
commands. For global installs, it can add the install bin directory to the shell
profile when that directory is not already on `PATH`. It does not initialize
memory unless `--init` is passed.

The installer command streams only the installer script into `sh`. It does not
put memory in a temporary location and it does not remove `.tree-ring`,
installed binaries, Cargo caches, source checkouts, or shell profiles.
Persistent memory lives in the configured memory root, normally `.tree-ring`
for project-local use or whatever path you pass with `--root`.

Initialization creates the SQLite store and non-destructive agent-awareness
files in the memory root:

- `.tree-ring/AGENTS.md`: DOX-style Tree Ring Memory guidance and root
  `AGENTS.md` merge notes.
- `.tree-ring/SKILL.md`: portable skill instructions for agent runtimes.
- `.tree-ring/CLI.md`: quick command reference for recall, strict automatic
  capture, remember, evidence, DOX/Revolve sync, import/export, audit,
  maintenance, and TUI usage.

Existing awareness files are left untouched. Tree Ring Memory does not modify a
project's root `AGENTS.md`; merge the generated guidance manually when you want
DOX-aware agents to see it before entering `.tree-ring/`.

Useful installer options:

```bash
sh install.sh --help
sh install.sh --project --init --release latest
sh install.sh --global --install-dir "$HOME/.local"
sh install.sh --no-animation  # stable output; kept for explicit script usage
sh install.sh --no-path-update
sh install.sh --release 0.15.3
sh install.sh --archive-url https://example/tree-ring-memory-0.15.3-darwin-arm64.tar.gz --archive-sha256 <sha256>
```

After install, rerun onboarding anytime:

```bash
tree-ring welcome
tree-ring welcome --init
tree-ring
```

By default, the installer uses `cargo install` from the Git repository or a
local `--source` checkout. `--release latest` or `--release <version>` resolves
and verifies the matching official prebuilt archive. Advanced callers can still
use `--archive-url` plus `--archive-sha256` explicitly.

## Update Tree Ring Memory

Check the official release without changing files:

```bash
tree-ring update --check
```

After authorizing an update, update the active executable in its existing
project-local, direct-prefix, or Homebrew-managed scope:

```bash
tree-ring update
tree-ring --version
```

The updater verifies the official release archive and checksum and does not
install a second copy in a different prefix. After updating, return to each
project root and safely backfill its managed guidance:

```bash
tree-ring --root .tree-ring init
tree-ring --root .tree-ring integrations status --verbose
```

CLIs older than v0.15 do not contain `tree-ring update`. Upgrade those with the
same manager or install prefix first: Homebrew with `brew upgrade tree-ring`, a
project-local install with `install.sh --project --release latest`, or another
direct install with `install.sh --install-dir <existing-prefix> --release
latest`. Use `command -v tree-ring` and `which -a tree-ring` afterward to find
an older binary that may still shadow the updated executable.

Open the terminal console after a global install:

```bash
tree-ring tui
```

If your shell cannot find `tree-ring` after a global install, run it directly or
add the install bin directory to the current terminal. The installer can update
future shell sessions through your shell profile, but a child installer process
cannot rewrite the already-running parent shell environment:

```bash
$HOME/.local/bin/tree-ring tui
export PATH="$HOME/.local/bin:$PATH"
```

Open the terminal console after a project-local install:

```bash
.tree-ring/bin/tree-ring --root .tree-ring tui
```

## CLI Preview

The `tree-ring` command is the Rust CLI.

```bash
tree-ring init
tree-ring remember "Use protocol-first design." --event-type decision --tag architecture
tree-ring capture "Use receipt-backed lifecycle checkpoints." --event-type decision --ring cambium --project example-service --agent-profile codex --workflow-id workflow-1 --session-id session-1 --operation-id auto-checkpoint-1 --source-ref agent-checkpoint:checkpoint
tree-ring evidence "Snapshot invalidation fixed stale unread chat state." --outcome promoted --evidence-ref evals/chat-state/run-042 --score 0.91
tree-ring recall "protocol design"
tree-ring forget mem_example --mode delete --reason "example cleanup"
tree-ring export --output memories.jsonl
tree-ring import memories.jsonl --dry-run
tree-ring import memories.jsonl
tree-ring audit --audit-type sensitive
tree-ring consolidate --period-type manual --dry-run
tree-ring maintain
tree-ring maintain --apply-expired --repair-fts
tree-ring policy status
tree-ring dox sync --source-root . --dry-run
tree-ring revolve sync --source-root revolve --dry-run
tree-ring integrations scan --source-root .
```

The CLI stores memory in `.tree-ring/` by default.

Command ownership is Rust-native:

- `init` creates the SQLite store plus `.tree-ring/AGENTS.md`,
  `.tree-ring/SKILL.md`, and `.tree-ring/CLI.md` without overwriting existing
  files, then attempts create-only project harness configuration.
- `remember`, `recall`, and `forget` cover direct memory capture, retrieval, redaction, and deletion.
- `capture` is the strict automatic lifecycle-write path: agent-scoped only,
  normal sensitivity only, bounded cambium/scar/seed classifications, and
  required checkpoint identity, idempotency, and provenance.
- `evidence` is the Revolve-inspired improvement-loop entry point for evaluated outcomes.
- `dox sync` and `revolve sync` read source files without changing them and save source-linked summaries to the memory store. Use `--dry-run` to preview without saving.
- `integrations scan` discovers nearby agent-framework markers and suggests setup paths without changing their config.
- `export`, `import`, `audit`, `consolidate`, and `maintain` are local maintenance surfaces over the same SQLite store.
- `policy` manages optional coordinated multi-agent write authorization and its
  protected-write audit trail.
- `welcome` and `tui` are the terminal onboarding and operator-console surfaces.

## Same-Host Multi-Agent Workflow

A coordinator can fan work out to multiple local CLI processes that share one
Tree Ring root. Give every worker a unique agent profile and operation ID while
sharing the workflow and session:

```bash
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
```

At fan-in, omit the agent-profile filter so the coordinator sees every
agent-partitioned result:

```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
```

When writing, `scope=agent` requires `agent_profile`, `scope=workflow` requires
`workflow_id`, and `scope=session` requires `session_id`. A coordinator's
aggregate recall may intentionally omit the agent-profile filter. Project and
global scopes remain shared. These fields are always routing and consolidation
partitions, not read ACLs; any process with filesystem access to the store can
perform unfiltered recall. The optional Coordinated policy described below adds
write authorization to official Rust/CLI paths without changing that read
boundary.
Pre-0.12 private-scope records that lack the now-required identity are migrated
to a deterministic, per-record `legacy-*` partition and marked for review
instead of being widened into shared scope or becoming unexportable.

`TREE_RING_AGENT_PROFILE`, `TREE_RING_WORKFLOW_ID`, and
`TREE_RING_SESSION_ID` can supply the matching flag defaults. `operation_id`
provides write idempotency inside the `(project, workflow_id, agent_profile)`
namespace: an exact retry returns the existing memory ID, while a different
payload using the same key fails nonzero. Session ID is retained context but is
not part of that idempotency namespace. Replacing an active row preserves its
prior operation namespace as a one-way claim. Redaction also keeps a memory-ID
tombstone, so replacement import cannot restore the payload by omitting the
operation ID; only explicit hard deletion releases those claims.

The shared-root contract is limited to concurrent processes on one host using a
local filesystem. Tree Ring does not claim distributed locking, cross-host
SQLite coordination, or safe database sharing over NFS/network filesystems.
For work spanning hosts, keep per-host roots and use an explicit,
evidence-preserving fan-in.

The bounded acceptance test at
`crates/tree-ring-memory-cli/tests/multi_agent_acceptance.rs` holds a real
SQLite write lock, starts eight real CLI workers, verifies they wait and then
complete, exercises each recall filter and operation conflict behavior, checks
exact row/FTS parity through `tree-ring --json maintain`, and then verifies
concurrent worker denials, coordinator-authorized publication and promotion,
capability rotation, and protected-write audit records. This is same-host
evidence, not sustained-load, crash-recovery, fairness, adversarial local-user,
or distributed-storage certification.

### Coordinated Write Policy

Every store starts in backward-compatible Open mode. For fan-out/fan-in where
only a designated coordinator should publish shared conclusions or mutate
existing memory, explicitly enable Coordinated mode:

```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 coordinator capability once. Put it only in
`TREE_RING_COORDINATOR_TOKEN`; never pass it as a CLI flag or retain it in
memory events, logs, source refs, scripts, or committed files. Tree Ring stores
only a hash. `policy status` and `policy audit` are read-only and never reveal
the capability. 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. Inject the variable only into coordinator processes; explicitly
remove it from every ordinary worker's environment so fan-out children cannot
inherit coordinator authority.

In Coordinated mode, an ordinary worker may create only non-heartwood
`scope=agent` memory whose `agent_profile` matches the worker's write context.
Set that identity with `--agent-profile <worker>` or
`TREE_RING_AGENT_PROFILE=<worker>`. The coordinator capability is required for:

- project, global, workflow, session, or other shared/non-agent writes
- heartwood creation or promotion
- JSONL import and persisted DOX/Revolve adapter results
- persisted consolidation
- ring changes and supersede/delete/redact lifecycle operations
- maintenance with apply or repair flags

Recall, export, policy status/audit, adapter dry-runs, consolidation dry-runs,
and report-only maintenance remain read-only. Protected allow/deny decisions
are recorded by `policy audit` without recording the plaintext capability.

Rotate the capability while the current one is exported, then immediately
replace the environment value 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
```

Rotation invalidates the old capability. `policy disable` also requires the
current capability and returns the store to Open mode.

This policy is operational write authorization in official Rust/CLI store
paths. It is not a read ACL, an operating-system security boundary, or
protection against an adversary who controls the local database files or
process environment. The supported shared root remains one host and a local
filesystem.

### v0.13 Schema-v3 Upgrade

Treat the first v0.13 open of an existing store as a coordinated, one-way
upgrade:

1. Stop every Tree Ring CLI, plugin, TUI, and bundled worker using the root.
2. Checkpoint SQLite WAL state and make a verified backup of the store.
3. Upgrade every CLI, plugin, and bundled worker before any process reopens it.
4. Open the root with v0.13, which migrates it to schema v3 and installs the
   writer-protocol fence.

Do not run v0.12 against an upgraded root. Memory inserts, updates, and deletes
from old v0.12 writers are fenced; all mixed-version operation is unsupported
even if an older read or maintenance command appears to work.
Rollback is supported only by stopping all processes and restoring the complete
pre-upgrade backup.

## Evidence Loop

The Revolve-inspired loop is exposed through `tree-ring evidence`. It records
evaluated outcomes as memory with an evidence reference instead of treating
claims as durable truth without support.

```bash
tree-ring evidence "Snapshot invalidation fixed stale unread chat state." \
  --outcome promoted \
  --evidence-ref evals/chat-state/run-042 \
  --project agent-ui \
  --score 0.91

tree-ring evidence "Aggressive caching caused stale multi-chat state." \
  --outcome rejected \
  --evidence-ref evals/cache-branch/run-013 \
  --project agent-ui
```

Outcome mapping:

- `promoted` -> `heartwood`, durable `evaluation_promotion`
- `rejected` -> `scar`, durable `evaluation_rejection`
- `deferred` -> `seed`, `evaluation_hypothesis`
- `observed` -> `outer`, `evaluation_result`

This is not a replacement for Revolve records. Use source refs that point back
to real evaluations, checkpoints, PRs, issues, logs, or run artifacts.

## Source Adapters

Tree Ring Memory includes Rust-native source adapters. They produce concise,
source-linked memory events and then persist through the same SQLite store as
manual memories.

```bash
tree-ring dox sync --source-root . --dry-run
tree-ring dox sync --source-root . --project example-service

tree-ring revolve sync --source-root revolve --dry-run
tree-ring revolve sync --source-root revolve --project example-service
```

DOX sync discovers `AGENTS.md` files, stores summaries and source refs, and
keeps the source files authoritative. It can scan a project root or a single
`AGENTS.md` file. It does not copy entire project-contract trees into memory,
does not weaken child contracts, and does not let memory replace fresh DOX
traversal before edits.

Revolve sync scans a Revolve root or an evidence file. It imports promoted
outcomes as heartwood, rejected outcomes as scars, deferred hypotheses as
seeds, and observed results as outer-ring evidence. It keeps source refs back
to the Revolve/evaluation record and does not treat incomparable or
outcome-free files as durable truth.

For both adapters, run `--dry-run` first. Imported memory is a concise recall
aid; the source `AGENTS.md`, Revolve record, evaluation artifact, PR, issue,
test, or run log remains authoritative. In Coordinated mode, persisting either
adapter's result requires `TREE_RING_COORDINATOR_TOKEN`; dry-run discovery does
not.

Harness activation starts with the project-local default flow above. For
diagnostic evidence, use:

```bash
tree-ring integrations status --verbose
tree-ring integrations certify
```

- `integrations certify` writes JSON and Markdown evidence that keeps
  configured, active, isolated, blocked, skipped, and failed results distinct.
  A marker-only result cannot pass certification.
- `recall-quality` writes non-private recall diagnostics under
  `target/tree-ring-certification/recall-quality/default-fixture-v1.json`
  and merges the result into
  `target/tree-ring-certification/evidence-index.json`. It uses deterministic
  safe fixture memories, records returned ids, rank positions, score factors,
  and latency, and marks each query as `pass`, `fail`, or `needs_review`.

```bash
tree-ring recall-quality --source-root .
```

`tree-ring integrations scan --source-root .` remains a read-only diagnostic;
it cannot establish runtime use. `integrations link` remains an advanced alias
for controlled bridge work. Default `init` handles safe project-local adapter
configuration, while global configuration remains explicit opt-in. Neither
command replaces or removes an existing final bridge or activation manifest;
entries that require mutation remain unchanged for explicit review.

`tree-ring export` writes newline-delimited JSON. The first line is a
`tree_ring_memory_export` header with schema and plugin version metadata; each
remaining line is a `memory_event` envelope. The command excludes sensitive and
superseded memories unless `--include-sensitive` or `--include-superseded` is
set. Import validates all events, batches writes through SQLite, skips duplicate
ids by default, and replaces existing ids only with `--replace-existing`.

`tree-ring audit` is non-mutating. It reports deterministic local findings for
stale expiry, sensitive retention, low-confidence durable memory, supersession
integrity, and conservative contradiction candidates.

`tree-ring consolidate` creates deterministic local summary memories without an
LLM. Dry-run mode writes nothing. Persisted consolidation is idempotent for the
same period and source-memory set unless `--force` is provided. Sensitive
non-secret memories are summarized without copying raw payload text and require
review; secret-like memories are excluded from consolidation.

`tree-ring maintain` is safe by default. Without apply flags it is a dry-run
report, including on a missing root. It can apply eligible temporary-memory
expiry, redact secret-like memories, and rebuild SQLite FTS only when explicitly
asked through `--apply-expired`, `--apply-secret-redactions`, or `--repair-fts`.

## Terminal Console Preview

The Rust CLI includes a framework-agnostic Ratatui console for humans and agent
operators working from a terminal:

```bash
tree-ring tui
tree-ring --root .tree-ring tui --event-stream ./tree-ring-events.jsonl --tick-ms 150
tree-ring --root .tree-ring tui --agent-profile worker-storage
```

From a source checkout without installing:

```bash
cargo run -p tree-ring-memory-cli -- --root .tree-ring welcome --init --no-animation
cargo run -p tree-ring-memory-cli -- --root .tree-ring remember "Try the TUI with a first memory." --event-type lesson --scope project
cargo run -p tree-ring-memory-cli -- --root .tree-ring tui
```

The console keeps an animated straight-on tree-ring face visible at all times.
The visual layer generates a backend-independent ring frame first, then rasterizes
that frame into high-resolution terminal cells for the ambient HUD. Individual
rings carry clockwise or counter-clockwise highlights, pulse with matching memory
activity, and shimmer through scar marks on each tick. That keeps the always-on
animation cheap and portable while leaving room for richer Kitty/iTerm2
image-protocol rendering in welcome or expanded views later.
Store-watch polling updates persisted counts from SQLite, while the optional
event stream lights rings in real time without treating stream events as durable
truth.

The dashboard counts memories saved in the selected project's store. A successful
harness recall can return zero results from an empty store; its activation receipt
does not create a memory. Automatic capture adds only durable outcomes selected by
an agent working in that project.

`/sync` previews DOX summaries from the project's `AGENTS.md` files, including
local instruction files that may not be tracked in Git. Review the source paths,
project, destination store and candidates before confirming. Confirmation saves
that preview and refreshes the dashboard; cancellation leaves memories unchanged.
Files containing detected secret content are skipped entirely. With a custom
memory-store `--root`, the TUI scans the project from which it was launched.
Repeated sync updates the same source-linked records rather than duplicating them.
DOX records retain their stable IDs and include a source-root fingerprint. If a
shared store has the same ID from another project or root, sync rejects the whole
batch; use separate project stores. Matching legacy records without a fingerprint
can be updated in the source project's `.tree-ring` store; their earlier location
cannot be verified. Shared legacy records and fingerprinted records copied from
a different root require provenance review before reuse. Sync does not
automatically rebind a recorded fingerprint or migrate IDs.

If a shared legacy store rejects a sync, preserve that store and select an empty,
dedicated store for this source project. For example, when the project's
`.tree-ring` store is unused:

```bash
tree-ring --root /path/to/project/.tree-ring dox sync --source-root /path/to/project --project project-name --dry-run
# After reviewing the candidates, repeat without --dry-run to save them.
```

If that destination already contains conflicting records, choose a new dedicated
directory with `--root` instead. Existing memories remain in the original store;
this creates reviewed summaries from authoritative source files and does not
transfer or relabel old memories. There is no automatic legacy-provenance
migration command.

In Coordinated mode, saving requires the coordinator capability in the terminal
environment when the TUI starts; preview remains available without it.

Useful keys and commands:

- `s` focuses search, `/` opens the slash command palette, `r` opens exploded
  ring view, `q` quits.
- `i` toggles sensitive-memory visibility, `u` toggles superseded-memory
  visibility.
- In the `/sync` preview, `j`/`k` select candidates, Left/Right or Page Up/Down
  scroll the preview, `y` saves, and `n` or Escape cancels.
- Slash commands include `/rings`, `/search <query>`, `/remember <summary>`,
  `/forget`, `/redact`, `/promote`, `/scar`, `/seed`, `/supersede <old_id>`,
  `/consolidate`, `/export <file>`, `/sync`, `/integrations`, `/stream`, and
  `/watch`.

`--agent-profile` (or `TREE_RING_AGENT_PROFILE`) makes TUI `/remember` create
agent-scoped memory for that profile. Without a profile, `/remember` keeps its
Open-mode global default and is therefore rejected for an unprivileged
Coordinated-mode worker. TUI lifecycle operations such as promote, scar, seed,
supersede, forget/redact, and persisted consolidation require
`TREE_RING_COORDINATOR_TOKEN` in Coordinated mode.

Destructive or authority-changing operations are confirmation-gated. Sensitive
details stay hidden by default, and secret-like memory is blocked before
storage.

Event stream lines are local JSONL objects. They are display signals only:

```json
{"event":"remembered","ring":"cambium","label":"Stored project lesson"}
{"event":"policy_blocked","ring":"scar","label":"Secret-like memory blocked"}
```

## Development Checks

```bash
cargo test --locked
sh install.sh --help
cargo run -p tree-ring-memory-cli -- --help
cargo run -p tree-ring-memory-cli -- welcome --no-animation
cargo run -p tree-ring-memory-cli -- tui --help
cargo run -p tree-ring-memory-cli -- export --help
cargo run -p tree-ring-memory-cli -- import --help
cargo run -p tree-ring-memory-cli -- audit --help
cargo run -p tree-ring-memory-cli -- consolidate --help
cargo run -p tree-ring-memory-cli -- maintain --help
cargo run -p tree-ring-memory-cli -- policy --help
cargo run -p tree-ring-memory-cli -- dox sync --help
cargo run -p tree-ring-memory-cli -- revolve sync --help
cargo run -p tree-ring-memory-cli -- integrations scan --help
cargo test -p tree-ring-memory-cli --test multi_agent_acceptance
cargo run --release -p tree-ring-memory-sqlite --example performance_smoke -- 1000
sh scripts/certify-tree-ring.sh
sh scripts/package-release.sh
```

The Rust CLI writes the canonical SQLite/raw JSON shape. The performance smoke
asserts nonempty recalls, emits a `METRICS_JSON=` line, and uses conservative
local thresholds of at least 500 inserts/sec and max recall latency of 250 ms
for the synthetic workload.

`scripts/certify-tree-ring.sh` runs the fuller local certification suite:
formatting, tests, Clippy, release build, isolated project/global installs, CLI
JSON smokes, DOX/Revolve adapter smokes, integration-scan origin checks,
install-size, recall-speed, recall-quality diagnostics, CLI, adapter, and
harness checks, import throughput, and 10k/30k recall timing. It writes
`target/tree-ring-certification/summary.md`,
`target/tree-ring-certification/metrics.json`, and
`target/tree-ring-certification/evidence-index.json`.

Most recent branch-local certification run, generated at
`2026-07-15T22:02:33Z`:

- Release binary: 6,366,432 bytes.
- Project install with init: 6,292 KB.
- Global install: 6,244 KB.
- CLI import: 10,000 memories in 4 seconds, about 2,500/sec.
- 10k recall: 3.451 ms average, 6.197 ms max.
- 30k recall: 7.538 ms average, 13.495 ms max.
- Harness matrix: 5 pass, 1 skip. Codex, Claude Code, OpenCode, Goose, and
  Agent Zero/A0 passed; Pi was skipped because only a user-home marker was
  present in the fixture.
- Recall quality: 4 queries, 4 pass, 0 fail, 0 needs review; average latency
  0.137 ms, max latency 0.418 ms.
- Agent Zero plugin smoke: skipped because `TREE_RING_AGENT_ZERO_ROOT` was not
  set.

Certification also runs the default memory quality scenario pack under
`fixtures/quality/`. Those scenarios prove recall gates, spam rejection,
stale-truth suppression, evidence requirements, and behavior-proof outcomes.
The quality report is written to
`target/tree-ring-certification/quality/quality-report.json` with a readable
summary at `target/tree-ring-certification/quality/quality-summary.md`.

An explicit agent workflow evaluation keeps paired trial workspaces and an
observed evidence report separate from normal certification and CI. It requires
a validated explicit model ID and records `codex:<model-id>` in the paired
reports:

```bash
cargo run --locked -p tree-ring-memory-cli --example workflow_proof -- \
  fixtures/workflow-proof target/tree-ring-certification/workflow-proof \
  --model <model-id>
```

See [agent workflow proof](docs/integrations/agent-workflow-proof.md) for the
controlled command, retained artifacts, exact structured-outcome checks, and
interpretation limits.

`scripts/package-release.sh` builds the Rust CLI in release mode, verifies its
version and archive layout, then creates a platform tarball under `dist/` with
a SHA-256 checksum file. A matching `v<version>` tag builds the Linux x86_64
and macOS ARM64 archives, verifies both, and attaches them to that GitHub
Release; a manually dispatched run remains artifact-only. Linux x86_64
artifacts are built and executed on Debian Bookworm (glibc 2.36); older glibc
systems must build from source.

## Design Docs

- `docs/architecture/rust-core-roadmap.md`
- `docs/architecture/rust-core-status.md`
- `docs/integrations/agent-skill.md`
- `docs/protocol/memory-event.md`

Historical migration and planning documents are retained under `docs/superpowers/`
and `docs/feature/`. Some of those records describe earlier Python prototype or
binding options that have since been superseded by the Rust-native runtime.
The current activation protocol is documented in
[`docs/protocol/harness-activation.md`](docs/protocol/harness-activation.md).

## Agent Workflow Integration

- `skills/tree-ring-memory/SKILL.md` gives agents portable guidance for when to recall, automatically capture, remember, redact, forget, or avoid memory capture.
- `templates/dox/AGENTS.md` is a DOX-style project contract template for repos that want Tree Ring Memory rules alongside source code.
- `docs/integrations/agent-skill.md` explains how to use both without making memory more authoritative than local project docs.
- `tree-ring init` creates canonical guidance and safely configures maintained
  project-local adapters when create-only publication is possible; status
  remains receipt-backed.

For DOX-style project awareness, merge the relevant generated `.tree-ring/AGENTS.md`
sections into the project root `AGENTS.md`. The CLI intentionally does not
rewrite root project contracts automatically.

`tree-ring init` creates managed project-local bridges where an adapter can do
so safely. It never replaces or removes an existing bridge or activation
manifest; contested entries are preserved as `needs-user-review`. If durability
becomes indeterminate after publication, published disk material is preserved,
the in-memory changed harness state remains marked for review, and any manifest
already published on disk is left intact. A bridge is not proof of runtime use.
`tree-ring integrations status` reports the exact non-active state and one
action, such as Pi trust, an Agent Zero plugin, a missing mount, or unmanaged-file
review. Do not treat Hermes or another unverified runtime as active.

For Agent Zero, `init` also creates only Tree Ring's passive
`needs-plugin` binding. The separate `tree_ring_memory` plugin owns its
absolute, non-project `activation-capability.json` descriptor and uses it
internally after the user selects the mounted project. Only its
descriptor-scoped status and a new-session preflight can advance the runtime
view to `configured-awaiting-proof` and then receipt-backed `active`. There is
no manual descriptor workflow, and the core/plugin release pair must be
compatible before this path is available.

Memory updates are agent-mediated. Maintained lifecycle bridges perform recall
at session and subagent start, then enforce one automatic checkpoint at stop.
The active agent submits zero to three concise durable normal-sensitivity
candidates through strict `tree-ring capture`; manual `remember` and `evidence`
remain separate surfaces. Zero is correct when nothing reusable occurred.
Tree Ring does not scrape transcripts, run a hidden recorder, or turn TUI event
streams into durable memory without a validated write command.

## Brand Assets

- `assets/tree-ring-memory-logo.png`
- `assets/tree-ring-memory-banner.png`

## Principles

- Local-first by default.
- Protocol before adapters.
- Explainable recall.
- Sensitive data fails closed.
- Forgetting and supersession are first-class.
- Memory quality should be testable.

Installer onboarding (`welcome --init`) initializes the same project activation
manifest and safe, create-only harness bridges as `init` starting in CLI 0.15.7.
Existing user hooks and memory stores are preserved. Onboarding reports each
harness state; automatic use still requires host trust and a fresh receipt.

前置环境：macOS ARM64 或 Linux x86_64（README 明确验证的预编译平台）；源码安装需 Rust 与 Cargo；可选 Homebrew。权限：本地文件系统写入，同主机共享写入需 TREE_RING_COORDINATOR_TOKEN；Coordinated 模式下不同操作需 coordinator 能力。模型/API Key：README 未说明需要模型密钥，待核验。费用：资料未说明收费项目，待核验。境外依赖：GitHub raw、GitHub Pages、Homebrew tap；国内可达性待核验。Windows 支持：资料未说明，待核验。