Skip to content

About

Agent-scoped persistent storage MCP server: namespaces, TTL tiers, audit log, SQLite

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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.

About

Agent-scoped persistent storage MCP server: namespaces, TTL tiers, audit log, SQLite

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages