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.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

madb_mcp_server-0.2.12-cp313-cp313-win_amd64.whl (597.3 kB view details)

Uploaded Aug 12, 2026 CPython 3.13Windows x86-64

madb_mcp_server-0.2.12-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.7 MB view details)

Uploaded Aug 12, 2026 CPython 3.13manylinux: glibc 2.17+ x86-64

madb_mcp_server-0.2.12-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.6 MB view details)

Uploaded Aug 12, 2026 CPython 3.13manylinux: glibc 2.17+ ARM64

madb_mcp_server-0.2.12-cp313-cp313-macosx_11_0_arm64.whl (663.2 kB view details)

Uploaded Aug 12, 2026 CPython 3.13macOS 11.0+ ARM64

madb_mcp_server-0.2.12-cp312-cp312-win_amd64.whl (599.6 kB view details)

Uploaded Aug 12, 2026 CPython 3.12Windows x86-64

madb_mcp_server-0.2.12-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.7 MB view details)

Uploaded Aug 12, 2026 CPython 3.12manylinux: glibc 2.17+ x86-64

madb_mcp_server-0.2.12-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.6 MB view details)

Uploaded Aug 12, 2026 CPython 3.12manylinux: glibc 2.17+ ARM64

madb_mcp_server-0.2.12-cp312-cp312-macosx_11_0_arm64.whl (668.3 kB view details)

Uploaded Aug 12, 2026 CPython 3.12macOS 11.0+ ARM64

madb_mcp_server-0.2.12-cp311-cp311-win_amd64.whl (621.0 kB view details)

Uploaded Aug 12, 2026 CPython 3.11Windows x86-64

