swarmstate

Drop-in state backend for LangGraph, CrewAI & custom agent loops - Rust core, framework-agnostic, built for production.

~12.8× faster checkpoint writes than SqliteSaver on LangGraph's interface, and O(1) state snapshots (hundreds of thousands× faster than a deepcopy on large state). Reproducible numbers → swarmstate.github.io/benchmarks.

swarmstate is a state and checkpointing backend with a Rust core and a Python API for multi-agent systems. It does not compete with visible agent frameworks; it acts as low-level infrastructure - much like engines such as DuckDB, ClickHouse, Arrow, or Polars sit underneath data applications without replacing them.

It solves three production pains:

  1. State lock-in across frameworks - a framework-agnostic store so migrating frameworks doesn't lose state.
  2. Checkpointing cost and latency - a Rust-backed implementation of LangGraph's checkpointer interface.
  3. Deterministic routing paid for in tokens - a native handoff graph that resolves rule-based transitions in microseconds.

Installation

pip install swarmstate            # prebuilt abi3 wheels, no compiler required
uv add swarmstate                 # or with uv

Optional extras: swarmstate[langgraph], swarmstate[crewai], swarmstate[redis], swarmstate[disk], swarmstate[postgres], swarmstate[otel], swarmstate[all].

Usage

import swarmstate as ss

store = ss.Store()                              # in-memory, msgpack codec
store.set("workflow", "onboarding", {"step": 3, "data": {...}})
snap = store.snapshot()                          # cheap, immutable snapshot
store.set("workflow", "onboarding", {"step": 4})
store.restore(snap)                              # rollback
store.get("workflow", "onboarding")              # -> {"step": 3, "data": {...}}

snap2 = store.snapshot()
snap2.diff(snap)                                 # {"added": [...], "removed": [...], "changed": [...]}

# Batch ops: one GIL release / round-trip for the whole set
store.set_many([("workflow", "a", {...}), ("workflow", "b", {...})])
store.get_many([("workflow", "a"), ("workflow", "b")])   # -> [..., ...], order preserved

# Deterministic, LLM-free routing (resolved natively in Rust)
g = ss.HandoffGraph()
g.add_edge("triage", "billing", when="category == 'billing'")
g.add_edge("triage", "human")                    # unconditional default
g.route("triage", {"category": "billing"})       # -> "billing"

Drop-in LangGraph checkpointer (pip install "swarmstate[langgraph]"):

from swarmstate.integrations.langgraph import SwarmStateSaver

graph = builder.compile(checkpointer=SwarmStateSaver())   # replaces SqliteSaver, 1 line

Optional metrics on checkpoint operations (opt-in, zero overhead when unused):

from swarmstate.observability import InMemoryMetrics       # or OpenTelemetryMetrics

metrics = InMemoryMetrics()
saver = SwarmStateSaver(metrics=metrics)
# ... run the graph ...
metrics.summary()   # {"put": {"count": 12, "p50_ms": 0.006, ...}, "get_tuple": {...}}

OpenTelemetry tracing (each checkpoint op becomes a swarmstate.checkpoint.<op> span):

from swarmstate.observability import get_tracer     # needs swarmstate[otel]

saver = SwarmStateSaver(tracer=get_tracer())         # composes with metrics=...

Status

Early development.

  • M0 (scaffolding) ✅ - Rust core builds; import swarmstate works.
  • M1 (Rust store) ✅ - concurrent KV store, msgpack codec, O(1) immutable snapshots, incremental diffs, GIL released on hot paths.
  • M2 (HandoffGraph) ✅ - deterministic conditional routing with a safe Rust condition evaluator (no eval), cycle detection.
  • M3 (LangGraph adapter) ✅ - SwarmStateSaver, a drop-in BaseCheckpointSaver backed by the Store; snapshot/roll back the whole checkpoint DB at once.
  • M4 (Benchmarks) ✅ - SwarmStateSaver.put ~12.8× faster than SqliteSaver; Store.snapshot() is O(1) (hundreds of thousands× faster than deep-copying large state). Reproducible: benchmarks/run.py; charts & tables in the docs.
  • M5 (CrewAI adapter + backends) ✅ - persistent, drop-in checkpointer backends RedisStore, DiskStore (SQLite) and PostgresStore, all msgpack wire-format, plus SwarmStateStorage (portable memory backed by a shared Store).
  • M6 (docs · wheels · PyPI) ✅ - full docs site, benchmarks, cross-platform abi3 wheels, and PyPI publishing via Trusted Publishing (OIDC).
  • Observability ✅ - opt-in metrics hooks and OpenTelemetry tracing on checkpoint ops (put / put_writes / get_tuple): an in-memory sink, an OpenTelemetry metrics sink, and per-op spans (swarmstate[otel]). Zero overhead when unused. Strict mypy in CI.
  • Free-threaded (no-GIL) ready ✅ - the Rust core declares free-threaded support, so on a free-threaded CPython build (cp313t) the store doesn't collapse under threads the way the GIL build does: on a set+get workload at 8 threads it sustains ~1.8M ops/s vs ~130k on GIL Python (over 10x), where the GIL build gets much slower as threads are added. (These workloads are allocation-bound, so neither scales linearly with cores; the win is avoiding the GIL's collapse.) Version-specific cp313t wheels ship alongside the abi3 ones.
  • Batch API ✅ - Store.set_many / get_many (and on every backend) amortize the per-call overhead over a batch: one GIL release for the in-memory core, one round-trip for networked backends. On free-threaded at 8 threads, set_many is ~3x the throughput of individual sets. SwarmStateSaver uses it internally: put_writes (and the incremental channel blobs) flush all writes of a step in a single set_many, so fan-out steps that emit many pending writes pay one lock/round-trip instead of one per write.

