zkr

Evidence-backed temporal memory for personal agents.

zkr keeps source evidence authoritative, represents facts as temporal claims, and produces bounded retrieval packs with citations. Raw captures remain searchable before a claim is extracted. Embeddings and search indexes are projections that can be rebuilt from the stored evidence.

Principles

• Sources and evidence are authoritative; indexes are disposable.
• Claims keep both when they were true and when they were recorded.
• Corrections supersede history instead of silently rewriting it.
• Retrieval is bounded, tenant-scoped, and cited.
• Accepted claims replace their supporting raw capture in results instead of duplicating it.
• Reflection suggestions stay outside durable memory until a caller explicitly stores cited evidence, a claim, a correction, a profile projection, or a review.

See the architecture, embedding design, and memory-system research.

Transcript captures can include an optional locator with device_id, provider, stream_id, segment_id, start_ms, and end_ms. The locator remains attached to its evidence citation and can be retrieved with the locator CLI command. Library callers can use MemoryDb::remember_with_locator without changing existing RememberInput code.

Install

cargo install zkr

The library is consumed as the zkr crate. The CLI reads one JSON object of at most 1 MiB from stdin and writes one JSON object to stdout.

printf '%s' '{"tenant_id":"local","person_id":"me","kind":"conversation","text":"I prefer short plans.","captured_at":1784615483,"recorded_at":1784615484,"claim":{"subject":"me","predicate":"prefers","value":"short plans","kind":"preference","valid_from":1784615483}}' \
  | zkr --db ~/.zkr/memory.db remember

printf '%s' '{"tenant_id":"local","person_id":"me","query":"plans","limit":5}' \
  | zkr --db ~/.zkr/memory.db search

correct requires separate valid_at and recorded_at values. Add an as_of object with those same keys to search only when bitemporal history is required; ordinary retrieval returns current supported claims. Run zkr --help for link, profile, profiles, delete, review, reviews, projections, embed, and export. link records supporting or contradicting evidence without changing a claim. profile derives its key and value from a live profile_fact claim and keeps one current projection per scoped key. projections returns bounded stale or missing work with the exact text, revision, and SHA-256 hash required by embed. Retrieval excerpts are capped at 4096 UTF-8 bytes while retaining their evidence citation.

export returns a bounded, tenant/person-scoped page of authoritative commits. Send export_format: 1 and start with after_commit: 0; keep the first page's high_water_mark fixed while requesting later pages with next_after_commit and next_after_event_index so one export observes a stable boundary. A host must stage contiguous event indexes from zero through event_count - 1 for each commit, verify the declared count, atomically apply the complete commit, and only then acknowledge and durably advance its applied cursor. Request cursors may move while staging, but they are not proof that a commit was applied. Each serialized authoritative record shares the CLI request boundary's 1 MiB compatibility limit; an oversized write or migration fails explicitly and atomically. The feed includes durable sources, evidence, claims, links, corrections, deletions, profiles, and reviews. It excludes embeddings and FTS indexes because they are rebuildable projections. The host owns authentication, transport, retries, acknowledgement state, and destination policy. Migration from schema v7 bootstraps the durable rows visible at upgrade time but cannot reconstruct explicit correction lineage that predates the v8 commit feed.

Agent plugins

Native plugin sources are available from the repository checkout and are not included in the crates.io package.

OpenClaw

Link or copy plugins/openclaw into an OpenClaw extension location, install it with Bun, then enable the zkr memory slot. It implements OpenClaw's native memory capability plus memory_search and memory_get, while preserving the explicit zkr_* tools. Its optional command, database, tenant, and person settings default to zkr, ~/.zkr/memory.db, openclaw, and the active agent ID. The plugin is tested against OpenClaw 2026.7.1-2 (plugin API and gateway); its Bun ES module sources invoke only the local zkr CLI, so it does not provide an embedding service, telemetry, host scheduling, or agent lifecycle management.

Hermes Agent

Link or copy plugins/hermes to $HERMES_HOME/plugins/zkr, then set:

memory:
  provider: zkr

Both plugins expose store, search, correction, deletion, and cited reflection through the neutral CLI. Hermes supports Hermes Agent 0.19.0 and Python 3.11–3.13 through its native Python MemoryProvider contract, keeps captured_at, valid_from, and recorded_at distinct, persists completed turns to a local write-behind queue before returning, recovers pending turns on startup, flushes on shutdown, and skips non-primary agent contexts. Queue records outside the configured tenant and person are quarantined. The plugins do not add framework dependencies to the Rust crate.

Development

OpenClaw's real loader requires Node's node:sqlite, so it cannot run under this repository's Bun-only JavaScript gates. The plugin tests compile against the installed SDK, exercise capability registration and runtime search/read behavior, and build the distributable; run openclaw plugins inspect zkr --runtime in a supported OpenClaw Node runtime for the external loader check.

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo check --all-targets --all-features
cargo test --all-features

License

ISC

Acknowledgements

The systems and research that informed zkr are listed in ACKNOWLEDGEMENTS.md.