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 sharded store scales across cores: ~1.9M set+get ops/s at 8 threads vs ~196k on GIL Python (~9.8x), where the GIL build gets slower with more threads. 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, set_many is ~4x the throughput of individual sets.

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 8, 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 8, 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.0.tar.gz (89.7 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.0-cp313-cp313t-win_amd64.whl (268.4 kB view details)

Uploaded CPython 3.13tWindows x86-64

swarmstate-0.10.0-cp313-cp313t-macosx_11_0_arm64.whl (361.2 kB view details)

Uploaded CPython 3.13tmacOS 11.0+ ARM64

swarmstate-0.10.0-cp39-abi3-win_amd64.whl (273.0 kB view details)

Uploaded CPython 3.9+Windows x86-64

swarmstate-0.10.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (390.7 kB view details)

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

swarmstate-0.10.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (386.9 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

swarmstate-0.10.0-cp39-abi3-macosx_11_0_arm64.whl (365.6 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

swarmstate-0.10.0-cp39-abi3-macosx_10_12_x86_64.whl (379.6 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for swarmstate-0.10.0.tar.gz
Algorithm Hash digest
SHA256 09ae1a9293d1567a165a361f2b5290736d8fd8a2a4a576c92b1dacb56f6e1e12
MD5 d4d0d84eea1d9cd2d151b35ab284cc01
BLAKE2b-256 c30d0aa649826b5b6a3725956536147ab27c491cc422edeb2816cab338a554a7

See more details on using hashes here.

Provenance

The following attestation bundles were made for swarmstate-0.10.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.10.0-cp313-cp313t-win_amd64.whl.

File metadata

File hashes

Hashes for swarmstate-0.10.0-cp313-cp313t-win_amd64.whl
Algorithm Hash digest
SHA256 20a190382e6f42439908886b691974cdf291de1137c822e7deaf2e4a591d97a7
MD5 3f398a5aed21c359a2b21fde83ad58b8
BLAKE2b-256 88e25cea4d9948404c3f88bde048810c3c50db54be356f7794afd22007da267b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.0-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5635481333fe0d01bb63fbd5fb969d4d8adc4c2a54ab7d3ea609237102215b0b
MD5 5363d711f2b23f810b3be0392cc46917
BLAKE2b-256 f8e389fda75217d071c7dc9a63acc953710d92016037eb3602065094c1219950

See more details on using hashes here.

Provenance

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

File metadata

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

File hashes

Hashes for swarmstate-0.10.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4483fc2560dc7eadd864ba71ed0b46a540fcc974677c32c733dce2c9f6089ea0
MD5 30330624cbf2b2b2a53dc72b824ecfcc
BLAKE2b-256 2792886b047a92781882ec4ab779516deb963a26b5f513bcaeeba75fb6a8dacc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f072ea0060dbb5c3e215b3f5cf82e357f1502d0d11d89f228ba8ccb050349d23
MD5 eb3f00025e470fc9e6aaf1794a5ae634
BLAKE2b-256 57c691f2c3a3ad40e8fb6981c61efb7c1c334c09ab59aedd84a8309843b73186

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 38e1617511ce2955e9946316285977e69aaa7f42b4734cf6994b32aea9f9a269
MD5 81a34c37612542afd1066ece67d8fa9d
BLAKE2b-256 e0485f67eea785d6bc7c49145e721acfe7ac0fc373289bc82051e6b708d98aec

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 30cdc61db69e31990f766596d5207ac071588ff6c87f2985b0b688336900f814
MD5 0a9372cd224d1577c2cf38fa1d12da1c
BLAKE2b-256 c193c791c3aeebafcab15ea06894bb05e7003100eb631b7c96a1d6dbc4699fc5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 143ea9f77d6bc5eeadf75d937ce4adc796bdbe8fe2773b076af4e4714861c379
MD5 0f8274ee60f33e42567b882301fe8d5f
BLAKE2b-256 740b0a5e76f903d00bfd3e21108d704cbfa7e3a8c16dfb7814fcba8c665cd98a

See more details on using hashes here.

Provenance

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

0.11.0

14 files

0.10.4

10 files

0.10.3

8 files

0.10.2

8 files

0.10.1

8 files

This release

0.10.0 This release

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