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.2.tar.gz (92.1 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.2-cp313-cp313t-win_amd64.whl (268.2 kB view details)

Uploaded CPython 3.13tWindows x86-64

swarmstate-0.10.2-cp313-cp313t-macosx_11_0_arm64.whl (361.8 kB view details)

Uploaded CPython 3.13tmacOS 11.0+ ARM64

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

Uploaded CPython 3.9+Windows x86-64

swarmstate-0.10.2-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.2-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.2-cp39-abi3-macosx_11_0_arm64.whl (366.1 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

swarmstate-0.10.2-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.2.tar.gz.

File metadata

  • Download URL: swarmstate-0.10.2.tar.gz
  • Upload date:
  • Size: 92.1 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.2.tar.gz
Algorithm Hash digest
SHA256 aab09a4f7ef5f4d5c435fc8fc37d31cbb2e5680cb77086403aa8bdb91bf928d8
MD5 fb959ae7725d162c347b1bd615d6cef5
BLAKE2b-256 f33918ddbeadd5e51db7f04307ce5947ba52d6f39f16e4e502e897af14d8adb0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.2-cp313-cp313t-win_amd64.whl
Algorithm Hash digest
SHA256 69837b2bf14dfddee7e9631d5f1048af884f5c684c01f58620acba3569879c08
MD5 8a61d0f727cc6e31fa4a74f8085e53f1
BLAKE2b-256 9210fdd66f4991b0eab8b57301629f3c0a8164b9241c2fccdb8f62ff32f0820a

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.2-cp313-cp313t-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 05f9e82338d574f826554b022e746c08aa41c558122ba63f279d57e65b791458
MD5 8d897a4c8e3afe1100a0877dda0b149e
BLAKE2b-256 08471933c028bd546831157cad057762bd4e21f9ec7cd6f00c082600401e7a75

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: swarmstate-0.10.2-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.2-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 15b4de869b91afc3cd0aaaf45c6fd8691d83329c0a8bb7d0650b93f4ad76b033
MD5 01408f6fa4ecdf59c87c6ec327b5c202
BLAKE2b-256 87852e2189d8ca9afc5a362f66d8edbfe23859d945b2306e0e8ebbbbb763ea51

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.2-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 67c9fb94f08758a720045fa52df9b9f3efbc2ed2bbfddc1b18633d01981caef7
MD5 262296e37b8e97cc4d1a4ddd993ccd26
BLAKE2b-256 0b18b77a0336a1802fc4950a476c8a231275e8943ed3fe2e1756ca4cd00d351f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.2-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 72f94164d46118e2781ef8ff92ca4319524c67262bc928429a113f5d70f2de0e
MD5 cd5ef46df6d6e5f912b65d6343777851
BLAKE2b-256 be1b567b6b2118501b9a397403d5fa0541a957e7fc7e41ffbb3f25f748b7694d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.2-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e17c102fd301b04ec96e1d372f6cf767f3100ab72d45b2c98a32a46d0e793a9f
MD5 deb3c965de4480b489264ca8050e3114
BLAKE2b-256 f732447c31bd09fc91bd9462874617eebf2d8cfc3c3e3b5bb7910b4d35a2c308

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for swarmstate-0.10.2-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 44e24252deddafcb195304f5150f91092d6895b7e5a50e24a36aaae304b47ed2
MD5 ed8d0c99346ea24d0ef3e2be6de6d4b0
BLAKE2b-256 9f17f4d65bff33923836b7e88065f643a8ec6f361750d065ab9e3ad35d45900b

See more details on using hashes here.

Provenance

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

This release

0.10.2 This release

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