Metadata-Version: 2.4
Name: madb-mcp-server
Version: 0.1.0
Summary: MCP server for Meta-AgentsDB — persistent causal memory for AI agents
Project-URL: Homepage, https://meta-agents.ai
Project-URL: Repository, https://github.com/spshkar84/meta-agents-db
Author-email: Pushkar Singh <01@meta-agents.ai>, Pushkar Singh <spshkar84@gmail.com>, Pushkar Singh <spshkar84@meta-agents.ai>
License-Expression: Apache-2.0
Keywords: agents,claude,database,mcp,memory
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: meta-agents-db>=0.1.0
Description-Content-Type: text/markdown

# 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 (9)

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

## 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)
