Skip to main content
Write-behind replication is how a local @sovseal/mcp-server or SDK instance keeps an encrypted, off-device copy of its memory store without blocking on the network for every write.

​
How it works

A background sync worker polls the local LanceDB store every SOVSEAL_SYNC_INTERVAL_MS (default 2000 ms) for rows marked sync_status: 'pending'. It bundles them into AES-256-GCM encrypted blocks — capped at 64 KB ciphertext per block, well under the server’s 256 KB hard limit — assigns each block the next monotonic sequence_number from a durable cursor persisted at ~/.sovseal/state.json, and POSTs it to /replicate. The worker drains at most 5,000 rows per poll cycle, so a burst of writes doesn’t produce one unbounded batch.

​
Crash safety

Crash safety comes from LanceDB’s own write-ahead log, not from the sync worker: the MCP tool handler commits a memory row to disk before returning success to the caller, so a worker that crashes or was never running picks the row up on its next start. The sync cursor is only persisted to state.json after a block’s rows have actually flipped to synced — a crash mid-flight simply replays that block on restart, and the server’s (agent_id, sequence_number) idempotency check makes that replay a no-op rather than a duplicate.

​
Conflict resolution: fails closed, not automatic merge

sovseal does not attempt automatic conflict resolution. If the sync worker detects that another writer already holds a different block at the same sequence_number — a split-brain condition, typically two devices whose local cursors have diverged — it halts immediately rather than guessing which version is correct. The affected rows stay pending, sync stops for that agent entirely, and the worker logs which sequence numbers conflicted. Resolving a split-brain requires reconciling the divergent devices manually before sync can resume; there is no server-side merge. The other two halt conditions are auth_error (a 401 from /replicate, per the table above) and trial_expired.

​
Where this fits

Replication is separate from the newer store/recall semantic-memory API (see SDK Reference: Overview) — store/recall talk to the local engine over IPC and have no sync/replication step at all. Write-behind replication applies to snapshot/restore-style zero-knowledge state checkpointing and to the MCP server’s local memory store when a paid sov_live_ key is configured.