Examples

Runnable, offline, deterministic demos in examples/:

  • support_triage.py - a LangGraph workflow tying together HandoffGraph routing, SwarmStateSaver checkpointing and snapshot/restore time-travel.
  • state_portability.py - state as standard msgpack bytes, read back and cross-checked against the msgpack package.

Development

python -m venv .venv && source .venv/bin/activate
pip install maturin pytest
maturin develop --release     # compile the Rust core and install it locally
cargo test                    # Rust core tests
pytest -q                     # Python API tests

License

MIT

Project links

Data verified by PyPI on Jul 28, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.11.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for salmeron from gravatar.com salmeron

Credits

Author: swarmstate

GitHub Statistics

Data verified by PyPI on Jul 28, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.9

Provides Extra

all bench crewai dev disk docs langgraph otel postgres redis

Tags

agents langgraph crewai checkpoint state rust multi-agent

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

swarmstate-0.10.3.tar.gz (92.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

swarmstate-0.10.3-cp313-cp313t-win_amd64.whl (268.2 kB view details)

Uploaded CPython 3.13tWindows x86-64

swarmstate-0.10.3-cp313-cp313t-macosx_11_0_arm64.whl (362.0 kB view details)

Uploaded CPython 3.13tmacOS 11.0+ ARM64

swarmstate-0.10.3-cp39-abi3-win_amd64.whl (273.1 kB view details)

Uploaded CPython 3.9+Windows x86-64

swarmstate-0.10.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (386.7 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64

swarmstate-0.10.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (383.5 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

swarmstate-0.10.3-cp39-abi3-macosx_11_0_arm64.whl (366.1 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

swarmstate-0.10.3-cp39-abi3-macosx_10_12_x86_64.whl (380.1 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file swarmstate-0.10.3.tar.gz.

File metadata

  • Download URL: swarmstate-0.10.3.tar.gz
  • Upload date:
  • Size: 92.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for swarmstate-0.10.3.tar.gz
Algorithm Hash digest
SHA256 812d84b590a8e56bbc35a8dd12153ce1d574f1baac0f0a9f755dd721167b5afa
MD5 3a6fafa78ddc367e13e114b32511ff81
BLAKE2b-256 98cf0469b1cf9d9dbb475840cf3beb41e52f335d43b2361b0187fa517aa4b8c6

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3.tar.gz:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp313-cp313t-win_amd64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.3-cp313-cp313t-win_amd64.whl
Algorithm Hash digest
SHA256 fd3e7e9b9473bd9df03988db476eceec107fd328630288bb8ced88069b449ba8
MD5 e715895566657f04a0d8f27ce5bd93fc
BLAKE2b-256 b881bfce6e22f34b7ae0e3418ac263a47bfd8fe6cdcb9c42832d398b350aaa79

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp313-cp313t-win_amd64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp313-cp313t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.3-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 d1373da6250fdc7b870140ad3c0e422afdccfadb873c1bc0bba952d5dfa9770d
MD5 f8e7fc00618ecf0d259a3887c4aa4d95
BLAKE2b-256 15254d23623913206aecc1c096a206387d5f3ca93cd850984fbd60b1bbd0f6ab

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp313-cp313t-macosx_11_0_arm64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: swarmstate-0.10.3-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 273.1 kB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for swarmstate-0.10.3-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 dd1658611de926ce7ffe9195240ff74913658d3c848ecb345a9e8278b5fcc8cb
MD5 0a2498f627f842a30b6af53dc88d8050
BLAKE2b-256 f18eac9c1276c594f962390619adefa4736f3a7373dbff2b92efa4cc1130e394

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp39-abi3-win_amd64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 7deed8d184f671079d2c2c4988442e75aa39ff7afd0ad247132e7c15399b951c
MD5 2b33e5a2ade6f5c65493dded7c7212d9
BLAKE2b-256 cf4ae80d830a10e8d3786e4fa0a8175c5be6b7244a448f07d1960e0871ffc482

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0b1d1b5bdff1c099d16583cc3271159fca6091a690c2da9f93d629c220e5e38a
MD5 3884d7aeb09f3a38242b5163949a6c63
BLAKE2b-256 ee3754dd809bb3ad4b67d7d9531984831c8128379d7f9b7e9a897eacc9b73b0f

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.3-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 76c08880a8e21105f1cce4c7bb5b0a59d206be4665326477cd439625f9b7feb5
MD5 25852d1b227661ae1a118da86736ce61
BLAKE2b-256 f61fc59be465ac7de04291e5abcf50531d8b75f4f8266c2a9a1edc1039f73868

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file swarmstate-0.10.3-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.3-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 20eae62ca29398e789f67edad867280f2c7c4af93c5caa3efd1cafef75b1fe68
MD5 67ddd338c231bdc2f836af074e087714
BLAKE2b-256 ec912bfde39b8bd772f76c4b94ab35fb856979d5fe9a32694e9c8f8089fbb737

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.3-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on swarmstate/swarmstate

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.11.0

14 files

0.10.4

10 files

This release

0.10.3 This release

8 files

0.10.2

8 files

0.10.1

8 files

0.10.0

8 files

0.9.2

6 files

0.9.1

6 files

0.9.0

6 files

0.8.0

6 files

0.7.0

6 files

0.6.0

6 files

0.5.0

6 files

0.4.0

6 files

0.3.0

6 files

0.2.1

6 files

0.2.0

6 files

0.1.0

6 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page