madb-mcp-server 0.1.0__tar.gz

madb_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,54 @@
+# Rust build artifacts
+target/
+**/target/
+**/*.rs.bk
+
+# Cargo — keep Cargo.lock at workspace root (we're an application, not a library)
+# Individual crate Cargo.lock files should not be committed.
+crates/*/Cargo.lock
+
+# Python (maturin develop install side-effects + venvs)
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+.venv/
+venv/
+.Python
+build/
+dist/
+*.whl
+
+# Editor / OS
+.DS_Store
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.env
+.env.local
+
+# Maturin develop side-effects — the installed wheel lives in the caller's
+# venv; we do not want any artifact under the project tree.
+.maturin/
+
+# Test coverage reports
+target/criterion/
+*.profraw
+*.profdata
+coverage/
+
+# MADB runtime data directories (should never be in the repo).
+# Intentionally NOT using a global *.lock pattern so the workspace
+# Cargo.lock stays tracked (Rust workspace Cargo.lock must be committed).
+data/
+/tmp/madb*
+**/data/madb*
+**/data/maos_memory*
+**/wal/*.log
+**/hlc.json
+# MADB data-dir lockfile is literally named "LOCK" (no extension)
+# inside the data directory, not at the workspace root.
+**/data/**/LOCK

madb_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+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)

madb_mcp_server-0.1.0/README.md

@@ -0,0 +1,111 @@
+# 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)

madb_mcp_server-0.1.0/__main__.py

@@ -0,0 +1,4 @@
+"""Allow `python -m madb_mcp_server` to launch the MCP server."""
+from madb_mcp_server import mcp
+
+mcp.run()

madb_mcp_server-0.1.0/madb_mcp_analytics.py

