edobusy/agenthold

**Stop your AI agents from silently overwriting each other.**
When two agents update the same value, the second write quietly destroys the first. No error, no exception, just wrong data and a system that keeps running. agenthold is an MCP server that gives agents shared, versioned state with conflict detection built in. Think of it as git for your agents' working memory.
---
The problem
When two agents update the same value at the same time, the second write silently overwrites the first. No exception is raised. The value is wrong. The system keeps running.
Two agents read a $10,000 budget and allocate from it independently. Total committed: $15,000. The budget object never complains. This is a **read-modify-write conflict**: each agent's write assumes nothing changed since its read.
---
How it works
agenthold solves this with **optimistic concurrency control (OCC)**, the same mechanism Postgres uses in UPDATE ... WHERE version = N and DynamoDB uses in conditional writes.
Every value stored in agenthold has a version number. When an agent writes, it passes the version it read. If the stored version has changed since the read, the write is **rejected** with a ConflictError that includes the current value. The agent re-reads, recalculates, and retries.
The losing agent detects the conflict, re-reads the real remaining budget ($2,000), and adjusts its allocation. The total committed is always exactly $10,000. Every write is tracked.
OCC is the right fit for agent workflows because:
- Agents do work between reads and writes (network calls, LLM inference). You cannot hold a database lock across that work.
- Conflicts are rare. Retrying once is cheaper than acquiring a lock on every read.
- The retry logic is simple, explicit, and fully in the agent's control.
---
Works with any agent framework
agenthold connects via MCP (Model Context Protocol), the open standard for tool integration. Any framework that speaks MCP can use agenthold with zero glue code.
| Framework | How to connect |
|---|---|
| **Claude Desktop / Claude Code** | Built-in: add to mcpServers config |
| **Cursor / Continue / Windsurf** | Built-in: add to MCP config |
| **LangChain / LangGraph** | langchain-mcp-adapters |
| **CrewAI** | Native mcps field on Agent |
| **OpenAI Agents SDK** | Built-in mcp_servers param |
| **Google ADK** | Built-in MCP Toolbox |
| **AutoGen** | autogen_ext.tools.mcp |
| **PydanticAI** | Native MCP integration |
agenthold is not a framework. It is **shared infrastructure** that sits underneath your orchestration layer, the same way a database sits underneath your application. Your agents keep their existing tools and logic; agenthold adds the coordination primitive they are missing.
> **Not using MCP yet?** agenthold also works as a Python library you can call directly from any framework. Import StateStore, call .get() and .set() with version checks, and you have conflict-safe shared state.
---
Architecture
Every write carries a version number. If the stored version has changed since an agent's read, the write is rejected and the agent retries with current data. This is the same mechanism used by Postgres conditional updates and DynamoDB conditional writes.
---
Quick start
1. Install
2. Add to your MCP client config
3. Done
Agents automatically coordinate. No CLAUDE.md, no system prompt changes, no namespace design.
When an agent connects, it sees five self-documenting tools: agenthold_register, agenthold_claim, agenthold_release, agenthold_status, and agenthold_wait. The tool descriptions tell the agent when and how to use each one. Server instructions reinforce the protocol when the MCP client includes them.
---
Resources
agenthold identifies resources by canonical URIs. Tools accept either form:
- **Bare path** (e.g. "src/main.py") — resolves against the workspace named default, or the only configured workspace if exactly one exists.
- **Explicit URI** — "file:// / " for files, "custom:// " for opaque resources.
Equivalent inputs (./src/main.py, src\main.py, src//main.py, an absolute path inside the workspace) all canonicalize to the same internal URI, so two agents using different shorthands never fragment the keyspace. Path traversal (..) and dot segments (.) are rejected at the boundary.