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

Tool discovery

The table below describes selected tools, not the complete active profile. Use MCP list_tools or capabilities(output_format="json") for the active tool names and count. Advanced tools may be hidden by the selected profile.

0.2.15 candidate recall contract

recall returns a versioned JSON packet, including in the default output mode. The standard wheel enables Candle, with runtime initialization/fallback depending on configuration and model availability. Recall admission uses experimental lexical content coverage. Shared tags, importance and recency do not establish relevance. memory_context uses the same admission rule. admission_mode="ranked" retains diagnostic candidate access; raw search is also available.

Context records retain payload, event ID, timestamp and causal parents; they omit engine diagnostics and vectors. The context default is now 1,500 estimated tokens (also the preview profile maximum) to accommodate the complete receipt envelope.

The complete packet is bounded by a conservative UTF-8 byte estimate (one byte per estimated token), including metadata. Records that do not fit are omitted; budgets smaller than the receipt envelope return budget_exhausted. This can return fewer records than the previous payload-only estimator.

temporal_axis="effective" preserves the legacy as_of_ms semantics. temporal_axis="knowledge" uses an explicit supersession timestamp. Legacy supersessions without that timestamp fail explicitly when encountered. This does not restore forgotten records or promise complete MVCC history. A downgrade to an older writer may discard the added timestamp; retain a backup before an upgrade and do not mix old and new writers when relying on knowledge history. Integrity hashes also preserve their original timestamp independently of lifecycle overlays; older writers do not understand this field. Existing corrupted chains are not silently repaired or relinked by this change.

Model identity is reported separately from verified health. An unknown model does not establish semantic readiness or vector-index compatibility. The semantic admission thresholds and broader held-out quality gates remain pending.

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

Environment Variables

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

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.