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

spatial_memory/verify.py

@@ -0,0 +1,140 @@
+"""Verify spatial-memory installation and dependencies.
+
+Run: python -m spatial_memory.verify
+"""
+
+import contextlib
+import io
+import logging
+import os
+import sys
+import warnings
+
+
+def _suppress_noise() -> None:
+    """Suppress noisy warnings and logs from dependencies."""
+    warnings.filterwarnings("ignore")
+    # Suppress verbose loggers
+    for logger_name in [
+        "sentence_transformers",
+        "optimum",
+        "huggingface_hub",
+        "transformers",
+    ]:
+        logging.getLogger(logger_name).setLevel(logging.ERROR)
+    # Suppress HF symlink warnings on Windows
+    os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
+
+
+def main() -> int:
+    """Verify installation and print status."""
+    _suppress_noise()
+
+    print("Spatial Memory MCP - Installation Verification")
+    print("=" * 50)
+
+    errors = []
+    onnx_available = False
+
+    # Check core dependencies
+    print("\nChecking core dependencies...")
+
+    try:
+        import lancedb  # noqa: F401
+        print("  [OK] lancedb")
+    except ImportError as e:
+        print(f"  [FAIL] lancedb: {e}")
+        errors.append("lancedb")
+
+    try:
+        import sentence_transformers  # noqa: F401
+        print("  [OK] sentence-transformers")
+    except ImportError as e:
+        print(f"  [FAIL] sentence-transformers: {e}")
+        errors.append("sentence-transformers")
+
+    try:
+        import mcp  # noqa: F401
+        print("  [OK] mcp")
+    except ImportError as e:
+        print(f"  [FAIL] mcp: {e}")
+        errors.append("mcp")
+
+    try:
+        import hdbscan  # noqa: F401
+        print("  [OK] hdbscan")
+    except ImportError as e:
+        print(f"  [FAIL] hdbscan: {e}")
+        errors.append("hdbscan")
+
+    try:
+        import umap  # noqa: F401
+        print("  [OK] umap-learn")
+    except ImportError as e:
+        print(f"  [FAIL] umap-learn: {e}")
+        errors.append("umap-learn")
+
+    # Check ONNX Runtime (optional but recommended)
+    print("\nChecking ONNX Runtime (for faster embeddings)...")
+
+    try:
+        import onnxruntime  # noqa: F401
+        print("  [OK] onnxruntime")
+    except ImportError:
+        print("  [WARN] onnxruntime not installed")
+
+    # Suppress "Multiple distributions" message from optimum
+    with contextlib.redirect_stdout(io.StringIO()):
+        try:
+            import optimum.onnxruntime  # noqa: F401
+            optimum_ok = True
+        except ImportError:
+            optimum_ok = False
+
+    if optimum_ok:
+        print("  [OK] optimum")
+    else:
+        print("  [WARN] optimum not installed")
+
+    # Check embedding service
+    print("\nChecking embedding service...")
+
+    try:
+        from spatial_memory.core.embeddings import EmbeddingService, _is_onnx_available
+
+        onnx_available = _is_onnx_available()
+        print(f"  ONNX Runtime available: {onnx_available}")
+
+        # Suppress model loading messages
+        with contextlib.redirect_stdout(io.StringIO()), \
+             contextlib.redirect_stderr(io.StringIO()):
+            svc = EmbeddingService()
+            backend = svc.backend
+            dimensions = svc.dimensions
+            vec = svc.embed("test")
+
+        print(f"  Active backend: {backend}")
+        print(f"  Embedding dimensions: {dimensions}")
+        print(f"  Embedding test: OK (shape: {vec.shape})")
+
+    except Exception as e:
+        print(f"  [FAIL] Embedding service error: {e}")
+        errors.append("embedding-service")
+
+    # Summary
+    print("\n" + "=" * 50)
+    if errors:
+        print(f"FAILED: {len(errors)} issue(s) found")
+        print(f"Missing: {', '.join(errors)}")
+        print("\nTry: pip install -e \".[dev]\"")
+        return 1
+    else:
+        print("SUCCESS: All dependencies verified!")
+        if not onnx_available:
+            print("\nTip: Install ONNX for 2-3x faster embeddings:")
+            print("  pip install sentence-transformers[onnx]")
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

spatial_memory_mcp-1.9.1.dist-info/METADATA

