@masorinho99/statesync-client

StateSync — the global state database for AI coding agents.

Two lines. Any agent. Persistent memory.

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

npm install @masorinho99/statesync-client

import { StateSync } from "@masorinho99/statesync-client";

const sync = new StateSync({ apiKey: "ss_live_..." });          // 1

await sync.checkpoint({ project: "my-app", messages: history });  // 2a
const ctx = await sync.pull({ project: "my-app", agent: "windsurf" }); // 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 Windsurf can pick up exactly where Cursor 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

OpenAI Agents SDK pattern

import OpenAI from "openai";
import { StateSync } from "@masorinho99/statesync-client";

const openai = new OpenAI();
const sync = new StateSync({ apiKey: process.env.STATESYNC_API_KEY });

// 1) On every turn, pull the compressed brief instead of the full history:
const { compressed_context } = await sync.pull({
  project: "todo-app",
  agent: "openai-agents",
  query: userTurn.content,
});

const messages = [
  { role: "system", content: compressed_context.summary },
  ...compressed_context.highlights,
  ...compressed_context.recent,
  userTurn,
];

const resp = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages,
});

// 2) After the turn, save the state so the next agent (Cursor, Claude, whatever)
//    picks up exactly here:
await sync.checkpoint({
  project: "todo-app",
  agent: "openai-agents",
  messages: [...messages, resp.choices[0].message],
  files: ["src/App.tsx"],
});

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 |

Node-SDK-specific reference: https://www.statesync.it/docs/sdk-node

Windsurf / Cursor / Claude Desktop (MCP)

@masorinho99/statesync-client is the direct HTTP SDK. If you'd rather have your editor attach snapshots as native context, StateSync also runs as an MCP server — drop this into your MCP 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 exposed: statesync://project/{id}, statesync://project/{id}/snapshots, statesync://snapshot/{id}, statesync://audit.

API surface

new StateSync({ apiKey, baseUrl?, timeoutMs?, fetchImpl? })

• apiKey — required (or set STATESYNC_API_KEY).
• baseUrl — defaults to the hosted service.
• timeoutMs — request timeout (default 30 000).
• fetchImpl — custom fetch (Node 18+ has global fetch).

sync.checkpoint({ project, messages, files?, decisions?, testsPassed?, testsFailed?, agent?, metadata? })

Save an agent state snapshot. project accepts either a proj_... id or a project name (auto-created on first use).

sync.pull({ project, agent?, query?, maxTokens? })

Return the compressed unified context. See CompressedContext in the types.

sync.compress({ messages, query?, maxTokens?, projectName? })

One-shot compression (no project required) — useful to preview savings.

sync.listProjects() / sync.createProject(name, description?)

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.

Links

• 📚 Documentation: https://www.statesync.it/docs
• 🎛️ Dashboard: https://www.statesync.it/dashboard
• 📖 OpenAPI spec: https://www.statesync.it/openapi.json
• 📦 Sister SDK (Python): https://pypi.org/project/agent-state-api/

License

MIT.