memgraph-sdk 0.1.0__tar.gz

memgraph_sdk-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.env
+.DS_Store

memgraph_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Memgraph
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

memgraph_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.4
+Name: memgraph-sdk
+Version: 0.1.0
+Summary: Official Python SDK for Memgraph - the memory graph for AI agents
+Project-URL: Homepage, https://memgraph.ai
+Project-URL: Documentation, https://memgraph.ai/docs
+Project-URL: Repository, https://github.com/memgraph-ai/memgraph-sdk
+Project-URL: Bug Tracker, https://github.com/memgraph-ai/memgraph-sdk/issues
+Project-URL: Changelog, https://github.com/memgraph-ai/memgraph-sdk/blob/main/CHANGELOG.md
+Author-email: Memgraph Team <sdk@memgraph.ai>
+License: MIT License
+        
+        Copyright (c) 2026 Memgraph
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agents,ai,context,llm,memgraph,memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: requests>=2.25.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: all
+Requires-Dist: httpx>=0.24.0; extra == 'all'
+Requires-Dist: rich>=13.0.0; extra == 'all'
+Provides-Extra: async
+Requires-Dist: httpx>=0.24.0; extra == 'async'
+Provides-Extra: cli
+Requires-Dist: rich>=13.0.0; extra == 'cli'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Memgraph SDK
+
+The official Python SDK for **[Memgraph](https://memgraph.ai)** -- the memory graph for AI agents.
+
+[![PyPI version](https://badge.fury.io/py/memgraph-sdk.svg)](https://pypi.org/project/memgraph-sdk/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install memgraph-sdk
+```
+
+For async support:
+
+```bash
+pip install "memgraph-sdk[async]"
+```
+
+## Quick Start
+
+```python
+from memgraph_sdk import MemgraphClient
+
+client = MemgraphClient(
+    api_key="mg_your_api_key",
+    tenant_id="your-tenant-id",
+)
+
+# Store a memory
+client.add(
+    text="User prefers dark mode and uses PyTorch.",
+    user_id="user_123",
+)
+
+# Search for relevant context
+result = client.search(
+    query="What does this user prefer?",
+    user_id="user_123",
+)
+print(result)
+```
+
+## Async Client
+
+```python
+from memgraph_sdk import AsyncMemgraphClient
+
+async with AsyncMemgraphClient(
+    api_key="mg_your_api_key",
+    tenant_id="your-tenant-id",
+) as client:
+    await client.add("User prefers dark mode", user_id="user_123")
+    result = await client.search("user preferences", user_id="user_123")
+```
+
+## Memory Intelligence API
+
+```python
+# Memory health metrics
+health = client.health(user_id="user_123")
+
+# Detect contradictions
+contradictions = client.contradictions(user_id="user_123")
+
+# Evaluate retrieval quality
+evaluation = client.evaluate(query="test query", user_id="user_123")
+
+# Cognitive Integrity Score (0-100)
+score = client.mcis(user_id="user_123")
+
+# Run benchmarks
+result = client.benchmark(scenario="contradiction_storm")
+scenarios = client.benchmark_scenarios()
+```
+
+## CLI
+
+```bash
+# Initialize Memgraph in your project
+memgraph init
+
+# Store a memory
+memgraph remember "We decided to use PostgreSQL" -c decision
+
+# Search memories
+memgraph recall "database choice"
+
+# Check connection
+memgraph status
+```
+
+## Configuration
+
+The client reads the API URL from the `MEMGRAPH_API_URL` environment variable, defaulting to `http://localhost:8001/v1`. You can also pass it explicitly:
+
+```python
+client = MemgraphClient(
+    api_key="mg_your_key",
+    tenant_id="your-tenant-id",
+    base_url="https://api.memgraph.ai/v1",
+)
+```
+
+## Examples
+
+See the [examples/](examples/) directory for complete integration examples:
+
+- [Quick Start](examples/quick_start.py) -- Basic add and search
+- [Agent Integration](examples/agent_integration.py) -- OpenAI-powered agent with memory
+- [MCP Server](examples/integrations/mcp_server.py) -- Model Context Protocol server for Claude/Cursor
+- [LangChain](examples/integrations/langchain_integration.py) -- LangChain integration
+- [OpenAI](examples/integrations/openai_integration.py) -- OpenAI integration
+- [Benchmarks](examples/integrations/benchmark.py) -- Performance benchmarking
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

memgraph_sdk-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Memgraph SDK
+
+The official Python SDK for **[Memgraph](https://memgraph.ai)** -- the memory graph for AI agents.
+
+[![PyPI version](https://badge.fury.io/py/memgraph-sdk.svg)](https://pypi.org/project/memgraph-sdk/)
+[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install memgraph-sdk
+```
+
+For async support:
+
+```bash
+pip install "memgraph-sdk[async]"
+```
+
+## Quick Start
+
+```python
+from memgraph_sdk import MemgraphClient
+
+client = MemgraphClient(
+    api_key="mg_your_api_key",
+    tenant_id="your-tenant-id",
+)
+
+# Store a memory
+client.add(
+    text="User prefers dark mode and uses PyTorch.",
+    user_id="user_123",
+)
+
+# Search for relevant context
+result = client.search(
+    query="What does this user prefer?",
+    user_id="user_123",
+)
+print(result)
+```
+
+## Async Client
+
+```python
+from memgraph_sdk import AsyncMemgraphClient
+
+async with AsyncMemgraphClient(
+    api_key="mg_your_api_key",
+    tenant_id="your-tenant-id",
+) as client:
+    await client.add("User prefers dark mode", user_id="user_123")
+    result = await client.search("user preferences", user_id="user_123")
+```
+
+## Memory Intelligence API
+
+```python
+# Memory health metrics
+health = client.health(user_id="user_123")
+
+# Detect contradictions
+contradictions = client.contradictions(user_id="user_123")
+
+# Evaluate retrieval quality
+evaluation = client.evaluate(query="test query", user_id="user_123")
+
+# Cognitive Integrity Score (0-100)
+score = client.mcis(user_id="user_123")
+
+# Run benchmarks
+result = client.benchmark(scenario="contradiction_storm")
+scenarios = client.benchmark_scenarios()
+```
+
+## CLI
+
+```bash
+# Initialize Memgraph in your project
+memgraph init
+
+# Store a memory
+memgraph remember "We decided to use PostgreSQL" -c decision
+
+# Search memories
+memgraph recall "database choice"
+
+# Check connection
+memgraph status
+```
+
+## Configuration
+
+The client reads the API URL from the `MEMGRAPH_API_URL` environment variable, defaulting to `http://localhost:8001/v1`. You can also pass it explicitly:
+
+```python
+client = MemgraphClient(
+    api_key="mg_your_key",
+    tenant_id="your-tenant-id",
+    base_url="https://api.memgraph.ai/v1",
+)
+```
+
+## Examples
+
+See the [examples/](examples/) directory for complete integration examples:
+
+- [Quick Start](examples/quick_start.py) -- Basic add and search
+- [Agent Integration](examples/agent_integration.py) -- OpenAI-powered agent with memory
+- [MCP Server](examples/integrations/mcp_server.py) -- Model Context Protocol server for Claude/Cursor
+- [LangChain](examples/integrations/langchain_integration.py) -- LangChain integration
+- [OpenAI](examples/integrations/openai_integration.py) -- OpenAI integration
+- [Benchmarks](examples/integrations/benchmark.py) -- Performance benchmarking
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

memgraph_sdk-0.1.0/memgraph_sdk/__init__.py

@@ -0,0 +1,12 @@
+"""Memgraph SDK - The official Python SDK for Memgraph, the memory graph for AI agents."""
+
+__version__ = "0.1.0"
+
+from .client import MemgraphClient
+
+try:
+    from .async_client import AsyncMemgraphClient
+except ImportError:
+    AsyncMemgraphClient = None  # httpx not installed
+
+__all__ = ["MemgraphClient", "AsyncMemgraphClient", "__version__"]

memgraph_sdk-0.1.0/memgraph_sdk/async_client.py

@@ -0,0 +1,163 @@
+"""
+Async SDK client for Memgraph.
+
+Uses httpx for non-blocking HTTP calls, suitable for async frameworks
+(FastAPI, aiohttp, etc.) and high-throughput pipelines.
+
+Usage:
+    from memgraph_sdk import AsyncMemgraphClient
+
+    async with AsyncMemgraphClient(api_key="...", tenant_id="...") as client:
+        await client.add("User prefers dark mode", user_id="u1")
+        ctx = await client.search("What theme does the user prefer?", user_id="u1")
+"""
+
+import os
+from typing import Dict, Any, Optional
+
+try:
+    import httpx
+except ImportError:
+    raise ImportError(
+        "httpx is required for AsyncMemgraphClient. Install it with: pip install httpx"
+    )
+
+
+class AsyncMemgraphClient:
+    def __init__(self, api_key: str, tenant_id: str, base_url: str = None, timeout: float = 30.0):
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+        self.base_url = base_url or os.getenv("MEMGRAPH_API_URL", "http://localhost:8001/v1")
+        self._client = httpx.AsyncClient(
+            base_url=self.base_url,
+            headers={"X-API-KEY": api_key},
+            timeout=timeout,
+        )
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+
+    async def close(self):
+        await self._client.aclose()
+
+    async def add(self, text: str, user_id: str, metadata: Optional[Dict] = None) -> Dict:
+        """Add a memory via the /ingest endpoint."""
+        data = {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "text": text,
+        }
+        resp = await self._client.post("/ingest", data=data)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def search(self, query: str, user_id: str, agent_id: str = "sdk_client") -> Dict[str, Any]:
+        """Retrieve relevant context for a query via /context endpoint."""
+        payload = {
+            "task": query,
+            "user_id": user_id,
+            "tenant_id": self.tenant_id,
+            "agent_id": agent_id,
+        }
+        resp = await self._client.post("/context", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_context(self, query: str, user_id: str) -> Dict[str, Any]:
+        """Alias for search()."""
+        return await self.search(query, user_id)
+
+    async def log_event(
+        self,
+        event_type: str,
+        content: Dict[str, Any],
+        user_id: str = "default_user",
+        agent_id: str = "sdk_client",
+        thread_id: Optional[str] = None,
+    ) -> Dict:
+        """Log a raw event to the /events endpoint."""
+        payload = {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "agent_id": agent_id,
+            "event_type": event_type,
+            "content": content,
+        }
+        if thread_id:
+            payload["thread_id"] = thread_id
+
+        resp = await self._client.post("/events", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def get_beliefs(self, user_id: str, limit: int = 50) -> list:
+        """Fetch beliefs for a user via /beliefs endpoint."""
+        resp = await self._client.get(
+            "/beliefs",
+            params={"tenant_id": self.tenant_id, "subject_id": user_id, "limit": limit},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------------------------------------------------------------------
+    # Memory Intelligence API
+    # ------------------------------------------------------------------
+
+    async def health(self, user_id: Optional[str] = None) -> Dict[str, Any]:
+        """Get memory health metrics for the tenant (optionally scoped to a user)."""
+        params = {}
+        if user_id:
+            params["user_id"] = user_id
+        resp = await self._client.get("/intelligence/health", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def contradictions(self, user_id: Optional[str] = None) -> Dict[str, Any]:
+        """Get contradiction report — all detected contradictions with resolution history."""
+        params = {}
+        if user_id:
+            params["user_id"] = user_id
+        resp = await self._client.get("/intelligence/contradictions", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def evaluate(self, query: str, user_id: str) -> Dict[str, Any]:
+        """Run a retrieval query and get detailed scoring breakdown."""
+        payload = {"query": query, "user_id": user_id}
+        resp = await self._client.post("/intelligence/evaluate", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def mcis(self, user_id: Optional[str] = None, save: bool = False) -> Dict[str, Any]:
+        """Compute the Memgraph Cognitive Integrity Score (0-100)."""
+        params = {"save": str(save).lower()}
+        if user_id:
+            params["user_id"] = user_id
+        resp = await self._client.get("/intelligence/mcis", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def mcis_history(self, user_id: Optional[str] = None, limit: int = 30) -> Dict[str, Any]:
+        """Get historical MCIS snapshots for trend visualization."""
+        params = {"limit": limit}
+        if user_id:
+            params["user_id"] = user_id
+        resp = await self._client.get("/intelligence/mcis/history", params=params)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def benchmark(self, scenario: str) -> Dict[str, Any]:
+        """Run a memory benchmark scenario (e.g. 'contradiction_storm', 'retrieval_accuracy')."""
+        payload = {"scenario": scenario}
+        resp = await self._client.post("/benchmark/run", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    async def benchmark_scenarios(self) -> list:
+        """List available benchmark scenarios."""
+        resp = await self._client.get("/benchmark/scenarios")
+        resp.raise_for_status()
+        return resp.json().get("scenarios", [])

memgraph_sdk-0.1.0/memgraph_sdk/cli.py

@@ -0,0 +1,308 @@
+#!/usr/bin/env python3
+"""
+Memgraph CLI - One-command setup for AI agent memory integration.
+
+Usage:
+    memgraph init       # Set up Memgraph in current project
+    memgraph remember   # Store a memory
+    memgraph recall     # Search memories
+    memgraph status     # Check connection
+"""
+import os
+import sys
+import shutil
+import argparse
+from pathlib import Path
+
+try:
+    import requests
+except ImportError:
+    requests = None
+
+# --- Constants ---
+CLOUD_URL = "https://api.memgraph.ai/v1"
+LOCAL_URL = os.getenv("MEMGRAPH_API_URL", "http://localhost:8001/v1")
+CONFIG_FILE = ".memgraph.env"
+SKILL_DIR = ".agent/skills/memgraph"
+
+# Template for skill file
+SKILL_TEMPLATE = '''---
+name: Memgraph Memory
+description: Seamless long-term memory for AI agents via Memgraph. Auto-learn, inject context, and suggest based on project history.
+---
+
+# Memgraph Memory Skill
+
+This skill gives you persistent memory across sessions.
+
+## MCP Tools Available
+
+| Tool | Use For |
+|------|---------|
+| `memgraph_search` | Find past decisions, architecture, context |
+| `memgraph_remember` | Store new facts and learnings |
+
+## When to SEARCH
+Call `memgraph_search` BEFORE answering questions about:
+- Architecture or design patterns
+- Previous decisions or bugs
+- "How does X work?" / "Why did we choose Y?"
+
+## When to REMEMBER
+Call `memgraph_remember` AFTER:
+- Completing a significant feature or fix
+- User makes an architectural decision
+- Resolving a tricky bug
+
+Categories: `decision`, `architecture`, `bug_fix`, `preference`, `general`
+'''
+
+MCP_CONFIG_TEMPLATE = '''{
+  "mcpServers": {
+    "memgraph": {
+      "command": "python3",
+      "args": ["${MCP_SERVER_PATH}"],
+      "env": {
+        "MEMGRAPH_API_URL": "${API_URL}",
+        "MEMGRAPH_TENANT_ID": "${TENANT_ID}",
+        "MEMGRAPH_API_KEY": "${API_KEY}"
+      }
+    }
+  }
+}
+'''
+
+
+def get_package_dir():
+    """Get the memgraph-sdk package installation directory."""
+    return Path(__file__).parent.parent
+
+
+def init_project():
+    """Initialize Memgraph in the current project."""
+    print("🚀 Memgraph Agent Memory Setup\n")
+
+    # 1. Choose deployment mode
+    print("Where is your Memgraph server running?")
+    print("  1) Cloud (api.memgraph.ai)")
+    print("  2) On-prem / Local (localhost:8001)")
+    print("  3) Custom URL")
+
+    choice = input("\nChoose [1/2/3]: ").strip()
+
+    if choice == "1":
+        api_url = CLOUD_URL
+    elif choice == "2":
+        api_url = LOCAL_URL
+    elif choice == "3":
+        api_url = input("Enter API URL: ").strip()
+    else:
+        print("Invalid choice")
+        return
+
+    # 2. Get credentials
+    tenant_id = input("\nTenant ID: ").strip()
+    api_key = input("API Key (optional, press Enter to skip): ").strip()
+
+    # 3. Create .memgraph.env
+    config_path = Path(CONFIG_FILE)
+    with open(config_path, "w") as f:
+        f.write(f"MEMGRAPH_API_URL={api_url}\n")
+        f.write(f"MEMGRAPH_TENANT_ID={tenant_id}\n")
+        if api_key:
+            f.write(f"MEMGRAPH_API_KEY={api_key}\n")
+    print(f"\n✅ Created {CONFIG_FILE}")
+
+    # 4. Create skill directory
+    skill_path = Path(SKILL_DIR)
+    skill_path.mkdir(parents=True, exist_ok=True)
+
+    skill_file = skill_path / "SKILL.md"
+    with open(skill_file, "w") as f:
+        f.write(SKILL_TEMPLATE)
+    print(f"✅ Created {skill_file}")
+
+    # 5. Copy or reference MCP server
+    mcp_server_path = get_package_dir() / "examples" / "integrations" / "mcp_server.py"
+    if mcp_server_path.exists():
+        mcp_dest = skill_path / "mcp_server.py"
+        shutil.copy(mcp_server_path, mcp_dest)
+        print(f"✅ Copied MCP server to {mcp_dest}")
+
+    # 6. Create MCP config hints
+    print("\n📋 To enable MCP in your editor:")
+    print("\n   For Cursor, add to .cursor/mcp.json:")
+    mcp_config = MCP_CONFIG_TEMPLATE.replace("${API_URL}", api_url)
+    mcp_config = mcp_config.replace("${TENANT_ID}", tenant_id)
+    mcp_config = mcp_config.replace("${API_KEY}", api_key or "")
+    mcp_config = mcp_config.replace("${MCP_SERVER_PATH}", str(skill_path / "mcp_server.py"))
+    print(mcp_config)
+
+    print("\n🎉 Memgraph agent memory is ready!")
+    print("   Your AI agent can now use memgraph_search and memgraph_remember tools.")
+
+
+def remember_cmd(text: str, category: str = "general"):
+    """Store a memory via CLI."""
+    if not requests:
+        print("Error: 'requests' package not installed. Run: pip install requests")
+        return
+
+    config = load_config()
+    if not config:
+        print("Error: Not initialized. Run 'memgraph init' first.")
+        return
+
+    try:
+        resp = requests.post(
+            f"{config['api_url']}/ingest",
+            data={
+                "tenant_id": config["tenant_id"],
+                "user_id": "cli_user",
+                "text": f"[{category}] {text}",
+            },
+            headers={"X-API-KEY": config.get("api_key", "")},
+            timeout=10
+        )
+        if resp.status_code == 200:
+            print(f"✅ Remembered: {text[:80]}...")
+        else:
+            print(f"❌ Error: {resp.text}")
+    except requests.ConnectionError:
+        print("❌ Cannot connect to Memgraph server")
+
+
+def recall_cmd(query: str):
+    """Search memories via CLI."""
+    if not requests:
+        print("Error: 'requests' package not installed. Run: pip install requests")
+        return
+
+    config = load_config()
+    if not config:
+        print("Error: Not initialized. Run 'memgraph init' first.")
+        return
+
+    try:
+        resp = requests.post(
+            f"{config['api_url']}/context",
+            json={
+                "tenant_id": config["tenant_id"],
+                "user_id": "cli_user",
+                "task": query,
+                "agent_id": "cli"
+            },
+            headers={"X-API-KEY": config.get("api_key", "")},
+            timeout=10
+        )
+        if resp.status_code == 200:
+            data = resp.json()
+            results = data.get("results", [])
+            if results:
+                print(f"\n🔍 Found {len(results)} results for '{query}':\n")
+                for r in results:
+                    if isinstance(r, dict):
+                        print(f"  • {r.get('text', r)}")
+                    else:
+                        print(f"  • {r}")
+            else:
+                print("No memories found for this query.")
+        else:
+            print(f"❌ Error: {resp.text}")
+    except requests.ConnectionError:
+        print("❌ Cannot connect to Memgraph server")
+
+
+def status_cmd():
+    """Check Memgraph connection status."""
+    config = load_config()
+    if not config:
+        print("❌ Not initialized. Run 'memgraph init' first.")
+        return
+
+    print(f"📡 API URL: {config['api_url']}")
+    print(f"🏢 Tenant:  {config['tenant_id']}")
+    print(f"🔑 API Key: {'***' + config['api_key'][-4:] if config.get('api_key') else '(not set)'}")
+
+    if requests:
+        try:
+            resp = requests.get(f"{config['api_url']}/health", timeout=5)
+            if resp.status_code == 200:
+                print("\n✅ Server is reachable")
+            else:
+                print(f"\n⚠️  Server returned: {resp.status_code}")
+        except requests.ConnectionError:
+            print("\n❌ Cannot connect to server")
+    else:
+        print("\n⚠️  Cannot check connection (requests not installed)")
+
+
+def load_config():
+    """Load config from .memgraph.env file."""
+    config_path = Path(CONFIG_FILE)
+    if not config_path.exists():
+        return None
+
+    config = {}
+    with open(config_path) as f:
+        for line in f:
+            line = line.strip()
+            if "=" in line and not line.startswith("#"):
+                key, value = line.split("=", 1)
+                key = key.strip().lower().replace("memgraph_", "")
+                config[key] = value.strip()
+
+    return {
+        "api_url": config.get("api_url", LOCAL_URL),
+        "tenant_id": config.get("tenant_id"),
+        "api_key": config.get("api_key")
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Memgraph - AI Agent Memory Graph",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  memgraph init                    # Set up Memgraph in current project
+  memgraph remember "Used JWT"     # Store a memory
+  memgraph recall "authentication" # Search memories
+  memgraph status                  # Check connection
+"""
+    )
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    # init
+    subparsers.add_parser("init", help="Initialize Memgraph in current project")
+
+    # remember
+    rem_parser = subparsers.add_parser("remember", help="Store a memory")
+    rem_parser.add_argument("text", help="Text to remember")
+    rem_parser.add_argument("-c", "--category", default="general",
+                           choices=["decision", "architecture", "bug_fix", "preference", "general"])
+
+    # recall
+    rec_parser = subparsers.add_parser("recall", help="Search memories")
+    rec_parser.add_argument("query", help="Search query")
+
+    # status
+    subparsers.add_parser("status", help="Check connection status")
+
+    args = parser.parse_args()
+
+    if args.command == "init":
+        init_project()
+    elif args.command == "remember":
+        remember_cmd(args.text, args.category)
+    elif args.command == "recall":
+        recall_cmd(args.query)
+    elif args.command == "status":
+        status_cmd()
+    else:
+        parser.print_help()
+
+
+if __name__ == "__main__":
+    main()

memgraph_sdk-0.1.0/memgraph_sdk/client.py

@@ -0,0 +1,115 @@
+import os
+import requests
+from typing import List, Dict, Any, Optional
+
+class MemgraphClient:
+    def __init__(self, api_key: str, tenant_id: str, base_url: str = None):
+        self.api_key = api_key
+        self.tenant_id = tenant_id
+        self.base_url = base_url or os.getenv("MEMGRAPH_API_URL", "http://localhost:8001/v1")
+        self.headers = {
+            "X-API-KEY": api_key,
+            # "Content-Type" is handled automatically by requests for Form data or JSON
+        }
+
+    def add(self, text: str, user_id: str, metadata: Optional[Dict] = None) -> Dict:
+        """
+        Add a memory via the /ingest endpoint.
+        Uses multipart/form-data as required by the backend.
+        """
+        data = {
+            "tenant_id": self.tenant_id,
+            "user_id": user_id,
+            "text": text,
+        }
+        # If we had metadata/files, we would add them here.
+        # Verify if metadata is supported by ingest_omni (it currently isn't in the Form params shown in ingest.py, 
+        # but the logic creates an event with content_payload which we might want to extend later).
+        
+        resp = requests.post(f"{self.base_url}/ingest", data=data, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def search(self, query: str, user_id: str, agent_id: str = "sdk_client") -> Dict[str, Any]:
+        """
+        Retrieve relevant context for a query via /context endpoint.
+        """
+        payload = {
+            "task": query, # Server expects 'task', not 'query' based on E2E
+            "user_id": user_id,
+            "tenant_id": self.tenant_id,
+            "agent_id": agent_id
+        }
+        resp = requests.post(f"{self.base_url}/context", json=payload, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    # Deprecated/Legacy methods mapped to new ones for compatibility
+    def log_event(self, event_type: str, content: Dict[str, Any], metadata: Optional[Dict] = None) -> Dict:
+        # Fallback to ingest if content has text
+        if "text" in content:
+            return self.add(content["text"], "legacy_user")
+        raise NotImplementedError("Generic log_event not fully supported yet.")
+
+    def get_context(self, query: str, user_id: str) -> Dict[str, Any]:
+        return self.search(query, user_id)
+
+    # ------------------------------------------------------------------
+    # Memory Intelligence API
+    # ------------------------------------------------------------------
+
+    def health(self, user_id: Optional[str] = None) -> Dict[str, Any]:
+        """Get memory health metrics for the tenant (optionally scoped to a user)."""
+        params = {}
+        if user_id:
+            params["user_id"] = user_id
+        resp = requests.get(f"{self.base_url}/intelligence/health", params=params, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def contradictions(self, user_id: Optional[str] = None) -> Dict[str, Any]:
+        """Get contradiction report — all detected contradictions with resolution history."""
+        params = {}
+        if user_id:
+            params["user_id"] = user_id
+        resp = requests.get(f"{self.base_url}/intelligence/contradictions", params=params, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def evaluate(self, query: str, user_id: str) -> Dict[str, Any]:
+        """Run a retrieval query and get detailed scoring breakdown."""
+        payload = {"query": query, "user_id": user_id}
+        resp = requests.post(f"{self.base_url}/intelligence/evaluate", json=payload, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def mcis(self, user_id: Optional[str] = None, save: bool = False) -> Dict[str, Any]:
+        """Compute the Memgraph Cognitive Integrity Score (0-100)."""
+        params = {"save": str(save).lower()}
+        if user_id:
+            params["user_id"] = user_id
+        resp = requests.get(f"{self.base_url}/intelligence/mcis", params=params, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def mcis_history(self, user_id: Optional[str] = None, limit: int = 30) -> Dict[str, Any]:
+        """Get historical MCIS snapshots for trend visualization."""
+        params = {"limit": limit}
+        if user_id:
+            params["user_id"] = user_id
+        resp = requests.get(f"{self.base_url}/intelligence/mcis/history", params=params, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def benchmark(self, scenario: str) -> Dict[str, Any]:
+        """Run a memory benchmark scenario (e.g. 'contradiction_storm', 'retrieval_accuracy')."""
+        payload = {"scenario": scenario}
+        resp = requests.post(f"{self.base_url}/benchmark/run", json=payload, headers=self.headers)
+        resp.raise_for_status()
+        return resp.json()
+
+    def benchmark_scenarios(self) -> List[Dict]:
+        """List available benchmark scenarios."""
+        resp = requests.get(f"{self.base_url}/benchmark/scenarios", headers=self.headers)
+        resp.raise_for_status()
+        return resp.json().get("scenarios", [])

memgraph_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "memgraph-sdk"
+dynamic = ["version"]
+description = "Official Python SDK for Memgraph - the memory graph for AI agents"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Memgraph Team", email = "sdk@memgraph.ai" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+keywords = ["memgraph", "ai", "memory", "agents", "llm", "rag", "context"]
+dependencies = [
+    "requests>=2.25.0",
+    "pydantic>=2.0.0",
+    "typing-extensions>=4.0.0",
+]
+requires-python = ">=3.8"
+
+[project.scripts]
+memgraph = "memgraph_sdk.cli:main"
+
+[project.optional-dependencies]
+async = ["httpx>=0.24.0"]
+cli = ["rich>=13.0.0"]
+all = ["httpx>=0.24.0", "rich>=13.0.0"]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "httpx>=0.24.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://memgraph.ai"
+Documentation = "https://memgraph.ai/docs"
+Repository = "https://github.com/memgraph-ai/memgraph-sdk"
+"Bug Tracker" = "https://github.com/memgraph-ai/memgraph-sdk/issues"
+Changelog = "https://github.com/memgraph-ai/memgraph-sdk/blob/main/CHANGELOG.md"
+
+[tool.hatch.version]
+path = "memgraph_sdk/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "memgraph_sdk/",
+    "LICENSE",
+    "README.md",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["memgraph_sdk"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]