spatial-memory-mcp 1.9.1__py3-none-any.whl

spatial_memory/__init__.py

@@ -0,0 +1,97 @@
+"""Spatial Memory MCP Server - Vector-based semantic memory for LLMs."""
+
+__version__ = "1.9.1"
+__author__ = "arman-tech"
+
+# Re-export core components for convenience
+# Adapters
+from spatial_memory.adapters.lancedb_repository import LanceDBMemoryRepository
+from spatial_memory.config import Settings, get_settings
+from spatial_memory.core import (
+    ClusterInfo,
+    ClusteringError,
+    ConfigurationError,
+    # Core services
+    Database,
+    EmbeddingError,
+    EmbeddingService,
+    Filter,
+    FilterGroup,
+    FilterOperator,
+    JourneyStep,
+    # Models
+    Memory,
+    MemoryNotFoundError,
+    MemoryResult,
+    MemorySource,
+    NamespaceNotFoundError,
+    # Errors
+    SpatialMemoryError,
+    StorageError,
+    ValidationError,
+    VisualizationCluster,
+    VisualizationData,
+    VisualizationEdge,
+    VisualizationError,
+    VisualizationNode,
+)
+
+# Server
+from spatial_memory.server import SpatialMemoryServer, create_server
+
+# Services
+from spatial_memory.services.memory import (
+    ForgetResult,
+    MemoryService,
+    NearbyResult,
+    RecallResult,
+    RememberBatchResult,
+    RememberResult,
+)
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    # Configuration
+    "Settings",
+    "get_settings",
+    # Errors
+    "SpatialMemoryError",
+    "MemoryNotFoundError",
+    "NamespaceNotFoundError",
+    "EmbeddingError",
+    "StorageError",
+    "ValidationError",
+    "ConfigurationError",
+    "ClusteringError",
+    "VisualizationError",
+    # Models
+    "Memory",
+    "MemorySource",
+    "MemoryResult",
+    "ClusterInfo",
+    "JourneyStep",
+    "VisualizationNode",
+    "VisualizationEdge",
+    "VisualizationCluster",
+    "VisualizationData",
+    "Filter",
+    "FilterOperator",
+    "FilterGroup",
+    # Core services
+    "Database",
+    "EmbeddingService",
+    # Services
+    "MemoryService",
+    "RememberResult",
+    "RememberBatchResult",
+    "RecallResult",
+    "NearbyResult",
+    "ForgetResult",
+    # Adapters
+    "LanceDBMemoryRepository",
+    # Server
+    "SpatialMemoryServer",
+    "create_server",
+]

spatial_memory/__main__.py

