Allows Hermes Agent to integrate with AgentCheckpoint for managing shared state and coordinating multi-agent workflows with atomic reads and writes.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@agentcheckpoint save checkpoint for the analysis pipeline: step 3 passed"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Atomic key-value state store for AI agent coordination.
🌐 🇪🇸 Español · 🇫🇷 Français · 🇧🇷 Português
pip install agentcheckpointThen add it to your MCP client of choice (jump to Client Configuration).
Related MCP server: JustClone Coordination MCP Server
Semantic memory stores —vector DBs, agentmemory, mem0, etc.— are designed for facts and learning, not state coordination. When multiple agents read and write shared state, here's what happens:
Problem | What happens | Consequence |
| Each save creates a new entry | Dozens of stale versions pile up |
| Returns semantically close results, not the latest | Agents read outdated state |
No concurrency control | Two agents read the same state, write without coordination | Changes overwrite each other, data loss |
No version guard | One write can blindly overwrite another agent's work | Corrupted workflows, re-executed work |
Bottom line: your agents work with stale state, re-run tasks already completed, and burn compute on duplicated effort.
AgentCheckpoint is not a memory store — it's a shared state store with atomic guarantees. Think of it as a traffic light or shared memory for AI agents.
┌──────────────────────┐ MCP stdio ┌────────────────────┐ SQLite WAL ┌──────────────┐
│ Agent A │ ───────────────→│ │ ──────────────→│ │
│ Agent B │ ───────────────→│ AgentCheckpoint │ ──────────────→│ state.db │
│ Cron Worker C │ ───────────────→│ MCP Server │ ──────────────→│ (1 file) │
│ Pipeline D │ ←──────────────│ │ ←──────────────│ │
└──────────────────────┘ └────────────────────┘ └──────────────┘Feature | AgentCheckpoint | agentmemory / vector DB | Redis | JSON file |
Purpose | State coordination | Facts, learning | Generic cache | Basic persistence |
Write | Always replaces (UPSERT) | Always appends (INSERT) | Overwrites (no versioning) | Overwrites entire file |
Read |
|
| Direct key lookup | Parse & search |
Concurrency | Optimistic Concurrency Control (OCC) | None | None native | None |
Persistence | SQLite WAL (transactional, ACID) | Varies by backend | RAM / RDB / AOF | Filesystem-dependent |
Infrastructure | Zero — single stdio process | Server, API, indices | Dedicated server | Zero |
MCP Tooling | Native — auto-discovery of tools | No | No | No |
Lines of code | ~150 | Thousands | ~50K+ | ~5 (no guarantees) |
Use both together: AgentCheckpoint for shared state, vector memory / agentmemory for facts, observations, and discoveries.
Tool | Description | When to use |
| Read the current value, version, and timestamp for a key | Before any modification |
| Write with optional version guard (OCC) | When multiple agents write the same key |
| Unconditional atomic write | When a single agent/worker owns the key |
| List keys matching a SQL LIKE pattern | Auditing, discovery, debugging |
| Remove a key permanently | Cleanup of completed state |
Each tool is auto-discovered through the MCP protocol — no extra configuration needed.
Note for MCP clients: in some clients tools are prefixed as
mcp_checkpoint_get_state,mcp_checkpoint_set_state, etc.
pip install agentcheckpoint
# or with uv:
uv pip install agentcheckpointConfiguration varies by platform. After adding, restart your client or reload MCP servers.
Edit claude_desktop_config.json:
{
"mcpServers": {
"checkpoint": {
"command": "agentcheckpoint",
"timeout": 10
}
}
}Add to ~/.claude/settings.json:
{
"mcpServers": {
"checkpoint": {
"command": "agentcheckpoint",
"timeout": 10
}
}
}Or via CLI:
claude mcp add checkpoint -- python -m agentcheckpointAdd to ~/.cursor/mcp.json:
{
"mcpServers": {
"checkpoint": {
"command": "agentcheckpoint",
"timeout": 10
}
}
}Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"checkpoint": {
"command": "agentcheckpoint",
"timeout": 10
}
}
}Add to ~/.continue/config.json:
{
"experimental": {
"mcpServers": {
"checkpoint": {
"command": "agentcheckpoint",
"timeout": 10
}
}
}
}Add to ~/.hermes/config.yaml:
mcp_servers:
checkpoint:
command: "agentcheckpoint"
timeout: 10Then run /reload-mcp in-session, or restart the gateway.
{
"mcpServers": {
"checkpoint": {
"command": "uvx",
"args": ["agentcheckpoint"],
"timeout": 10
}
}
}Ask your agent:
"What tools do I have from the checkpoint MCP server?"
You should see all 5 tools listed above.
# Save state
mcp_checkpoint_force_set_state(
key="project:build-status",
value='{"phase": "testing", "passed": 13, "failed": 2}'
)
# Read state later
status = mcp_checkpoint_get_state(key="project:build-status")
# → {status: "ok", key: "...", value: {...}, version: 1, updated_at: "2026-06-16T..."}Use force_set_state — always succeeds, always replaces:
# Nightly worker: checkpoint progress
mcp_checkpoint_force_set_state(
key="checkpoint:nocturnal-2026-06-16",
value='{"status": "in-progress", "started_at": "2026-06-16T03:00:00Z"}'
)
# ... processing ...
mcp_checkpoint_force_set_state(
key="checkpoint:nocturnal-2026-06-16",
value='{"status": "completed", "records_processed": 1427, "finished_at": "..."}'
)Use get_state + set_state with the version guard (Optimistic Concurrency Control):
# 1. READ with version
current = mcp_checkpoint_get_state(key="workflow:plan-today")
plan = json.loads(current["value"])
# plan.current_index = 5, version = 3
# 2. MODIFY
plan.current_index += 1
plan.current_task = "analysis"
# 3. WRITE with the version we read
result = mcp_checkpoint_set_state(
key="workflow:plan-today",
value=json.dumps(plan),
expected_version=current["version"] # ← OCC guard
)
if result["status"] == "conflict":
# Another agent changed the state → re-read and retry
pass
elif result["status"] == "ok":
# Write succeeded, new version assigned
print(f"Checkpoint updated, version {result['version']}")Each write carries the version observed at read time. If another agent changed the key in between, the write fails with conflict — you re-read and retry. This is standard Optimistic Concurrency Control (OCC), the same pattern used by Elasticsearch, CouchDB, and Git.
# Attempt to acquire a lock (create-only)
result = mcp_checkpoint_set_state(
key="lock:db-migration",
value=json.dumps({"owner": "agent-A", "acquired_at": "..."}),
expected_version=0 # ← only works if it DOESN'T exist
)
if result["status"] == "ok":
# Lock acquired — run critical operation
run_migration()
# Release
mcp_checkpoint_delete_state(key="lock:db-migration")
else:
# Lock held by another — wait or abort
pass# Before starting: was this already completed?
state = mcp_checkpoint_get_state(key="checkpoint:generate-invoices")
if state["status"] != "not_found":
print("Work already completed, skipping")
return
# Claim + execute
mcp_checkpoint_force_set_state(
key="checkpoint:generate-invoices",
value='{"status": "started"}'
)
# ... do the work ...Keep your keys organized with this structure:
<domain>:<identifier>[:<attribute>]Example | Purpose |
| Multi-step workflow state |
| Build state for a project |
| Mutex for critical operation |
| Daily execution plan |
| Nightly worker checkpoint |
| Cron job coordination |
Best practices:
Use colons (:) as separators — readable and work with SELECT LIKE
Keep keys under 200 characters
Values must always be valid JSON
Use list_state(pattern="project:%") to find all keys in a domain
get_state(key)Parameter | Type | Required | Description |
|
| ✅ | Key to read |
Success response:
{"status": "ok", "key": "workflow:plan", "value": "...", "version": 3, "updated_at": "2026-06-16T..."}Key not found:
{"status": "not_found", "key": "workflow:plan"}set_state(key, value, expected_version?)Parameter | Type | Required | Description |
|
| ✅ | Key to write |
|
| ✅ | Value (JSON string) |
|
| ❌ | -1=unconditional (default), 0=create-only, N=versioned update |
Version guard behavior:
| Result |
| Always writes (like |
| Creates only if it DOESN'T exist. Fails with |
| Updates only if stored version matches N. Fails with |
force_set_state(key, value)Unconditional. Always writes. No version guard.
Parameter | Type | Required | Description |
|
| ✅ | Key to write |
|
| ✅ | Value (JSON string) |
list_state(pattern?)Parameter | Type | Required | Description |
|
| ❌ | SQL LIKE pattern ( |
delete_state(key)Parameter | Type | Required | Description |
|
| ✅ | Key to delete |
Env var | Default | Description |
|
| SQLite database file path |
Custom path example:
CHECKPOINT_DB_PATH=/tmp/my-state.db agentcheckpoint┌──────────────────────┐ stdio (stdin/stdout) ┌────────────────────┐
│ │ │ │
│ MCP Client │ ────── JSON-RPC (MCP) ───────→ │ agentcheckpoint │
│ (Claude, Cursor, │ ←────────────────────────────── │ MCP Server │
│ Windsurf, Hermes) │ │ │
│ │ │ ┌──────────────┐ │
└──────────────────────┘ │ │ SQLite WAL │ │
│ │ state.db │ │
│ │ (1 file) │ │
│ └──────────────┘ │
└────────────────────┘Transport: stdio (MCP subprocess) — no network ports, no containers
Database: SQLite in WAL mode (Write-Ahead Logging) for concurrent reads without blocking
Concurrency: PRAGMA synchronous=NORMAL — balance between durability and speed
Validation: all values validated as JSON on write
Versioning: every UPSERT atomically increments the version counter
Connection timeout: 5 seconds in SQLite, 10 seconds recommended in MCP client
Atomicity: writes are transactional — either fully persisted or not persisted at all
Q: Does AgentCheckpoint replace agentmemory? A: No. They're complementary. AgentCheckpoint coordinates state (who did what? which step are we on?). agentmemory stores facts and learnings (what did we discover? how does X work?). Use both together.
Q: Can I run multiple instances pointing at the same file?
A: SQLite WAL supports multiple concurrent readers, but for multiple writers it's best to use a single MCP server instance. For high availability, consider placing the .db on a shared volume.
Q: What if the process crashes mid-write? A: SQLite WAL guarantees atomicity — either the full change is persisted or nothing is. No partial writes.
Q: How large can a value be? A: Values are JSON strings. SQLite can theoretically handle up to ~1GB, but we recommend keeping values under 100KB. For large data, store a reference (file path, URL) as the value.
Q: How do I clean up old checkpoints?
A: Use delete_state for individual keys or write a script that iterates with list_state and deletes based on updated_at.
Q: Does it support TTL / auto-expiration?
A: Not natively, but you can implement it in your agent: when reading, check updated_at and decide if the state is stale.
git clone https://github.com/erniomaldo/agentcheckpoint
cd agentcheckpoint
pip install -e ".[dev]"Source code lives in src/agentcheckpoint/:
File | What it does |
| Package version |
| Entry point ( |
| Complete MCP server (~150 lines) |
Fork the repo
Create a branch (git checkout -b feature/awesome-thing)
Make your changes
Commit with clear messages
Push and open a Pull Request
MIT © Ernesto Maldonado
Language | File |
🇺🇸 English |
|
🇪🇸 Español | |
🇫🇷 Français | |
🇧🇷 Português |
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Durable agent-to-agent handoffs and shared scratchpad for multi-agent workflows.
Coordinate multiple AI agents over MCP: atomic claims, leases, shared ledger, handoffs, tasks.
Encrypted A2A object storage for autonomous agent state and artifacts
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/erniomaldo/agentcheckpoint'
If you have feedback or need assistance with the MCP directory API, please join our Discord server