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.

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 9, 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 9, 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.1.tar.gz (89.8 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.1-cp313-cp313t-win_amd64.whl (268.4 kB view details)

Uploaded CPython 3.13tWindows x86-64

swarmstate-0.10.1-cp313-cp313t-macosx_11_0_arm64.whl (361.4 kB view details)

Uploaded CPython 3.13tmacOS 11.0+ ARM64

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

Uploaded CPython 3.9+Windows x86-64

swarmstate-0.10.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (390.8 kB view details)

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

swarmstate-0.10.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (387.0 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

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

Uploaded CPython 3.9+macOS 11.0+ ARM64

swarmstate-0.10.1-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.1.tar.gz.

File metadata

  • Download URL: swarmstate-0.10.1.tar.gz
  • Upload date:
  • Size: 89.8 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.1.tar.gz
Algorithm Hash digest
SHA256 0f43f169211715d19a210c92c277e043a25d162cce37599bfec656b7f36c0bb9
MD5 cd411bd10b9d77a0f1471fd7ef11adb1
BLAKE2b-256 b380d85bc38ea54cb55a5e7a8423b6a7f6655963f81df34f7ef9b01942a62982

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.1-cp313-cp313t-win_amd64.whl
Algorithm Hash digest
SHA256 a8855dd96d6fa07f9e7ed8227bf1180da369e1947bdd1dbd43af552d84ca46c4
MD5 4c944c67f38432abc47cbafe54d0699b
BLAKE2b-256 b0cefa5c5ae02d1cdb4f0dfe9ea82c9dad3926dcb20005af563600a86d48ffc1

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.1-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 db944a7b5fc853d7323263ed88b37cecbb59b6ee138fb31ec668d4e82bcee784
MD5 71158493ebfdf8437a88bdf00e100cf6
BLAKE2b-256 08d93bd33d4224b2c82e6d96b0be4f713f93ca1d89191be105262b94800da819

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: swarmstate-0.10.1-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.1-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 36842ec109424816902e8065d353bd1b01ce93b5010ca4d241fb417b625fa509
MD5 3553255bfdd48635059e0da233e46e88
BLAKE2b-256 2f27ae0404862d2c5959a73cc30a4c7f4fad1043c66ee4566531e5a99cc5c40b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8b4b1fb02e19e0dbb5b678361efce9d0ca541c8a5d6cff8627a658b7a4a23466
MD5 651fb2450f93f77c696fe925ba77d03d
BLAKE2b-256 dd5785c91c21c7fe0472f083891abeb7217b907389fae06949a722e775bcca4e

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 12b4f5df2190339a1db7edf470b876f8b4c9ac2a271ad012095050387fa8b276
MD5 bd3f8b17df0d0f0331ea5b20ef9c720f
BLAKE2b-256 9891633c03aa0750f6641ab62e6c4460e9a9311e4f6b5c020f475aded9946fd8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ae0fed1c7b38aabc1b0e9524d410bb0d677eee2bf425e80613641b8606519fca
MD5 b94d2192483917b233bab34874410f25
BLAKE2b-256 610bdcb715862751af73265278830adb6e1edc70fcc6b80ae7bf2544f8709224

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.1-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6f2aa10b7234b510a0b618a577f924dbefd4bf6141a4e43ea76b5fd3c6d51470
MD5 c7a1be9d179ff701484ea7e185156a1c
BLAKE2b-256 118561fbc34ae4b24499df5f9e1c8fb6bc2cef228970a377c37e8a701c9765cd

See more details on using hashes here.

Provenance

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

This release

0.10.1 This release

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