Tree Ring Memory for Agent Zero

This plugin is an Agent Zero bridge to the Rust-native Tree Ring Memory CLI. Plugin version 2.1.0 targets the upstream tree-ring 0.12 command and JSON contracts; it does not maintain a second Python memory engine.

The Rust CLI owns validation, sensitivity classification, SQLite/FTS storage, recall ranking, import/export, audit, consolidation, maintenance, DOX/Revolve adapters, and integration discovery. The plugin owns only Agent Zero tools, API envelopes, Web UI shaping, safe host paths, runtime status, and legacy migration.

Install

In Agent Zero, open Plugins → Install, choose the Git repository option, and use:

https://github.com/TerminallyLazy/tree-ring-memory-agent-zero

The installer clones this repository into usr/plugins/tree_ring_memory, then hooks.py automatically validates the packaged CLI, initializes the Rust store, imports a pending Python-v1 store through the validated migration path, and audits the result. Existing memory under usr/memory/tree_ring_memory is preserved across updates and uninstall. The community marketplace entry uses the same repository and manifest.

Requirements

• Agent Zero with this directory mounted at /a0/usr/plugins/tree_ring_memory/.
• An executable tree-ring 0.12.x binary. The plugin requires at least 0.12.0 and fails closed on other minor versions. The published plugin bundles Linux binaries for Agent Zero's x86_64 and aarch64 Docker runtimes.
• Python 3.12+ in the Agent Zero framework runtime.

Binary discovery order:

1. TREE_RING_MEMORY_CLI or cli.binary.
2. /a0/usr/plugins/tree_ring_memory/bin/linux-<architecture>/tree-ring.
3. /a0/usr/plugins/tree_ring_memory/bin/tree-ring for an operator-supplied generic fallback.
4. <memory-root>/bin/tree-ring.
5. tree-ring on the framework runtime PATH.

Readiness is visible in the plugin settings and Tree Ring Memory dashboard. There is no manual Execute step.

Both published Linux binaries are built from the exact upstream v0.12.0 tag in matching Rust Linux environments. Building the x86-64 target on Debian Bookworm also avoids the newer GLIBC requirement of the upstream release archive, while upstream v0.12.0 does not publish a Linux ARM64 archive at all. Operators on another platform can use Tree Ring's official installer or build from source, then configure cli.binary or place the executable at usr/plugins/tree_ring_memory/bin/tree-ring.

The install hook selects only the executable already packaged for the running Docker architecture; it does not download or build executable code. Any replacement binary remains an explicit operator action.

Storage

The default memory root remains:

/a0/usr/memory/tree_ring_memory/

The current Rust-owned database is:

/a0/usr/memory/tree_ring_memory/memory.sqlite

The Python-v1 database is preserved as read-only migration input:

/a0/usr/memory/tree_ring_memory/indexes/memory.sqlite

Uninstall preserves both stores. Removing the memory root remains a deliberate operator action outside automatic plugin lifecycle handling.

Legacy Migration

Migration never edits or deletes the old SQLite database. During install or update, hooks.py reads raw_json, normalizes Python-v1 null/string and chat-scope differences, writes a mode-0600 temporary JSONL file, validates that file with tree-ring import --dry-run, and only then imports it through the Rust CLI. The temporary file is removed after the attempt.

Migration is idempotent. A marker under <memory-root>/migrations/ prevents accidental repeats, while the Rust importer skips duplicate IDs by default. The original legacy database remains available as read-only recovery input.

Agent Tools

• remember: concise memory through the upstream remember surface.
• evidence: evaluated outcomes with a required evidence reference.
• recall: Rust-ranked recall with optional Agent Zero ring/event post-filters.
• forget: explicit-ID delete or redact.
• consolidate: daily, weekly, monthly, yearly, or manual consolidation.
• audit_memory: non-mutating quality, privacy, and integrity audit.
• maintain_memory: dry-run maintenance or explicit expiry/redaction/FTS repair.
• sync_dox: DOX source adapter; dry-run by default.
• sync_revolve: Revolve evidence adapter; dry-run by default.
• import_memory: dry-run by default, with optional duplicate replacement.
• export_memory: canonical JSONL export.

The v0.12 CLI does not expose query-wide forget, selected-memory export, Markdown/SQLite export, expiry, or supersession as scriptable commands. The plugin returns an explicit unsupported-operation error for those former Python-v1 surfaces.

Web UI

The panel provides runtime readiness, search, ring/event filters, memory detail, ring-derived copies, delete/redact, consolidation, safe DOX/Revolve previews, audit, and canonical JSONL export. Its concentric Tree Ring visual illuminates each ring relative to the busiest ring, while the adjacent ledger shows exact record counts and share of the store; selecting a ring filters the live results. The settings view contains only values the bridge actually consumes: binary/version/timeout, storage paths, and recall limits.

When the CLI is missing or incompatible, the panel stays available and shows the concrete readiness error instead of initializing a second store.

Lifecycle and Maintenance

hooks.py owns automatic setup. Its install hook is idempotent, and Agent Zero runs it after both fresh installs and updates. The configuration hook provides a second idempotent bootstrap path after an update so older installations cannot remain dependent on the removed execute.py script. Before an update, the hook exports the initialized canonical store as a recovery snapshot.

Interactive audit, consolidation, FTS repair, DOX/Revolve previews, import preview, and export remain available through the Web UI and Agent Zero tools. Sensitive recall and export remain opt-in. DOX AGENTS.md, Revolve evidence, current source, tests, and explicit user instructions remain authoritative over recalled memory.

Verification

Focused tests use temporary roots and make no network calls. Set TREE_RING_MEMORY_CLI to include the real Rust round trip:

TREE_RING_MEMORY_CLI=/path/to/tree-ring \
PYTHONPATH="$PWD" \
PYTHONDONTWRITEBYTECODE=1 \
python3 -m pytest -q -p no:cacheprovider usr/plugins/tree_ring_memory/tests

node --check usr/plugins/tree_ring_memory/webui/memory-store.js

For upstream certification, put the freshly built target/release/tree-ring on PATH and set TREE_RING_AGENT_ZERO_ROOT to this Agent Zero checkout.

Contribution Boundary

Keep implementation under usr/plugins/tree_ring_memory/ and the companion guidance under usr/skills/tree-ring-memory/. Do not modify Agent Zero core code for this integration. If upstream changes its CLI or JSON schema, update the adapter and version gate together, then rerun the real CLI and legacy-copy proofs before changing the supported series.