Skip to main content
Glama
erniomaldo

agentcheckpoint

by erniomaldo

AgentCheckpoint

Atomic key-value state store for AI agent coordination.

PyPI - Version PyPI - Python Versions License PyPI - Downloads



🌐 πŸ‡ͺπŸ‡Έ EspaΓ±ol Β· πŸ‡«πŸ‡· FranΓ§ais Β· πŸ‡§πŸ‡· PortuguΓͺs


πŸ“¦ Installation

pip install agentcheckpoint

Then add it to your MCP client of choice (jump to Client Configuration).


Related MCP server: JustClone Coordination MCP Server

🀨 The Problem

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

memory.save() has no update

Each save creates a new entry

Dozens of stale versions pile up

memory.recall() uses similarity

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.


βœ… The Solution

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           β”‚ ←──────────────│                    β”‚ ←──────────────│              β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

How it compares

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

SELECT WHERE key=? exact match

ORDER BY distance semantic

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.


πŸ› οΈ Tools (MCP API)

Tool

Description

When to use

get_state(key)

Read the current value, version, and timestamp for a key

Before any modification

set_state(key, value, expected_version?)

Write with optional version guard (OCC)

When multiple agents write the same key

force_set_state(key, value)

Unconditional atomic write

When a single agent/worker owns the key

list_state(pattern?)

List keys matching a SQL LIKE pattern

Auditing, discovery, debugging

delete_state(key)

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.


πŸš€ Quick Start

1. Install

pip install agentcheckpoint
# or with uv:
uv pip install agentcheckpoint

2. Add to your MCP client

Configuration varies by platform. After adding, restart your client or reload MCP servers.

🟣 Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "checkpoint": {
      "command": "agentcheckpoint",
      "timeout": 10
    }
  }
}

πŸ”΅ Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "checkpoint": {
      "command": "agentcheckpoint",
      "timeout": 10
    }
  }
}

Or via CLI:

claude mcp add checkpoint -- python -m agentcheckpoint

🟒 Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "checkpoint": {
      "command": "agentcheckpoint",
      "timeout": 10
    }
  }
}

🟠 Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "checkpoint": {
      "command": "agentcheckpoint",
      "timeout": 10
    }
  }
}

βšͺ Continue.dev

Add to ~/.continue/config.json:

{
  "experimental": {
    "mcpServers": {
      "checkpoint": {
        "command": "agentcheckpoint",
        "timeout": 10
      }
    }
  }
}

πŸ”Ά Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  checkpoint:
    command: "agentcheckpoint"
    timeout: 10

Then run /reload-mcp in-session, or restart the gateway.

🐍 Any client with uvx support

{
  "mcpServers": {
    "checkpoint": {
      "command": "uvx",
      "args": ["agentcheckpoint"],
      "timeout": 10
    }
  }
}

3. Verify

Ask your agent:

"What tools do I have from the checkpoint MCP server?"

You should see all 5 tools listed above.

4. First checkpoint

# 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..."}

🎯 Usage Patterns

Pattern 1: Single Writer (cron jobs, solo agents)

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": "..."}'
)

Pattern 2: Multiple Agents with OCC (the important one)

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.

Pattern 3: Distributed Lock

# 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

Pattern 4: Skip-if-done (idempotency guard)

# 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 ...

πŸ“ Key Naming Convention

Keep your keys organized with this structure:

<domain>:<identifier>[:<attribute>]

Example

Purpose

workflow:daily-digest

Multi-step workflow state

project:agentcheckpoint:build-status

Build state for a project

lock:database-migration

Mutex for critical operation

plan:2026-06-16

Daily execution plan

checkpoint:nocturnal-pillar-1

Nightly worker checkpoint

cron:news-morning

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


πŸ“Š API Reference

get_state(key)

Parameter

Type

Required

Description

key

string

βœ…

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

string

βœ…

Key to write

value

string

βœ…

Value (JSON string)

expected_version

integer

❌

-1=unconditional (default), 0=create-only, N=versioned update

Version guard behavior:

expected_version

Result

-1 (omitted)

Always writes (like force_set_state)

0

Creates only if it DOESN'T exist. Fails with conflict if it does

N > 0

Updates only if stored version matches N. Fails with conflict if it doesn't

force_set_state(key, value)

Unconditional. Always writes. No version guard.

Parameter

Type

Required

Description

key

string

βœ…

Key to write

value

string

βœ…

Value (JSON string)

list_state(pattern?)

Parameter

Type

Required

Description

pattern

string

❌

SQL LIKE pattern (% = any text, _ = single char). Default: %

delete_state(key)

Parameter

Type

Required

Description

key

string

βœ…

Key to delete


βš™οΈ Configuration

Env var

Default

Description

CHECKPOINT_DB_PATH

~/.hermes/checkpoints.db

SQLite database file path

Custom path example:

