Agent-scoped persistent storage as an MCP server. Give any MCP client (Claude Code, Claude Desktop, Cursor, custom agents) a durable memory with namespace isolation, TTL retention tiers, and a full audit trail - backed by a single SQLite file.
Provenance note: this is a clean Stage 4 rebuild (2026-07-09) from the recovered SWARM OS spec. The original scaffold was lost with an expired session; the spec (seven tools, SQLite, TTL tiers, audit logging, namespace isolation) survived in project memory and this implementation was rebuilt and re-tested from it.
Agents forget everything between sessions, and multi-agent setups trample each other's state. AgentStore gives each agent (or each purpose) an isolated namespace, expires scratch data automatically, and records every read, write, delete, and denied access - so storage doubles as the audit log and approval-queue state layer for a governed agent fleet.
| Tool | Purpose |
|---|---|
store_set |
Write a JSON value to namespace/key with a TTL tier |
store_get |
Read a value (null on miss or expiry) |
store_delete |
Remove a key |
store_list |
List keys in a namespace, optional prefix filter |
store_query |
Substring search across stored values |
store_stats |
Entry count, bytes, per-tier breakdown per namespace |
audit_read |
Read the audit trail, filter by namespace or operation |
| Tier | Retention | Use for |
|---|---|---|
ephemeral |
1 hour | Scratch state inside a single run |
session |
24 hours | Working context across a day's runs |
working |
7 days (default) | Active project state |
durable |
Never expires | Decisions, long-term memory, audit anchors |
Expired entries are purged lazily on every operation - no background process needed.
Set AGENTSTORE_NAMESPACES to a comma-separated allowlist and the server refuses any operation outside it. Denied attempts are themselves written to the audit log (op = denied:<operation>), so cross-namespace probing by an agent is visible, not silent.
pip install -e ".[dev]"
pytest # 15 tests, no MCP dependency needed for the core
python -m agentstore.server # run as an MCP server (stdio)Claude Desktop / Claude Code config:
{
"mcpServers": {
"agentstore": {
"command": "python",
"args": ["-m", "agentstore.server"],
"env": {
"AGENTSTORE_DB": "/path/to/agentstore.db",
"AGENTSTORE_AGENT_ID": "researcher-1",
"AGENTSTORE_NAMESPACES": "research,briefs"
}
}
}
}MCP client (Claude Code / Desktop / Cursor / custom agent)
| stdio (JSON-RPC)
v
server.py FastMCP - seven thin tool wrappers, env-based config
|
v
store.py pure-stdlib engine: namespaces, TTL purge, audit writes
|
v
SQLite entries (namespace,key PK) + audit (append-only)
Design choices: the engine has zero dependencies and is fully tested standalone, so the MCP layer stays a wrapper you can swap (HTTP transport, different protocol) without touching storage logic. One SQLite file means backup is cp, inspection is any SQLite browser, and hosting cost is zero.
MIT.