pip install conflux-state

🔥 Why AI Swarms Break Traditional Databases

When 10–30 autonomous agents collaborate on one codebase, research workflow, or incident response room, shared state turns into a bottleneck:

_{Reproduce on your machine in 1 second (zero external dependencies): python examples/silent_overwrite_benchmark.py}

📦 Installation

Install the zero-dependency core protocol + conflux-server + conflux-mcp CLI from PyPI (both import conflux and import conflux_state work out of the box, with full py.typed static type hints):

pip install conflux-state

Optional extras for asymmetric Ed25519 keys and native orchestration frameworks:

pip install "conflux-state[crypto]"        # Ed25519 public-key signing
pip install "conflux-state[langgraph]"     # LangGraph CheckpointSaver + Store
pip install "conflux-state[crewai]"        # CrewAI StorageBackend + FlowPersistence + Tools
pip install "conflux-state[autogen]"       # AutoGen Memory + FunctionTools
pip install "conflux-state[integrations]"  # All framework adapters

🚀 60-Second Quickstart

# Canonical import is `conflux` (`import conflux_state` is also supported as an alias)
from conflux import Cluster, InMemoryTransport, state_hash

# 3 autonomous agents writing concurrently with ZERO locks or coordinator
cluster = Cluster({"planner", "coder", "verifier"}, transport=InMemoryTransport())

cluster.node("planner").counter_inc("swarm.tasks_done", 2)
cluster.node("coder").counter_inc("swarm.tasks_done", 3)
cluster.node("verifier").set_add("swarm.verified_modules", "auth.py")

# Concurrent conflicting proposals on an MVRegister (neither agent has seen the other yet!)
cluster.node("planner").mv_set("arch.cache_layer", "redis-cluster")
cluster.node("coder").mv_set("arch.cache_layer", "in-memory-lru")

# Single anti-entropy gossip sweep -> identical SHA-256 state across all nodes
cluster.gossip_round()

assert cluster.read("planner", "swarm.tasks_done") == 5
assert state_hash(cluster.node("planner").replica.state) == state_hash(cluster.node("coder").replica.state)

# Both concurrent proposals survived the merge! Inspect & causally resolve:
print(cluster.node("verifier").conflicts())
# -> {'arch.cache_layer': [{'agent': 'planner', 'value': 'redis-cluster', ...},
#                          {'agent': 'coder',   'value': 'in-memory-lru', ...}]}

cluster.node("verifier").mv_resolve("arch.cache_layer", "tiered-lru-plus-redis")
cluster.gossip_round()
assert cluster.node("planner").conflicts() == {}
assert cluster.read("planner", "arch.cache_layer") == "tiered-lru-plus-redis"

🧠 Architecture & Lattice CRDTs

  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
  │ Claude Code  │     │  LangGraph   │     │    CrewAI    │     │   AutoGen    │
  │ (conflux-mcp)│     │ Checkpointer │     │ Memory/Flows │     │ Team Memory  │
  └──────┬───────┘     └──────┬───────┘     └──────┬───────┘     └──────┬───────┘
         │  Signed Envelopes (HMAC-SHA256 / Ed25519 + Namespace & Quota Guards)
         ▼                    ▼                    ▼                    ▼
  ┌─────────────────────────────────────────────────────────────────────────────┐
  │                 Conflux Gossip Mesh (TCP / RFC6455 WS / TLS)                │
  │    Node Alpha  ◄───────  Pairwise Anti-Entropy Join  ───────►  Node Beta    │
  │  [Journal + Snapshots]     state = join(a_1, ..., a_n)     [Journal + Snaps]│
  └─────────────────────────────────────────────────────────────────────────────┘

Every key in Conflux lives inside an ORMap over mathematically verified join-semilattices (tests/test_crdts.py & tests/test_mcp.py):

• Idempotent: $a \sqcup a = a$
• Commutative: $a \sqcup b = b \sqcup a$
• Associative: $(a \sqcup b) \sqcup c = a \sqcup (b \sqcup c)$

⚔️ Causal Conflict Preservation & Resolution (MVRegister)

