feat(examples): add zero-knowledge secure memory reference implementation (Synapse Layer)

examples/mcp-secure-memory/examples/mcp-secure-memory/README.md

@@ -0,0 +1,196 @@
+Reference Implementation: Zero-Knowledge Secure Memory for MCP
+Give any MCP-compatible agent a privacy-first, audit-ready memory layer in under 5 minutes.
+
+PyPI License MCP Compatible
+
+The Problem
+MCP gives AI agents access to tools and data — but no standardized way to persist memory securely. When agents store context between sessions, sensitive information (PII, credentials, health data) often ends up in plaintext logs or unprotected vector stores.
+
+This reference implementation solves that with two MCP tools backed by Synapse Layer:
+
+Tool	Description
+store_memory	Sanitize → validate → apply differential privacy → store
+recall_memory	Semantic search with automatic self-healing of conflicting memories
+Every memory operation is audit-ready and returns cryptographic integrity hashes, trust quotients, and full sanitization/privacy metadata.
+
+Security Model
+Raw Input ──► PII Sanitization ──► Intent Validation ──► DP Noise Injection ──► Encrypted Storage
+                  │                       │                       │
+                  ▼                       ▼                       ▼
+            Names, emails,          Category +              ε-differential
+            phones, SSNs           confidence              privacy guarantee
+            auto-stripped          auto-classified          (configurable ε)
+Properties
+Property	Guarantee
+PII Removal	Automatic detection and stripping of names, emails, phone numbers, SSNs, and other PII patterns before storage
+Differential Privacy	Configurable ε-DP noise injection on embeddings — mathematically provable privacy bounds
+Intent Validation	Every memory is classified by intent category with confidence scoring
+Self-Healing	Conflicting memories with overlapping semantics are automatically reclassified via keyword consensus
+Audit Trail	Every store returns: memory_id, content_hash (SHA-256), trust_quotient, and full sanitization/privacy details
+Zero-Knowledge	The SDK processes all data locally — no external API calls, no telemetry, no data leaves your environment
+Quick Start
+Prerequisites
+Python 3.10+
+An MCP-compatible client (Claude Desktop, MCP Inspector, or any custom client)
+1. Install
+pip install synapse-layer "mcp[cli]"
+2. Configure Environment
+cp .env.example .env
+# Edit .env to set your SYNAPSE_AGENT_ID and privacy epsilon
+3. Run the Server
+# Direct execution (stdio transport — default for Claude Desktop)
+python server.py
+
+# Or via MCP CLI
+mcp run server.py
+Integration Guides
+Claude Desktop
+Add to your Claude Desktop configuration file (claude_desktop_config.json):
+
+{
+  "mcpServers": {
+    "synapse-secure-memory": {
+      "command": "python",
+      "args": ["path/to/examples/mcp-secure-memory/server.py"],
+      "env": {
+        "SYNAPSE_AGENT_ID": "claude-desktop",
+        "SYNAPSE_PRIVACY_EPSILON": "0.5"
+      }
+    }
+  }
+}
+Once configured, Claude can use natural language to store and recall memories:
+
+"Remember that the user prefers dark mode and lives in Berlin."
+
+→ store_memory is called automatically. PII (city name as location data) is sanitized. An audit payload is returned with memory_id and trust_quotient.
+
+"What do I know about the user's preferences?"
+
+→ recall_memory returns semantically similar memories with self-healing metadata.
+
+LangChain
+from langchain_mcp_adapters.client import MultiServerMCPClient
+
+async with MultiServerMCPClient(
+    {
+        "synapse-memory": {
+            "command": "python",
+            "args": ["path/to/server.py"],
+            "env": {
+                "SYNAPSE_AGENT_ID": "langchain-agent",
+                "SYNAPSE_PRIVACY_EPSILON": "0.5",
+            },
+        }
+    }
+) as client:
+    tools = client.get_tools()
+    # tools now includes store_memory and recall_memory
+    # Use with any LangChain agent: create_react_agent, AgentExecutor, etc.
+CrewAI
+from crewai import Agent, Task, Crew
+from crewai_tools import MCPServerAdapter
+
+# Connect to the Synapse Layer MCP server
+mcp_tools = MCPServerAdapter(
+    server_params={
+        "command": "python",
+        "args": ["path/to/server.py"],
+        "env": {"SYNAPSE_AGENT_ID": "crewai-agent"},
+    }
+)
+
+researcher = Agent(
+    role="Research Analyst",
+    goal="Gather and securely persist research findings",
+    tools=mcp_tools.tools,  # includes store_memory + recall_memory
+)
+
+crew = Crew(agents=[researcher], tasks=[...])
+crew.kickoff()
+MCP Inspector (Testing)
+# Start the server
+python server.py
+
+# In another terminal — launch MCP Inspector
+npx -y @modelcontextprotocol/inspector
+
+# Connect to stdio://python server.py
+# Test store_memory and recall_memory interactively
+API Reference
+store_memory
+Parameter	Type	Default	Description
+content	str	required	Raw text to memorize (PII auto-stripped)
+confidence	float	0.9	Agent confidence in this memory (0.0–1.0)
+metadata	str | null	null	Optional JSON string with extra key-value pairs
+Returns:
+
+{
+  "memory_id": "a1b2c3d4...",
+  "trust_quotient": 0.8234,
+  "sanitized": true,
+  "privacy_applied": true,
+  "content_hash": "sha256:e5f6...",
+  "timestamp": 1712345678.123
+}
+recall_memory
+Parameter	Type	Default	Description
+query	str	required	Natural-language query
+top_k	int	5	Maximum memories to return
+Returns:
+
+[
+  {
+    "memory_id": "a1b2c3d4...",
+    "content": "User prefers dark mode",
+    "similarity": 0.9412,
+    "trust_quotient": 0.8234,
+    "self_healed": false,
+    "timestamp": 1712345678.123
+  }
+]
+Configuration
+Environment Variable	Default	Description
+SYNAPSE_AGENT_ID	mcp-secure-memory	Unique namespace for this agent's memories
+SYNAPSE_PRIVACY_EPSILON	0.5	DP epsilon (lower = stronger privacy)
+LOG_LEVEL	INFO	Server log verbosity
+Architecture
+┌──────────────────────────────────────────────────┐
+│                  MCP Client                       │
+│         (Claude / LangChain / CrewAI)             │
+└─────────────────────┬────────────────────────────┘
+                      │ JSON-RPC (stdio / SSE)
+                      ▼
+┌──────────────────────────────────────────────────┐
+│            MCP Server (this file)                 │
+│         store_memory  |  recall_memory            │
+└─────────────────────┬────────────────────────────┘
+                      │
+                      ▼
+┌──────────────────────────────────────────────────┐
+│            Synapse Layer SDK                      │
+│  ┌────────────┐ ┌───────────┐ ┌───────────────┐  │
+│  │ Sanitizer  │ │ Validator │ │ DP Privacy    │  │
+│  │ (PII)      │ │ (Intent)  │ │ (ε-noise)     │  │
+│  └────────────┘ └───────────┘ └───────────────┘  │
+│  ┌────────────────────────────────────────────┐   │
+│  │       Self-Healing Memory Engine           │   │
+│  │   (conflict resolution + reclassification) │   │
+│  └────────────────────────────────────────────┘   │
+└──────────────────────────────────────────────────┘
+File Structure
+examples/mcp-secure-memory/
+├── server.py                  # MCP server — the only file you need to run
+├── mcp_registry_config.json   # Claude Desktop configuration template
+├── requirements.txt           # Python dependencies
+├── .env.example               # Environment variable template
+└── README.md                  # This file
+Contributing
+We welcome contributions! See CONTRIBUTING.md for guidelines.
+
+If you build an integration with a new MCP client, please open a PR adding it to the Integration Guides section above.
+
+License
+Apache 2.0 — see LICENSE for details.
+
+Built by Synapse Layer — Privacy-first cognitive infrastructure for AI agents.

