madb-mcp-server

madb-mcp-server

Persistent causal memory for Claude Code — causal chains, composite-scored recall, and a built-in Memory-ROI meter.

madb-mcp-server gives Claude Code (and any MCP-compatible client) a real database backend for agent memory: causal chains, composite-scored recall, a tamper-evident integrity chain, 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 (run the analytics tool to see your session's ratio)

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:

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

License

Meta-Agents.AI Proprietary License v1.0. Install-and-use is permitted for end-users of the published wheels; source access, OEM embedding, and hosted-service rights are reserved for separately-negotiated agreements. Patent pending.