superlocalmemory 2.8.6 → 3.0.0

package/src/subscription_manager.py

@@ -1,391 +0,0 @@
-#!/usr/bin/env python3
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""
-SubscriptionManager — Manages durable and ephemeral event subscriptions.
-
-Subscribers register interest in specific event types and receive matching
-events via their chosen channel (SSE, WebSocket, Webhook).
-
-Subscription Types:
-    Durable (default)  — Persisted to DB, survives disconnect, auto-replay on reconnect
-    Ephemeral (opt-in) — In-memory only, dies on disconnect
-
-Filter Syntax:
-    {
-        "event_types": ["memory.created", "memory.deleted"],  // null = all types
-        "min_importance": 5,                                    // null = no filter
-        "source_protocols": ["mcp", "cli"],                     // null = all protocols
-        "projects": ["myapp"]                                   // null = all projects
-    }
-"""
-
-import json
-import logging
-import threading
-from datetime import datetime
-from pathlib import Path
-from typing import Optional, List, Dict, Any
-
-logger = logging.getLogger("superlocalmemory.subscriptions")
-
-
-class SubscriptionManager:
-    """
-    Manages event subscriptions for the Event Bus.
-
-    Thread-safe. Durable subscriptions persist to SQLite. Ephemeral
-    subscriptions are in-memory only.
-    """
-
-    _instances: Dict[str, "SubscriptionManager"] = {}
-    _instances_lock = threading.Lock()
-
-    @classmethod
-    def get_instance(cls, db_path: Optional[Path] = None) -> "SubscriptionManager":
-        """Get or create the singleton SubscriptionManager."""
-        if db_path is None:
-            db_path = Path.home() / ".claude-memory" / "memory.db"
-        key = str(db_path)
-        with cls._instances_lock:
-            if key not in cls._instances:
-                cls._instances[key] = cls(db_path)
-            return cls._instances[key]
-
-    @classmethod
-    def reset_instance(cls, db_path: Optional[Path] = None) -> None:
-        """Remove singleton. Used for testing."""
-        with cls._instances_lock:
-            if db_path is None:
-                cls._instances.clear()
-            else:
-                key = str(db_path)
-                if key in cls._instances:
-                    del cls._instances[key]
-
-    def __init__(self, db_path: Path):
-        self.db_path = Path(db_path)
-
-        # Ephemeral subscriptions (in-memory only)
-        self._ephemeral: Dict[str, dict] = {}
-        self._ephemeral_lock = threading.Lock()
-
-        self._init_schema()
-        logger.info("SubscriptionManager initialized: db=%s", self.db_path)
-
-    def _init_schema(self):
-        """Create subscriptions table if it doesn't exist."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _create(conn):
-                conn.execute('''
-                    CREATE TABLE IF NOT EXISTS subscriptions (
-                        id INTEGER PRIMARY KEY AUTOINCREMENT,
-                        subscriber_id TEXT NOT NULL UNIQUE,
-                        channel TEXT NOT NULL,
-                        filter TEXT NOT NULL DEFAULT '{}',
-                        webhook_url TEXT,
-                        durable INTEGER DEFAULT 1,
-                        last_event_id INTEGER DEFAULT 0,
-                        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-                    )
-                ''')
-                conn.execute('''
-                    CREATE INDEX IF NOT EXISTS idx_subs_channel
-                    ON subscriptions(channel)
-                ''')
-                conn.commit()
-
-            mgr.execute_write(_create)
-        except ImportError:
-            import sqlite3
-            conn = sqlite3.connect(str(self.db_path))
-            try:
-                conn.execute('''
-                    CREATE TABLE IF NOT EXISTS subscriptions (
-                        id INTEGER PRIMARY KEY AUTOINCREMENT,
-                        subscriber_id TEXT NOT NULL UNIQUE,
-                        channel TEXT NOT NULL,
-                        filter TEXT NOT NULL DEFAULT '{}',
-                        webhook_url TEXT,
-                        durable INTEGER DEFAULT 1,
-                        last_event_id INTEGER DEFAULT 0,
-                        created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
-                        updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
-                    )
-                ''')
-                conn.execute('CREATE INDEX IF NOT EXISTS idx_subs_channel ON subscriptions(channel)')
-                conn.commit()
-            finally:
-                conn.close()
-
-    # =========================================================================
-    # Subscribe / Unsubscribe
-    # =========================================================================
-
-    def subscribe(
-        self,
-        subscriber_id: str,
-        channel: str = "sse",
-        filter_obj: Optional[dict] = None,
-        webhook_url: Optional[str] = None,
-        durable: bool = True,
-    ) -> dict:
-        """
-        Register a subscription.
-
-        Args:
-            subscriber_id: Unique identifier for the subscriber
-            channel: Delivery channel — 'sse', 'websocket', 'webhook'
-            filter_obj: Event filter (see module docstring for syntax)
-            webhook_url: URL for webhook channel (required if channel='webhook')
-            durable: If True, persists to DB; if False, in-memory only
-
-        Returns:
-            Subscription dict with id and details
-
-        Raises:
-            ValueError: If channel is invalid or webhook_url missing for webhook channel
-        """
-        if channel not in ("sse", "websocket", "webhook"):
-            raise ValueError(f"Invalid channel: {channel}. Must be sse, websocket, or webhook")
-
-        if channel == "webhook" and not webhook_url:
-            raise ValueError("webhook_url is required for webhook channel")
-
-        # Validate webhook URL format
-        if webhook_url and not (webhook_url.startswith("http://") or webhook_url.startswith("https://")):
-            raise ValueError("webhook_url must start with http:// or https://")
-
-        filter_json = json.dumps(filter_obj or {})
-        now = datetime.now().isoformat()
-
-        sub = {
-            "subscriber_id": subscriber_id,
-            "channel": channel,
-            "filter": filter_obj or {},
-            "webhook_url": webhook_url,
-            "durable": durable,
-            "last_event_id": 0,
-            "created_at": now,
-        }
-
-        if durable:
-            self._persist_subscription(sub, filter_json)
-        else:
-            with self._ephemeral_lock:
-                self._ephemeral[subscriber_id] = sub
-
-        logger.info("Subscription created: id=%s, channel=%s, durable=%s", subscriber_id, channel, durable)
-        return sub
-
-    def _persist_subscription(self, sub: dict, filter_json: str):
-        """Save durable subscription to database."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _upsert(conn):
-                conn.execute('''
-                    INSERT INTO subscriptions (subscriber_id, channel, filter, webhook_url, durable, created_at, updated_at)
-                    VALUES (?, ?, ?, ?, 1, ?, ?)
-                    ON CONFLICT(subscriber_id) DO UPDATE SET
-                        channel = excluded.channel,
-                        filter = excluded.filter,
-                        webhook_url = excluded.webhook_url,
-                        updated_at = excluded.updated_at
-                ''', (
-                    sub["subscriber_id"],
-                    sub["channel"],
-                    filter_json,
-                    sub.get("webhook_url"),
-                    sub["created_at"],
-                    sub["created_at"],
-                ))
-                conn.commit()
-
-            mgr.execute_write(_upsert)
-        except Exception as e:
-            logger.error("Failed to persist subscription: %s", e)
-
-    def unsubscribe(self, subscriber_id: str) -> bool:
-        """
-        Remove a subscription (durable or ephemeral).
-
-        Args:
-            subscriber_id: ID of the subscription to remove
-
-        Returns:
-            True if subscription was found and removed
-        """
-        removed = False
-
-        # Remove ephemeral
-        with self._ephemeral_lock:
-            if subscriber_id in self._ephemeral:
-                del self._ephemeral[subscriber_id]
-                removed = True
-
-        # Remove durable
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _delete(conn):
-                conn.execute("DELETE FROM subscriptions WHERE subscriber_id = ?", (subscriber_id,))
-                conn.commit()
-                return conn.total_changes > 0
-
-            if mgr.execute_write(_delete):
-                removed = True
-        except Exception as e:
-            logger.error("Failed to delete subscription: %s", e)
-
-        return removed
-
-    def update_last_event_id(self, subscriber_id: str, event_id: int) -> None:
-        """Update the last event ID received by a durable subscriber (for replay)."""
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            def _update(conn):
-                conn.execute(
-                    "UPDATE subscriptions SET last_event_id = ?, updated_at = ? WHERE subscriber_id = ?",
-                    (event_id, datetime.now().isoformat(), subscriber_id)
-                )
-                conn.commit()
-
-            mgr.execute_write(_update)
-        except Exception as e:
-            logger.error("Failed to update last_event_id: %s", e)
-
-    # =========================================================================
-    # Query Subscriptions
-    # =========================================================================
-
-    def get_matching_subscribers(self, event: dict) -> List[dict]:
-        """
-        Get all subscriptions that match a given event.
-
-        Applies filter logic: event_types, min_importance, source_protocols.
-
-        Args:
-            event: Event dict with event_type, importance, source_protocol, etc.
-
-        Returns:
-            List of matching subscription dicts
-        """
-        all_subs = self.list_subscriptions()
-        matching = []
-
-        for sub in all_subs:
-            if self._matches_filter(sub.get("filter", {}), event):
-                matching.append(sub)
-
-        return matching
-
-    def _matches_filter(self, filter_obj: dict, event: dict) -> bool:
-        """Check if an event matches a subscription filter."""
-        if not filter_obj:
-            return True  # No filter = match all
-
-        # Event type filter
-        allowed_types = filter_obj.get("event_types")
-        if allowed_types and event.get("event_type") not in allowed_types:
-            return False
-
-        # Importance filter
-        min_importance = filter_obj.get("min_importance")
-        if min_importance and (event.get("importance", 0) < min_importance):
-            return False
-
-        # Protocol filter
-        allowed_protocols = filter_obj.get("source_protocols")
-        if allowed_protocols and event.get("source_protocol") not in allowed_protocols:
-            return False
-
-        return True
-
-    def list_subscriptions(self) -> List[dict]:
-        """Get all active subscriptions (durable + ephemeral)."""
-        subs = []
-
-        # Ephemeral
-        with self._ephemeral_lock:
-            subs.extend(list(self._ephemeral.values()))
-
-        # Durable (from DB)
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            with mgr.read_connection() as conn:
-                cursor = conn.cursor()
-                cursor.execute("""
-                    SELECT subscriber_id, channel, filter, webhook_url, durable,
-                           last_event_id, created_at, updated_at
-                    FROM subscriptions
-                """)
-                for row in cursor.fetchall():
-                    filter_obj = {}
-                    try:
-                        filter_obj = json.loads(row[2]) if row[2] else {}
-                    except (json.JSONDecodeError, TypeError):
-                        pass
-
-                    subs.append({
-                        "subscriber_id": row[0],
-                        "channel": row[1],
-                        "filter": filter_obj,
-                        "webhook_url": row[3],
-                        "durable": bool(row[4]),
-                        "last_event_id": row[5],
-                        "created_at": row[6],
-                        "updated_at": row[7],
-                    })
-        except Exception as e:
-            logger.error("Failed to list durable subscriptions: %s", e)
-
-        return subs
-
-    def get_subscription(self, subscriber_id: str) -> Optional[dict]:
-        """Get a specific subscription by ID."""
-        # Check ephemeral first
-        with self._ephemeral_lock:
-            if subscriber_id in self._ephemeral:
-                return self._ephemeral[subscriber_id]
-
-        # Check durable
-        try:
-            from db_connection_manager import DbConnectionManager
-            mgr = DbConnectionManager.get_instance(self.db_path)
-
-            with mgr.read_connection() as conn:
-                cursor = conn.cursor()
-                cursor.execute(
-                    "SELECT subscriber_id, channel, filter, webhook_url, durable, last_event_id FROM subscriptions WHERE subscriber_id = ?",
-                    (subscriber_id,)
-                )
-                row = cursor.fetchone()
-                if row:
-                    filter_obj = {}
-                    try:
-                        filter_obj = json.loads(row[2]) if row[2] else {}
-                    except (json.JSONDecodeError, TypeError):
-                        pass
-                    return {
-                        "subscriber_id": row[0],
-                        "channel": row[1],
-                        "filter": filter_obj,
-                        "webhook_url": row[3],
-                        "durable": bool(row[4]),
-                        "last_event_id": row[5],
-                    }
-        except Exception as e:
-            logger.error("Failed to get subscription: %s", e)
-
-        return None

package/src/tree/__init__.py

@@ -1,59 +0,0 @@
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Tree — Hierarchical Memory Tree Management.
-
-Composes the TreeManager class from focused mixin modules:
-  - schema.py  : DB initialization and root-node bootstrap
-  - nodes.py   : Node CRUD and count aggregation
-  - queries.py : Read-only tree traversal and statistics
-  - builder.py : Full tree construction from memories table
-"""
-from pathlib import Path
-from typing import Optional
-
-from .schema import TreeSchemaMixin, MEMORY_DIR, DB_PATH
-from .nodes import TreeNodesMixin
-from .queries import TreeQueriesMixin
-from .builder import TreeBuilderMixin
-
-
-class TreeManager(TreeSchemaMixin, TreeNodesMixin, TreeQueriesMixin, TreeBuilderMixin):
-    """
-    Manages hierarchical tree structure for memory navigation.
-
-    Tree Structure:
-        Root
-        +-- Project: NextJS-App
-        |   +-- Category: Frontend
-        |   |   +-- Memory: React Components
-        |   |   +-- Memory: State Management
-        |   +-- Category: Backend
-        |       +-- Memory: API Routes
-        +-- Project: Python-ML
-
-    Materialized Path Format:
-        - Root: "1"
-        - Project: "1.2"
-        - Category: "1.2.3"
-        - Memory: "1.2.3.4"
-
-    Benefits:
-        - Fast subtree queries: WHERE tree_path LIKE '1.2.%'
-        - O(1) depth calculation: count dots in path
-        - O(1) parent lookup: parse path
-        - No recursive CTEs needed
-    """
-
-    def __init__(self, db_path: Optional[Path] = None):
-        """
-        Initialize TreeManager.
-
-        Args:
-            db_path: Optional custom database path
-        """
-        self.db_path = db_path or DB_PATH
-        self._init_db()
-        self.root_id = self._ensure_root()
-
-
-__all__ = ['TreeManager', 'MEMORY_DIR', 'DB_PATH']

