agent-state

MCP server for cross-session, cross-agent state coordination. The "Terraform state backend for agents" — compare-and-swap state, advisory leases, a decision log, and handoff/resume between agents.

Coordination, not memory. Memory servers recall facts over time. agent-state coordinates live working state across sessions and agents — with the concurrency primitives (CAS, leases) that keep parallel agents from clobbering each other. That space is unowned; memory is crowded.

Install

// Claude Desktop / any MCP client
{
  "mcpServers": {
    "agent-state": {
      "command": "npx",
      "args": ["-y", "@dcassociatesgroup/agent-state"],
      "env": { "AGENT_STATE_DIR": "~/.agent-state" }   // optional; defaults to ~/.agent-state
    }
  }
}

Tools (9)

| Tool | Purpose | |------|---------| | get_state | Read a state doc + its etag (a sha256 CAS token). | | update_state | Write state with optional ifMatch etag — compare-and-swap rejects the write if state changed underneath you, killing the lost-update race. | | race_check | Ask whether an etag you hold is still current before acting on possibly-stale data. | | acquire_lease / release_lease | Advisory locks — signal "I'm working this resource," with TTL. Informational; they never block writes. | | record_decision / list_decisions | Append-only decision log so later agents know why and don't relitigate. | | handoff / resume | Bundle summary + state into a packet another agent resumes exactly once. |

get/update (CAS) is durability; lease is intent-signaling; handoff/resume is transfer. Together they let multiple agents share one workspace without stepping on each other.

Storage

v0.1 stores JSON under AGENT_STATE_DIR (default ~/.agent-state), namespaced, with atomic writes (temp file + rename). Names are validated ([A-Za-z0-9._-], no separators) to prevent traversal. Single-machine, zero network, zero telemetry.

Roadmap

• v0.1 (this): local store, 9 coordination tools. Free, forever, for solo/local use.
• Hosted tier: the same 9 tools over a shared backend — many agents across machines coordinating on the same namespaces, with server-side CAS and lease enforcement. The architectural paywall: solo is free; team coordination is the paid service. Upgrade is a config change, not a rewrite.

Develop

npm install
npm run build     # tsc -> dist/
npm run smoke     # live MCP protocol test: spawns the server, drives it as a client

Apache-2.0. Built by Derek Coleman & Associates Inc.