madb_mcp_server-0.2.12-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (5.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.11manylinux: glibc 2.17+ x86-64

madb_mcp_server-0.2.12-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (5.0 MB view details)

Uploaded Aug 12, 2026 CPython 3.11manylinux: glibc 2.17+ ARM64

madb_mcp_server-0.2.12-cp311-cp311-macosx_11_0_arm64.whl (690.2 kB view details)

Uploaded Aug 12, 2026 CPython 3.11macOS 11.0+ ARM64

madb_mcp_server-0.2.12-cp310-cp310-win_amd64.whl (617.6 kB view details)

Uploaded Aug 12, 2026 CPython 3.10Windows x86-64

madb_mcp_server-0.2.12-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (4.7 MB view details)

Uploaded Aug 12, 2026 CPython 3.10manylinux: glibc 2.17+ x86-64

madb_mcp_server-0.2.12-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (4.7 MB view details)

Uploaded Aug 12, 2026 CPython 3.10manylinux: glibc 2.17+ ARM64

madb_mcp_server-0.2.12-cp310-cp310-macosx_11_0_arm64.whl (696.5 kB view details)

Uploaded Aug 12, 2026 CPython 3.10macOS 11.0+ ARM64

File details

Details for the file madb_mcp_server-0.2.12-cp313-cp313-win_amd64.whl.

File metadata

Download URL: madb_mcp_server-0.2.12-cp313-cp313-win_amd64.whl
Upload date: Aug 12, 2026
Size: 597.3 kB
Tags: CPython 3.13, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for madb_mcp_server-0.2.12-cp313-cp313-win_amd64.whl
Algorithm	Hash digest
SHA256	`c766a72b6fcae45d7b5fc37c5d4c5e99bf81727b6c690981c26d04ccf74787cc`
MD5	`b885c2a81eb48e99ccce7d9c9af8e732`
BLAKE2b-256	`b14384eaa4ba2ed1c122185558d04a9170a34c799574302f9f0150a844f77417`

Algorithm	Hash digest
SHA256	`18873878d91d63ce55600ebbca23aa5d04ed3404de244f7e954573c482fb0e5b`
MD5	`8fbc5c37ec06686727712dd27e27b1e4`
BLAKE2b-256	`0720ddc5110f465afa17408677f3cb2590d35c1db1ddf15799a44b5827d5eb58`

Algorithm	Hash digest
SHA256	`8d55bddcb4e5c773e964aafea5aa17c62c0bc9aedd409cfa34969e4619437a73`
MD5	`17958792d9b15665ad25dda4e0a929d7`
BLAKE2b-256	`225f6f8fc9c2ae95e163b5d3feb7e5965f7007a577e0f3cfb09cf48b3c2203fa`

Algorithm	Hash digest
SHA256	`5b373f70d814ad9df7867fedd32805bdd5966bcc5e73e09c59ed2be5f94b53cf`
MD5	`39dcfade2f2c6970410ebff2e6e07193`
BLAKE2b-256	`f37a15a8945797eda8c2e69b50339ec872067812f6ed5f78c238ff31136a5066`

Algorithm	Hash digest
SHA256	`930e18c8de91989307ec340cf6f61db942907bac1029539d1cb1814c0dff37a6`
MD5	`103411f00c7293082a9814e4ceecb51f`
BLAKE2b-256	`449ff5a31dce5c5c1ff37fd5078d7fb1ca58372413aa35e5c78f10c8bfad93a8`

Algorithm	Hash digest
SHA256	`d1a539cca887ea555a329c2eaec27eeb6e6a5ac1523b528dda31d5029eb26e6f`
MD5	`76bc2c93349cefe5ac52a8bd86d7eac3`
BLAKE2b-256	`517e423841ad3ca813164167a6de5930e342e304594c1905de77e159efd50b66`

Algorithm	Hash digest
SHA256	`3ab10062f20562546ef06ffefff9fe7b4f4b96845ee053bac141979a0398b56f`
MD5	`a4fb66b2978eab52946ca742017d4cbb`
BLAKE2b-256	`edff0cc234377cb24c47419516f2beb5d62f9f1ccfdba8ef123697cabda6f7fa`

Algorithm	Hash digest
SHA256	`403ebc6d153e9531ae6f19766df3bd75273cc713ac33ecebf3fc718c3b6f9f7a`
MD5	`36740627406834ec48160ca91b1d4325`
BLAKE2b-256	`d0db1002d3c5ccee8a06b4a2e9791aaf63d02c508e9809047b604387eae0d1f9`

Algorithm	Hash digest
SHA256	`f899b9ecbc5b8b42aeb0f0d16906ce7ad5815bd700e1fc1e741972a75f796aca`
MD5	`6a2ebf2579c9225eb6e401372854e2e8`
BLAKE2b-256	`c791a145fd0a890cd7606e53f6ade4748076a9d4b3c6be3a80ed9d0046cd9a59`

Algorithm	Hash digest
SHA256	`9bb8c1996b27393ccd67c726b35519182e99b51d931b9a6a10ea3b86f419900a`
MD5	`e36d906758cbf425b1e28fc05d8d3459`
BLAKE2b-256	`379a19ef72ffe6a649d83fe2eac99e82ca819e3769d7feaaca2b2e0c16778bb9`

Algorithm	Hash digest
SHA256	`8ce412c9248da42f84d5cdb07829322118d7982c3c1f39da872f25ebc9b1387e`
MD5	`98c86777a19b375a94d7ae58ca403b74`
BLAKE2b-256	`7bd40522eed0d225df0c785908c34ff1213c9df51eeac49a8339d19a7975aa6f`

Algorithm	Hash digest
SHA256	`1f3e1239ccbab00fab5296b41eb5eb9f986417d253ad260ee72d49ef79260175`
MD5	`ba3233e6c20805ff3325ed3289f37d9f`
BLAKE2b-256	`3937f56975ed9eea44f5dfa482712fb0d5d2e636ae3e0df86ed05ffa77f54a6b`

Algorithm	Hash digest
SHA256	`486fbb7e949a4eacf1c0faa0f1515934d01884048db57aa90761d9dc1eea9ea4`
MD5	`1a181b410957db2759c408dca2570a1c`
BLAKE2b-256	`909a2d3370448a7c4a00b2bfefddd9e450c06c86e2dd9063af51620174a7cda8`

Algorithm	Hash digest
SHA256	`c7010b51b1d2272fdeae1cc3fae7a8c851667378e1ab522835517033e7afbafc`
MD5	`a64e4e4fe8cb3d0615be844328da5c7b`
BLAKE2b-256	`704876342df22c0ddc605bc807e209717316c1d2d6f47d638d6e2238cbc744f7`

Algorithm	Hash digest
SHA256	`fac3967d878c0cdd9b30a954e1436335e431aeb0d72c4ca1567f6e88379ee48c`
MD5	`03c5c18c7498441f780ad8b3d1b72b11`
BLAKE2b-256	`778435aa95a44a7c8889078091d91043231eb5522f41114dc93fc4ded519e74d`

Algorithm	Hash digest
SHA256	`834c01e01010cdc75c95ae165f5080f132b08af3c95fef9421b62ed7c2569eef`
MD5	`a6c8d925c0b00df75a307d21597ec03b`
BLAKE2b-256	`4fba7e1e879e226c55c145414e09e7bac182e1a5ca2e2ea86a428c09232064d6`

madb-mcp-server 0.2.12

madb-mcp-server

Install

Claude Code Setup

Claude Desktop Setup

Tools (12)

Memory ROI

Resources

Environment Variables

Privacy & Telemetry

How It Works

License

Project links

Key dates

1 maintainer

Credits

License

Requires

Tags

Classifiers

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details