Storage & audit

Bezial needs the guarantees git gives a shared repository - version history, provenance, rollback - but git itself is dev-facing and a poor fit for how agents manage memory. So Bezial reimplements those guarantees over a flat, versioned object store and an append-only audit log. There is no git anywhere.

The object store

ObjectStore is the storage abstraction. FilesystemObjectStore is the local dev and test adapter; Cloudflare R2 implements the same interface in production (chosen for zero egress fees and conditional writes).

It models object versioning directly:

• Every put creates a new immutable version - history is append-only.
• A restore of an older version is itself a new write, never a mutation or deletion of history.
• The filesystem adapter is content-addressed (blobs/<sha256>, deduped across versions) with per-key ordered version metadata (refs/<key>.json).

So a document’s full history is always recoverable, and rolling back is just writing a prior version forward.

Spaces

A space is one object-store namespace (spaces/<id>/documents/...) plus its own append-only change log and its own graph partition. Spaces are isolated by construction and scale to many namespaces cheaply - thousands of them is not a special case. Everything - documents, versions, audit entries, the derived graph - is scoped to a space.

The write path

The write path is server-owned, serialized per file (a keyed async mutex), and last-writer-wins.

• add(principal, text) appends to the caller’s dated author-log note (<id>/<date>.md).
• write(principal, path, content) replaces a document.
• Concurrent writes to the same file never interleave; writes to different files run freely.
• Files are strongly consistent: a read reflects committed writes immediately (read-your-writes). Only the derived graph lags, and recall settles the relevant pending changes before answering.

The append-only audit log

Every space has one change log, and it exposes only append and list - no update, no delete. Every write attempt records:

• who - the acting principal id,
• what - the action (add / write / restore) and the document path,
• when - the timestamp,
• the permission-check result - including denials, which write nothing but are still logged,
• the diff - what changed, and the from/to versions.

This log is the provenance, the audit trail, and the compliance record in one place. It replaces git blame and git log: “who added this, and when, and were they allowed to?” is a query against the log, filtered to the entries the caller may see.

// Every mutation is recorded; audit is permission-filtered to the caller.
const entries = await alice.audit('team', { path: 'alice/preferences.md' });

Why not git

Git is built for developers merging source code, not for agents continuously appending and revising memory. Its guarantees are the valuable part; its interface, its merge model, and its assumptions are not. Reimplementing versioning and provenance over an object store keeps those guarantees while making the substrate serverless, per-space, and shaped for how memory is actually written. See Multiplayer for how a shared space builds on this.