@@ -0,0 +1,343 @@
+#!/usr/bin/env python3
+# Copyright 2025-2026 Pushkar Singh / Meta-Agents.AI
+# SPDX-License-Identifier: Apache-2.0
+# Part of Meta-AgentsDB — the first database designed for autonomous AI agents.
+# https://meta-agents.ai
+"""
+madb_mcp_analytics — MCP usage instrumentation for Meta-AgentsDB
+================================================================
+
+Lightweight, stdlib-only analytics collector that records every MCP tool
+invocation and produces point-in-time usage snapshots with Memory ROI.
+
+Storage: append-only JSONL log at ``$MADB_DATA_DIR/mcp_analytics.jsonl``.
+Hot path: in-memory counters (dict of tool -> count / latency / errors).
+Flush: background thread every 60 s + ``atexit``.
+
+Session tracking:
+  Each MCP server process lifetime = one Claude Code session.
+  A ``session_id`` (UUID4) is generated at init and stamped on every
+  JSONL line + snapshot. This lets the report group calls by session
+  and compute per-session Memory ROI.
+
+Memory ROI model:
+  When Claude recalls memories instead of re-reading source files,
+  each recalled token represents context served "for free" — without
+  a file read round-trip. We estimate:
+
+    recall_tokens_saved = tokens_served_from_recall
+    avg_file_read_tokens = 1500  (conservative median for a source file)
+    file_reads_avoided   = recall_tokens_saved / avg_file_read_tokens
+    memory_roi           = recall_tokens_saved / max(memories_written_tokens, 1)
+
+  The ``recall_precision`` metric tracks the quality of recalled results
+  via the composite similarity score (avg top_score across all recalls).
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import os
+import platform
+import threading
+import time
+import uuid
+from collections import defaultdict
+from typing import Any
+
+# Typical token count when Claude reads a source file via Read tool.
+# Used as the denominator for "file reads avoided" estimation.
+AVG_FILE_READ_TOKENS = 1500
+
+
+def _resolve_user_fingerprint() -> dict[str, str]:
+    """Resolve machine + user identity once at process start.
+
+    Returns a dict with ``user`` (login name) and ``host`` (hostname).
+    Both fall back to ``"unknown"`` if the OS call fails (e.g. inside
+    a sandboxed container with no /etc/passwd).
+    """
+    try:
+        user = os.getlogin()
+    except OSError:
+        user = os.environ.get("USER", os.environ.get("USERNAME", "unknown"))
+    host = platform.node() or "unknown"
+    return {"user": user, "host": host}
+
+
+class _ToolStats:
+    """Mutable per-tool accumulator (not thread-safe on its own — the
+    caller must hold the lock)."""
+
+    __slots__ = (
+        "calls", "errors", "latency_sum", "latency_max",
+        "latencies", "result_count_sum", "tokens_served",
+        "recall_hits", "top_scores",
+    )
+
+    def __init__(self) -> None:
+        self.calls: int = 0
+        self.errors: int = 0
+        self.latency_sum: float = 0.0
+        self.latency_max: float = 0.0
+        self.latencies: list[float] = []
+        self.result_count_sum: int = 0
+        self.tokens_served: int = 0
+        self.recall_hits: int = 0       # recalls returning >= 1 result
+        self.top_scores: list[float] = []  # best score per recall (precision signal)
+
+
+class McpAnalytics:
+    """In-process analytics collector for the MADB MCP server.
+
+    Usage::
+
+        analytics = McpAnalytics("/path/to/mcp_analytics.jsonl")
+
+        t0 = time.perf_counter()
+        # ... tool work ...
+        analytics.record_call("recall", (time.perf_counter()-t0)*1000,
+                              True, {"result_count": 5, "tokens": 420,
+                                     "top_score": 0.87})
+
+        print(json.dumps(analytics.snapshot(), indent=2))
+    """
+
+    def __init__(self, log_path: str, flush_interval: float = 60.0) -> None:
+        self._log_path = log_path
+        self._flush_interval = flush_interval
+        self._fingerprint = _resolve_user_fingerprint()
+        self._session_id = str(uuid.uuid4())
+        self._session_seq = 0  # monotonic call counter within session
+
+        self._lock = threading.Lock()
+        self._tools: dict[str, _ToolStats] = defaultdict(_ToolStats)
+        self._total_calls: int = 0
+        self._total_errors: int = 0
+        self._start_ts: float = time.time()
+
+        # Track writes for ROI denominator (tokens written into memory)
+        self._memories_written_tokens: int = 0
+
+        # Pending JSONL lines waiting to be flushed
+        self._pending: list[str] = []
+
+        # Background flush thread
+        self._stop = threading.Event()
+        self._thread = threading.Thread(
+            target=self._flush_loop, daemon=True, name="madb-mcp-analytics"
+        )
+        self._thread.start()
+        atexit.register(self.flush_to_disk)
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def record_call(
+        self,
+        tool: str,
+        latency_ms: float,
+        success: bool,
+        meta: dict[str, Any] | None = None,
+    ) -> None:
+        """Record a single MCP tool invocation."""
+        meta = meta or {}
+
+        with self._lock:
+            self._session_seq += 1
+            seq = self._session_seq
+
+        line = json.dumps({
+            "ts": time.time(),
+            "session_id": self._session_id,
+            "session_seq": seq,
+            "tool": tool,
+            "latency_ms": round(latency_ms, 2),
+            "ok": success,
+            "user": self._fingerprint["user"],
+            "host": self._fingerprint["host"],
+            "tenant": meta.get("tenant", ""),
+            "result_count": meta.get("result_count", 0),
+            "tokens": meta.get("tokens", 0),
+            "top_score": meta.get("top_score", 0.0),
+            "payload_tokens": meta.get("payload_tokens", 0),
+        })
+
+        with self._lock:
+            ts = self._tools[tool]
+            ts.calls += 1
+            ts.latency_sum += latency_ms
+            ts.latencies.append(latency_ms)
+            if latency_ms > ts.latency_max:
+                ts.latency_max = latency_ms
+            if not success:
+                ts.errors += 1
+                self._total_errors += 1
+            ts.result_count_sum += meta.get("result_count", 0)
+            ts.tokens_served += meta.get("tokens", 0)
+            self._total_calls += 1
+            self._pending.append(line)
+
+            # Recall-specific tracking
+            if tool == "recall":
+                rc = meta.get("result_count", 0)
+                if rc > 0:
+                    ts.recall_hits += 1
+                top = meta.get("top_score", 0.0)
+                if top > 0:
+                    ts.top_scores.append(top)
+
+            # Track write payload size for ROI denominator
+            if tool == "remember":
+                self._memories_written_tokens += meta.get("payload_tokens", 0)
+
+    def snapshot(self) -> dict[str, Any]:
+        """Point-in-time usage summary for the ``analytics`` MCP tool.
+
+        Includes session context, per-tool stats, recall precision,
+        and Memory ROI computation.
+        """
+        with self._lock:
+            tools: dict[str, Any] = {}
+            total_recalls = 0
+            recall_hits = 0
+            total_tokens_served = 0
+            total_results = 0
+            all_latencies: list[float] = []
+            all_top_scores: list[float] = []
+            memories_written = 0
+
+            for name, ts in self._tools.items():
+                avg_lat = ts.latency_sum / ts.calls if ts.calls else 0
+                lats = sorted(ts.latencies)
+                p50 = _percentile(lats, 50)
+                p99 = _percentile(lats, 99)
+                tools[name] = {
+                    "calls": ts.calls,
+                    "errors": ts.errors,
+                    "avg_latency_ms": round(avg_lat, 1),
+                    "p50_latency_ms": round(p50, 1),
+                    "p99_latency_ms": round(p99, 1),
+                    "max_latency_ms": round(ts.latency_max, 1),
+                }
+                all_latencies.extend(ts.latencies)
+
+                if name == "recall":
+                    total_recalls = ts.calls
+                    recall_hits = ts.recall_hits
+                    total_tokens_served = ts.tokens_served
+                    total_results = ts.result_count_sum
+                    all_top_scores = ts.top_scores[:]
+                    tools[name]["tokens_served"] = ts.tokens_served
+                    tools[name]["total_results"] = ts.result_count_sum
+                    tools[name]["recall_hits"] = ts.recall_hits
+
+                if name == "remember":
+                    memories_written = ts.calls
+                    tools[name]["memories_written"] = ts.calls
+
+            all_sorted = sorted(all_latencies)
+
+            # --- Recall precision ---
+            recall_hit_rate = (
+                round(recall_hits / max(total_recalls, 1) * 100, 1)
+                if total_recalls > 0 else 0.0
+            )
+            avg_top_score = (
+                round(sum(all_top_scores) / len(all_top_scores), 3)
+                if all_top_scores else 0.0
+            )
+            avg_results_per_recall = (
+                round(total_results / max(total_recalls, 1), 1)
+                if total_recalls > 0 else 0.0
+            )
+
+            # --- Memory ROI ---
+            file_reads_avoided = round(
+                total_tokens_served / AVG_FILE_READ_TOKENS, 1
+            )
+            memory_roi = (
+                round(total_tokens_served / max(self._memories_written_tokens, 1), 2)
+                if self._memories_written_tokens > 0
+                else 0.0
+            )
+            session_duration = round(time.time() - self._start_ts, 1)
+            calls_per_minute = (
+                round(self._total_calls / max(session_duration / 60, 0.01), 1)
+            )
+
+            return {
+                "session_id": self._session_id,
+                "user": self._fingerprint["user"],
+                "host": self._fingerprint["host"],
+                "session_duration_s": session_duration,
+                "session_calls": self._total_calls,
+                "calls_per_minute": calls_per_minute,
+                "total_calls": self._total_calls,
+                "total_errors": self._total_errors,
+                "error_rate": round(
+                    self._total_errors / max(self._total_calls, 1) * 100, 2
+                ),
+                "all_tool_p50_ms": round(_percentile(all_sorted, 50), 1),
+                "all_tool_p99_ms": round(_percentile(all_sorted, 99), 1),
+                "recall_precision": {
+                    "hit_rate_pct": recall_hit_rate,
+                    "avg_top_score": avg_top_score,
+                    "avg_results_per_recall": avg_results_per_recall,
+                    "total_recalls": total_recalls,
+                    "recalls_with_results": recall_hits,
+                },
+                "memory_roi": {
+                    "tokens_served_from_recall": total_tokens_served,
+                    "memories_written": memories_written,
+                    "memories_written_tokens": self._memories_written_tokens,
+                    "est_file_reads_avoided": file_reads_avoided,
+                    "write_to_read_ratio": memory_roi,
+                },
+                "tools": tools,
+            }
+
+    def flush_to_disk(self) -> None:
+        """Write pending JSONL lines to disk."""
+        with self._lock:
+            if not self._pending:
+                return
+            lines = self._pending[:]
+            self._pending.clear()
+
+        # Ensure parent directory exists
+        os.makedirs(os.path.dirname(self._log_path) or ".", exist_ok=True)
+        with open(self._log_path, "a") as f:
+            for line in lines:
+                f.write(line + "\n")
+
+    def stop(self) -> None:
+        """Stop the background flush thread (for clean shutdown)."""
+        self._stop.set()
+        self._thread.join(timeout=2)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _flush_loop(self) -> None:
+        while not self._stop.wait(self._flush_interval):
+            self.flush_to_disk()
+
+
+def _percentile(sorted_values: list[float], pct: float) -> float:
+    """Compute a percentile from a pre-sorted list."""
+    if not sorted_values:
+        return 0.0
+    k = (len(sorted_values) - 1) * (pct / 100)
+    f = int(k)
+    c = f + 1
+    if c >= len(sorted_values):
+        return sorted_values[-1]
+    return sorted_values[f] + (k - f) * (sorted_values[c] - sorted_values[f])