epistemic-graph-memory 1.2.0__py3-none-any.whl

epistemic_graph_memory-1.2.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: epistemic-graph-memory
+Version: 1.2.0
+Summary: A universal, long-term project memory tool utilizing a local SQLite graph structure for AI agents.
+Author: Divyansh Ailani
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.1.2
+
+# Graph-Memory
+
+A universal, long-term project memory tool utilizing a local SQLite graph structure to solve context amnesia for AI coding agents.
+
+**Natively built for Antigravity (AG)**, Graph-Memory provides autonomous AI agents with a highly structured, relational brain. It is exposed universally via the **Model Context Protocol (MCP)**, meaning any framework (Claude Desktop, Cursor, Codex, Aider) can share and update the exact same graph in real-time.
+
+## Overview
+When AI agents work on complex software projects over long periods, flat markdown files like `project_memory.md` often fail because they lack structural context and the agent forgets the relationships between different files, tasks, and infrastructure.
+
+**Graph-Memory** solves this by providing a **Trust-Weighted Epistemic Graph** database (SQLite-backed) that your agents interact with to store long-term architecture. It forces agents to provide confidence levels on the facts they log, entirely preventing silent hallucinations.
+
+## File Structure
+
+```
+Graph memory/
+├── .agents/                    # Database and exports (auto-generated per workspace)
+│   ├── graph_memory.sqlite     # The isolated SQLite brain
+│   └── graph_memory_vis.html   # The interactive visual graph
+├── scripts/
+│   ├── db.py                   # Core SQLite bindings, schema, and epistemic logic
+│   ├── mcp_server.py           # The Universal Model Context Protocol (MCP) Server
+│   └── memory_tool.py          # The CLI tool & HTML Visualizer
+├── SKILL.md                    # Antigravity native skill instructions and rules
+├── README.md                   # This documentation
+├── CHANGELOG.md                # Version history
+└── ISSUES.md                   # Known bugs and future roadmap
+```
+
+## Features
+- **Trust-Weighted Epistemic Graph**: The graph strictly tracks *when* a fact was logged, and *how* it was verified. If an agent just assumes a fact, the graph flags it as stale. It only trusts explicit code reads and executed tests.
+- **Idempotent Nodes & Edges**: Agents log Tasks, Decisions, Infrastructure, and Bugs as connected nodes.
+- **Strict Modeling Rules**: Rules enforced via instructions ensure no orphaned nodes and strict typing.
+- **Obsidian-style Vis.js HTML Export**: Generate beautiful, physics-based, dark-mode graph visualizations in your browser. Stale or hallucinated nodes are visually flagged.
+- **Universal State**: The database is stored locally in `.agents/graph_memory.sqlite`, meaning Claude Desktop, Cursor, and Antigravity can all read/write to the exact same brain simultaneously.
+
+## Quickstart
+
+### 1. Installation
+
+You can now install Graph-Memory globally via pip! No more cloning needed.
+
+```bash
+pip install epistemic-graph-memory
+```
+
+This installs two global commands:
+- `graph-memory` (The local CLI tool)
+- `graph-memory-mcp` (The MCP server for AI agents)
+
+### 2. Connect to your AI
+
+Graph-Memory exposes the exact 9 standard MCP Tool signatures (`create_entities`, `search_nodes`, `add_observations`, etc.). This makes it a **100% Drop-In Replacement** for the official Anthropic Memory Server.
+
+Add the following to your AI framework's configuration:
+
+**macOS/Linux:**
+```json
+{
+  "mcpServers": {
+    "graph-memory": {
+      "command": "graph-memory-mcp"
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "graph-memory": {
+      "command": "graph-memory-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Pro-Tip: Enabling "Live" Auto-Updates
+In Antigravity (AG), Graph-Memory is deeply integrated, meaning the agent automatically updates the database in the background without you asking.
+
+**To get this same "Live Auto-Update" behavior in Claude Desktop, Cursor, or Codex**, you must paste the following rule into your **Project Instructions**, `.cursorrules`, or `.codexrules` file:
+
+```markdown
+# Automated Graph Memory Tracking
+You have access to a `graph_memory` MCP server. You MUST proactively and automatically use the `add_node` and `add_relation` tools to track project state without the user explicitly asking you to. 
+
+Whenever you:
+1. Complete a significant task or milestone.
+2. Make an architectural decision.
+3. Discover or setup new infrastructure.
+
+Quietly run the graph tools at the end of your turn to log this information so it isn't forgotten.
+```
+*Without this rule, Claude/Cursor will treat the graph as a purely manual tool and will only update it when explicitly asked.*
+
+---
+
+## Antigravity Installation (Native)
+If you are using Antigravity, you can link this repository directly into your skills folder to use it natively via CLI.
+
+**macOS/Linux:**
+```bash
+ln -s "/path/to/Graph memory" ~/.gemini/config/skills/graph_memory
+```
+
+**Windows (Run Command Prompt as Administrator):**
+```cmd
+mklink /D "C:\Users\YOUR_USERNAME\.gemini\config\skills\graph_memory" "C:\path\to\Graph memory"
+```
+
+### Manual CLI Tools
+
+You can interact with the graph database directly from your terminal using the installed `graph-memory` command! By default, it will look for `.agents/graph_memory.sqlite` in your current working directory.
+
+```bash
+# Add an Entity with JSON properties (Observations)
+graph-memory add_node "Postgres_DB" "Database" '{"observations": ["Assumed based on backend code."]}'
+
+# Add a Relation
+graph-memory add_relation "Server_VM" "HAS_DB" "Postgres_DB"
+
+# Get a Node's Subgraph
+graph-memory get_node "Postgres_DB"
+
+# Search using FTS5 Natural Language
+graph-memory search "Assumed based on backend"
+
+# Soft-Delete a Node
+graph-memory delete_node "Postgres_DB"
+
+# Export Graph to an Interactive HTML file
+graph-memory export_html my_graph.html
+```
+
+## Advanced Configuration
+
+You can override the default database location by setting the environment variable:
+```bash
+export GRAPH_MEMORY_DB_PATH="/path/to/my_global_brain.sqlite"
+```

epistemic_graph_memory-1.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+graph_memory/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graph_memory/cli.py,sha256=0yFSCDhjFj_3gfVC2sqFL74sVVUvoum2lsHnrvW7LK0,6404
+graph_memory/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graph_memory/core/engine.py,sha256=--BGt9BLvIjHKmYmDRIHARPTftBPJ9zYJD0W5JpHnVI,13835
+graph_memory/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graph_memory/mcp/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+graph_memory/mcp/server.py,sha256=pJ2uWwaObTeRARZUlMke1VqbH5tzIyW4nUdKjNO5Sj8,12781
+epistemic_graph_memory-1.2.0.dist-info/METADATA,sha256=rgLVUZIFLwCv1kmLe8GfO61aKNuQ4lWML68hlKpEmx0,6283
+epistemic_graph_memory-1.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+epistemic_graph_memory-1.2.0.dist-info/entry_points.txt,sha256=T1BmYtsC9vk2NbcgCNdGr8-SbOix4WCCjTnY-iFObAQ,103
+epistemic_graph_memory-1.2.0.dist-info/top_level.txt,sha256=sl6KUYXhExtlOvLC5RGwfXzfWxtz5CrPtoBUWgR8-eg,13
+epistemic_graph_memory-1.2.0.dist-info/RECORD,,

epistemic_graph_memory-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

epistemic_graph_memory-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+graph-memory = graph_memory.cli:main
+graph-memory-mcp = graph_memory.mcp.server:main

epistemic_graph_memory-1.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+graph_memory

graph_memory/cli.py

@@ -0,0 +1,145 @@
+import argparse
+import sys
+import json
+import os
+import glob
+
+from graph_memory.core import engine
+
+def main():
+    parser = argparse.ArgumentParser(description="Graph-Memory CLI Tool")
+    parser.add_argument("--db", type=str, help="Path to the SQLite database (defaults to workspace/.agents/graph_memory.sqlite)")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # get_node
+    get_node_parser = subparsers.add_parser("get_node", help="Get a node and its relationships")
+    get_node_parser.add_argument("node_id", type=str, help="The ID of the node to retrieve")
+
+    # delete_node
+    delete_node_parser = subparsers.add_parser("delete_node", help="Soft-delete a node")
+    delete_node_parser.add_argument("node_id", type=str, help="The ID of the node to soft-delete")
+
+    # add_node (Maps to create_entities / add_observation)
+    add_node_parser = subparsers.add_parser("add_node", help="Add or update a node")
+    add_node_parser.add_argument("node_id", type=str, help="The unique identifier for the node")
+    add_node_parser.add_argument("label", type=str, help="The label/type for the node")
+    add_node_parser.add_argument("properties", type=str, nargs="?", default="{}", help="JSON properties (optional)")
+
+    # add_relation (Maps to create_relations)
+    add_relation_parser = subparsers.add_parser("add_relation", help="Add a relationship between nodes")
+    add_relation_parser.add_argument("source_id", type=str, help="Source node ID")
+    add_relation_parser.add_argument("relation_type", type=str, help="Type of relationship")
+    add_relation_parser.add_argument("target_id", type=str, help="Target node ID")
+    add_relation_parser.add_argument("properties", type=str, nargs="?", default="{}", help="JSON properties (optional)")
+
+    # search
+    search_parser = subparsers.add_parser("search", help="Full-text search across nodes")
+    search_parser.add_argument("query", type=str, help="Search query")
+
+    # import_md
+    import_md_parser = subparsers.add_parser("import", help="Import legacy markdown files into the graph")
+    import_md_parser.add_argument("directory", type=str, help="Directory containing .md files")
+
+    # export_html
+    export_html_parser = subparsers.add_parser("export_html", help="Export the graph to an HTML visualization")
+    export_html_parser.add_argument("output_file", type=str, help="Output HTML file path")
+
+    args = parser.parse_args()
+    
+    db_path = args.db or engine.get_db_path()
+    engine.init_db(db_path)
+
+    try:
+        if args.command == "get_node":
+            result = engine.serialize_subgraph(db_path, args.node_id)
+            print(result)
+
+        elif args.command == "delete_node":
+            engine.soft_delete_entity(db_path, args.node_id)
+            print(f"Node '{args.node_id}' soft-deleted successfully.")
+
+        elif args.command == "add_node":
+            props = json.loads(args.properties)
+            engine.get_or_create_node(db_path, args.node_id, args.label, props)
+            print(f"Node '{args.node_id}' added/updated successfully.")
+
+        elif args.command == "add_relation":
+            props = json.loads(args.properties)
+            engine.create_relation(db_path, args.source_id, args.target_id, args.relation_type, props)
+            print(f"Relation created: {args.source_id} -[{args.relation_type}]-> {args.target_id}")
+
+        elif args.command == "search":
+            results = engine.search_nodes(db_path, args.query)
+            print(json.dumps(results, indent=2))
+
+        elif args.command == "import":
+            md_files = glob.glob(os.path.join(args.directory, "**/*.md"), recursive=True)
+            for fpath in md_files:
+                basename = os.path.basename(fpath)
+                node_id = os.path.splitext(basename)[0]
+                try:
+                    with open(fpath, "r", encoding="utf-8") as f:
+                        content = f.read()
+                    # Create node
+                    engine.get_or_create_node(db_path, node_id, "Document", {"type": "legacy_markdown"})
+                    # Add content as observation
+                    engine.add_observation(db_path, node_id, f"Content snippet: {content[:500]}")
+                    print(f"Imported: {node_id}")
+                except Exception as e:
+                    print(f"Error importing {fpath}: {e}")
+
+        elif args.command == "export_html":
+            graph = engine.read_graph(db_path)
+            
+            # Simple HTML generator using vis.js
+            nodes_js = []
+            for n in graph["nodes"]:
+                nodes_js.append({
+                    "id": n["id"],
+                    "label": n["id"],
+                    "title": json.dumps(n["properties"])
+                })
+            
+            edges_js = []
+            for e in graph["edges"]:
+                edges_js.append({
+                    "from": e["source_id"],
+                    "to": e["target_id"],
+                    "label": e["relation_type"],
+                    "title": json.dumps(e["properties"])
+                })
+                
+            html_content = f"""
+            <!DOCTYPE html>
+            <html>
+            <head>
+                <title>Graph Memory Visualization</title>
+                <script type="text/javascript" src="https://unpkg.com/vis-network/standalone/umd/vis-network.min.js"></script>
+                <style type="text/css">
+                    #mynetwork {{ width: 100vw; height: 100vh; border: 1px solid lightgray; }}
+                </style>
+            </head>
+            <body>
+            <div id="mynetwork"></div>
+            <script type="text/javascript">
+                var nodes = new vis.DataSet({json.dumps(nodes_js)});
+                var edges = new vis.DataSet({json.dumps(edges_js)});
+                var container = document.getElementById('mynetwork');
+                var data = {{ nodes: nodes, edges: edges }};
+                var options = {{}};
+                var network = new vis.Network(container, data, options);
+            </script>
+            </body>
+            </html>
+            """
+            
+            with open(args.output_file, "w") as f:
+                f.write(html_content)
+            print(f"Exported HTML visualization to {args.output_file}")
+
+    except Exception as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+
+if __name__ == "__main__":
+    main()

graph_memory/core/engine.py

@@ -0,0 +1,355 @@
+import sqlite3
+import json
+import os
+from contextlib import contextmanager
+from datetime import datetime, timezone
+
+# ---------------------------------------------------------------------------
+# Database Configuration
+# ---------------------------------------------------------------------------
+
+def get_db_path(workspace_dir: str = None) -> str:
+    """
+    Resolve the SQLite database path. Checks GRAPH_MEMORY_DB_PATH env var first,
+    then falls back to workspace_dir/.agents/graph_memory.sqlite.
+    """
+    env_path = os.environ.get("GRAPH_MEMORY_DB_PATH")
+    if env_path:
+        return env_path
+    
+    if not workspace_dir:
+        workspace_dir = os.getcwd()
+        
+    agents_dir = os.path.join(workspace_dir, ".agents")
+    os.makedirs(agents_dir, exist_ok=True)
+    return os.path.join(agents_dir, "graph_memory.sqlite")
+
+# ---------------------------------------------------------------------------
+# Concurrency & Transactions
+# ---------------------------------------------------------------------------
+
+@contextmanager
+def get_connection(db_path: str):
+    """
+    Provides a base connection with required PRAGMAs for concurrency and integrity.
+    """
+    # check_same_thread=False allows multi-agent thread pools (like CrewAI) to share connections safely.
+    conn = sqlite3.connect(db_path, check_same_thread=False, timeout=30.0)
+    # WAL mode for concurrent readers and a single writer
+    conn.execute("PRAGMA journal_mode = WAL;")
+    # Enforce foreign key constraints
+    conn.execute("PRAGMA foreign_keys = ON;")
+    # Enable auto-vacuum to instantly reclaim space when nodes are pruned/soft-deleted
+    conn.execute("PRAGMA auto_vacuum = INCREMENTAL;")
+    
+    try:
+        yield conn
+    finally:
+        conn.close()
+
+@contextmanager
+def write_transaction(conn: sqlite3.Connection):
+    """
+    Forces an immediate write-lock. 
+    Prevents 'database is locked' deadlock errors when multiple agents try to write simultaneously in WAL mode.
+    """
+    conn.execute("BEGIN IMMEDIATE;")
+    try:
+        yield conn
+        conn.commit()
+    except Exception as e:
+        conn.rollback()
+        raise e
+
+# ---------------------------------------------------------------------------
+# Schema Initialization
+# ---------------------------------------------------------------------------
+
+def init_db(db_path: str):
+    """
+    Initialize the Trust-Weighted Epistemic Graph schema.
+    """
+    with get_connection(db_path) as conn:
+        with write_transaction(conn):
+            # Nodes Table (Entities)
+            # Includes tracking for memory decay and soft deletes.
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS Nodes (
+                    id TEXT PRIMARY KEY,
+                    label TEXT NOT NULL,
+                    properties TEXT, -- JSON payload
+                    created_at TEXT NOT NULL,
+                    last_verified_at TEXT,
+                    updated_at TEXT NOT NULL,
+                    access_count INTEGER DEFAULT 0,
+                    status TEXT DEFAULT 'active', -- active, superseded
+                    is_deleted INTEGER DEFAULT 0
+                )
+            """)
+            
+            # Edges Table (Relations)
+            # Uses ON DELETE CASCADE and a UNIQUE composite key.
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS Edges (
+                    source_id TEXT NOT NULL,
+                    target_id TEXT NOT NULL,
+                    relation_type TEXT NOT NULL,
+                    properties TEXT, -- JSON payload
+                    created_at TEXT NOT NULL,
+                    last_verified_at TEXT,
+                    status TEXT DEFAULT 'active', -- active, superseded
+                    FOREIGN KEY(source_id) REFERENCES Nodes(id) ON DELETE CASCADE,
+                    FOREIGN KEY(target_id) REFERENCES Nodes(id) ON DELETE CASCADE,
+                    UNIQUE(source_id, target_id, relation_type)
+                )
+            """)
+            
+            # FTS5 Shadow Table for Full-Text Search
+            conn.execute("""
+                CREATE VIRTUAL TABLE IF NOT EXISTS NodesFTS USING fts5(
+                    id, label, properties, content='Nodes', content_rowid='rowid'
+                )
+            """)
+            
+            # Triggers to keep FTS5 synchronized with the main Nodes table
+            conn.execute("""
+                CREATE TRIGGER IF NOT EXISTS tr_nodes_ai AFTER INSERT ON Nodes BEGIN
+                    INSERT INTO NodesFTS(rowid, id, label, properties)
+                    VALUES (new.rowid, new.id, new.label, new.properties);
+                END;
+            """)
+            conn.execute("""
+                CREATE TRIGGER IF NOT EXISTS tr_nodes_ad AFTER DELETE ON Nodes BEGIN
+                    INSERT INTO NodesFTS(NodesFTS, rowid, id, label, properties)
+                    VALUES ('delete', old.rowid, old.id, old.label, old.properties);
+                END;
+            """)
+            conn.execute("""
+                CREATE TRIGGER IF NOT EXISTS tr_nodes_au AFTER UPDATE ON Nodes BEGIN
+                    INSERT INTO NodesFTS(NodesFTS, rowid, id, label, properties)
+                    VALUES ('delete', old.rowid, old.id, old.label, old.properties);
+                    INSERT INTO NodesFTS(rowid, id, label, properties)
+                    VALUES (new.rowid, new.id, new.label, new.properties);
+                END;
+            """)
+            
+            # JSON Expression Index
+            conn.execute("""
+                CREATE INDEX IF NOT EXISTS idx_nodes_type
+                ON Nodes(json_extract(properties, '$.type'))
+            """)
+
+# ---------------------------------------------------------------------------
+# Core Operations
+# ---------------------------------------------------------------------------
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+def search_nodes(db_path: str, query: str) -> list:
+    """
+    Full-Text Search across the graph using FTS5. Excludes soft-deleted nodes.
+    """
+    init_db(db_path)
+    with get_connection(db_path) as conn:
+        cursor = conn.execute("""
+            SELECT n.id, n.label, n.properties, n.status 
+            FROM NodesFTS f
+            JOIN Nodes n ON f.rowid = n.rowid
+            WHERE NodesFTS MATCH ? AND n.is_deleted = 0
+            ORDER BY rank
+            LIMIT 20
+        """, (query,))
+        
+        results = []
+        for row in cursor.fetchall():
+            results.append({
+                "id": row[0],
+                "label": row[1],
+                "properties": json.loads(row[2]) if row[2] else {},
+                "status": row[3]
+            })
+            
+            # Update access count to prevent memory decay
+            with write_transaction(conn):
+                conn.execute("""
+                    UPDATE Nodes 
+                    SET access_count = access_count + 1, updated_at = ? 
+                    WHERE id = ?
+                """, (now_iso(), row[0]))
+                
+        return results
+
+def get_or_create_node(db_path: str, node_id: str, label: str, properties: dict = None) -> str:
+    """
+    Creates a node, or returns an existing one to prevent fragmentation.
+    Implements the "Supersession" problem solution.
+    """
+    init_db(db_path)
+    props = properties or {}
+    
+    with get_connection(db_path) as conn:
+        with write_transaction(conn):
+            # Check for exact match first
+            row = conn.execute("SELECT id, properties FROM Nodes WHERE id = ? AND is_deleted = 0", (node_id,)).fetchone()
+            
+            if row:
+                # Update properties (observations map into properties here)
+                existing_props = json.loads(row[1]) if row[1] else {}
+                existing_props.update(props)
+                conn.execute("""
+                    UPDATE Nodes 
+                    SET properties = ?, updated_at = ?, access_count = access_count + 1
+                    WHERE id = ?
+                """, (json.dumps(existing_props), now_iso(), node_id))
+                return node_id
+            
+            # Insert new node
+            conn.execute("""
+                INSERT INTO Nodes (id, label, properties, created_at, updated_at)
+                VALUES (?, ?, ?, ?, ?)
+            """, (node_id, label, json.dumps(props), now_iso(), now_iso()))
+            
+            return node_id
+
+def create_relation(db_path: str, source_id: str, target_id: str, relation_type: str, properties: dict = None):
+    """
+    Draw an edge. Composite UNIQUE constraint prevents identical duplicates.
+    """
+    init_db(db_path)
+    props = properties or {}
+    
+    with get_connection(db_path) as conn:
+        with write_transaction(conn):
+            conn.execute("""
+                INSERT INTO Edges (source_id, target_id, relation_type, properties, created_at)
+                VALUES (?, ?, ?, ?, ?)
+                ON CONFLICT(source_id, target_id, relation_type) DO UPDATE SET
+                    properties = excluded.properties,
+                    last_verified_at = ?
+            """, (source_id, target_id, relation_type, json.dumps(props), now_iso(), now_iso()))
+
+def add_observation(db_path: str, node_id: str, observation: str):
+    """
+    Appends an observation directly into the 'observations' array in the properties JSON payload.
+    """
+    init_db(db_path)
+    
+    with get_connection(db_path) as conn:
+        with write_transaction(conn):
+            row = conn.execute("SELECT properties FROM Nodes WHERE id = ? AND is_deleted = 0", (node_id,)).fetchone()
+            if not row:
+                raise ValueError(f"Node '{node_id}' not found or is deleted.")
+            
+            props = json.loads(row[0]) if row[0] else {}
+            observations = props.get("observations", [])
+            observations.append(observation)
+            props["observations"] = observations
+            
+            conn.execute("""
+                UPDATE Nodes 
+                SET properties = ?, updated_at = ?
+                WHERE id = ?
+            """, (json.dumps(props), now_iso(), node_id))
+
+def soft_delete_entity(db_path: str, node_id: str):
+    """
+    Soft-deletes a node by setting is_deleted=1.
+    """
+    init_db(db_path)
+    with get_connection(db_path) as conn:
+        with write_transaction(conn):
+            conn.execute("UPDATE Nodes SET is_deleted = 1, updated_at = ? WHERE id = ?", (now_iso(), node_id))
+
+def delete_relation(db_path: str, source_id: str, target_id: str, relation_type: str):
+    """
+    Hard-deletes an edge.
+    """
+    init_db(db_path)
+    with get_connection(db_path) as conn:
+        with write_transaction(conn):
+            conn.execute("""
+                DELETE FROM Edges 
+                WHERE source_id = ? AND target_id = ? AND relation_type = ?
+            """, (source_id, target_id, relation_type))
+
+def read_graph(db_path: str) -> dict:
+    """
+    Exports the entire active graph topology.
+    """
+    init_db(db_path)
+    with get_connection(db_path) as conn:
+        nodes = []
+        for row in conn.execute("SELECT id, label, properties FROM Nodes WHERE is_deleted = 0").fetchall():
+            nodes.append({
+                "id": row[0],
+                "label": row[1],
+                "properties": json.loads(row[2]) if row[2] else {}
+            })
+            
+        edges = []
+        for row in conn.execute("SELECT source_id, target_id, relation_type, properties FROM Edges").fetchall():
+            edges.append({
+                "source_id": row[0],
+                "target_id": row[1],
+                "relation_type": row[2],
+                "properties": json.loads(row[3]) if row[3] else {}
+            })
+            
+        return {"nodes": nodes, "edges": edges}
+
+# ---------------------------------------------------------------------------
+# Serialization
+# ---------------------------------------------------------------------------
+
+def serialize_subgraph(db_path: str, central_node_id: str) -> str:
+    """
+    Converts a node's immediate neighborhood into an LLM-readable format.
+    Maximizes attention while minimizing token bloat.
+    """
+    init_db(db_path)
+    with get_connection(db_path) as conn:
+        node = conn.execute("""
+            SELECT label, properties, status, updated_at 
+            FROM Nodes 
+            WHERE id = ? AND is_deleted = 0
+        """, (central_node_id,)).fetchone()
+        
+        if not node:
+            return f"Node '{central_node_id}' not found or deleted."
+            
+        label, props_json, status, updated_at = node
+        props = json.loads(props_json) if props_json else {}
+        
+        output = [
+            f"Entity: {central_node_id} ({label})",
+            f"Status: {status} | Last Updated: {updated_at}",
+            f"Metadata: {json.dumps(props, indent=2)}",
+            "Relationships:"
+        ]
+        
+        edges = conn.execute("""
+            SELECT relation_type, target_id, properties 
+            FROM Edges 
+            WHERE source_id = ?
+        """, (central_node_id,)).fetchall()
+        
+        if not edges:
+            output.append("  (None)")
+        else:
+            for rel_type, target, e_props in edges:
+                output.append(f"  -[{rel_type}]-> {target} (Context: {e_props})")
+                
+        # Also show incoming edges
+        incoming_edges = conn.execute("""
+            SELECT source_id, relation_type, properties 
+            FROM Edges 
+            WHERE target_id = ?
+        """, (central_node_id,)).fetchall()
+        
+        if incoming_edges:
+            output.append("Incoming Relationships:")
+            for source, rel_type, e_props in incoming_edges:
+                output.append(f"  {source} -[{rel_type}]-> (this) (Context: {e_props})")
+                
+        return "\n".join(output)

graph_memory/mcp/server.py

@@ -0,0 +1,312 @@
+import asyncio
+import json
+import os
+from typing import List, Dict, Any
+from mcp.server.models import InitializationOptions
+import mcp.types as types
+from mcp.server import NotificationOptions, Server
+from mcp.server.stdio import stdio_server
+
+from graph_memory.core import engine
+
+# Default DB Path
+DB_PATH = engine.get_db_path()
+
+# Ensure DB is initialized
+engine.init_db(DB_PATH)
+
+server = Server("graph-memory")
+
+@server.list_tools()
+async def handle_list_tools() -> list[types.Tool]:
+    """
+    Exposes the 9 standard Anthropic MCP Memory Tool signatures.
+    This makes the package a "Drop-In Replacement" for the official memory server.
+    """
+    return [
+        types.Tool(
+            name="create_entities",
+            description="Create multiple new entities in the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "entities": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "name": {"type": "string", "description": "The name/ID of the entity"},
+                                "entityType": {"type": "string", "description": "The type or label of the entity"},
+                                "observations": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": "An array of observation strings about this entity"
+                                }
+                            },
+                            "required": ["name", "entityType", "observations"]
+                        }
+                    }
+                },
+                "required": ["entities"]
+            }
+        ),
+        types.Tool(
+            name="create_relations",
+            description="Create multiple new relations between entities in the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "relations": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "from": {"type": "string", "description": "The name of the source entity"},
+                                "to": {"type": "string", "description": "The name of the target entity"},
+                                "relationType": {"type": "string", "description": "The type of relation"}
+                            },
+                            "required": ["from", "to", "relationType"]
+                        }
+                    }
+                },
+                "required": ["relations"]
+            }
+        ),
+        types.Tool(
+            name="add_observations",
+            description="Add new observations to existing entities in the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "observations": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "entityName": {"type": "string", "description": "The name of the entity"},
+                                "contents": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": "An array of observation strings to add"
+                                }
+                            },
+                            "required": ["entityName", "contents"]
+                        }
+                    }
+                },
+                "required": ["observations"]
+            }
+        ),
+        types.Tool(
+            name="delete_entities",
+            description="Delete multiple entities and their associated relations from the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "entityNames": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "An array of entity names to delete"
+                    }
+                },
+                "required": ["entityNames"]
+            }
+        ),
+        types.Tool(
+            name="delete_observations",
+            description="Delete specific observations from entities in the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "deletions": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "entityName": {"type": "string", "description": "The name of the entity"},
+                                "observations": {
+                                    "type": "array",
+                                    "items": {"type": "string"},
+                                    "description": "An array of observation strings to delete"
+                                }
+                            },
+                            "required": ["entityName", "observations"]
+                        }
+                    }
+                },
+                "required": ["deletions"]
+            }
+        ),
+        types.Tool(
+            name="delete_relations",
+            description="Delete multiple relations from the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "relations": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "properties": {
+                                "from": {"type": "string", "description": "The name of the source entity"},
+                                "to": {"type": "string", "description": "The name of the target entity"},
+                                "relationType": {"type": "string", "description": "The type of relation"}
+                            },
+                            "required": ["from", "to", "relationType"]
+                        }
+                    }
+                },
+                "required": ["relations"]
+            }
+        ),
+        types.Tool(
+            name="read_graph",
+            description="Read the entire knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {},
+            }
+        ),
+        types.Tool(
+            name="search_nodes",
+            description="Search for nodes in the knowledge graph based on a query.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "query": {"type": "string", "description": "The search query to match against entity names, types, and observation content."}
+                },
+                "required": ["query"]
+            }
+        ),
+        types.Tool(
+            name="open_nodes",
+            description="Open specific nodes in the knowledge graph.",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "names": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "An array of entity names to retrieve"
+                    }
+                },
+                "required": ["names"]
+            }
+        ),
+    ]
+
+@server.call_tool()
+async def handle_call_tool(
+    name: str, arguments: dict | None
+) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
+    """
+    Handle tool executions, mapping Anthropic's standard API to our SQLite backend.
+    """
+    if not arguments:
+        arguments = {}
+        
+    try:
+        if name == "create_entities":
+            entities = arguments.get("entities", [])
+            for ent in entities:
+                engine.get_or_create_node(
+                    DB_PATH,
+                    node_id=ent["name"],
+                    label=ent["entityType"],
+                    properties={"observations": ent.get("observations", []), "type": ent["entityType"]}
+                )
+            return [types.TextContent(type="text", text=f"Created {len(entities)} entities successfully.")]
+
+        elif name == "create_relations":
+            relations = arguments.get("relations", [])
+            for rel in relations:
+                engine.create_relation(
+                    DB_PATH,
+                    source_id=rel["from"],
+                    target_id=rel["to"],
+                    relation_type=rel["relationType"]
+                )
+            return [types.TextContent(type="text", text=f"Created {len(relations)} relations successfully.")]
+
+        elif name == "add_observations":
+            observations = arguments.get("observations", [])
+            for obs in observations:
+                for content in obs.get("contents", []):
+                    engine.add_observation(DB_PATH, obs["entityName"], content)
+            return [types.TextContent(type="text", text=f"Added observations successfully.")]
+
+        elif name == "delete_entities":
+            entityNames = arguments.get("entityNames", [])
+            for name in entityNames:
+                engine.soft_delete_entity(DB_PATH, name)
+            return [types.TextContent(type="text", text=f"Soft deleted {len(entityNames)} entities successfully.")]
+
+        elif name == "delete_observations":
+            deletions = arguments.get("deletions", [])
+            for deletion in deletions:
+                node_id = deletion["entityName"]
+                obs_to_delete = deletion.get("observations", [])
+                
+                # Fetch current properties manually to perform deletion
+                with engine.get_connection(DB_PATH) as conn:
+                    row = conn.execute("SELECT properties FROM Nodes WHERE id = ? AND is_deleted = 0", (node_id,)).fetchone()
+                    if row:
+                        props = json.loads(row[0]) if row[0] else {}
+                        current_obs = props.get("observations", [])
+                        new_obs = [o for o in current_obs if o not in obs_to_delete]
+                        props["observations"] = new_obs
+                        with engine.write_transaction(conn):
+                            conn.execute("UPDATE Nodes SET properties = ?, updated_at = ? WHERE id = ?", 
+                                         (json.dumps(props), engine.now_iso(), node_id))
+                                         
+            return [types.TextContent(type="text", text=f"Deleted observations successfully.")]
+
+        elif name == "delete_relations":
+            relations = arguments.get("relations", [])
+            for rel in relations:
+                engine.delete_relation(
+                    DB_PATH,
+                    source_id=rel["from"],
+                    target_id=rel["to"],
+                    relation_type=rel["relationType"]
+                )
+            return [types.TextContent(type="text", text=f"Deleted {len(relations)} relations successfully.")]
+
+        elif name == "read_graph":
+            graph = engine.read_graph(DB_PATH)
+            return [types.TextContent(type="text", text=json.dumps(graph, indent=2))]
+
+        elif name == "search_nodes":
+            query = arguments.get("query", "")
+            results = engine.search_nodes(DB_PATH, query)
+            return [types.TextContent(type="text", text=json.dumps(results, indent=2))]
+
+        elif name == "open_nodes":
+            names = arguments.get("names", [])
+            outputs = []
+            for name in names:
+                subgraph = engine.serialize_subgraph(DB_PATH, name)
+                outputs.append(subgraph)
+            return [types.TextContent(type="text", text="\n---\n".join(outputs))]
+
+        else:
+            raise ValueError(f"Unknown tool: {name}")
+
+    except Exception as e:
+        return [types.TextContent(type="text", text=f"Error executing {name}: {str(e)}")]
+
+async def run_mcp_server():
+    """Runs the MCP server using stdio."""
+    options = server.create_initialization_options()
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            options
+        )
+
+def main():
+    asyncio.run(run_mcp_server())
+
+if __name__ == "__main__":
+    main()