memorygraphMCP 0.11.7__py3-none-any.whl

memorygraph/cloud_database.py

@@ -0,0 +1,297 @@
+"""
+Cloud-specific database implementation for MemoryGraph.
+
+This module provides a CloudMemoryDatabase class that wraps the CloudBackend
+to provide the same interface as MemoryDatabase for tool handlers.
+"""
+
+import logging
+import uuid
+from typing import Dict, List, Optional, Any, Tuple
+from datetime import datetime, timezone
+
+from .models import (
+    Memory, MemoryType, Relationship, RelationshipType,
+    RelationshipProperties, SearchQuery, MemoryContext,
+    MemoryError, MemoryNotFoundError, RelationshipError,
+    ValidationError, DatabaseConnectionError, SchemaError, PaginatedResult
+)
+from .backends.cloud_backend import CloudBackend
+
+logger = logging.getLogger(__name__)
+
+
+class CloudMemoryDatabase:
+    """Cloud-specific implementation of memory database operations.
+
+    This class wraps CloudBackend to provide the same interface expected by
+    the MCP tool handlers, delegating to the CloudBackend's REST API methods.
+    """
+
+    def __init__(self, backend: CloudBackend) -> None:
+        """
+        Initialize with a Cloud backend connection.
+
+        Args:
+            backend: CloudBackend instance
+        """
+        self.backend = backend
+
+    async def close(self) -> None:
+        """Close the backend connection."""
+        if self.backend:
+            await self.backend.disconnect()
+
+    async def initialize_schema(self) -> None:
+        """
+        Initialize schema (no-op for cloud backend).
+
+        Schema is managed by the cloud service.
+        """
+        logger.info("Schema initialization skipped - managed by cloud service")
+        await self.backend.initialize_schema()
+
+    async def store_memory(self, memory: Memory) -> str:
+        """
+        Store a memory in the cloud and return its ID.
+
+        Args:
+            memory: Memory object to store
+
+        Returns:
+            ID of the stored memory
+
+        Raises:
+            DatabaseConnectionError: If storage fails
+        """
+        if not memory.id:
+            memory.id = str(uuid.uuid4())
+
+        return await self.backend.store_memory(memory)
+
+    async def get_memory(self, memory_id: str, include_relationships: bool = True) -> Optional[Memory]:
+        """
+        Retrieve a memory by ID.
+
+        Args:
+            memory_id: ID of the memory to retrieve
+            include_relationships: Whether to include relationships (not currently used by cloud backend)
+
+        Returns:
+            Memory object if found, None otherwise
+
+        Raises:
+            DatabaseConnectionError: If query fails
+        """
+        return await self.backend.get_memory(memory_id)
+
+    async def search_memories(self, search_query: SearchQuery) -> List[Memory]:
+        """
+        Search for memories based on query parameters.
+
+        Args:
+            search_query: SearchQuery object with filter criteria
+
+        Returns:
+            List of Memory objects matching the search criteria
+
+        Raises:
+            DatabaseConnectionError: If search fails
+        """
+        return await self.backend.search_memories(search_query)
+
+    async def search_memories_paginated(self, search_query: SearchQuery) -> PaginatedResult:
+        """
+        Search for memories with pagination support.
+
+        Note: Cloud API does not return total count, so total_count is set to -1
+        to indicate unknown. Use has_more to determine if more pages exist.
+
+        Args:
+            search_query: SearchQuery object with filter criteria, limit, and offset
+
+        Returns:
+            PaginatedResult with memories and pagination metadata.
+            total_count is -1 (unknown) since cloud API doesn't provide it.
+
+        Raises:
+            DatabaseConnectionError: If search fails
+        """
+        # CloudBackend's search_memories already handles pagination via limit/offset
+        memories = await self.backend.search_memories(search_query)
+
+        # Cloud API doesn't return total count - use -1 to indicate unknown
+        # has_more is determined by whether we got a full page of results
+        has_more = len(memories) == search_query.limit
+        next_offset = (search_query.offset + search_query.limit) if has_more else None
+
+        return PaginatedResult(
+            results=memories,
+            total_count=-1,  # Unknown - cloud API doesn't provide total count
+            limit=search_query.limit,
+            offset=search_query.offset,
+            has_more=has_more,
+            next_offset=next_offset
+        )
+
+    async def update_memory(self, memory: Memory) -> bool:
+        """
+        Update an existing memory.
+
+        Args:
+            memory: Memory object with updated fields
+
+        Returns:
+            True if update succeeded, False if memory not found
+
+        Raises:
+            ValidationError: If memory ID is missing
+            DatabaseConnectionError: If update fails due to connection issues
+        """
+        if not memory.id:
+            raise ValidationError("Memory must have an ID to update")
+
+        # Convert memory to update dict
+        updates = {
+            "title": memory.title,
+            "content": memory.content,
+            "summary": memory.summary,
+            "tags": memory.tags,
+            "importance": memory.importance,
+        }
+
+        # Remove None values
+        updates = {k: v for k, v in updates.items() if v is not None}
+
+        try:
+            result = await self.backend.update_memory(memory.id, updates)
+            return result is not None
+        except MemoryNotFoundError:
+            # Memory doesn't exist - return False as per interface contract
+            return False
+
+    async def delete_memory(self, memory_id: str) -> bool:
+        """
+        Delete a memory and all its relationships.
+
+        Args:
+            memory_id: ID of the memory to delete
+
+        Returns:
+            True if deletion succeeded, False otherwise
+
+        Raises:
+            DatabaseConnectionError: If deletion fails
+        """
+        return await self.backend.delete_memory(memory_id)
+
+    async def create_relationship(
+        self,
+        from_memory_id: str,
+        to_memory_id: str,
+        relationship_type: RelationshipType,
+        properties: RelationshipProperties = None
+    ) -> str:
+        """
+        Create a relationship between two memories.
+
+        Args:
+            from_memory_id: Source memory ID
+            to_memory_id: Target memory ID
+            relationship_type: Type of relationship
+            properties: Relationship properties (optional)
+
+        Returns:
+            ID of the created relationship
+
+        Raises:
+            RelationshipError: If relationship creation fails
+            DatabaseConnectionError: If database operation fails
+        """
+        return await self.backend.create_relationship(
+            from_memory_id=from_memory_id,
+            to_memory_id=to_memory_id,
+            relationship_type=relationship_type,
+            properties=properties
+        )
+
+    async def get_related_memories(
+        self,
+        memory_id: str,
+        relationship_types: List[RelationshipType] = None,
+        max_depth: int = 2
+    ) -> List[Tuple[Memory, Relationship]]:
+        """
+        Get memories related to a specific memory.
+
+        Args:
+            memory_id: ID of the memory to find relations for
+            relationship_types: Filter by specific relationship types (optional)
+            max_depth: Maximum depth for graph traversal
+
+        Returns:
+            List of tuples containing (Memory, Relationship)
+
+        Raises:
+            DatabaseConnectionError: If query fails
+        """
+        return await self.backend.get_related_memories(
+            memory_id=memory_id,
+            relationship_types=relationship_types,
+            max_depth=max_depth
+        )
+
+    async def update_relationship_properties(
+        self,
+        from_memory_id: str,
+        to_memory_id: str,
+        relationship_type: RelationshipType,
+        properties: RelationshipProperties
+    ) -> bool:
+        """
+        Update properties of an existing relationship.
+
+        Note: Cloud backend does not yet support updating relationship properties.
+
+        Args:
+            from_memory_id: Source memory ID
+            to_memory_id: Target memory ID
+            relationship_type: Type of relationship to update
+            properties: Updated relationship properties
+
+        Raises:
+            NotImplementedError: Cloud backend does not support this operation
+        """
+        raise NotImplementedError(
+            "Cloud backend does not yet support updating relationship properties. "
+            f"Attempted to update: {from_memory_id} -{relationship_type.value}-> {to_memory_id}"
+        )
+
+    async def get_memory_statistics(self) -> Dict[str, Any]:
+        """
+        Get database statistics and metrics.
+
+        Returns:
+            Dictionary containing various database statistics
+
+        Raises:
+            DatabaseConnectionError: If query fails
+        """
+        return await self.backend.get_statistics()
+
+    async def get_recent_activity(
+        self,
+        days: int = 7,
+        project: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Get recent memory activity summary.
+
+        Args:
+            days: Number of days to look back
+            project: Optional project filter
+
+        Returns:
+            Activity summary dictionary
+        """
+        return await self.backend.get_recent_activity(days=days, project=project)

memorygraph/config.py

@@ -0,0 +1,295 @@
+"""
+Configuration management for MemoryGraph.
+
+This module centralizes all configuration options and environment variable handling
+for the multi-backend memory server.
+"""
+
+import os
+from enum import Enum
+from typing import Optional, List
+
+
+class BackendType(Enum):
+    """Supported backend types."""
+    NEO4J = "neo4j"
+    MEMGRAPH = "memgraph"
+    SQLITE = "sqlite"
+    TURSO = "turso"
+    CLOUD = "cloud"
+    FALKORDB = "falkordb"
+    FALKORDBLITE = "falkordblite"
+    AUTO = "auto"
+
+
+# Tool profile definitions
+# Core mode: Essential tools for daily use (9 tools)
+# Extended mode: Core + advanced analytics (11 tools)
+TOOL_PROFILES = {
+    "core": [
+        # Essential memory operations (5 tools)
+        "store_memory",
+        "get_memory",
+        "search_memories",
+        "update_memory",
+        "delete_memory",
+        # Essential relationship operations (2 tools)
+        "create_relationship",
+        "get_related_memories",
+        # Discovery and navigation (2 tools)
+        "recall_memories",  # Primary search with fuzzy matching
+        "get_recent_activity",  # Session briefing
+    ],
+    "extended": [
+        # All Core tools (9)
+        "store_memory",
+        "get_memory",
+        "search_memories",
+        "update_memory",
+        "delete_memory",
+        "create_relationship",
+        "get_related_memories",
+        "recall_memories",
+        "get_recent_activity",
+        # Advanced analytics (2 additional)
+        "get_memory_statistics",  # Database stats
+        "search_relationships_by_context",  # Complex relationship queries
+        # Contextual search (1 additional)
+        "contextual_search",  # Scoped search within related memories
+    ],
+}
+
+
+class Config:
+    """
+    Configuration class for the memory server.
+
+    Environment Variables:
+        MEMORY_BACKEND: Backend type (neo4j|memgraph|sqlite|turso|cloud|falkordb|falkordblite|auto) [default: sqlite]
+
+        Neo4j Configuration:
+            MEMORY_NEO4J_URI or NEO4J_URI: Connection URI [default: bolt://localhost:7687]
+            MEMORY_NEO4J_USER or NEO4J_USER: Username [default: neo4j]
+            MEMORY_NEO4J_PASSWORD or NEO4J_PASSWORD: Password [required for Neo4j]
+
+        Memgraph Configuration:
+            MEMORY_MEMGRAPH_URI: Connection URI [default: bolt://localhost:7687]
+            MEMORY_MEMGRAPH_USER: Username [default: ""]
+            MEMORY_MEMGRAPH_PASSWORD: Password [default: ""]
+
+        SQLite Configuration:
+            MEMORY_SQLITE_PATH: Database file path [default: ~/.memorygraph/memory.db]
+
+        Turso Configuration:
+            MEMORY_TURSO_PATH: Local database file path [default: ~/.memorygraph/memory.db]
+            TURSO_DATABASE_URL: Turso database URL (e.g., libsql://your-db.turso.io)
+            TURSO_AUTH_TOKEN: Turso authentication token
+
+        Cloud Configuration:
+            MEMORYGRAPH_API_KEY: API key for MemoryGraph Cloud (required for cloud backend)
+            MEMORYGRAPH_API_URL: Cloud API base URL [default: https://graph-api.memorygraph.dev]
+            MEMORYGRAPH_TIMEOUT: Request timeout in seconds [default: 30]
+
+        Tool Profile Configuration:
+            MEMORY_TOOL_PROFILE: Tool profile (core|extended) [default: core]
+
+        Logging Configuration:
+            MEMORY_LOG_LEVEL: Log level (DEBUG|INFO|WARNING|ERROR) [default: INFO]
+
+        Multi-Tenancy Configuration (Phase 1):
+            MEMORY_MULTI_TENANT_MODE: Enable multi-tenant features [default: false]
+            MEMORY_DEFAULT_TENANT: Default tenant ID for single-tenant mode [default: default]
+            MEMORY_REQUIRE_AUTH: Require authentication for operations [default: false]
+
+        Authentication Configuration (Future - Phase 3):
+            MEMORY_AUTH_PROVIDER: Authentication provider (none|jwt|oauth2) [default: none]
+            MEMORY_JWT_SECRET: JWT signing secret (required if auth_provider=jwt)
+            MEMORY_JWT_ALGORITHM: JWT algorithm [default: HS256]
+
+        Audit Configuration (Future - Phase 4):
+            MEMORY_ENABLE_AUDIT_LOG: Log all access events [default: false]
+    """
+
+    # Backend Selection
+    BACKEND: str = os.getenv("MEMORY_BACKEND", "sqlite")
+
+    # Neo4j Configuration
+    NEO4J_URI: str = os.getenv("MEMORY_NEO4J_URI") or os.getenv("NEO4J_URI", "bolt://localhost:7687")
+    NEO4J_USER: str = os.getenv("MEMORY_NEO4J_USER") or os.getenv("NEO4J_USER", "neo4j")
+    NEO4J_PASSWORD: Optional[str] = os.getenv("MEMORY_NEO4J_PASSWORD") or os.getenv("NEO4J_PASSWORD")
+    NEO4J_DATABASE: str = os.getenv("MEMORY_NEO4J_DATABASE", "neo4j")
+
+    # Memgraph Configuration
+    MEMGRAPH_URI: str = os.getenv("MEMORY_MEMGRAPH_URI", "bolt://localhost:7687")
+    MEMGRAPH_USER: str = os.getenv("MEMORY_MEMGRAPH_USER", "")
+    MEMGRAPH_PASSWORD: str = os.getenv("MEMORY_MEMGRAPH_PASSWORD", "")
+
+    # SQLite Configuration
+    SQLITE_PATH: str = os.getenv("MEMORY_SQLITE_PATH", os.path.expanduser("~/.memorygraph/memory.db"))
+
+    # Turso Configuration
+    TURSO_PATH: str = os.getenv("MEMORY_TURSO_PATH", os.path.expanduser("~/.memorygraph/memory.db"))
+    TURSO_DATABASE_URL: Optional[str] = os.getenv("TURSO_DATABASE_URL")
+    TURSO_AUTH_TOKEN: Optional[str] = os.getenv("TURSO_AUTH_TOKEN")
+
+    # Cloud Configuration
+    MEMORYGRAPH_API_KEY: Optional[str] = os.getenv("MEMORYGRAPH_API_KEY")
+    MEMORYGRAPH_API_URL: str = os.getenv("MEMORYGRAPH_API_URL", "https://graph-api.memorygraph.dev")
+    MEMORYGRAPH_TIMEOUT: int = int(os.getenv("MEMORYGRAPH_TIMEOUT", "30"))
+
+    # Tool Profile Configuration
+    TOOL_PROFILE: str = os.getenv("MEMORY_TOOL_PROFILE", "core")
+
+    # Logging Configuration
+    LOG_LEVEL: str = os.getenv("MEMORY_LOG_LEVEL", "INFO")
+
+    # Feature Flags
+    AUTO_EXTRACT_ENTITIES: bool = os.getenv("MEMORY_AUTO_EXTRACT_ENTITIES", "true").lower() == "true"
+    SESSION_BRIEFING: bool = os.getenv("MEMORY_SESSION_BRIEFING", "true").lower() == "true"
+    BRIEFING_VERBOSITY: str = os.getenv("MEMORY_BRIEFING_VERBOSITY", "standard")
+    BRIEFING_RECENCY_DAYS: int = int(os.getenv("MEMORY_BRIEFING_RECENCY_DAYS", "7"))
+
+    # Relationship Configuration
+    ALLOW_RELATIONSHIP_CYCLES: bool = os.getenv("MEMORY_ALLOW_CYCLES", "false").lower() == "true"
+
+    # Multi-Tenancy Configuration (Phase 1)
+    MULTI_TENANT_MODE: bool = os.getenv("MEMORY_MULTI_TENANT_MODE", "false").lower() == "true"
+    DEFAULT_TENANT: str = os.getenv("MEMORY_DEFAULT_TENANT", "default")
+    REQUIRE_AUTH: bool = os.getenv("MEMORY_REQUIRE_AUTH", "false").lower() == "true"
+
+    # Authentication Configuration (Future Phase 3)
+    AUTH_PROVIDER: str = os.getenv("MEMORY_AUTH_PROVIDER", "none")
+    JWT_SECRET: Optional[str] = os.getenv("MEMORY_JWT_SECRET")
+    JWT_ALGORITHM: str = os.getenv("MEMORY_JWT_ALGORITHM", "HS256")
+
+    # Audit Configuration (Future Phase 4)
+    ENABLE_AUDIT_LOG: bool = os.getenv("MEMORY_ENABLE_AUDIT_LOG", "false").lower() == "true"
+
+    @classmethod
+    def get_backend_type(cls) -> BackendType:
+        """
+        Get the configured backend type.
+
+        Returns:
+            BackendType enum value
+        """
+        backend_str = cls.BACKEND.lower()
+        try:
+            return BackendType(backend_str)
+        except ValueError:
+            return BackendType.AUTO
+
+    @classmethod
+    def is_neo4j_configured(cls) -> bool:
+        """Check if Neo4j backend is properly configured."""
+        return bool(cls.NEO4J_PASSWORD)
+
+    @classmethod
+    def is_memgraph_configured(cls) -> bool:
+        """Check if Memgraph backend is configured."""
+        return bool(cls.MEMGRAPH_URI)
+
+    @classmethod
+    def is_multi_tenant_mode(cls) -> bool:
+        """
+        Check if multi-tenant mode is enabled.
+
+        Returns:
+            True if MEMORY_MULTI_TENANT_MODE=true, False otherwise
+        """
+        return cls.MULTI_TENANT_MODE
+
+    @classmethod
+    def get_default_tenant(cls) -> str:
+        """
+        Get default tenant ID for single-tenant mode.
+
+        Returns:
+            The default tenant identifier
+        """
+        return cls.DEFAULT_TENANT
+
+    @classmethod
+    def get_enabled_tools(cls) -> Optional[List[str]]:
+        """
+        Get the list of enabled tools based on the configured profile.
+
+        Returns:
+            List of tool names to enable, or None for legacy profiles (defaults to core)
+        """
+        profile = cls.TOOL_PROFILE.lower()
+        # Map legacy profiles to new ones
+        legacy_map = {
+            "lite": "core",
+            "standard": "extended",
+            "full": "extended"
+        }
+        profile = legacy_map.get(profile, profile)
+        return TOOL_PROFILES.get(profile, TOOL_PROFILES["core"])
+
+    @classmethod
+    def get_config_summary(cls) -> dict:
+        """
+        Get a summary of current configuration (without sensitive data).
+
+        Returns:
+            Dictionary with configuration summary
+        """
+        return {
+            "backend": cls.BACKEND,
+            "neo4j": {
+                "uri": cls.NEO4J_URI,
+                "user": cls.NEO4J_USER,
+                "password_configured": bool(cls.NEO4J_PASSWORD),
+                "database": cls.NEO4J_DATABASE
+            },
+            "memgraph": {
+                "uri": cls.MEMGRAPH_URI,
+                "user": cls.MEMGRAPH_USER,
+                "password_configured": bool(cls.MEMGRAPH_PASSWORD)
+            },
+            "sqlite": {
+                "path": cls.SQLITE_PATH
+            },
+            "turso": {
+                "path": cls.TURSO_PATH,
+                "database_url": cls.TURSO_DATABASE_URL,
+                "auth_token_configured": bool(cls.TURSO_AUTH_TOKEN)
+            },
+            "cloud": {
+                "api_url": cls.MEMORYGRAPH_API_URL,
+                "api_key_configured": bool(cls.MEMORYGRAPH_API_KEY),
+                "timeout": cls.MEMORYGRAPH_TIMEOUT
+            },
+            "logging": {
+                "level": cls.LOG_LEVEL
+            },
+            "features": {
+                "auto_extract_entities": cls.AUTO_EXTRACT_ENTITIES,
+                "session_briefing": cls.SESSION_BRIEFING,
+                "briefing_verbosity": cls.BRIEFING_VERBOSITY,
+                "briefing_recency_days": cls.BRIEFING_RECENCY_DAYS
+            },
+            "relationships": {
+                "allow_cycles": cls.ALLOW_RELATIONSHIP_CYCLES
+            },
+            "multi_tenancy": {
+                "enabled": cls.MULTI_TENANT_MODE,
+                "default_tenant": cls.DEFAULT_TENANT,
+                "require_auth": cls.REQUIRE_AUTH,
+                "auth_provider": cls.AUTH_PROVIDER,
+                "jwt_secret_configured": bool(cls.JWT_SECRET),
+                "audit_log_enabled": cls.ENABLE_AUDIT_LOG
+            }
+        }
+
+
+# Convenience function for getting config
+def get_config() -> Config:
+    """
+    Get the global configuration instance.
+
+    Returns:
+        Config instance
+    """
+    return Config