Agent Bookkeeper is a reusable archive-search system for agent-session evidence: local discovery, reliable delivery, durable storage, revision-aware cataloging, and provenance-bearing retrieval. It gives agents one trustworthy, replayable source of historical records without coupling them to an individual workstation or storage topology.
It complements, rather than replaces, an overall memory system such as Agent Historian:
- Bookkeeper records what happened and makes the raw evidence durably available.
- Its archive-search backend indexes that evidence for semantic and keyword retrieval.
- The current checkout, repository documentation, and decision records remain authoritative over any derived historical interpretation.
V1.5 implementation is underway. The current checkpoint implements the shared Rust domain and durable SQLite event catalog, with fixtures for canonical revisions, path-independent identity, moves, rewrites, tombstones/restores, and multiple records per session. It also has a guarded read-only filesystem scanner with a versioned Codex rollout schema, durable scan state, guarded tombstone grace, held-descriptor validation for borrowed source bytes, and a durable subscription/lease ledger that preserves per-record version ordering. A bounded path-consumer proof harness creates verified lease-scoped copies instead of exposing mutable source paths, and demonstrates idempotent redelivery with a fake adapter. The current library also exposes content-free catalog status and SQLite-aware backup/validation/restore helpers for the durable control ledger. It includes an explicit byte-budgeted integrity scrub with a durable cursor, so steady scans can stay metadata-only while unchanged records are still rehashed over time, plus measurement helpers for elapsed/CPU/memory/throughput evidence. The materialization cache uses an exclusive controller lock and reclaims recognized crash leftovers. A controlled MemPalace CLI adapter now passes only verified lease-scoped paths, provides a stable Bookkeeper record source ID, and writes durable provenance receipts. It is ready for a bounded operator cohort, not a standing worker or a general promotion claim.
The agent-bookkeeper-mempalace-controller binary is the corresponding
explicit one-shot runner. It requires absolute operator-supplied paths, two
stability scans, a hash budget, a hard per-record cohort limit, a delivery
count/byte limit, and a local MemPalace CLI. An optional source-relative include
manifest makes a cohort an exact allowlist rather than a size-limited prefix of
a larger archive. The controller owns only its SQLite ledger, lease cache, and
receipts; it never performs client transport or starts a timer. Its optional
Dockerfile provides an image layer while the operator supplies all runtime
paths, endpoints, and limits.
See implementation status.
V2's protocol is detailed but intentionally not frozen until the shared V1.5 domain model passes its gates. The plan is staged:
- V1 — external mirror: a minimal, reliable raw-file mirror using an operator-provided destination.
- V1.5 — catalog and controller: revision-aware discovery and independent consumer cursors over the V1 mirror.
- V2 — service-owned transport: a self-contained archive service with a local asynchronous client and incremental uploads.
The raw archive remains canonical throughout. V1.5 combines current external bytes with a durable metadata ledger; V2 combines committed objects and receipts. Derived projections, materialization caches, indexes, and consumer output must be safe to discard and rebuild.
The central evolution rule is: V1.5 establishes stable identity, revisions, the event ledger, and consumer delivery; V2 reuses those contracts and adds the client, upload API, canonical object store and receipts, verified payload reader, and rebuildable current projection.
- Architecture — scope, ownership, and data flow.
- Versioned design — V1, V1.5, and V2 decisions.
- Domain contract — producer/session/record identity, canonical revisions, ordering, and clocks.
- Payload and delivery contract — verified bytes, per-record ordering, settled outcomes, and replay modes.
- Durability contract — root guards, hashing/scrub, SQLite backup, receipts, cache, and crash recovery.
- Design review closure — resolution and proof mapping for the ten pre-implementation gaps.
- V1.5 design — catalog, reconciliation, durable events, and consumer delivery.
- V2 design — asynchronous client, chunk transport, archive storage, and commit protocol.
- Evolution boundary — overlap, dependencies, reuse, and cutover gates.
- Transport contract — identities, revisions, delivery, and durability semantics.
- Proof plan — functional and operational acceptance gates.
- Implementation status — implemented slices and remaining proof work.
- V1.5 checkpoint audit — fixture-proven behavior and the next deployment cohort.
- A proprietary transcript format.
- Learned-memory authoring or policy.
- A hard-coded server, network, cloud account, or storage backend.
- Running heavyweight work inside a lifecycle hook.
rtk cargo fmt --check
rtk cargo clippy --all-targets -- -D warnings
rtk cargo test
rtk git diff --checkInspect controller arguments with:
rtk cargo run --bin agent-bookkeeper-mempalace-controller -- --helpLicense selection is intentionally deferred until an implementation is ready to publish.