CHECKPOINT_DB_PATH=/tmp/my-state.db agentcheckpoint

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”       stdio (stdin/stdout)      β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                       β”‚                                  β”‚                    β”‚
β”‚  MCP Client           β”‚ ────── JSON-RPC (MCP) ───────→  β”‚  agentcheckpoint   β”‚
β”‚  (Claude, Cursor,     β”‚ ←────────────────────────────── β”‚  MCP Server        β”‚
β”‚   Windsurf, Hermes)   β”‚                                  β”‚                    β”‚
β”‚                       β”‚                                  β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜                                  β”‚  β”‚  SQLite WAL   β”‚  β”‚
                                                          β”‚  β”‚  state.db     β”‚  β”‚
                                                          β”‚  β”‚  (1 file)     β”‚  β”‚
                                                          β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
                                                          β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Technical details

  • 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


❓ FAQ

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.


πŸ§‘β€πŸ’» Development

git clone https://github.com/erniomaldo/agentcheckpoint
cd agentcheckpoint
pip install -e ".[dev]"

Source code lives in src/agentcheckpoint/:

File

What it does

__init__.py

Package version

__main__.py

Entry point (python -m agentcheckpoint)

server.py

Complete MCP server (~150 lines)

Contributing

  1. Fork the repo

  2. Create a branch (git checkout -b feature/awesome-thing)

  3. Make your changes

  4. Commit with clear messages

  5. Push and open a Pull Request


πŸ“œ License

MIT Β© Ernesto Maldonado


🌐 Languages

Language

File

πŸ‡ΊπŸ‡Έ English

README.md (this)

πŸ‡ͺπŸ‡Έ EspaΓ±ol

README.es.md

πŸ‡«πŸ‡· FranΓ§ais

README.fr.md

πŸ‡§πŸ‡· PortuguΓͺs

README.pt.md


Available Tools

5 tools
delete_stateA

Remove a checkpoint key and its value permanently.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesCheckpoint key to delete

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explicitly discloses the destructive, irreversible nature of the operation ("permanently") and clarifies that both the key and its associated value are removed. This goes beyond a simple tautology. It does not mention error behavior or return values, which is a minor gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that fronts the verb and resource, and includes the crucial adverb "permanently." It has no filler or redundancy, making it appropriately sized for the tool's simple purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter delete tool with no output schema, the description covers the core purpose, the destructive effect (key + value), and irreversibility. It does not explain return behavior or what happens if the key does not exist, but these are not critical for a straightforward deletion. Overall, it is sufficiently complete for an AI agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides 100% coverage with a clear description for the one parameter ("Checkpoint key to delete"). The tool description essentially restates this without adding new details about format, constraints, or special values. A baseline of 3 is appropriate given the complete schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ("Remove"), the resource ("a checkpoint key"), and adds that the value is also permanently deleted. This distinguishes it unambiguously from sibling tools like get_state, set_state, and list_state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when you want to delete a checkpoint entry) but provides no explicit guidance on when not to use it or how it differs from alternatives like force_set_state. No prerequisites or edge-case conditions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

force_set_stateA

Unconditionally write a checkpoint value. Always succeeds. Prefer for single-writer workflows. For concurrent writers, use set_state with expected_version.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesCheckpoint key
valueYesValue to store (must be JSON-encoded string)

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and discloses key traits: 'Unconditionally' indicates no version check, 'Always succeeds' signals reliability. It adds meaningful context beyond the schema, though it could also mention overwriting side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two compact sentences with no redundancy. The core action is front-loaded, followed by concise usage guidance, making every word earn its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple write tool with no output schema, the description covers purpose, behavioral traits, and usage. The 'unconditionally' implication covers overwriting, though explicit mention of potential data loss would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add parameter-specific details, but the schema already fully documents key and value, including value format requirement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'Unconditionally write a checkpoint value,' using a specific verb and resource. It distinguishes from siblings by contrasting with set_state for concurrent writers, making its unique role clear.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Prefer for single-writer workflows' and when not to: 'For concurrent writers, use set_state with expected_version.' This provides clear alternatives and exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_stateA

Read the current value of a checkpoint by key. Returns the latest stored JSON value, its version, and update timestamp. Returns {"status": "not_found"} if key doesn't exist.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesCheckpoint key, e.g. 'workflow:plan-2026-06-12'

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the return payload (latest JSON value, version, update timestamp) and the not_found behavior, which fully covers the observable behavior of this read-only tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (one parameter, read-only). The description explains the return format and the not_found case, which is complete for this operation. An output schema is absent, so the description's return value explanation is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 100% coverage of the single 'key' parameter with an example. The description does not add additional parameter semantics beyond the schema, so it stays at the baseline for schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies 'Read the current value of a checkpoint by key' with a clear verb and resource. It distinguishes from sibling tools (set_state, list_state, etc.) by describing the read semantics and return format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: to retrieve a stored checkpoint value. It does not explicitly mention alternatives or exclusions, but the sibling tool names make the distinction obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_stateA

List checkpoint keys matching a pattern (SQL LIKE syntax). Pass '%' or omit for all keys. Returns key, version, and updated_at for each match.

