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 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.

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.4.tar.gz (92.6 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.4-cp313-cp313t-win_amd64.whl (268.3 kB view details)

Uploaded CPython 3.13tWindows x86-64

swarmstate-0.10.4-cp313-cp313t-manylinux_2_34_x86_64.whl (373.8 kB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.34+ x86-64

swarmstate-0.10.4-cp313-cp313t-manylinux_2_34_aarch64.whl (365.6 kB view details)

Uploaded CPython 3.13tmanylinux: glibc 2.34+ ARM64

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

Uploaded CPython 3.13tmacOS 11.0+ ARM64

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

Uploaded CPython 3.9+Windows x86-64

swarmstate-0.10.4-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (386.6 kB view details)

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

swarmstate-0.10.4-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (383.6 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

swarmstate-0.10.4-cp39-abi3-macosx_11_0_arm64.whl (366.2 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

swarmstate-0.10.4-cp39-abi3-macosx_10_12_x86_64.whl (380.2 kB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: swarmstate-0.10.4.tar.gz
  • Upload date:
  • Size: 92.6 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.4.tar.gz
Algorithm Hash digest
SHA256 c0465d4233b5ece11aa153c976e6e8477de9f5898b95d2d21c55e81c1cacc9bf
MD5 12d8e78845b6d40ba2fc3705d6224a21
BLAKE2b-256 09b72ee064f1511c13fa2b92a3a405bde0df57a60142d0a03ebd3aaaf04bb4fb

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp313-cp313t-win_amd64.whl
Algorithm Hash digest
SHA256 de8aab56aa7e2895c23e502aef53f22779e1f41cb60a9067ec66c12f4dd0c661
MD5 eb0385ffdcffe6c0c445bd87ba9f986a
BLAKE2b-256 040537355001a5db0d6bb8bd088a125985829292c5ecf6a55e0864b704875ce4

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp313-cp313t-manylinux_2_34_x86_64.whl
Algorithm Hash digest
SHA256 7920b62bcfae5a43b18773cee1ddabdca6ecc80196dc604328b8cd0d09a77574
MD5 b27ed09cc3ad0bf4db8b6b42a62496fa
BLAKE2b-256 e6d032314e0343a542d01f306468546e53170cfca6a450dce79ac8e475d5d067

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp313-cp313t-manylinux_2_34_aarch64.whl
Algorithm Hash digest
SHA256 66ce911260df8d3054c68ac6915da34feac46bf2081c2668e0b36e4eb380d96f
MD5 835b49f2c70938d22de2a09a790ecf7c
BLAKE2b-256 6a95898c4610ddf54d2460631a82ffc9c5dd7e464804f056405ffa08c34a96e9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7baeb723bfdff4a757b484fad9da83f1d0ab267078ab308476b65d7aeb069096
MD5 f2e36136ca8179b90c9942559bdb096e
BLAKE2b-256 6bfb665facdd390219f34714107ac4c70a299b0d7aca8dc180f2ec9680d1f43a

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: swarmstate-0.10.4-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.4-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ab2c3401f4aa5b6cb45a6c7e6657b8bf817b5b01473aed731c48ea4ba340555e
MD5 70e843b9a3c88864d299ef117e0d54b3
BLAKE2b-256 fce42f3c38e4c3d02278d234692d860f40d97d9bcadc49d6278a99c11c77c5ae

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 41e47bcffddee0db3773088651fb58ff803c22e5bf64f6e11438ae491f541a5b
MD5 9c0aacabe3cc8aeb6bad82f78c40f16a
BLAKE2b-256 6edb0bb8d7bab5028cac785f21b7d84b463639fadf87f77a94fd171bc93634e7

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 9b8cee4f42c2a935b6e746e996678ed0fce62f73ffcefda33ac5f97a43a2d60e
MD5 5954b233b8a457c487f358b110515485
BLAKE2b-256 32dc09823cffd0a890a21d86a1cb236b48ddf4ffe5582337a59b1d44cc399114

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2afa697ec811bf5634e638ff54cae4460e3716aea9ad7448269a83f286f2cb8d
MD5 d5dbbe8771eb8f280f95115709b7edc3
BLAKE2b-256 2f8ec3578d86eaad397699651797e1e31d917e11ec589a3cec5363a5483b0aab

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.4-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c1a1c434b14bb79c2744cd680820a6a538978196c8ca8e6c8b4d4b0370d0a425
MD5 51493b4c3fade07f139d62b7fd5a4765
BLAKE2b-256 48a9fff789c7bfca9265377dd5ee74049d47f8807f7dc8bdf3e4e3bc61b34372

See more details on using hashes here.

Provenance

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

This release

0.10.4 This release

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