Skip to main content

swarmstate

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

Constant-time checkpoint readsget_tuple stays at ~7 µs whether a thread holds 5 or 2 000 checkpoints, where LangGraph's InMemorySaver climbs from ~5 µs to ~40 µs — and O(1) state snapshots: ~0.5 µs at any size, against 50 ms to deepcopy a 50 000-entry state. Durable writes land on par with SqliteSaver at the same fsync policy (~1.9× faster than its shipped default, which buys stronger durability). Method, hardware and raw numbers → 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. Checkpoint reads that get slower as threads grow - a Rust-backed implementation of LangGraph's checkpointer interface that resolves "the latest checkpoint" by lookup instead of scanning a thread's keys.
  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": [...]}

# Retention is opt-in: a snapshot the store keeps pins the state it saw
hist = ss.Store(max_history=10)                  # 0 (default) keeps none, None keeps all
hist.history()                                   # -> [Snapshot, ...], oldest first

# 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

Bounded memory for long-running threads — checkpointers keep every step by default, which for a service that never restarts means growth without end:

saver = SwarmStateSaver(max_checkpoints_per_thread=8)     # keep the newest N per thread

Older checkpoints are dropped with their pending writes and channel blobs. On a 300-invocation thread that is 0.5 MB instead of 28 MB, and the thread still resumes; time travel is limited to the retained window, so size it to taste.

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) ✅ - durable-vs-durable and in-memory-vs-in-memory comparisons on LangGraph's interface, read latency as a thread grows, Store.snapshot() vs deepcopy, and concurrency scaling. Reproducible: benchmarks/run.py; method and results in benchmarks/README.md.
  • 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 and cp314t wheels ship for Linux (x86_64/aarch64), macOS (arm64) and Windows (x64) 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.

Documentation

Guide, tutorials and API reference: swarmstate.github.iothe store, snapshots & diffs, the LangGraph checkpointer, persistent backends, the handoff graph and the benchmark method. The site is built from swarmstate/swarmstate.github.io.

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

Citing

If you use swarmstate in academic work, please cite it. GitHub's "Cite this repository" button (from CITATION.cff) produces ready-made APA and BibTeX entries. To cite the archived software release, use its Zenodo DOI (10.5281/zenodo.XXXXXXXX):

@software{salmeron_swarmstate,
  author    = {Salmeron, Jose L.},
  title     = {{swarmstate}: A state and checkpointing backend for multi-agent
               systems with a Rust core},
  year      = {2026},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.XXXXXXXX},
  url       = {https://github.com/swarmstate/swarmstate}
}

The DOI is minted when the first release is archived on Zenodo. Replacing 10.5281/zenodo.XXXXXXXX here, in CITATION.cff and on the docs site is all it takes — the placeholder is deliberate, so that nothing cites an identifier that does not resolve.

License

