agent-state-api

agent-state-api

StateSync — the global state database for AI coding agents.

Two lines. Any agent. Persistent memory.

📚 Full documentation → · 🚀 Quickstart · 🔑 Get an API key · 💬 MCP guide

---

pip install agent-state-api

from agent_state import StateSync

sync = StateSync(api_key="ss_live_...")               # 1

sync.checkpoint(project="my-app", messages=history)    # 2a
ctx = sync.pull(project="my-app", agent="cursor")      # 2b — 70% smaller

What it does

StateSync is a middleware layer that gives every AI agent in your stack the same long-term memory. It captures each agent's checkpoints (messages, files, decisions, test results) and returns a compressed, unified brief when the next agent starts — so Cursor can pick up exactly where Claude left off, without re-sending 50k tokens.

Under the hood: real semantic embeddings (BAAI/bge-small-en-v1.5) + temporal decay + LLM summarization → 70–85% smaller context on every sync.

👉 Read the concepts guide

Quickstart

Full walkthrough: https://www.statesync.it/docs/quickstart

from agent_state import StateSync

sync = StateSync(api_key="ss_live_...")

# 1) Cursor finishes a task
sync.checkpoint(
    project="todo-app",
    agent="cursor",
    messages=[
        {"role": "user", "content": "Add JWT auth"},
        {"role": "assistant", "content": "Added auth.py with bcrypt + jwt"},
    ],
    files=["auth.py", "server.py"],
    decisions=["Use bcrypt for password hashing"],
    tests_passed=["test_login"],
)

# 2) Claude Desktop takes over an hour later
brief = sync.pull(project="todo-app", agent="claude", query="password reset")
print(brief["compressed_context"]["summary"])
print("Savings:", brief["compressed_context"]["savings_pct"], "%")

API reference

Complete reference with endpoint tables, params, and response examples:

Python-SDK-specific reference: https://www.statesync.it/docs/sdk-python

Get an API key

Sign up free at https://www.statesync.it — 1,000 syncs/mo, no credit card. Create a key from Dashboard → API Keys, then export it:

export STATESYNC_API_KEY=ss_live_...

StateSync() with no args will pick it up.

MCP support

StateSync is also an MCP server. Drop this into your Cursor / Claude Desktop config:

{
  "mcpServers": {
    "statesync": {
      "url": "https://www.statesync.it/api/mcp",
      "headers": { "Authorization": "Bearer ss_live_..." }
    }
  }
}

Full MCP integration guide: https://www.statesync.it/docs/cursor Tools exposed: statesync_list_projects, statesync_create_project, statesync_checkpoint, statesync_pull. Resources: statesync://project/{id}, statesync://project/{id}/snapshots, statesync://snapshot/{id}, statesync://audit.

Links

• 📚 Documentation: https://www.statesync.it/docs
• 🎛️ Dashboard: https://www.statesync.it/dashboard
• 📖 OpenAPI spec: https://www.statesync.it/openapi.json
• 🧪 Swagger playground: https://www.statesync.it/docs (FastAPI auto-docs served at the API base)
• 📦 Sister SDK (Node/TS): https://www.npmjs.com/package/@statesync/client

License

MIT.