madb-mcp-server 0.2.8

MCP server for Meta-AgentsDB — persistent causal memory for AI agents

madb-mcp-server

Persistent causal memory for Claude Code — 4.65x recall ROI measured in production.

madb-mcp-server gives Claude Code (and any MCP-compatible client) a real database backend for agent memory: causal chains, composite-scored recall, policy-gated access, and built-in analytics.

Install

pip install madb-mcp-server

Or run directly with uvx (no install needed):

uvx madb-mcp-server

Claude Code Setup

claude mcp add madb -- uvx madb-mcp-server

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "madb": {
      "command": "uvx",
      "args": ["madb-mcp-server"],
      "env": {
        "MADB_DATA_DIR": "~/.madb/data",
        "MADB_TENANT_ID": "default"
      }
    }
  }
}

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "madb": {
      "command": "uvx",
      "args": ["madb-mcp-server"],
      "env": {
        "MADB_DATA_DIR": "~/.madb/data",
        "MADB_TENANT_ID": "default"
      }
    }
  }
}

Tools (12)

Tool	Description
remember	Store a memory with causal links, tags, and importance scoring
recall	Semantic recall — vector similarity + recency + causal proximity + importance
get_memory	Point lookup by event_id
forget	Soft-delete a memory (tombstone, preserved in causal chain)
search	Structured query by tenant + scope
list_recent	Last N memories for a tenant
save_skill	Store a reusable skill/pattern (GC-protected, idempotent by name)
recall_skill	Semantic skill recall with structured output
list_skills	List all saved skills ranked by composite score
stats	Engine metrics snapshot (writes, reads, flushes, compactions, WAL state)
trace_cause	Walk the causal DAG forward or backward from any memory
analytics	MCP usage analytics — call counts, latencies, recall precision, Memory ROI

Memory ROI

MADB tracks how much value its memory provides to your Claude sessions:

• Tokens served from recall — context delivered from memory instead of re-reading files
• File reads avoided — estimated file re-reads saved by recalling from memory
• Recall precision — hit rate and average relevance score
• Write-to-read ratio — tokens recalled per token written (measured 4.65x in production)

Run the analytics tool at any time to see your session's Memory ROI.

Resources

URI	Description
madb://memories/{event_id}	Read a single memory record

Environment Variables

Variable	Default	Description
MADB_DATA_DIR	~/.madb/data	Database storage directory
MADB_TENANT_ID	default	Default tenant for tool calls
MADB_API_KEY	(unset)	If set, every tool call must pass a matching api_key
MADB_TELEMETRY	(on)	Set to off to disable anonymous usage telemetry
MADB_SKIP_UPDATE_CHECK	(unset)	Set to 1 to disable the daily PyPI version check

Privacy & Telemetry

Your memory content never leaves your device — all data is stored locally under MADB_DATA_DIR (~/.madb by default).

To improve the product, the server sends anonymous usage telemetry:

• What is sent: an opaque random install id, the package version, the host OS/Python version, the MCP runtime (e.g. claude-code), and counts — tool-call totals, distinct tools used, recall hits, sessions.
• What is never sent: memory content, queries, payloads, tenant names, file paths, usernames, or hostnames. "We measure how much, never what."
• When: an activation event on first connect and a heartbeat at most once per day. Fire-and-forget; it never blocks or delays a tool call.
• Opt out completely: set MADB_TELEMETRY=off.

A one-time notice is printed on first launch. On first run the server also copies a bundled Claude Skill into ~/.claude/skills (existing files are left untouched) and checks PyPI for updates (MADB_SKIP_UPDATE_CHECK=1 to disable).

How It Works

MADB is an agent-native database built in Rust with 5 novel primitives:

1. Causal DAG — every memory links to what caused it, forming an evidence chain
2. Composite-scored recall — vector similarity + recency + causal proximity + importance
3. Storage-layer policy — scope and retention rules enforced at the engine level
4. Partitioned WAL — per-tenant write-ahead log for crash safety
5. Time-bucketed HNSW — vector index organized by time for recency-aware search

License

Apache-2.0 (patent pending)