How ALF syncs agent memory

ALF doesn't diff lines like git does. Each framework adapter first turns the agent's memory store into memory records — for markdown stores, one record per ## section; for database stores, one record per row. Every record has a stable identity (a UUID) and timestamps.

Every sync then produces a delta with two independent channels:

Channel 2 makes workspace restore always faithful, no matter how a file was edited. Channel 1 is what powers the dashboard, cross-runtime restore, and history — and its quality depends entirely on record identity being stable. That's what reconciliation guarantees: the same memory keeps the same id across syncs, even when the agent rewrites its store in place.

Memory lives in files, so the obvious design is the one git perfected: diff the text, ship line patches, replay them. ALF deliberately doesn't do that, because syncing an agent's memory has different requirements than versioning its source code. The unit that matters is not a line — it's a memory: a thing with a type, a birth date, a provenance, and a lifecycle. The whole design follows from choosing that as the unit of change.

Patches describe text. The consumers need memories.

The sync stream doesn't just feed restore — it feeds the dashboard, search indexing, and (eventually) lineage. Those consumers ask questions like "which memories changed this week?" and "when did this fact first appear?". A record changelog answers them by construction; a patch stream would force every consumer to re-parse workspaces and re-derive meaning. It also keeps the backend honest and cheap: ingest is a blob write plus one atomic sequence check. All semantics live client-side, in the records.

Patches assume a cooperating base. Agents don't cooperate.

A line patch only applies against the exact text it was cut from; under drift it fuzzes, and under conflict it stops and asks a human. There is no human here — syncs run from shutdown hooks and cron on unattended runtimes. Record operations don't have that failure mode: an update replaces record 6f3e wherever and whatever it currently is, and concurrent writers are excluded up front by the sequence check rather than merged after the fact. Nothing in the pipeline can ever emit a conflict marker into an agent's memory.

Identity is resolved once, at write time.

Git stores snapshots and infers what moved or renamed later, per diff, per tool, heuristically. ALF does the inference exactly once — in the reconcile pass, against the last-synced base, deterministically — and then ships the conclusion. Every consumer downstream inherits stable identity for free. That single decision is what lets the dashboard show one memory evolving across months instead of a parade of unrelated records.

Half the fleet's memory isn't text.

ZeroClaw's memory is a SQLite database; Hermes' primary memory is one too. Line diffs don't exist for them. Records give markdown stores and database stores the same unit of change and the same wire format — a section behaves like a row. One mechanism, three very different frameworks, no adapter-specific diff logic anywhere.

And where text fidelity does matter, ALF doesn't diff at all.

The raw channel carries changed files whole, byte-exact — no hunks, no patch application, no risk of a mis-applied edit corrupting a workspace. At memory-file sizes (kilobytes), the bandwidth a line diff would save is noise; deltas are already small because they carry only what changed, and an idle sync uploads nothing at all. The efficiency that matters — not re-uploading unchanged memories — comes from stable identity, not from hunk granularity.

Three properties fall out of this loop. Idle syncs are free — if reconcile finds every record unchanged and no raw bytes differ, nothing is uploaded (no_changes: true). The cloud is an append-only ledger — a delta blob, once written at its sequence, is never rewritten. And identity survives curation — the reconcile step is where an in-place edit becomes a clean update to the same record instead of identity churn.

OpenClaw's MEMORY.md is not a log — the agent curates it: rewrites sections, re-ranks them, drops what stopped mattering. Here is a workspace at the last sync (sequence 2), with the four records ALF extracted from it:

One real agent turn later, the file has been rewritten wholesale: sections re-ranked, the reference code replaced in its slot, a lesson added, the scratch note gone.

Reconcile matches new sections to old records

At sync time, ALF pairs the fresh export against the base — by identical content first, then by heading — and carries each matched record's id and original created_at forward:

The uploaded delta says exactly what happened, and nothing else:

ZeroClaw keeps all agents' memory in one SQLite database, brain.db, one row per memory with a native UUID primary key. ALF exports one agent's slice (WHERE agent_id = ?) and uses the row's own id as the record id. Because identity is stored with the data — not derived from position — this store never had the curation problem: reconciliation just passes it through.

The agent's framework then mutates its memory the normal SQL way:

The next alf sync maps those one-to-one — same native id, same delta op. Unchanged rows match by id + content (pass P0); the edited row keeps its id through the id-equality pass (P3):

Hermes is often lumped in with OpenClaw, but only half of it behaves that way. Its primary memory is a session log in state.db: one record per conversation, keyed by the session's native id. A conversation is never rewritten — a later chat is a new session — so this store is structurally immune to the curation problem and always was.

The lesson generalizes: stores that append with native keys never needed help (Hermes sessions, ZeroClaw rows); stores that are curated in place get their identity from reconciliation (OpenClaw's MEMORY.md, Hermes' notes layer). One mechanism covers all of them — the adapters don't implement any diffing themselves.

The service stores the first sync as a full snapshot at sequence 0 and every later sync as a delta blob at the next sequence. Restore fetches the snapshot plus the deltas after it and replays them; point-in-time restore replays only up to the sequence you ask for.

Because reconciliation keeps ids stable, this ledger is also readable: the dashboard can show record 6f3e as one memory whose content evolved at sequence 3 — not as a parade of unrelated records winking in and out of existence. And because deltas are never rewritten, the curation at sequence 3 destroyed nothing: the pre-curation state is permanently addressable at sequence 2.

Reconciliation is deterministic and threshold-free — five passes, run in order, each consuming the records it matches. Matching is scoped per source file so unrelated files can't cross-pair.

Whatever the structured delta says, the raw channel always carries the changed files byte-exactly — so a same-runtime restore reproduces the workspace precisely, and the structured records can afford to be a clean, semantic history rather than a defensive copy.