AgentStore

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.

Why

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.

The seven tools

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

TTL tiers

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.

Namespace isolation

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.

Quickstart

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

Architecture

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.

License

MIT.