Metadata-Version: 2.4
Name: madb-mcp-server
Version: 0.2.6
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 v1.0
Project-URL: Homepage, https://meta-agents.ai
Project-URL: Repository, https://github.com/spshkar84/madb-meta-agents-db
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
Requires-Dist: meta-agents-db<0.3,>=0.2
Requires-Dist: mcp<2,>=1.0.0

# madb-mcp-server

Persistent causal memory for Claude Code — **4.65x recall ROI** measured in production.

`madb-mcp-server` gives Claude Code (and any MCP-compatible client) a real database backend for agent memory: causal chains, composite-scored recall, policy-gated access, 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"
      }
    }
  }
}
```

## 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 (measured 4.65x in production)

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

Apache-2.0 (patent pending)

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