package/src/tree/builder.py

@@ -1,185 +0,0 @@
-# SPDX-License-Identifier: MIT
-# Copyright (c) 2026 SuperLocalMemory (superlocalmemory.com)
-"""Tree Builder — Constructs the full tree from the memories table.
-
-Provides TreeBuilderMixin with build_tree, plus the CLI entry point.
-"""
-import sqlite3
-
-
-class TreeBuilderMixin:
-    """Builds the hierarchical tree from flat memory records."""
-
-    def build_tree(self):
-        """
-        Build complete tree structure from memories table.
-
-        Process:
-        1. Clear existing tree (except root)
-        2. Group memories by project
-        3. Group by category within projects
-        4. Link individual memories as leaf nodes
-        5. Update aggregated counts
-        """
-        conn = sqlite3.connect(self.db_path)
-        try:
-            cursor = conn.cursor()
-
-            # Clear existing tree (keep root)
-            cursor.execute('DELETE FROM memory_tree WHERE node_type != ?', ('root',))
-
-            # Step 1: Create project nodes
-            cursor.execute('''
-                SELECT DISTINCT project_path, project_name
-                FROM memories
-                WHERE project_path IS NOT NULL
-                ORDER BY project_path
-            ''')
-            projects = cursor.fetchall()
-
-            project_map = {}  # project_path -> node_id
-
-            for project_path, project_name in projects:
-                name = project_name or project_path.split('/')[-1]
-                node_id = self.add_node('project', name, self.root_id, description=project_path)
-                project_map[project_path] = node_id
-
-            # Step 2: Create category nodes within projects
-            cursor.execute('''
-                SELECT DISTINCT project_path, category
-                FROM memories
-                WHERE project_path IS NOT NULL AND category IS NOT NULL
-                ORDER BY project_path, category
-            ''')
-            categories = cursor.fetchall()
-
-            category_map = {}  # (project_path, category) -> node_id
-
-            for project_path, category in categories:
-                parent_id = project_map.get(project_path)
-                if parent_id:
-                    node_id = self.add_node('category', category, parent_id)
-                    category_map[(project_path, category)] = node_id
-
-            # Step 3: Link memories as leaf nodes
-            cursor.execute('''
-                SELECT id, content, summary, project_path, category, importance, created_at
-                FROM memories
-                ORDER BY created_at DESC
-            ''')
-            memories = cursor.fetchall()
-
-            for mem_id, content, summary, project_path, category, importance, created_at in memories:
-                # Determine parent node
-                if project_path and category and (project_path, category) in category_map:
-                    parent_id = category_map[(project_path, category)]
-                elif project_path and project_path in project_map:
-                    parent_id = project_map[project_path]
-                else:
-                    parent_id = self.root_id
-
-                # Create memory node
-                name = summary or content[:60].replace('\n', ' ')
-                self.add_node('memory', name, parent_id, memory_id=mem_id, description=content[:200])
-
-            # Step 4: Update aggregated counts
-            self._update_all_counts()
-
-            conn.commit()
-        finally:
-            conn.close()
-
-
-def run_cli():
-    """CLI entry point for tree_manager."""
-    import sys
-    import json
-    from src.tree import TreeManager
-
-    tree_mgr = TreeManager()
-
-    if len(sys.argv) < 2:
-        print("TreeManager CLI")
-        print("\nCommands:")
-        print("  python tree_manager.py build                  # Build tree from memories")
-        print("  python tree_manager.py show [project] [depth] # Show tree structure")
-        print("  python tree_manager.py subtree <node_id>      # Get subtree")
-        print("  python tree_manager.py path <node_id>         # Get path to root")
-        print("  python tree_manager.py stats                  # Show statistics")
-        print("  python tree_manager.py add <type> <name> <parent_id>  # Add node")
-        print("  python tree_manager.py delete <node_id>       # Delete node")
-        sys.exit(0)
-
-    command = sys.argv[1]
-
-    if command == "build":
-        print("Building tree from memories...")
-        tree_mgr.build_tree()
-        stats = tree_mgr.get_stats()
-        print(f"Tree built: {stats['total_nodes']} nodes, {stats['total_memories']} memories")
-
-    elif command == "show":
-        project = sys.argv[2] if len(sys.argv) > 2 else None
-        max_depth = int(sys.argv[3]) if len(sys.argv) > 3 else None
-
-        tree = tree_mgr.get_tree(project, max_depth)
-
-        def print_tree(node, indent=0):
-            if 'error' in node:
-                print(node['error'])
-                return
-
-            prefix = "  " * indent
-            icon = {"root": "\U0001f333", "project": "\U0001f4c1", "category": "\U0001f4c2", "memory": "\U0001f4c4"}.get(node['type'], "\u2022")
-
-            print(f"{prefix}{icon} {node['name']} (id={node['id']}, memories={node['memory_count']})")
-
-            for child in node.get('children', []):
-                print_tree(child, indent + 1)
-
-        print_tree(tree)
-
-    elif command == "subtree" and len(sys.argv) >= 3:
-        node_id = int(sys.argv[2])
-        nodes = tree_mgr.get_subtree(node_id)
-
-        if not nodes:
-            print(f"No subtree found for node {node_id}")
-        else:
-            print(f"Subtree of node {node_id}:")
-            for node in nodes:
-                indent = "  " * (node['depth'] - nodes[0]['depth'] + 1)
-                print(f"{indent}- {node['name']} (id={node['id']})")
-
-    elif command == "path" and len(sys.argv) >= 3:
-        node_id = int(sys.argv[2])
-        path = tree_mgr.get_path_to_root(node_id)
-
-        if not path:
-            print(f"Node {node_id} not found")
-        else:
-            print("Path to root:")
-            print(" > ".join([f"{n['name']} (id={n['id']})" for n in path]))
-
-    elif command == "stats":
-        stats = tree_mgr.get_stats()
-        print(json.dumps(stats, indent=2))
-
-    elif command == "add" and len(sys.argv) >= 5:
-        node_type = sys.argv[2]
-        name = sys.argv[3]
-        parent_id = int(sys.argv[4])
-
-        node_id = tree_mgr.add_node(node_type, name, parent_id)
-        print(f"Node created with ID: {node_id}")
-
-    elif command == "delete" and len(sys.argv) >= 3:
-        node_id = int(sys.argv[2])
-        if tree_mgr.delete_node(node_id):
-            print(f"Node {node_id} deleted")
-        else:
-            print(f"Node {node_id} not found")
-
-    else:
-        print(f"Unknown command: {command}")
-        sys.exit(1)