ParametersJSON Schema
NameRequiredDescriptionDefault
patternNoSQL LIKE pattern (default '%' = all keys)%

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the return fields (key, version, updated_at), supports pattern matching, and shows default behavior. It does not detail ordering, case sensitivity, or potential side effects, but for a listing operation, this is adequate behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences front-load the purpose and then add essential return-value detail. Every sentence earns its place with no filler or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has one optional parameter, no output schema, and is inherently simple. The description covers purpose, parameter behavior, and return fields completely for the tool's complexity. Sibling tools are named, further enriching context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already explains pattern, default, and meaning. The description adds the SQL LIKE context and 'omit for all keys', but these are largely redundant with the schema. No additional parameter details are provided, so baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') and resource ('checkpoint keys'), and clarifies matching via SQL LIKE syntax. It distinguishes from siblings like get_state, set_state, and delete_state by clearly indicating enumeration of keys rather than value access or mutation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for the pattern parameter ('Pass '%' or omit for all keys') and implies this tool is for listing keys, not retrieving individual state. However, it does not explicitly state when to use this tool over get_state or other alternatives, so it stops short of full guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

set_stateA

Atomically write a checkpoint with optional version guard. Pass expected_version from a prior get_state call. expected_version=0 β†’ create-only (fails if key exists). expected_version=N β†’ update only if stored version matches (conflict-safe). Omit expected_version or pass -1 β†’ unconditional write. Use force_set_state for simpler unconditional writes.

ParametersJSON Schema
NameRequiredDescriptionDefault
keyYesCheckpoint key
valueYesValue to store (must be JSON-encoded string)
expected_versionNoVersion guard: -1=unconditional, 0=create-only, N=versioned update

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains atomicity, version guard semantics, and conflict-safe behavior. The only minor gap is not explicitly stating what happens on version mismatch (e.g., fails vs. returns error), but it implies the write is conditional and conflict-safe, which is sufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with zero filler. It front-loads the core function, then details the version guard parameter, and ends with the alternative tool. Every sentence earns its place, making it appropriately sized for the complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters and no output schema, the description is highly complete. It covers the write semantics, version guard options, and when to use alternatives. It even mentions the recommended way to obtain expected_version from get_state, forming a complete usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the expected_version semantics in detail (0=create-only, N=versioned update, omit/-1=unconditional) and clarifying that value must be a JSON-encoded string, which goes beyond the schema's brief description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's core function: 'Atomically write a checkpoint with optional version guard.' It uses a specific verb ('write') and resource ('checkpoint'), and distinguishes itself from sibling tools by mentioning force_set_state as an alternative for simpler writes. This makes the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use this tool vs. alternatives: 'Use force_set_state for simpler unconditional writes.' It also explains the different expected_version modes (create-only, conditional update, unconditional), which tells the agent exactly in what scenarios to use this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv1.0.0
    • First observeddelete_state
    • First observedforce_set_state
    • First observedget_state
    • First observedlist_state
    • First observedset_state

TDQS

A4.3/5.0
Disambiguation3/5

set_state and force_set_state both perform writes, with set_state also supporting unconditional writes via omitted expected_version. The descriptions clarify intended use cases (concurrency-safe vs. simple writes), but the overlap creates a minor selection risk. Other tools are clearly distinct.

Naming Consistency5/5

All tools follow a clear [verb]_state pattern: get_state, set_state, force_set_state, list_state, delete_state. The compound verb force_set is still consistent and predictable.

Tool Count5/5

Five tools is well-scoped for a checkpoint store, covering read, write, list, delete, and a conditional-write variant without clutter or redundancy.

Completeness5/5

The set covers the full lifecycle: create (set_state with version 0), read (get_state), update (set_state with version), delete (delete_state), and listing (list_state). The force_set_state adds a convenience write, leaving no obvious gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    C
    maintenance
    Provides a shared context layer for AI agent teams to improve token efficiency through context deduplication and incremental state sharing. It enables multiple agents to coordinate tasks, share real-time discoveries, and manage dependencies while significantly reducing redundant data transmission.
    15
    0
    7
    MIT
  • F
    license
    Not graded
    quality
    Not graded
    maintenance
    A production-grade coordination hub that enables AI agents and human teams to work as a single organism by sharing tasks, context, decisions, and persistent memory across projects. It features two-tier agentic memory with per-agent hot caches, inter-agent messaging, and multi-agent authorship tracking for seamless collaboration.
    2
    -
  • A
    license
    Not graded
    quality
    C
    maintenance
    Gives AI agents persistent memory, handoffs, and shared context across sessions, enabling seamless continuity and multi-agent collaboration.
    82
    69
    -
  • A
    license
    Not graded
    quality
    B
    maintenance
    Airlock provides named resource locks, atomic shared state, presence, events, and a task queue for AI agents to coordinate on a shared filesystem, with blocking waits and SQLite-backed persistence.
    1
    MIT

Latest Blog Posts

MCP directory API

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