Metadata-Version: 2.4
Name: agent-state-api
Version: 0.1.1
Summary: StateSync — the global state database for AI coding agents. Two-line SDK to unify memory across Cursor, Claude, OpenAI and Emergent.
Author: StateSync
License: MIT
Project-URL: Homepage, https://www.statesync.it
Project-URL: Documentation, https://www.statesync.it/docs
Project-URL: Quickstart, https://www.statesync.it/docs/quickstart
Project-URL: API reference, https://www.statesync.it/docs/api-projects
Project-URL: MCP guide, https://www.statesync.it/docs/cursor
Project-URL: Dashboard, https://www.statesync.it/dashboard
Project-URL: OpenAPI spec, https://www.statesync.it/openapi.json
Project-URL: Node/TS SDK, https://www.npmjs.com/package/@statesync/client
Project-URL: Issues, https://www.statesync.it/docs
Keywords: ai,agents,llm,mcp,context,compression,cursor,claude
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.24
Dynamic: license-file

# agent-state-api

**StateSync — the global state database for AI coding agents.**

Two lines. Any agent. Persistent memory.

📚 **[Full documentation →](https://www.statesync.it/docs)**  ·  🚀 **[Quickstart](https://www.statesync.it/docs/quickstart)**  ·  🔑 **[Get an API key](https://www.statesync.it/dashboard/api-keys)**  ·  💬 **[MCP guide](https://www.statesync.it/docs/cursor)**

---

```bash
pip install agent-state-api
```

```python
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](https://www.statesync.it/docs/concepts)

## Quickstart

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

```python
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:

| Topic | Docs link |
|---|---|
| Projects API | https://www.statesync.it/docs/api-projects |
| Snapshots API | https://www.statesync.it/docs/api-snapshots |
| Sync & Compress | https://www.statesync.it/docs/api-sync |
| Analytics & Audit | https://www.statesync.it/docs/api-analytics |
| Rate limits & pricing | https://www.statesync.it/docs/guide-rate-limits |

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:

```bash
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:

```json
{
  "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.
