Tree Ring Memory

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 and the evidence-driven improvement loop in Revolve, with a deliberate nod to their original creator, Jan Tomášek. 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.14.0
• Launch discussion: #27
• Rust-native CLI article: https://terminallylazy.github.io/Tree-Ring-Memory/launch/rust-native-agent-memory-cli.md
• Feedback issue: #26
• Homebrew tap: https://github.com/TerminallyLazy/homebrew-tree-ring

Protocol preview history

• 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.

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.

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.

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

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

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

Quick Start

Activate project-local harnesses

tree-ring init
tree-ring integrations status

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

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.

Source install (requires Rust and Cargo):

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

Linux x86_64 prebuilt install (glibc 2.36 or newer):

curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- \
  --archive-url https://github.com/TerminallyLazy/Tree-Ring-Memory/releases/download/v0.14.0/tree-ring-memory-0.14.0-linux-x86_64.tar.gz \
  --archive-sha256 c72191aca81f195472272a1962df354fe0af04a08b01a7472a1faf987cd177fa

macOS ARM64 install with Homebrew:

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

Project-local source install with first-run initialization (requires Cargo):

curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init

Store the first project memory:

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:

tree-ring tui

Install Details

The installer builds the Rust CLI with cargo, installs tree-ring, then shows one stable terminal onboarding screen with a branded terminal ring and the next useful commands. For global installs, it also adds the install bin directory to your 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, 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:

sh install.sh --help
sh install.sh --project --init
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 --archive-url https://example/tree-ring-memory-0.14.0-darwin-arm64.tar.gz --archive-sha256 <sha256>

After install, rerun onboarding anytime:

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 builds can use --archive-url plus --archive-sha256 to install a prebuilt tree-ring binary archive.

Open the terminal console after a global install:

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:

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

Open the terminal console after a project-local install:

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

CLI Preview

The tree-ring command is the Rust CLI.

tree-ring init
tree-ring remember "Use protocol-first design." --event-type decision --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 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.
• evidence is the Revolve-inspired improvement-loop entry point for evaluated outcomes.
• dox sync and revolve sync are read-only source adapters that summarize and point back to authoritative files.
• 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:

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:

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:

tree-ring --root .tree-ring policy enable --coordinator release-coordinator
export TREE_RING_COORDINATOR_TOKEN='<one-time capability printed by enable>'
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. 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:

tree-ring --root .tree-ring policy rotate --coordinator release-coordinator-next
export TREE_RING_COORDINATOR_TOKEN='<new one-time 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.

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.

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:

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.

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:

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:

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.

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.
• 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:

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

Development Checks

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:

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

Agent Workflow Integration

• skills/tree-ring-memory/SKILL.md gives agents portable guidance for when to recall, 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. Bridge files tell the active agent when to call tree-ring recall, tree-ring remember, tree-ring evidence, tree-ring forget, tree-ring consolidate --dry-run, or tree-ring maintain. Tree Ring does not scrape transcripts, run a hidden recorder, or turn TUI event-stream pulses into durable memory without an explicit 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.