Metadata-Version: 2.4
Name: madb-mcp-server
Version: 0.2.15
Summary: MCP server for Meta-AgentsDB — persistent causal memory for AI agents
Author-email: Pushkar Singh <01@meta-agents.ai>, Pushkar Singh <spshkar84@gmail.com>, Pushkar Singh <spshkar84@meta-agents.ai>
License: META-AGENTS.AI PROPRIETARY LICENSE
        Version 1.1 — Effective 2026-10-17
        
        Owner-authorized binary-distribution terms for MADB 0.2.15, including
        meta-agents-db 0.2.15 and madb-mcp-server 0.2.15. This revision records
        rights-holder authorization, not counsel review or countersignature.
        No source-code distribution is authorized by this License.
        
        ================================================================
        1. PARTIES
        ================================================================
        
        This License is a binding agreement between:
        
          "Licensor": Meta-Agents.AI LLC, a Wyoming limited liability company,
          the sole rights holder of the Meta-Agents Database ("MADB") software
          and associated materials.
        
          "Licensee": the individual or legal entity that installs,
          downloads, executes, or otherwise accesses the Software.
        
        ================================================================
        2. DEFINITIONS
        ================================================================
        
        "Software" means the Meta-Agents Database ("MADB") software, including
        compiled binary artifacts, binary Python wheels, and native extensions
        distributed by Licensor, in whole or in part. Source code, build inputs,
        credentials, signing keys, and other secrets are excluded from the grant.
        Separately licensed documentation, Skills, and third-party components
        retain their own terms; this License does not replace them.
        
        "Hosted Service" means any offering, made available to third parties
        over a network, in which the Software provides a substantial portion
        of the functionality delivered.
        
        "Commercial Product" means any product or service sold, licensed, or
        otherwise monetized that incorporates, redistributes, or depends
        operationally on the Software.
        
        "Authorized Use" has the meaning given in Section 3.
        
        ================================================================
        3. GRANT OF LIMITED LICENSE
        ================================================================
        
        Subject to Licensee's continuing compliance with this License,
        Licensor grants to Licensee a personal, non-exclusive, non-transferable,
        non-sublicensable, revocable license to:
        
          (a) install and execute the Software on computing infrastructure
              owned or controlled by Licensee;
        
          (b) use the Software for Licensee's internal business operations,
              research, or personal use, including in production environments
              where the Software serves Licensee's own users; and
        
          (c) make a reasonable number of internal backup copies of the
              Software as needed for (a) and (b).
        
        All other rights are reserved to Licensor.
        
        Licensor may distribute authorized binaries through PyPI and other
        channels it designates. This does not grant Licensee redistribution
        rights. No source distribution (sdist), proprietary source, build system,
        credential, or secret is authorized for release under this approval.
        
        ================================================================
        4. RESTRICTIONS
        ================================================================
        
        Licensee shall NOT, and shall not permit any third party to:
        
          (a) offer the Software, or any substantial portion of it, as a
              Hosted Service to third parties;
        
          (b) redistribute, resell, sublicense, lease, rent, or otherwise
              transfer the Software to any third party, whether in original
              or modified form;
        
          (c) incorporate the Software into a Commercial Product made
              available to third parties, except under a separate written
              agreement with Licensor;
        
          (d) reverse engineer, decompile, disassemble, or otherwise
              attempt to derive the source code, underlying algorithms,
              data structures, or trade secrets of the Software, or reconstruct
              a buildable source-code version from its binaries, except
              to the minimum extent expressly permitted by applicable law
              that cannot be waived by contract;
        
          (e) remove, alter, or obscure any proprietary notice, license
              file, or attribution bundled with the Software;
        
          (f) circumvent, disable, or interfere with any license-validation,
              usage-metering, or tier-gating mechanism included in the
              Software;
        
          (g) use the Software to train, fine-tune, or otherwise inform any
              machine-learning model intended to replicate or compete with
              the Software's functionality; or
        
          (h) use the Software in violation of applicable law, or in any
              manner that could cause material harm to Licensor, its other
              licensees, or third parties; or
        
          (i) extract, disclose, publish, transfer, or use Licensor's nonpublic
              source code, build inputs, credentials, signing keys, or other
              secrets without separate express written authorization. Accidental
              inclusion in an artifact grants no permission to use or disclose
              such material. Licensee may use its own credentials through the
              Software's supported interfaces.
        
        ================================================================
        5. RESERVED RIGHTS — SEPARATELY LICENSABLE
        ================================================================
        
        The following rights are expressly reserved by Licensor and are
        available only pursuant to a separate written agreement:
        
          (a) access to the source code of the Software, whether for audit,
              modification, or any other purpose;
        
          (b) rights to embed the Software within a Commercial Product
              ("OEM Rights");
        
          (c) rights to offer the Software as a Hosted Service;
        
          (d) rights of attribution, co-branding, or representation beyond
              those required to comply with Section 4(e); and
        
          (e) rights of redistribution in any form.
        
        Licensor may, in its sole discretion, enter into bilateral agreements
        granting one or more of the above rights to specific parties on
        negotiated terms.
        
        ================================================================
        6. INTELLECTUAL PROPERTY
        ================================================================
        
        The Software is licensed, not sold. Licensor retains all right, title,
        and interest in and to the Software, including all intellectual
        property rights. Nothing in this License transfers ownership to
        Licensee. No rights are granted by implication, estoppel, or otherwise
        except as expressly set forth herein.
        
        ================================================================
        7. PRIOR VERSIONS AND RELATIONSHIP TO APACHE LICENSE 2.0
        ================================================================
        
        Prior versions of portions of the Software were made available under
        the Apache License, Version 2.0 (available at
        https://www.apache.org/licenses/LICENSE-2.0). Those prior versions,
        to the extent actually distributed under that license, remain
        available under those terms for the specific revisions so distributed.
        This revision applies to the MADB 0.2.15 binary distributions identified
        above and later binary releases expressly adopting it. It does not revoke
        rights in earlier distributions or override third-party license obligations.
        
        ================================================================
        8. TERM AND TERMINATION
        ================================================================
        
        This License is effective until terminated. Licensor may terminate
        this License immediately upon notice if Licensee breaches any
        provision of Section 4. Upon termination, Licensee shall cease all
        use of the Software and destroy all copies in Licensee's possession
        or control. Sections 4, 6, 9, 10, 11, 12, and 15 survive termination.
        
        ================================================================
        9. DISCLAIMER OF WARRANTY
        ================================================================
        
        THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND,
        EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT,
        OR ACCURACY. LICENSOR DOES NOT WARRANT THAT THE SOFTWARE WILL BE
        UNINTERRUPTED, ERROR-FREE, OR FREE OF HARMFUL COMPONENTS.
        
        ================================================================
        10. LIMITATION OF LIABILITY
        ================================================================
        
        TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL
        LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL,
        CONSEQUENTIAL, OR EXEMPLARY DAMAGES, OR FOR ANY LOSS OF PROFITS,
        REVENUE, DATA, OR BUSINESS OPPORTUNITY, ARISING OUT OF OR RELATED
        TO THIS LICENSE OR THE SOFTWARE, WHETHER IN CONTRACT, TORT, OR
        OTHERWISE, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF
        SUCH DAMAGES. LICENSOR'S TOTAL CUMULATIVE LIABILITY SHALL NOT EXCEED
        ONE HUNDRED U.S. DOLLARS (USD $100).
        
        ================================================================
        11. EXPORT, SANCTIONS, AND COMPLIANCE
        ================================================================
        
        Licensee agrees to comply with all applicable export control and
        sanctions laws. The Software may not be downloaded, used, or
        re-exported into any country subject to a U.S. government embargo
        or on any U.S. government list of prohibited or restricted parties.
        
        ================================================================
        12. GOVERNING LAW AND VENUE
        ================================================================
        
        This License is governed by and construed in accordance with the
        laws of the State of Wyoming, without regard to its conflict-of-laws
        principles. Any dispute arising out of or relating to this License
        shall be brought exclusively in the state or federal courts located
        in Laramie County, Wyoming, and the parties irrevocably consent to
        the personal jurisdiction of those courts.
        
        ================================================================
        13. CONTACT
        ================================================================
        
        To request a separately-licensable right under Section 5, or for
        any other inquiry regarding this License:
        
          Licensor: Meta-Agents.AI LLC (Wyoming)
          Attn:     Pushkar Singh
          Email:    01@meta-agents.ai
          Website:  https://meta-agents.ai
        
        ================================================================
        14. ENTIRE AGREEMENT
        ================================================================
        
        This License constitutes the entire agreement between the parties
        with respect to the Software and supersedes all prior or
        contemporaneous communications, whether oral or written.
        
        ================================================================
        15. REMEDIES FOR UNAUTHORIZED SOURCE OR SECRET ACCESS
        ================================================================
        
        For a breach of Section 4(d) or 4(i), Licensor stipulates damages of
        USD $2,300,000 per license, to the extent enforceable under applicable
        law. This is a contractual damages provision, not a government-imposed
        fine or criminal penalty. Inclusion does not establish that the amount
        is enforceable or a reasonable estimate of loss.
        
        If the stipulated amount is held unenforceable, Licensor retains the
        right to seek proven damages and other relief available under applicable
        law, including injunctive relief where warranted. There shall be no
        double recovery for the same injury. Nothing in this section restricts
        rights that applicable law does not permit the parties to waive.
        
        END OF LICENSE
        
Project-URL: Homepage, https://meta-agents.ai
Project-URL: Documentation, https://meta-agents.ai/docs
Keywords: mcp,agents,memory,database,claude
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: meta-agents-db==0.2.15
Requires-Dist: mcp<2,>=1.0.0
Dynamic: license-file

# madb-mcp-server

<!-- mcp-name: ai.meta-agents/madb -->

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

```bash
pip install madb-mcp-server
```

Or run directly with uvx (no install needed):

```bash
uvx madb-mcp-server
```

## Claude Code Setup

```bash
claude mcp add madb -- uvx madb-mcp-server
```

Or add to your project's `.mcp.json`:

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

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

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

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](https://github.com/spshkar84/meta-agents-db/blob/main/LICENSE). 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.

<!-- mcp-name: io.github.spshkar84/madb-memory -->
