Slivingdoc: Git Semantics Over S3 for Multi-Agent State Sync

Multi-agent systems fail when agents cannot share context reliably. Slivingdoc tackles this by separating state synchronization from orchestration logic. It combines git-style conflict resolution with S3 persistence, exposing two operations (pull and commit) through a CLI or MCP server. Agents see a directory of UTF-8 text files. The plumbing handles concurrency, merges, and durability.

This is not version control for code. It is a coordination primitive for agent memory.

The State Synchronization Problem

Agent swarms need shared context. When multiple agents run concurrently (different machines, different times, different orchestrators), they must read and write to a common notebook without clobbering each other’s work. Traditional approaches fail:

Databases: Require schema agreement, connection pooling, and transaction logic agents do not have.
File locks: Break when agents crash or run on different hosts.
Event streams: Force agents to replay history to reconstruct state.
Git directly: Agents cannot resolve merge conflicts or manage branches.

Slivingdoc solves this by hiding git semantics behind two operations and using S3 as the single source of truth.

Architecture: Git Conflict Resolution + S3 Persistence

The system has three layers:

Local checkout: A directory of plain text files. Agents read and write with standard file tools.
Merge engine: Git-based conflict resolution that merges local edits with the accepted remote state.
S3 backend: Immutable packs (git objects) plus a single mutable manifest (current) that points to the accepted state.

Pull Operation

GET current manifest from S3
  ↓
Download referenced packs (immutable git objects)
  ↓
Merge remote state with local unpublished edits
  ↓
Write merged files to local directory

Each checkout remembers its baseline (what it last saw). Unpublished local edits are never overwritten. The agent sees only files, never git object IDs or S3 keys.

Commit Operation

Merge local changes with latest remote state
  ↓
Pack result into immutable git objects
  ↓
Upload pack to S3
  ↓
Conditional replace of current manifest (atomic publication)

The delta is computed from the checkout’s baseline. A path that was never pulled is rejected with INVALID_REQUEST before any network work. This forces agents to pull once before committing, preventing blind writes.

Publication is a single conditional replace of the current manifest. If another agent published first, the commit fails and the caller must pull again.

MCP Server Interface

Slivingdoc runs as an MCP server in stdio mode. It exposes two tools:

notes_pull(path): Pulls the notebook into the specified directory.
notes_commit(path, message): Commits changes from that directory with a log message.

Agents call these tools through the Model Context Protocol. They do not see git commands, branches, or merge syntax. The directory is the entire interface.

Example agent interaction:

# Agent pulls notebook
result = mcp_client.call_tool("notes_pull", {"path": "/workspace/agent1"})

# Agent reads and writes files
with open("/workspace/agent1/context.txt", "a") as f:
    f.write("Processed 42 records\n")

# Agent commits changes
result = mcp_client.call_tool("notes_commit", {
    "path": "/workspace/agent1",
    "message": "Updated record count"
})

The MCP server handles all git and S3 operations. The agent sees only success or failure.

Concurrency Guarantees

Multiple agents can pull and commit concurrently. The system serializes writes through the atomic current manifest update.

Scenario	Behavior
Two agents pull simultaneously	Both get the same accepted state. No conflict.
Two agents commit simultaneously	One succeeds. The other’s conditional replace fails. Loser must pull and retry.
Agent pulls, another commits, first agent commits	First agent’s commit fails. Must pull to merge the new state, then retry.
Agent crashes mid-commit	Pack upload succeeds (immutable), but manifest update fails. No corruption. Next pull sees old state.
S3 eventual consistency delay	Conditional replace uses strong consistency. Reads may lag, but writes are serialized.

The baseline tracking prevents lost updates. If an agent pulls at version N, edits locally, and tries to commit when the remote is at version N+5, the commit merges all intermediate changes before publishing.

Why S3 Instead of a Database

S3 provides three properties databases do not:

Immutable storage: Packs are written once, never modified. No update anomalies.
Global accessibility: Any agent with credentials can access the bucket, regardless of network topology.
Built-in backup: S3 versioning and replication are infrastructure primitives, not application concerns.

The trade-off is latency. Each pull and commit involves network round trips. This is acceptable for agent context (minutes to hours between operations), not for high-frequency state machines (milliseconds).

Failure Modes and Recovery

Network partition during commit: Pack upload succeeds, manifest update fails. The pack is orphaned but harmless. Next pull sees the old state. The agent retries the commit, uploading a new pack.

Corrupted local checkout: Pull again. The merge engine reconstructs the accepted state from S3 and re-merges local edits.

S3 bucket deleted: All state is lost. Slivingdoc has no local-first fallback. Backup the bucket with S3 versioning or cross-region replication.

Merge conflict the engine cannot resolve: Currently unspecified. Git’s conflict markers would appear in files, but agents cannot parse them. This is a known gap.

Agent writes binary files: Rejected. Slivingdoc only handles UTF-8 text. Binary blobs break the merge engine.

Deployment Shape

Run as a CLI tool or MCP server. No daemon, no background sync. Files move only on explicit pull and commit.

CLI mode:

slivingdoc pull
# edit files
slivingdoc commit -m "agent updated context"

MCP server mode:

slivingdoc mcp-server --stdio

The MCP server reads tool calls from stdin and writes responses to stdout. The orchestrator (e.g., a LangGraph runner or custom agent loop) manages the server process.

Configuration is environment variables:

S3_BUCKET: The bucket name.
S3_REGION: AWS region.
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY: Credentials.

No config files, no state database, no schema migrations.

Observability Gaps

Slivingdoc has no built-in observability. You cannot see:

How many agents are active.
Which agent last committed.
Commit history (no log command).
Merge conflicts that were auto-resolved.

The current manifest contains a pointer to the latest pack, but no metadata about who wrote it or when. You must instrument the orchestrator to log tool calls.

For production use, wrap the MCP server in a proxy that logs every notes_pull and notes_commit call with agent ID and timestamp.

Security Boundaries

All agents share the same S3 bucket and see the entire notebook. There is no per-agent isolation, no access control within the notebook, and no encryption at rest beyond S3’s server-side encryption.

If one agent is compromised, it can read and overwrite all shared context. Mitigation strategies:

Use separate buckets for different trust zones.
Run Slivingdoc in a sandboxed environment with scoped IAM roles.
Audit S3 access logs to detect anomalous commit patterns.

The MCP server runs with the same privileges as the orchestrator process. If the orchestrator is compromised, so is the notebook.

Technical Verdict

Use Slivingdoc when:

You have multiple agents that need to share context across runs or hosts.
Agents run asynchronously (minutes to hours between operations).
You want durable storage without managing a database.
You can tolerate S3 latency and eventual consistency for reads.

Avoid Slivingdoc when:

Agents need sub-second state updates (use Redis or a message queue).
You need per-agent access control or audit trails (build a proxy layer first).
Agents must handle binary data (Slivingdoc rejects it).
You require merge conflict resolution beyond git’s automatic merging (agents cannot parse conflict markers).

The separation of state synchronization from orchestration logic is the key insight. Slivingdoc does not solve swarm coordination, but it removes one failure mode: agents losing context because they cannot share state reliably.

Agentic AI, minus the noise.