@@ -0,0 +1,509 @@
+Metadata-Version: 2.4
+Name: spatial-memory-mcp
+Version: 1.9.1
+Summary: Spatial bidirectional persistent memory MCP server for LLMs - vector-based semantic memory as a navigable landscape
+Project-URL: Homepage, https://github.com/arman-tech/spatial-memory-mcp
+Project-URL: Repository, https://github.com/arman-tech/spatial-memory-mcp
+Project-URL: Documentation, https://github.com/arman-tech/spatial-memory-mcp#readme
+Project-URL: Changelog, https://github.com/arman-tech/spatial-memory-mcp/blob/master/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/arman-tech/spatial-memory-mcp/issues
+Author: arman-tech
+License: MIT
+License-File: LICENSE
+Keywords: embeddings,llm,mcp,memory,semantic-search,spatial,vector
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: filelock>=3.12.0
+Requires-Dist: hdbscan>=0.8.33
+Requires-Dist: lancedb>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: pydantic-settings>=2.0.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: sentence-transformers[onnx]>=2.2.0
+Requires-Dist: umap-learn>=0.5.5
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: prometheus-client>=0.20.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client>=0.20.0; extra == 'metrics'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'
+Requires-Dist: tiktoken>=0.5.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# Spatial Memory MCP Server
+
+[![PyPI version](https://badge.fury.io/py/spatial-memory-mcp.svg)](https://pypi.org/project/spatial-memory-mcp/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A vector-based spatial memory system that treats knowledge as a navigable landscape, not a filing cabinet.
+
+> **Version 1.8.0** — Production-ready with 1,400+ tests passing.
+
+## Supported Platforms
+
+- **Windows 11**
+- **macOS** (latest)
+- **Linux** (Fedora, Ubuntu, Linux Mint)
+
+## Overview
+
+Spatial Memory MCP Server provides persistent, semantic memory for LLMs through the Model Context Protocol (MCP). Unlike traditional keyword-based memory systems, it uses vector embeddings to enable:
+
+- **Semantic Search**: Find memories by meaning, not just keywords
+- **Spatial Navigation**: Discover connections through `journey` and `wander` operations
+- **Auto-Clustering**: `regions` automatically groups related concepts
+- **Cognitive Dynamics**: Memories consolidate, decay, and reinforce like human cognition
+- **Auto-Decay**: Memories automatically fade over time, keeping recent knowledge prominent
+- **Visual Understanding**: Generate Mermaid/SVG/JSON visualizations of your knowledge space
+- **Hybrid Search**: Combine vector similarity with full-text search
+
+## Why Spatial Memory?
+
+### Zero Cognitive Load
+**You never think about memory. Claude handles everything automatically.**
+
+- Auto-loads relevant context at session start
+- Recognizes memory-worthy moments and asks "Save this? y/n"
+- Synthesizes answers naturally—no raw JSON, no memory IDs
+- MCP instructions inject automatically—zero configuration
+
+### Cognitive Architecture, Not Storage
+Other memory systems store embeddings. Spatial Memory implements how memory actually works:
+
+- **Decay**: Memories fade over time (Ebbinghaus forgetting curve)
+- **Reinforcement**: Frequently accessed memories grow stronger
+- **Consolidation**: Similar memories merge intelligently
+- **Extraction**: Auto-capture facts, decisions, patterns from conversations
+
+### Spatial Navigation (Unique Innovation)
+Navigate knowledge like a landscape, not a filing cabinet:
+
+| Tool | What It Does |
+|------|-------------|
+| **Journey** | SLERP between two memories—discover what's conceptually in between |
+| **Wander** | Random walk exploration—find unexpected connections |
+| **Regions** | HDBSCAN clustering—see how your knowledge self-organizes |
+| **Visualize** | UMAP projection—view your memory space in 2D/3D |
+
+### 22 Tools vs. 3-6 in Competitors
+Full lifecycle management: core operations, spatial navigation, memory lifecycle, hybrid search, namespace management, data import/export, and health/stats monitoring.
+
+### Enterprise-Ready
+Connection pooling, circuit breakers, per-agent rate limiting, request tracing, response caching, and defense-in-depth security (path traversal prevention, SQL injection detection, input validation).
+
+> *See [MARKETING.md](MARKETING.md) for the complete comparison with competitors.*
+
+## Features
+
+- **22 MCP tools** across 4 categories (core, spatial, lifecycle, utility)
+- **Clean Architecture** with ports/adapters pattern for testability
+- **LanceDB** vector storage with automatic indexing
+- **Dual embedding support**: Local (sentence-transformers) or OpenAI API
+- **ONNX Runtime** by default for 2-3x faster embeddings
+- **Enterprise features**: Connection pooling, retry logic, batch operations
+- **Comprehensive security**: Path validation, SQL injection prevention, input sanitization
+- **1400+ tests** including security edge cases
+
+## Roadmap
+
+| Phase | Status | Features |
+|-------|--------|----------|
+| Phase 1: Foundation | Complete | Config, Database, Embeddings, Models, Errors |
+| Phase 2: Core Operations | Complete | `remember`, `recall`, `nearby`, `forget` |
+| Phase 3: Spatial Operations | Complete | `journey`, `wander`, `regions`, `visualize` |
+| Phase 4: Lifecycle Operations | Complete | `consolidate`, `extract`, `decay`, `reinforce` |
+| Phase 5: Utilities | Complete | `stats`, `namespaces`, `export`, `import`, `hybrid_recall` |
+| Phase 6: Polish & Release | Complete | v1.8.0 on PyPI |
+
+## Installation
+
+### From PyPI (Recommended)
+
+```bash
+pip install spatial-memory-mcp
+
+# Or with uv
+uv pip install spatial-memory-mcp
+```
+
+### Development Setup
+
+```bash
+git clone https://github.com/arman-tech/spatial-memory-mcp.git
+cd spatial-memory-mcp
+pip install -e ".[dev]"
+```
+
+### With OpenAI Support
+
+```bash
+# From PyPI
+pip install spatial-memory-mcp[openai]
+
+# From source
+pip install -e ".[dev,openai]"
+```
+
+### Verify Installation
+
+After installation, verify that all dependencies are correctly installed:
+
+```bash
+python -m spatial_memory.verify
+```
+
+Or manually check:
+
+```python
+# Run in Python interpreter
+from spatial_memory.core.embeddings import EmbeddingService, _is_onnx_available
+print(f"ONNX available: {_is_onnx_available()}")
+svc = EmbeddingService()
+print(f"Backend: {svc.backend}, Dimensions: {svc.dimensions}")
+```
+
+Expected output with ONNX Runtime (default):
+```
+ONNX available: True
+Backend: onnx, Dimensions: 384
+```
+
+If ONNX shows as unavailable, reinstall with:
+```bash
+pip install --force-reinstall "sentence-transformers[onnx]"
+```
+
+### CLI Commands
+
+The `spatial-memory` CLI provides several commands:
+
+```bash
+# Start the MCP server (default)
+spatial-memory serve
+
+# View the MCP instructions injected into Claude's context
+spatial-memory instructions
+
+# Run database migrations
+spatial-memory migrate --status    # Check migration status
+spatial-memory migrate --dry-run   # Preview migrations
+spatial-memory migrate             # Apply pending migrations
+
+# Show version
+spatial-memory --version
+```
+
+The `instructions` command is useful for understanding what behavioral guidelines are automatically injected when the MCP server connects to Claude.
+
+### Optional Performance Dependencies
+
+For best performance, install these optional dependencies:
+
+```bash
+# ONNX Runtime - 2-3x faster embeddings, 60% less memory
+pip install onnxruntime
+
+# Or install with sentence-transformers ONNX support
+pip install "sentence-transformers[onnx]"
+
+# scipy - Optimized pairwise similarity calculations
+# Used by visualize, regions, and consolidate operations
+pip install scipy
+```
+
+**Performance comparison:**
+
+| Component | Without | With | Benefit |
+|-----------|---------|------|---------|
+| ONNX Runtime | PyTorch inference | ONNX inference | 2-3x faster embeddings |
+| scipy | numpy matrix ops | scipy.cdist | Faster similarity calculations |
+
+Both are optional - the system includes fallbacks that use numpy when these aren't available.
+
+## Configuration
+
+Copy `.env.example` to `.env` and customize:
+
+```bash
+cp .env.example .env
+```
+
+### Key Configuration Options
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_MEMORY_PATH` | `./.spatial-memory` | LanceDB storage directory |
+| `SPATIAL_MEMORY_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Embedding model (local or `openai:*`) |
+| `SPATIAL_MEMORY_EMBEDDING_BACKEND` | `auto` | Backend: `auto`, `onnx`, or `pytorch` |
+| `SPATIAL_MEMORY_OPENAI_API_KEY` | - | Required only for OpenAI embeddings |
+| `SPATIAL_MEMORY_LOG_LEVEL` | `INFO` | Logging verbosity |
+| `SPATIAL_MEMORY_AUTO_CREATE_INDEXES` | `true` | Auto-create vector indexes |
+| `SPATIAL_MEMORY_AUTO_DECAY_ENABLED` | `true` | Enable automatic importance decay |
+| `SPATIAL_MEMORY_AUTO_DECAY_FUNCTION` | `exponential` | Decay function: `exponential`, `linear`, or `step` |
+| `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED` | `true` | Persist decay updates to database |
+
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the complete configuration reference.
+
+### Embedding Models
+
+**Local models** (no API key required):
+- `all-MiniLM-L6-v2` - Fast, good quality (384 dimensions)
+- `all-mpnet-base-v2` - Slower, better quality (768 dimensions)
+
+**OpenAI models** (requires API key):
+- `openai:text-embedding-3-small` - Fast, cost-effective (1536 dimensions)
+- `openai:text-embedding-3-large` - Best quality (3072 dimensions)
+
+### Embedding Backend
+
+By default, local models use **ONNX Runtime** for 2-3x faster inference and 60% less memory:
+
+| Backend | Speed | Memory | Notes |
+|---------|-------|--------|-------|
+| ONNX Runtime (default) | 2-3x faster | 60% less | Optimized for CPU inference |
+| PyTorch | Baseline | Baseline | Full flexibility |
+
+Configure via environment variable:
+```bash
+# Auto-detect (default) - uses ONNX if available
+SPATIAL_MEMORY_EMBEDDING_BACKEND=auto
+
+# Force specific backend
+SPATIAL_MEMORY_EMBEDDING_BACKEND=onnx
+SPATIAL_MEMORY_EMBEDDING_BACKEND=pytorch
+```
+
+## Usage
+
+Add to your Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "spatial-memory": {
+      "command": "python",
+      "args": ["-m", "spatial_memory"],
+      "env": {
+        "SPATIAL_MEMORY_MEMORY_PATH": "/path/to/memory/storage"
+      }
+    }
+  }
+}
+```
+
+## Available Tools (22 Total)
+
+For complete API documentation including parameters, return types, and examples, see [docs/API.md](docs/API.md).
+
+### Core Operations
+
+| Tool | Description |
+|------|-------------|
+| `remember` | Store a memory with optional tags, importance, and metadata |
+| `remember_batch` | Store multiple memories efficiently in a single operation |
+| `recall` | Find memories semantically similar to a query with optional filters |
+| `nearby` | Find memories spatially close to a specific memory by ID |
+| `forget` | Remove a memory by ID |
+| `forget_batch` | Remove multiple memories by IDs |
+
+### Spatial Operations
+
+| Tool | Description |
+|------|-------------|
+| `journey` | Interpolate a path between two memories using SLERP, discovering concepts along the way |
+| `wander` | Random walk through memory space for serendipitous discovery |
+| `regions` | Discover conceptual regions via HDBSCAN clustering with auto-generated labels |
+| `visualize` | Generate 2D visualization (JSON coordinates, Mermaid diagrams, or SVG) |
+
+### Lifecycle Operations
+
+| Tool | Description |
+|------|-------------|
+| `decay` | Reduce importance of stale/unused memories based on time or access patterns |
+| `reinforce` | Boost importance of useful memories |
+| `extract` | Auto-extract memorable facts, decisions, and insights from text |
+| `consolidate` | Find and merge similar/duplicate memories with configurable strategies |
+
+### Utility Operations
+
+| Tool | Description |
+|------|-------------|
+| `stats` | Get comprehensive database statistics (counts, storage, indexes) |
+| `namespaces` | List all namespaces with memory counts |
+| `delete_namespace` | Delete a namespace and all its memories |
+| `rename_namespace` | Rename a namespace |
+| `export_memories` | Export memories to Parquet, JSON, or CSV format |
+| `import_memories` | Import memories from exported files with validation |
+| `hybrid_recall` | Combined vector + full-text search with configurable weighting |
+| `health` | Check system health status |
+
+## Tool Examples
+
+### Remember a Memory
+
+```
+Store this: "Use repository pattern for database access in this project"
+Tags: architecture, patterns
+Importance: 0.8
+```
+
+### Semantic Recall
+
+```
+What do I know about database patterns?
+```
+
+### Journey Between Concepts
+
+```
+Show me a journey from "React components" to "database design"
+```
+This reveals intermediate concepts like state management, data flow, API design, etc.
+
+### Discover Regions
+
+```
+What conceptual regions exist in my memories?
+```
+Returns auto-clustered groups with labels and representative memories.
+
+### Apply Memory Decay
+
+```
+Decay unused memories (dry run first to preview)
+```
+
+### Export for Backup
+
+```
+Export all memories to parquet format
+```
+
+## Security Features
+
+- **Path Traversal Prevention**: All file operations validate paths against allowed directories
+- **Symlink Attack Protection**: Optional symlink blocking for sensitive environments
+- **SQL Injection Prevention**: 13 patterns covering major attack vectors
+- **Input Validation**: Pydantic models validate all inputs
+- **Error Sanitization**: Internal errors return reference IDs, not stack traces
+- **Secure Credential Handling**: API keys stored as SecretStr
+
+## Deployment Considerations
+
+### Network Filesystems (NFS/SMB/CIFS)
+
+Spatial Memory uses file-based locking to prevent data corruption when multiple processes access the same storage. **File locking does not work reliably on network filesystems** such as NFS, SMB/CIFS, or SSHFS.
+
+If the storage path is on a network filesystem, you will see a warning at startup:
+
+```
+WARNING: Storage path appears to be on a network filesystem (nfs).
+File-based locking does not work reliably on network filesystems.
+Running multiple instances against this storage may cause data corruption.
+```
+
+**Recommendations:**
+1. **Use local storage** (default: `./.spatial-memory`) for reliable operation
+2. **Single instance only**: If you must use network storage, ensure only one MCP server instance accesses it
+3. **Acknowledge the risk**: Set `SPATIAL_MEMORY_ACKNOWLEDGE_NETWORK_FS_RISK=true` to suppress the warning
+
+## Development
+
+### Running Tests
+
+```bash
+# All tests
+pytest tests/ -v
+
+# Fast unit tests only
+pytest tests/ -m unit -v
+
+# Security-specific tests
+pytest tests/ -k "security or injection" -v
+```
+
+### Type Checking
+
+```bash
+mypy spatial_memory/ --ignore-missing-imports
+```
+
+### Linting
+
+```bash
+ruff check spatial_memory/ tests/
+```
+
+## Architecture
+
+The project follows Clean Architecture principles:
+
+```
+spatial_memory/
+├── core/           # Domain logic (database, embeddings, models, errors)
+├── services/       # Application services (memory, spatial, lifecycle)
+├── adapters/       # Infrastructure (LanceDB repository)
+├── ports/          # Protocol interfaces
+└── server.py       # MCP server entry point
+```
+
+See [SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md](SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md) for visual architecture documentation.
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [docs/API.md](docs/API.md) | Complete API reference for all 22 tools |
+| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Full configuration reference (env vars, .mcp.json, auto-decay) |
+| [docs/BENCHMARKS.md](docs/BENCHMARKS.md) | Performance benchmarks and test results |
+| [docs/METRICS.md](docs/METRICS.md) | Prometheus metrics documentation |
+| [docs/troubleshooting.md](docs/troubleshooting.md) | Troubleshooting guide |
+
+## Troubleshooting
+
+### Common Issues
+
+**Model download fails**: The first run downloads the embedding model (~80MB). Ensure internet connectivity.
+
+**Permission errors**: Check that `SPATIAL_MEMORY_MEMORY_PATH` is writable.
+
+**OpenAI errors**: Verify `SPATIAL_MEMORY_OPENAI_API_KEY` is set correctly.
+
+**Import validation errors**: Use `dry_run=true` first to preview validation issues.
+
+## Contributing
+
+Contributions welcome! Please:
+1. Fork the repository
+2. Create a feature branch
+3. Add tests for new functionality
+4. Ensure all tests pass
+5. Submit a pull request
+
+## Security
+
+For security vulnerabilities, please email directly rather than opening a public issue.
+
+## For Claude Code Users
+
+When the MCP server connects, behavioral instructions are **automatically injected** into Claude's context—no configuration needed. Run `spatial-memory instructions` to view what gets injected.
+
+For contributors working on this codebase, [CLAUDE.md](CLAUDE.md) provides project-specific guidance for AI assistants.
+
+## License
+
+MIT - See [LICENSE](LICENSE)