MIT

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.11.0.tar.gz (138.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.11.0-cp314-cp314t-win_amd64.whl (299.5 kB view details)

Uploaded CPython 3.14tWindows x86-64

swarmstate-0.11.0-cp314-cp314t-manylinux_2_34_x86_64.whl (413.2 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.34+ x86-64

swarmstate-0.11.0-cp314-cp314t-manylinux_2_34_aarch64.whl (402.0 kB view details)

Uploaded CPython 3.14tmanylinux: glibc 2.34+ ARM64

swarmstate-0.11.0-cp314-cp314t-macosx_11_0_arm64.whl (394.4 kB view details)

Uploaded CPython 3.14tmacOS 11.0+ ARM64

swarmstate-0.11.0-cp313-cp313t-win_amd64.whl (299.4 kB view details)

Uploaded CPython 3.13tWindows x86-64

swarmstate-0.11.0-cp313-cp313t-manylinux_2_34_x86_64.whl (413.0 kB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.34+ x86-64

swarmstate-0.11.0-cp313-cp313t-manylinux_2_34_aarch64.whl (402.1 kB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.34+ ARM64

swarmstate-0.11.0-cp313-cp313t-macosx_11_0_arm64.whl (394.3 kB view details)

Uploaded CPython 3.13tmacOS 11.0+ ARM64

swarmstate-0.11.0-cp39-abi3-win_amd64.whl (309.0 kB view details)

Uploaded CPython 3.9+Windows x86-64

swarmstate-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (427.8 kB view details)

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

swarmstate-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (420.7 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

swarmstate-0.11.0-cp39-abi3-macosx_11_0_arm64.whl (400.9 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

swarmstate-0.11.0-cp39-abi3-macosx_10_12_x86_64.whl (420.7 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for swarmstate-0.11.0.tar.gz
Algorithm Hash digest
SHA256 8a88cc54a93d6563380eb4ae9768349c3c91207b6cbacea15b0033dfeee45bd6
MD5 90a6df2e894476f10c269fe9a4c80db2
BLAKE2b-256 e4e2515378c990f0622c6fa5a5e701a104bd4419e3541c770d10bd2d3b4ab93d

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0.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.11.0-cp314-cp314t-win_amd64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp314-cp314t-win_amd64.whl
Algorithm Hash digest
SHA256 84ca8176601b5b90088b13df3ace7830da96d74b16557927a7167e614b22c6a1
MD5 87ef9a58c1df26c85517bb1f8b283635
BLAKE2b-256 13e5231a326243666554299a241c579bf4dd3cec086178f2f5c9c20d86835e7f

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-cp314-cp314t-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.11.0-cp314-cp314t-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp314-cp314t-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 723e7a60848650b897cba20dcc4decf9c9c7e80d9cebd1b45f9d55dc17eec809
MD5 06433bf35aa3795b6f1081c8156aea7f
BLAKE2b-256 f47337dbf04a016f9a789ffd3d498cdfa461ea6d9e8bb60e6d92405af9f33666

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-cp314-cp314t-manylinux_2_34_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.11.0-cp314-cp314t-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp314-cp314t-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 a8799d8c78115c5324d5488948c404cf22edb8f0acefb9a896f58ae15d2f8e3c
MD5 05bf727ab5a275604ecc4255a5f50cdc
BLAKE2b-256 6c0dbb8123e032b4572dcf215cdeb083627bbb3a9a0c284a6354fe9ccba13828

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-cp314-cp314t-manylinux_2_34_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.11.0-cp314-cp314t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp314-cp314t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f109d8c5a4427be8cc07d56b5bea77fd67021df38f6d68147f76bc241dc53fdf
MD5 6107b7317ee183a3900d1507374fe144
BLAKE2b-256 162869c64edf06cc6962d3e0ecb65c0d648f703d2000cc5ba7f31fe16c5e3a26

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-cp314-cp314t-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.11.0-cp313-cp313t-win_amd64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp313-cp313t-win_amd64.whl
Algorithm Hash digest
SHA256 c4d1c11e95543b0d1da616ec9ff8cf9dd564ef76978eedbd6cd1e1350521e163
MD5 31297b85b08ae6014930c104b63eaa75
BLAKE2b-256 aaa170ac1cd879e9e6b901300f067f2dac56f90b50886bc327e885e2189cba2f

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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.11.0-cp313-cp313t-manylinux_2_34_x86_64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp313-cp313t-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 9f81f11e8f9691aa97eff968e74a106370423793de28729afa0d6dba59b4e808
MD5 30a4fc747c80038d7173f7f08eea0e25
BLAKE2b-256 6f4bbdd3dd08a1f3fc2a08e7a30ce0aa77a30dc1e404a2b9be37095b10ad6d11

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-cp313-cp313t-manylinux_2_34_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.11.0-cp313-cp313t-manylinux_2_34_aarch64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp313-cp313t-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 fb63e2146625c53c6ea12128f1faac64edc120e52cecd7bd9c00c0eda9b06c42
MD5 38ea9d542d56f774271e868f6b729f36
BLAKE2b-256 51d481a0977d361a67d0641efde187e16668cd897b32354f17a7af21ced1fbae

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-cp313-cp313t-manylinux_2_34_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.11.0-cp313-cp313t-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8f66501e57ca4a0cb96e0a9f4c4417e946152706f4ad372d16648fec815a01c0
MD5 d2a1391709853a8f9c1e12f5bd85b252
BLAKE2b-256 4de1eaa223595817b1f5419b58faed33a67d88fe140ebea51e6db9206d01f4d1

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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.11.0-cp39-abi3-win_amd64.whl.

File metadata

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

File hashes

Hashes for swarmstate-0.11.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 32a740b3d0f20ac7ce0aedc3178fc964bd8a4e56e19cadbb925eea45f7225eb0
MD5 5ffebb12989618200c1d798dccce0eac
BLAKE2b-256 0294dac7af09974b824f11e84aa8ecee9c6f1d9dbbd1d8d541144eab534bb32e

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0905e9a1b2587613a4194d78507231554b334d0e883ed1ca9a29e68a351726d8
MD5 06026fb9249df3f9d4fe0acf92b7c720
BLAKE2b-256 5ae0fdce1ba7d96dfdae999478b69bca0f8967071d2c210546718a6e702de4cd

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6905ce90939147a4ebe348acfc42db9c90ad04137a54a8e4440f4ef997cbff65
MD5 bc86e62631504ac87e20562fbbbb7b28
BLAKE2b-256 b71580de13f47048249a84e025759943641c3e47e469b4b7dd67ba732111ff1f

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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.11.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9b883eb6d8fbd4d60e35dd43552941c7a789fb01c59305c7d3f96a7237bc82d2
MD5 d1f3f321d2fb5a7c737b30b3a9d5bf53
BLAKE2b-256 d06f77bba581f60d129bafecd6039e4c6990709b51866d74a96f973737d4a5f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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.11.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for swarmstate-0.11.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 251430136222c48248a4566e58166ac7eb7ac96a65b7ce4d52c8b4833af9ed75
MD5 b1052406f5912cf5d958118f97b2bb33
BLAKE2b-256 a46a27514d85ed1fdb95a75873f6656d613a12b6fc6b0372870c7690a44977b3

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.11.0-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

This release

0.11.0 This release

14 files

0.10.4

10 files

0.10.3

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