diff --git a/README.md b/README.md index 094c1dc..e4e1e5d 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,11 @@ ![Tree Ring Memory retro roller-rink banner](assets/tree-ring-memory-banner.png) -Tree Ring Memory is a framework-agnostic 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 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 @@ -12,37 +14,43 @@ 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. -## Status - -Tree Ring Memory is in protocol-preview status. - -Launch feedback is being collected in -[GitHub issue #26](https://github.com/TerminallyLazy/Tree-Ring-Memory/issues/26): -try the installer, run the first commands, and report where agent memory breaks -or which framework bridge should come next. - -Launch page: - -Launch release: - -Launch discussion: +Tree Ring Memory is in protocol-preview status. Current launch links: -Rust-native CLI article: +- Launch page: +- Launch release: +- Launch discussion: +- Rust-native CLI article: +- Feedback issue: +- Homebrew tap: -Homebrew tap: +
+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 adds Rust-owned JSONL import/export with privacy-preserving defaults across the CLI. -- v0.5 adds Rust-owned audit checks for stale, sensitive, low-confidence, supersession, and contradiction candidates. -- v0.6 adds Rust-owned deterministic consolidation with idempotent summary records and cautious sensitive-memory handling. -- v0.7 makes the public facade Rust-native only and adds Rust-owned maintenance for expiry, secret redaction, and FTS repair. -- v0.8 removes Python-owned runtime behavior. -- v0.9 removes tracked Python source, tests, smoke scripts, and the optional CPython extension from the canonical repo. -- v0.10 adds a one-line installer plus Rust-native terminal onboarding with animated terminal tree rings. -- v0.11 makes the repo fully Rust-native, wires TUI export/consolidation actions, adds DOX/Revolve sync adapters, and adds agent-framework discovery. -- The Rust CLI also includes a Ratatui operator console behind `tree-ring tui`. +- 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. + +
+ +## 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. +- 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: @@ -55,7 +63,32 @@ 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. -## Install +## 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. + +![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 Global user install: @@ -76,6 +109,27 @@ Project-local install with first-run initialization: curl -fsSL https://raw.githubusercontent.com/TerminallyLazy/Tree-Ring-Memory/main/install.sh | sh -s -- --project --init ``` +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 + 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 @@ -146,19 +200,6 @@ Open the terminal console after a project-local install: .tree-ring/bin/tree-ring --root .tree-ring tui ``` -## First Example - -```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 -``` - ## CLI Preview The `tree-ring` command is the Rust CLI. @@ -265,7 +306,8 @@ tree-ring integrations certify --source-root . states are evidence records, not broad compatibility claims. - `recall-quality` writes non-private recall diagnostics under `target/tree-ring-certification/recall-quality/default-fixture-v1.json` - and merges the result into `evidence-index.json`. It uses deterministic + 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`. @@ -393,18 +435,26 @@ 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` and `metrics.json`. +`target/tree-ring-certification/summary.md`, +`target/tree-ring-certification/metrics.json`, and +`target/tree-ring-certification/evidence-index.json`. -Latest local certification run, generated at `2026-07-09T02:42:24Z` with -Agent Zero plugin smoke enabled: +Most recent branch-local certification run, generated at +`2026-07-09T15:34:52Z`: -- Release binary: 6,104,272 bytes. -- Project install with init: 6,032 KB. -- Global install: 5,988 KB. +- Release binary: 6,352,528 bytes. +- Project install with init: 6,272 KB. +- Global install: 6,228 KB. - CLI import: 10,000 memories in 5 seconds, about 2,000/sec. -- 10k recall max: 6.740 ms. -- 30k recall max: 14.705 ms. -- Agent Zero plugin smoke: passed. +- 10k recall: 3.643 ms average, 6.499 ms max. +- 30k recall: 7.608 ms average, 13.634 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.118 ms, max latency 0.370 ms. +- Agent Zero plugin smoke: skipped because `TREE_RING_AGENT_ZERO_ROOT` was not + set. `scripts/package-release.sh` builds the Rust CLI in release mode, creates a platform tarball under `dist/`, and writes a SHA-256 checksum file. Tag pushes diff --git a/docs/assets/readme-tui-dashboard.png b/docs/assets/readme-tui-dashboard.png new file mode 100644 index 0000000..48f5e62 Binary files /dev/null and b/docs/assets/readme-tui-dashboard.png differ diff --git a/docs/assets/readme-tui-evidence.png b/docs/assets/readme-tui-evidence.png new file mode 100644 index 0000000..3b689b0 Binary files /dev/null and b/docs/assets/readme-tui-evidence.png differ diff --git a/docs/assets/readme-tui-integrations.png b/docs/assets/readme-tui-integrations.png new file mode 100644 index 0000000..6449f28 Binary files /dev/null and b/docs/assets/readme-tui-integrations.png differ diff --git a/docs/assets/readme-tui-search.png b/docs/assets/readme-tui-search.png new file mode 100644 index 0000000..6a4eac4 Binary files /dev/null and b/docs/assets/readme-tui-search.png differ