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
analyticstool 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
activationevent on first connect and aheartbeatat 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.
1 maintainer
Metadata
1 maintainer
Release files for madb-mcp-server 0.2.14
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
Total release size: 48.0 MB
Release files / madb_mcp_server-0.2.14-cp313-cp313-win_amd64.whl
| Download URL | madb_mcp_server-0.2.14-cp313-cp313-win_amd64.whl |
|---|---|
| Size | 657.9 kB |
| Tags | CPython 3.13 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
f2cbe34a8ba58a69c1aa7453757ace3e8fa283d64a8d1fdf799b870c572aece3
|
|
BLAKE2b-256 checksum How to use checksums |
554dddebf3508f818e88eccf8d16063752e3b929891b6bcfdec9d715d297c217
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | madb_mcp_server-0.2.14-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
8a45207124a31c6cffcfd4870ceeae4411f5a9d3654eacc2054f01aa4d1f8d3f
|
|
BLAKE2b-256 checksum How to use checksums |
d2104a24286123c748126076a8a1e2e4a378704bd9c84c62627cb2ad13db710b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | madb_mcp_server-0.2.14-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.13 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
56ee32d622a9642fb029934437db4abfa821dca07fc0b03baa0455c5bd1ecfe9
|
|
BLAKE2b-256 checksum How to use checksums |
dcef824c0e562eaa5774072d7b50a8c72cc63becfc9c89e16b95c56028647d3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp313-cp313-macosx_11_0_arm64.whl
| Download URL | madb_mcp_server-0.2.14-cp313-cp313-macosx_11_0_arm64.whl |
|---|---|
| Size | 745.9 kB |
| Tags | CPython 3.13 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
4a16efacf3aae13d640fb2d388124f836e10ea5613b700a3e680500355e6f036
|
|
BLAKE2b-256 checksum How to use checksums |
b581c71187facef6bb9a324e24ee4478b08c7dbaa9c519dc9daffe7a70c5ce9e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp312-cp312-win_amd64.whl
| Download URL | madb_mcp_server-0.2.14-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 660.1 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
570074d522ab91065f958459264b5c3d6ca9138937957c56ea10206381001072
|
|
BLAKE2b-256 checksum How to use checksums |
f2eb6135bfb0737dc91ecc9c75165a89b35fda3e079f6d65bc4cac62334cf7cf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | madb_mcp_server-0.2.14-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
a54ee95763e7fb282f27f6b4c1e37c45a418d405df29a98244e76255303fc0ad
|
|
BLAKE2b-256 checksum How to use checksums |
bdc42a4776bbdbc93b5a324d580e99f576979e2c55bac3001fc91f6c069aa027
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | madb_mcp_server-0.2.14-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 5.1 MB |
| Tags | CPython 3.12 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
4bc035ddff62febd056fb044705379e705bb51b84bb26c027cab2af1d2d6e92f
|
|
BLAKE2b-256 checksum How to use checksums |
3ac80f9f1db9ee50e981a80ea412aa6c6891c2c2b345dbd21ebabf3c3e0fe1cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp312-cp312-macosx_11_0_arm64.whl
| Download URL | madb_mcp_server-0.2.14-cp312-cp312-macosx_11_0_arm64.whl |
|---|---|
| Size | 750.9 kB |
| Tags | CPython 3.12 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
64fc88a669823ad0a33d285a34d1e4714fd26e356e5fa2f73bfc6d4ad449c7f4
|
|
BLAKE2b-256 checksum How to use checksums |
ba9df32d046a681bf7c52bd4bef3381676b50d920e24ec09dd7ed71f7ed30262
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp311-cp311-win_amd64.whl
| Download URL | madb_mcp_server-0.2.14-cp311-cp311-win_amd64.whl |
|---|---|
| Size | 704.7 kB |
| Tags | CPython 3.11 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
54bf8df4d48fc6a1872a535992bee8a052301aff579612b600664f586f62c853
|
|
BLAKE2b-256 checksum How to use checksums |
a450ca2519e3211891ea58a40539cf7c2042e6491d4c5a25a358bb490237885d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | madb_mcp_server-0.2.14-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 5.6 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
122bf90ded445665dc437a7349a23e3682a55414ba0adc3395fb4062216fc97c
|
|
BLAKE2b-256 checksum How to use checksums |
f778024282f58cdd8dc91aaf9a1a2bb8e72b0ac8a8dc419258d61cee223069eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | madb_mcp_server-0.2.14-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 5.5 MB |
| Tags | CPython 3.11 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
d7048ebf3eb7746344025c083aaf5f75e25f9d3bc9367537359b6869e2b56cb2
|
|
BLAKE2b-256 checksum How to use checksums |
0bfc4754a68e8aefe6afa658986c732ac32ad83a80a82d24805b0c015abc9ad0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp311-cp311-macosx_11_0_arm64.whl
| Download URL | madb_mcp_server-0.2.14-cp311-cp311-macosx_11_0_arm64.whl |
|---|---|
| Size | 757.4 kB |
| Tags | CPython 3.11 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
85ecffa5f5082be3868e656b0d3fdc7d937344990e1bf588f01574773f5ecf2d
|
|
BLAKE2b-256 checksum How to use checksums |
0671ea2a826c412b6a6846f569d346d63b1945c6554ef9b154c029301014a5c9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp310-cp310-win_amd64.whl
| Download URL | madb_mcp_server-0.2.14-cp310-cp310-win_amd64.whl |
|---|---|
| Size | 699.0 kB |
| Tags | CPython 3.10 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
bb3639c32da8a25c9a483ddd8aded4ea384feb17c78c6fd36d31052fbe27a186
|
|
BLAKE2b-256 checksum How to use checksums |
52cab32ec8c95995eacabe44ef221a7d045becd11f6d67a780b6305df3069cd8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
| Download URL | madb_mcp_server-0.2.14-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl |
|---|---|
| Size | 5.3 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
5c08b00ed4c75d85779eb7e943716edafbf7cf39d6f6cf70a39664f646a7ac0b
|
|
BLAKE2b-256 checksum How to use checksums |
ddb39c947a16a4a245ab902e8e342030de0702d6d7e85195a95d313b75902ce0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
| Download URL | madb_mcp_server-0.2.14-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl |
|---|---|
| Size | 5.2 MB |
| Tags | CPython 3.10 Linux glibc 2.17+ ARM64 |
|
SHA-256 checksum How to use checksums |
e0434a89a2369d777cd4cc0c4f377ea369612f2b3c748af5d843bbe802683b5e
|
|
BLAKE2b-256 checksum How to use checksums |
d4a0bbdfd9ed20964b2b6e6b9403a1cc16e86568248d51152587d5b2ef8d4a5a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logRelease files / madb_mcp_server-0.2.14-cp310-cp310-macosx_11_0_arm64.whl
| Download URL | madb_mcp_server-0.2.14-cp310-cp310-macosx_11_0_arm64.whl |
|---|---|
| Size | 765.3 kB |
| Tags | CPython 3.10 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
30fa4b02860729827054f6fe606f1ec2b72c8bb2d08d38c04550df73c741724c
|
|
BLAKE2b-256 checksum How to use checksums |
91335ec19fcc57050324d24ee4078d8fa7353663baf876aa1b096cc14afb5216
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logSecurity for madb-mcp-server 0.2.14
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 16 files in this release have been uploaded with provenance metadata.
Attestation for madb_mcp_server-0.2.14-cp313-cp313-win_amd64.whl
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 24, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