Last-Writer-Wins (LWWRegister) is ideal for status heartbeats, but dangerous when two agents concurrently draft an architecture spec, API schema, or plan while partitioned.

Conflux's MVRegister tracks causal (tick:agent) dots and superseded sets:

1. Sequential updates on a node automatically supersede the dots that node has already seen — behaving like a clean register with zero clutter.
2. True concurrent writes (emitted before gossip sync) preserve every competing agent's value in conflicts() / candidates(key), while read(key) still returns a deterministic canonical winner so readers never crash.
3. Causal resolution (mv_resolve) records a merged value superseding all observed candidate dots — clearing the conflict across the entire cluster permanently (even if delayed pre-resolution gossip arrives later!).

from conflux import Client

with Client("127.0.0.1", 7001, agent_id="lead-reviewer") as c:
    for key, candidates in c.conflicts(prefix="spec.").items():
        print(f"Conflict on {key}: {[cand['value'] for cand in candidates]}")
        c.mv_resolve(key, {"merged": True, "approved_by": "lead-reviewer"})

🔌 MCP Server: Claude Code, Cursor & Windsurf (conflux-mcp)

Run multiple coding or research agents in parallel on the same repository without stepping on each other's files or losing shared context. conflux-mcp is a zero-dependency MCP JSON-RPC 2.0 server supporting both newline-delimited stdio and Content-Length framing.

Add to Claude Desktop / Claude Code / Cursor (mcp.json)

Standalone durable local mode (zero setup):

{
  "mcpServers": {
    "conflux": {
      "command": "conflux-mcp",
      "args": ["--agent-id", "claude-architect", "--data", "./.conflux-mcp"]
    }
  }
}

Multi-agent networked mesh mode (connect N parallel agents to conflux-server):

{
  "mcpServers": {
    "conflux": {
      "command": "conflux-mcp",
      "args": [
        "--agent-id", "cursor-worker-2",
        "--connect", "127.0.0.1:7001",
        "--secret", "worker-2-hmac-secret",
        "--namespace", "repo."
      ]
    }
  }
}

Capabilities Exposed by conflux-mcp

• 13 Specialized MCP Tools:
  • Conflict-Aware State: conflux_mv_write, conflux_conflicts, conflux_resolve_conflict
  • Resource / File Leases: conflux_claim_resource (TTL lease + owner & intent reporting to prevent simultaneous file edits), conflux_release_resource
  • Core CRDTs & Batching: conflux_read, conflux_snapshot, conflux_register_set, conflux_counter_add, conflux_set_add, conflux_set_remove, conflux_batch
  • Reactive Handoffs & Queues: conflux_watch_wait (blocks until a peer updates a key), conflux_task_update
• MCP Prompts (/resolve_state_conflicts, /coordinate_parallel_swarm): One-slash-command workflows that inject live conflicts or swarm coordination rules into the agent's context.
• MCP Resources & URI Templates: conflux://state/snapshot, conflux://state/conflicts, and conflux://key/{key}.

🧩 Drop-In Framework Integrations

Every adapter in conflux.integrations accepts a Replica, Cluster node, Server, or networked Client, works with zero third-party dependencies, and automatically subclasses each framework's native interfaces when installed.

1. LangGraph (ConfluxCheckpointSaver + ConfluxStore)

Pause a StateGraph on Node A, replicate over gossip, and resume the exact same thread_id on Node B — while aggregating cross-thread CRDT counters and sets with zero locks:

from conflux import Client
from conflux.integrations.langgraph import ConfluxCheckpointSaver, ConfluxStore

client = Client("127.0.0.1", 7001, agent_id="planner", secret="s3cr3t")
store = ConfluxStore(client)

graph = builder.compile(
    checkpointer=ConfluxCheckpointSaver(client),
    store=store,
)
graph.invoke({"topic": "CRDTs"}, config={"configurable": {"thread_id": "run-42"}})
store.counter_inc(("metrics", "research"), "queries_executed", by=1)

Runnable demo: examples/langgraph_shared_state.py

2. CrewAI (ConfluxCrewStorage, ConfluxFlowPersistence, create_crewai_tools)