@@ -0,0 +1,271 @@
+"""Entry point for running the Spatial Memory MCP Server and CLI commands."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import sys
+from typing import NoReturn
+
+logger = logging.getLogger(__name__)
+
+
+def run_server() -> None:
+    """Run the Spatial Memory MCP Server."""
+    from spatial_memory.server import main as server_main
+
+    asyncio.run(server_main())
+
+
+def run_migrate(args: argparse.Namespace) -> int:
+    """Run database migrations.
+
+    Args:
+        args: Parsed command line arguments.
+
+    Returns:
+        Exit code (0 for success, 1 for error).
+    """
+    from spatial_memory.config import get_settings
+    from spatial_memory.core.database import Database
+    from spatial_memory.core.db_migrations import (
+        CURRENT_SCHEMA_VERSION,
+        MigrationManager,
+    )
+    from spatial_memory.core.embeddings import EmbeddingService
+
+    settings = get_settings()
+
+    # Set up logging based on verbosity
+    log_level = logging.DEBUG if args.verbose else logging.INFO
+    logging.basicConfig(
+        level=log_level,
+        format="%(levelname)s: %(message)s",
+    )
+
+    print("Spatial Memory Migration Tool")
+    print(f"Target schema version: {CURRENT_SCHEMA_VERSION}")
+    print(f"Database path: {settings.memory_path}")
+    print()
+
+    try:
+        # Create embedding service if needed for migrations
+        embeddings = None
+        if not args.dry_run:
+            # Only load embeddings for actual migrations (some may need re-embedding)
+            print("Loading embedding service...")
+            embeddings = EmbeddingService(
+                model_name=settings.embedding_model,
+                openai_api_key=settings.openai_api_key,
+                backend=settings.embedding_backend,  # type: ignore[arg-type]
+            )
+
+        # Connect to database
+        print("Connecting to database...")
+        db = Database(
+            storage_path=settings.memory_path,
+            embedding_dim=embeddings.dimensions if embeddings else 384,
+            auto_create_indexes=settings.auto_create_indexes,
+        )
+        db.connect()
+
+        # Create migration manager
+        manager = MigrationManager(db, embeddings)
+        manager.register_builtin_migrations()
+
+        current_version = manager.get_current_version()
+        print(f"Current schema version: {current_version}")
+
+        if args.status:
+            # Just show status, don't run migrations
+            pending = manager.get_pending_migrations()
+            if pending:
+                print(f"\nPending migrations ({len(pending)}):")
+                for migration in pending:
+                    print(f"  - {migration.version}: {migration.description}")
+            else:
+                print("\nNo pending migrations. Database is up to date.")
+
+            applied = manager.get_applied_migrations()
+            if applied:
+                print(f"\nApplied migrations ({len(applied)}):")
+                for record in applied:
+                    applied_ts = record.applied_at
+                    print(f"  - {record.version}: {record.description} (applied: {applied_ts})")
+
+            db.close()
+            return 0
+
+        if args.rollback:
+            # Rollback to specified version
+            print(f"\nRolling back to version {args.rollback}...")
+            result = manager.rollback(args.rollback)
+
+            if result.errors:
+                print("\nRollback failed with errors:")
+                for error in result.errors:
+                    print(f"  - {error}")
+                db.close()
+                return 1
+
+            if result.migrations_applied:
+                print("\nRolled back migrations:")
+                for v in result.migrations_applied:
+                    print(f"  - {v}")
+                print(f"\nCurrent version: {result.current_version}")
+            else:
+                print("\nNo migrations to rollback.")
+
+            db.close()
+            return 0
+
+        # Run pending migrations
+        pending = manager.get_pending_migrations()
+        if not pending:
+            print("\nNo pending migrations. Database is up to date.")
+            db.close()
+            return 0
+
+        print(f"\nPending migrations ({len(pending)}):")
+        for m in pending:
+            print(f"  - {m.version}: {m.description}")
+
+        if args.dry_run:
+            print("\n[DRY RUN] Would apply the above migrations.")
+            print("Run without --dry-run to apply.")
+            db.close()
+            return 0
+
+        # Confirm before applying
+        if not args.yes:
+            print()
+            response = input("Apply these migrations? [y/N] ").strip().lower()
+            if response not in ("y", "yes"):
+                print("Aborted.")
+                db.close()
+                return 0
+
+        print("\nApplying migrations...")
+        result = manager.run_pending(dry_run=False)
+
+        if result.errors:
+            print("\nMigration failed with errors:")
+            for error in result.errors:
+                print(f"  - {error}")
+            print("\nSome migrations may have been applied. Check database state.")
+            db.close()
+            return 1
+
+        print(f"\nSuccessfully applied {len(result.migrations_applied)} migration(s):")
+        for v in result.migrations_applied:
+            print(f"  - {v}")
+        print(f"\nCurrent version: {result.current_version}")
+
+        db.close()
+        return 0
+
+    except Exception as e:
+        logger.error(f"Migration failed: {e}", exc_info=args.verbose)
+        print(f"\nError: {e}")
+        return 1
+
+
+def run_version() -> None:
+    """Print version information."""
+    from spatial_memory import __version__
+
+    print(f"spatial-memory {__version__}")
+
+
+def run_instructions() -> None:
+    """Print the MCP server instructions that are auto-injected into Claude's context."""
+    from spatial_memory.server import SpatialMemoryServer
+
+    instructions = SpatialMemoryServer._get_server_instructions()
+    print(instructions)
+
+
+def main() -> NoReturn:
+    """Main entry point with subcommand support."""
+    parser = argparse.ArgumentParser(
+        prog="spatial-memory",
+        description="Spatial Memory MCP Server and CLI tools",
+    )
+    parser.add_argument(
+        "--version", "-V",
+        action="store_true",
+        help="Show version and exit",
+    )
+
+    subparsers = parser.add_subparsers(
+        dest="command",
+        title="commands",
+        description="Available commands",
+    )
+
+    # Server command (default)
+    subparsers.add_parser(
+        "serve",
+        help="Start the MCP server (default if no command given)",
+    )
+
+    # Instructions command
+    subparsers.add_parser(
+        "instructions",
+        help="Show the MCP instructions injected into Claude's context",
+    )
+
+    # Migrate command
+    migrate_parser = subparsers.add_parser(
+        "migrate",
+        help="Run database migrations",
+    )
+    migrate_parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Preview migrations without applying",
+    )
+    migrate_parser.add_argument(
+        "--status",
+        action="store_true",
+        help="Show migration status and exit",
+    )
+    migrate_parser.add_argument(
+        "--rollback",
+        metavar="VERSION",
+        help="Rollback to specified version (e.g., 1.0.0)",
+    )
+    migrate_parser.add_argument(
+        "-y", "--yes",
+        action="store_true",
+        help="Skip confirmation prompt",
+    )
+    migrate_parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose output",
+    )
+
+    args = parser.parse_args()
+
+    if args.version:
+        run_version()
+        sys.exit(0)
+
+    if args.command == "instructions":
+        run_instructions()
+        sys.exit(0)
+    elif args.command == "migrate":
+        sys.exit(run_migrate(args))
+    elif args.command == "serve" or args.command is None:
+        # Default to running the server
+        run_server()
+        sys.exit(0)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

spatial_memory/adapters/__init__.py

@@ -0,0 +1,7 @@
+"""Infrastructure adapters for Spatial Memory MCP Server."""
+
+from spatial_memory.adapters.lancedb_repository import LanceDBMemoryRepository
+
+__all__ = [
+    "LanceDBMemoryRepository",
+]