examples/mcp-secure-memory/examples/mcp-secure-memory/examples/mcp-secure-memory/examples/mcp-secure-memory/.env.example

@@ -0,0 +1,11 @@
+# Synapse Layer MCP Secure Memory — Environment Variables
+# ========================================================
+
+# ID único do agente (pode mudar para cada cliente)
+SYNAPSE_AGENT_ID=mcp-secure-memory
+
+# Nível de privacidade diferencial (quanto menor, mais privacidade)
+SYNAPSE_PRIVACY_EPSILON=0.5
+
+# Nível de log (INFO, DEBUG, WARNING)
+LOG_LEVEL=INFO

examples/mcp-secure-memory/examples/mcp-secure-memory/examples/mcp-secure-memory/examples/mcp-secure-memory/examples/mcp-secure-memory/mcp_registry_config.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "synapse-secure-memory": {
+      "command": "python",
+      "args": [
+        "path/to/examples/mcp-secure-memory/server.py"
+      ],
+      "env": {
+        "SYNAPSE_AGENT_ID": "claude-desktop",
+        "SYNAPSE_PRIVACY_EPSILON": "0.5"
+      }
+    }
+  }
+}

examples/mcp-secure-memory/examples/mcp-secure-memory/examples/mcp-secure-memory/requirements.txt