Plug Conflux directly into CrewAI's unified Memory (StorageBackend protocol with cosine-similarity + scoped recall), @persist Flows, and agent CRDT tools:

from crewai import Agent, Crew
from crewai.memory import Memory
from conflux import Client
from conflux.integrations.crewai import ConfluxCrewStorage, create_crewai_tools

client = Client("127.0.0.1", 7001, agent_id="researcher", secret="s3cr3t")
researcher = Agent(
    role="Researcher",
    goal="...",
    backstory="...",
    tools=create_crewai_tools(client, namespace="crew."),
)
crew = Crew(agents=[researcher], tasks=[...], memory=Memory(storage=ConfluxCrewStorage(client)))

Runnable demo: examples/crewai_shared_memory.py

3. AutoGen (ConfluxAutoGenMemory + create_autogen_tools)

Inject converged team memories and live CRDT state keys straight into AutoGen's ChatCompletionContext before every model turn:

from autogen_agentchat.agents import AssistantAgent
from conflux import Client
from conflux.integrations.autogen import ConfluxAutoGenMemory, create_autogen_tools

client = Client("127.0.0.1", 7001, agent_id="coder", secret="s3cr3t")
agent = AssistantAgent(
    name="coder",
    model_client=model_client,
    memory=[ConfluxAutoGenMemory(client, state_watch_prefix="team.")],
    tools=create_autogen_tools(client, namespace="team."),
)

Runnable demo: examples/autogen_shared_state.py

🛡️ Security, Durability & Benchmarks

Cryptographic Authority & Namespace Sandboxing

Equip any Server with an AgentRegistry to enforce HMAC-SHA256 (zero deps) or Ed25519 signatures, operation allowlists, write quotas, and key-prefix namespaces before an action ever merges:

from conflux import AgentRegistry, Client, Server

registry = AgentRegistry()
registry.register(
    "billing-agent",
    secret="hmac-secret-key",
    ops={"counter_inc", "mv_set", "lww_set"},
    namespaces=("billing.",),
    quota=1000,
)

server = Server("alpha", ("127.0.0.1", 7001), registry=registry, data_dir="./data/alpha").start()

Networked CLI Cluster + TLS + Signed Journals + Prometheus

# Start Node Alpha with TLS, HMAC-signed tamper-evident journal, and Prometheus /metrics
conflux-server --id alpha --listen 0.0.0.0:7001 \
    --cert ./cert.pem --key ./key.pem \
    --journal-key "$(openssl rand -hex 16)" \
    --data ./data/alpha --metrics-http

# Start Node Beta peered with Alpha over WebSocket (--transport ws) or TCP
conflux-server --id beta --listen 0.0.0.0:7002 \
    --peers 127.0.0.1:7001 --data ./data/beta

Measured Throughput (python benchmarks/bench.py)

• ~168,000 actions/sec deterministic local journal replay
• ~38,000 actions/sec full-mesh in-memory cluster convergence
• ~0.13 ms single-agent submit → fsync → ack round-trip over TCP (~0.17 ms over RFC6455 WebSocket)

Full formal protocol bounds and security review:

• 📄 Protocol Specification (docs/PROTOCOL.md) — wire framing, lattice join laws, probabilistic hash scale, snapshot compaction, and test conformance index.
• 🔒 Security Threat Model (docs/SECURITY.md) — constant-time signature verification, algorithm binding, replay idempotence, and keyless-reload refusal.

🧪 Running the Test Suite & Demos

python -m pytest                                  # 126 conformance, security, integration & MCP tests
python examples/silent_overwrite_benchmark.py     # 8-agent concurrency benchmark (LWW & SQLite vs CRDTs)
python examples/agent_crew_demo.py                # 6 signed agents + crash + torn journal + auto-heal
python examples/langgraph_shared_state.py         # Cross-node StateGraph pause & resume
python examples/crewai_shared_memory.py           # Signed 2-node TCP CrewAI memory & flow persistence
python examples/autogen_shared_state.py           # AutoGen context injection & CRDT tools

📜 License

Released under the MIT License. Built for deterministic, resilient multi-agent systems.