madb-mcp-server 0.1.0

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 (9)

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

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)