# 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

```bash
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:

```json
{
  "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.