Journal & Sync

Each agent in Akshi has a journal — a persistent, append-only log backed by an Automerge CRDT document. Journals sync across nodes in the mesh, giving agents convergent shared state without a central database.

Per-agent Automerge documents

Every agent gets its own Automerge document stored on the local filesystem. The CRDT data structure means:

• Concurrent edits from different nodes merge automatically.
• No coordination or locking is needed between peers.
• After sync, all nodes holding the same agent’s journal converge to the same state (identical Automerge heads).

Sync loop

The sync process runs in a continuous loop:

1. Capture changes — collect new Automerge changes since the last sync.
2. Sign envelope — wrap changes in a sync envelope signed with the node’s Ed25519 key.
3. Deliver to peers — send the envelope to each known peer via the active transport (HTTP or filesystem).
4. Process inbox — receive envelopes from peers, verify signatures, and merge changes into the local document.

HTTP transport

When peers are available, sync envelopes are delivered via:

POST /api/v1/sync/envelopes

The request body contains the signed envelope. The receiving node verifies the signature, checks peer trust, and applies the changes.

Verification

Every incoming envelope is verified before merging:

• Ed25519 signature check — the envelope must be signed by a known peer’s key.
• Peer trust check — the signing DID must be in the node’s trusted peer list.
• DID validation — the DID format and multicodec prefix must be valid.

Envelopes that fail any check are rejected and logged.

Convergence

After a successful sync round, both nodes hold the same Automerge document heads. This is a strong consistency guarantee within the CRDT model — given the same set of changes, all nodes produce the same state regardless of delivery order.