> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Replication & Sync

> How write-behind replication works, recovery semantics, and conflict resolution.

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 `POST`s it to `/replicate`.

| Outcome           | Effect                                                                             |
| ----------------- | ---------------------------------------------------------------------------------- |
| `200`             | The rows in that block flip to `synced`.                                           |
| Transient failure | Rows stay `pending`; the next poll cycle retries automatically.                    |
| `401`             | The worker halts permanently — this is an auth error, not something a retry fixes. |

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](/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.