mem9-guard-mcp

An MCP server that exposes mem9 (the TiDB team's persistent memory backend for AI agents) behind OWASP agent-memory-guard.

Agents never touch the raw mem9 API — every read and write goes through the guard:

MCP client (agent)
        │  memory_read / memory_write / ...
        ▼
  mem9-guard-mcp (this server)
        │  MemoryGuard + Policy.strict()   ← inspect, then block / quarantine / redact
        ▼
  Mem9Store adapter (MemoryStore Protocol)
        │  REST (X-API-Key)
        ▼
      mem9 (api.mem9.ai or self-hosted)

This protects agent memory against prompt injection, secret leakage, and memory poisoning: malicious or sensitive content is blocked, quarantined, or redacted according to policy before it ever reaches — or returns from — the store.

Tools

Tool	Description
memory_write(key, value, source_class, memory_class)	Guarded write. Result is allow / redact / quarantine / blocked
memory_read(key, default)	Read with integrity verification and outbound screening
memory_delete(key)	Delete a key (protected keys are blocked)
memory_list()	List stored keys
security_events(limit)	Recent security events emitted by the guard (for auditing)
quarantine_list()	Writes currently held in quarantine

rollback / snapshot restore is intentionally not exposed. Recovery is an operator action; giving it to agents would let them discard legitimate writes or cover up poisoned data.

Configuration (environment variables)

Variable	Description
MEM9_API_KEY	mem9 API key. Falls back to a local JSON store when unset
MEM9_API_URL	Defaults to https://api.mem9.ai. Override for self-hosted mem9
MEM9_AGENT_ID	X-Mnemo-Agent-Id header (optional)
MEM9_GUARD_POLICY	Path to a policy YAML. Defaults to Policy.strict()
MEM9_GUARD_LOCAL_PATH	Path of the fallback JSON store (default mem9_local_store.json)

Installing into Claude Code

Straight from GitHub (no clone needed — uvx fetches and builds on first run):

claude mcp add mem9-guard \
  --env MEM9_API_KEY=<your-key> \
  -- uvx --from git+https://github.com/Riku-KANO/mem9-guard-mcp mem9-guard-mcp

Or from a local clone (recommended while developing):

claude mcp add mem9-guard \
  --env MEM9_API_KEY=<your-key> \
  -- uv run --project <path-to-this-repo> mem9-guard-mcp

Notes:

• MEM9_API_KEY is optional — omit the --env line to use the local JSON store fallback.
• The server is registered for the current project by default; add --scope user to make it available in every project.
• For self-hosted mem9, add --env MEM9_API_URL=<url>.
• Verify with claude mcp list, or run /mcp in a new session to see the memory_write / memory_read / ... tools.

Other MCP clients

Any MCP client that supports stdio servers works, e.g.:

{
  "mcpServers": {
    "mem9-guard": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Riku-KANO/mem9-guard-mcp", "mem9-guard-mcp"],
      "env": { "MEM9_API_KEY": "<your-key>" }
    }
  }
}

Development

uv sync
uv run pytest

# End-to-end smoke test over stdio (no LLM involved)
uv run python scripts/smoke_stdio.py

Notes

The mem9 v1alpha2 JSON field names (content / metadata / id) are not yet covered by a published official schema, so they are centralized as assumptions in src/mem9_guard_mcp/client.py. If the real API differs, that is the only file that needs to change.

License

MIT