@@ -0,0 +1,2 @@
+synapse-layer>=1.0.6
+mcp[cli]>=1.0.0

examples/mcp-secure-memory/server.py

@@ -0,0 +1,126 @@
+"""
+Reference Implementation: Zero-Knowledge Secure Memory for MCP (Synapse Layer)
+
+A minimal MCP server that exposes two tools — store_memory and recall_memory —
+backed by Synapse Layer's privacy-first memory SDK. Every memory goes through
+automatic PII sanitization and differential-privacy noise injection before
+storage, giving any MCP-compatible client (Claude Desktop, LangChain, CrewAI,
+custom agents) a production-grade secure memory layer with zero configuration.
+
+Author : Synapse Layer — https://github.com/SynapseLayer
+License: Apache 2.0
+"""
+
+from __future__ import annotations
+
+import os
+import json
+import logging
+from typing import Optional
+
+from mcp.server.fastmcp import FastMCP
+from synapse_memory.core import SynapseMemory
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+AGENT_ID: str = os.getenv("SYNAPSE_AGENT_ID", "mcp-secure-memory")
+PRIVACY_EPSILON: float = float(os.getenv("SYNAPSE_PRIVACY_EPSILON", "0.5"))
+LOG_LEVEL: str = os.getenv("LOG_LEVEL", "INFO")
+
+logging.basicConfig(
+    level=getattr(logging, LOG_LEVEL.upper(), logging.INFO),
+    format="%(asctime)s [%(levelname)s] %(name)s — %(message)s",
+)
+logger = logging.getLogger("mcp-secure-memory")
+
+# ---------------------------------------------------------------------------
+# Synapse Layer memory instance (stateless — no DB required)
+# ---------------------------------------------------------------------------
+memory = SynapseMemory(
+    agent_id=AGENT_ID,
+    sanitize_enabled=True,
+    privacy_enabled=True,
+    privacy_epsilon=PRIVACY_EPSILON,
+)
+
+# ---------------------------------------------------------------------------
+# MCP server
+# ---------------------------------------------------------------------------
+mcp = FastMCP(
+    "Synapse Layer — Secure Memory",
+    json_response=True,
+)
+
+
+@mcp.tool()
+def store_memory(
+    content: str,
+    confidence: float = 0.9,
+    metadata: Optional[str] = None,
+) -> dict:
+    """Store a memory with automatic PII sanitization and differential-privacy
+    noise injection.  Returns an audit-ready payload including the memory ID,
+    trust quotient, and privacy/sanitization details.
+
+    Parameters
+    ----------
+    content : str
+        The raw text to memorize (PII will be stripped automatically).
+    confidence : float
+        How confident the agent is about this memory (0.0–1.0).
+    metadata : str | None
+        Optional JSON string with extra key-value pairs to attach.
+    """
+    meta = json.loads(metadata) if metadata else None
+    result = memory.store(content, confidence=confidence, metadata=meta)
+
+    return {
+        "memory_id": result.memory_id,
+        "trust_quotient": round(result.trust_quotient, 4),
+        "sanitized": result.sanitized,
+        "privacy_applied": result.privacy_applied,
+        "content_hash": result.content_hash,
+        "timestamp": result.timestamp,
+    }
+
+
+@mcp.tool()
+def recall_memory(query: str, top_k: int = 5) -> list[dict]:
+    """Recall memories semantically similar to *query*.  Results include
+    self-healing metadata — conflicting memories are automatically
+    reclassified before being returned.
+
+    Parameters
+    ----------
+    query : str
+        Natural-language query describing what the agent wants to remember.
+    top_k : int
+        Maximum number of memories to return (default 5).
+    """
+    results = memory.recall(query, top_k=top_k)
+
+    return [
+        {
+            "memory_id": r.memory_id,
+            "content": r.content,
+            "similarity": round(r.similarity, 4),
+            "trust_quotient": round(r.trust_quotient, 4),
+            "self_healed": r.self_healed,
+            "timestamp": r.timestamp,
+        }
+        for r in results
+    ]
+
+
+# ---------------------------------------------------------------------------
+# Entrypoint — stdio transport for Claude Desktop / MCP Inspector
+# ---------------------------------------------------------------------------
+if __name__ == "__main__":
+    logger.info(
+        "Starting Synapse Layer Secure Memory MCP server "
+        "(agent_id=%s, epsilon=%.2f)",
+        AGENT_ID,
+        PRIVACY_EPSILON,
+    )
+    mcp.run(transport="stdio")