spatial-memory-mcp 1.0.2__tar.gz

spatial_memory_mcp-1.0.2/.env.example

@@ -0,0 +1,153 @@
+# Spatial Memory MCP Server Configuration
+# Copy this file to .env and customize as needed.
+# All settings have sensible defaults - none are required.
+
+# =============================================================================
+# STORAGE
+# =============================================================================
+
+# Path to LanceDB storage directory
+# Default: ./.spatial-memory (relative to working directory)
+# SPATIAL_MEMORY_MEMORY_PATH=~/.spatial-memory
+
+# =============================================================================
+# EMBEDDING MODEL
+# =============================================================================
+
+# Embedding model to use. Options:
+#
+# Local models (no API key required, runs on your machine):
+#   - all-MiniLM-L6-v2 (default, 384 dims, fast, good quality)
+#   - all-mpnet-base-v2 (768 dims, slower, better quality)
+#   - Any sentence-transformers model from HuggingFace
+#
+# OpenAI API (requires SPATIAL_MEMORY_OPENAI_API_KEY):
+#   - openai:text-embedding-3-small (1536 dims, fast, cheap)
+#   - openai:text-embedding-3-large (3072 dims, best quality)
+#   - openai:text-embedding-ada-002 (1536 dims, legacy)
+#
+# SPATIAL_MEMORY_EMBEDDING_MODEL=all-MiniLM-L6-v2
+
+# Embedding dimensions (auto-detected for known models)
+# Only set this if using a custom model
+# SPATIAL_MEMORY_EMBEDDING_DIMENSIONS=384
+
+# =============================================================================
+# OPENAI (only needed for OpenAI embeddings)
+# =============================================================================
+
+# Your OpenAI API key (required only if using openai:* embedding model)
+# SPATIAL_MEMORY_OPENAI_API_KEY=sk-...
+
+# OpenAI model for embeddings (used when embedding_model starts with "openai:")
+# SPATIAL_MEMORY_OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+
+# =============================================================================
+# SERVER
+# =============================================================================
+
+# Logging level: DEBUG, INFO, WARNING, ERROR
+# SPATIAL_MEMORY_LOG_LEVEL=INFO
+
+# Log format: text or json
+# SPATIAL_MEMORY_LOG_FORMAT=text
+
+# =============================================================================
+# MEMORY DEFAULTS
+# =============================================================================
+
+# Default namespace for memories (multi-tenant isolation)
+# SPATIAL_MEMORY_DEFAULT_NAMESPACE=default
+
+# Default importance score for new memories (0.0 to 1.0)
+# SPATIAL_MEMORY_DEFAULT_IMPORTANCE=0.5
+
+# =============================================================================
+# LIMITS
+# =============================================================================
+
+# Maximum memories per batch operation (remember_batch, forget_batch)
+# SPATIAL_MEMORY_MAX_BATCH_SIZE=100
+
+# Maximum results returned from recall
+# SPATIAL_MEMORY_MAX_RECALL_LIMIT=100
+
+# Maximum steps in journey operation
+# SPATIAL_MEMORY_MAX_JOURNEY_STEPS=20
+
+# Maximum steps in wander operation
+# SPATIAL_MEMORY_MAX_WANDER_STEPS=20
+
+# Maximum memories to include in visualization
+# SPATIAL_MEMORY_MAX_VISUALIZE_MEMORIES=500
+
+# =============================================================================
+# DECAY SETTINGS
+# =============================================================================
+
+# Weight for time-based decay factor (0.0 to 1.0)
+# Higher = time since access matters more
+# SPATIAL_MEMORY_DECAY_TIME_WEIGHT=0.5
+
+# Weight for access-based decay factor (0.0 to 1.0)
+# Higher = access frequency matters more
+# SPATIAL_MEMORY_DECAY_ACCESS_WEIGHT=0.5
+
+# Days without access before decay starts
+# SPATIAL_MEMORY_DECAY_DAYS_THRESHOLD=30
+
+# =============================================================================
+# CLUSTERING (HDBSCAN)
+# =============================================================================
+
+# Minimum memories required to form a cluster
+# SPATIAL_MEMORY_MIN_CLUSTER_SIZE=3
+
+# =============================================================================
+# VISUALIZATION (UMAP)
+# =============================================================================
+
+# UMAP neighborhood size (affects local vs global structure)
+# Lower = more local structure, higher = more global structure
+# SPATIAL_MEMORY_UMAP_N_NEIGHBORS=15
+
+# UMAP minimum distance between points (0.0 to 1.0)
+# Lower = tighter clusters, higher = more spread out
+# SPATIAL_MEMORY_UMAP_MIN_DIST=0.1
+
+# =============================================================================
+# INDEXING CONFIGURATION
+# =============================================================================
+
+# Create vector index when dataset exceeds this size
+# SPATIAL_MEMORY_VECTOR_INDEX_THRESHOLD=10000
+
+# Automatically create indexes
+# SPATIAL_MEMORY_AUTO_CREATE_INDEXES=true
+
+# Search parameters (higher = better recall, slower)
+# SPATIAL_MEMORY_INDEX_NPROBES=20
+# SPATIAL_MEMORY_INDEX_REFINE_FACTOR=5
+
+# =============================================================================
+# HYBRID SEARCH
+# =============================================================================
+
+# Enable full-text search index
+# SPATIAL_MEMORY_ENABLE_FTS_INDEX=true
+
+# Default balance between vector (1.0) and keyword (0.0)
+# SPATIAL_MEMORY_DEFAULT_HYBRID_ALPHA=0.5
+
+# =============================================================================
+# PERFORMANCE
+# =============================================================================
+
+# Maximum retry attempts for storage operations
+# SPATIAL_MEMORY_MAX_RETRY_ATTEMPTS=3
+
+# Backoff between retries in seconds
+# SPATIAL_MEMORY_RETRY_BACKOFF_SECONDS=0.5
+
+# Connection pool size
+# SPATIAL_MEMORY_CONNECTION_POOL_MAX_SIZE=10

spatial_memory_mcp-1.0.2/.gitignore

@@ -0,0 +1,160 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.lancedb/
+*.lance/
+data/
+memories/
+.spatial-memory/
+
+# Secrets
+.env.local
+.env.*.local
+*.pem
+*.key
+credentials.json
+secrets.json
+
+# Claude Code local files
+.claude/
+.claude-memory/
+.mcp.json

spatial_memory_mcp-1.0.2/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Phase 2: Core operations (`remember`, `recall`, `nearby`, `forget`)
+- Phase 3: Spatial operations (`journey`, `wander`, `regions`, `visualize`)
+- Phase 4: Lifecycle operations (`consolidate`, `extract`, `decay`, `reinforce`)
+- Phase 5: Utility operations (`stats`, `namespaces`, `export`, `import`)
+- Phase 6: Integration tests, documentation, PyPI release
+
+## [0.1.0] - 2026-01-20
+
+### Added
+
+#### Configuration System
+- Pydantic-based settings with environment variable support
+- Dependency injection pattern for testability
+- Full configuration validation with bounds checking
+- Support for `.env` files
+
+#### Database Layer
+- LanceDB integration for vector storage
+- SQL injection prevention with pattern detection
+- UUID validation for memory IDs
+- Namespace format validation
+- Atomic updates with rollback support
+
+#### Embedding Service
+- Local embedding support via sentence-transformers
+- OpenAI API embedding support
+- Dual-backend architecture with automatic routing
+- Model: `all-MiniLM-L6-v2` (384 dimensions) as default
+
+#### Data Models
+- `Memory` - Core memory representation
+- `MemoryResult` - Search result with similarity score
+- `Filter` / `FilterGroup` - Query filtering system
+- `ClusterInfo` - Cluster metadata for regions
+- `JourneyStep` - Step in journey interpolation
+- `VisualizationData` - Visualization output format
+
+#### Error Handling
+- Custom exception hierarchy
+- `SpatialMemoryError` base class
+- Specific errors: `MemoryNotFoundError`, `NamespaceNotFoundError`, `EmbeddingError`, `StorageError`, `ValidationError`, `ConfigurationError`, `ClusteringError`, `VisualizationError`
+
+#### Testing
+- 71 unit tests covering all Phase 1 components
+- Pytest fixtures for isolated testing
+- Mock embedding service for fast tests
+
+#### Documentation
+- README with project overview and roadmap
+- Architecture diagrams (Mermaid)
+- Security documentation
+- Contributing guidelines
+- Configuration reference (`.env.example`)
+
+### Security
+- Input validation on all user-provided data
+- SQL injection prevention
+- Namespace isolation
+- Sanitized error messages

spatial_memory_mcp-1.0.2/CLAUDE.md

@@ -0,0 +1,34 @@
+# Claude Memory System
+
+This project has a persistent memory system. On EVERY conversation start, call `start_session()` to load context.
+
+## Automatic Behaviors
+
+1. **Session Start**: Always call `start_session()` first. This loads relevant context.
+
+2. **Memory Recognition**: When you recognize memory-worthy moments, ask briefly:
+   - "Save this decision?" (for architectural choices)
+   - "Save this fix?" (for error solutions)
+   - "Note this pattern?" (for reusable approaches)
+
+   Wait for "y" or similar confirmation, then save.
+
+3. **Memory Queries**: When asked about past decisions or context, use `search_memories` or `get_context`. Don't guess or hallucinate.
+
+4. **Session End**: If significant learnings occurred, offer: "Save session summary?"
+
+## Memory-Worthy Triggers
+
+Recognize these in conversation:
+- "Let's go with...", "We decided...", "The approach is..." → Decision
+- "The fix was...", "It was failing because..." → Error
+- "This pattern works...", "The trick is..." → Pattern
+- "Remember that...", "Important:..." → Explicit save request
+- "?" in a note-to-self context → Question/TODO
+
+## Tool Availability
+
+If memory tools fail (MCP server unavailable), continue helping but note:
+"Memory system is temporarily unavailable. I'll help without historical context."
+
+Don't pretend to remember things you can't access.

spatial_memory_mcp-1.0.2/CONTRIBUTING.md

@@ -0,0 +1,299 @@
+# Contributing to Spatial Memory MCP Server
+
+Thank you for your interest in contributing! This document provides guidelines for development.
+
+## Quick Start
+
+1. Read the [README](README.md) to understand project status (currently Phase 1)
+2. Set up your development environment (see [Installation](#installation) below)
+3. Run tests to verify setup: `pytest tests/ -v`
+4. Look for issues labeled "good first issue" on GitHub
+5. If using Claude Code, check [CLAUDE.md](CLAUDE.md) for AI assistant instructions
+
+## Supported Platforms
+
+This project supports development on:
+- **Windows 11**
+- **macOS** (latest)
+- **Linux** (Fedora, Ubuntu, Linux Mint)
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- Git
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/arman-tech/spatial-memory-mcp.git
+cd spatial-memory-mcp
+
+# Create virtual environment (recommended)
+python -m venv .venv
+
+# Activate virtual environment
+# Linux/macOS:
+source .venv/bin/activate
+# Windows (PowerShell):
+.venv\Scripts\Activate.ps1
+# Windows (CMD):
+.venv\Scripts\activate.bat
+
+# Install in development mode with dev dependencies
+pip install -e ".[dev]"
+```
+
+### Verify Installation
+
+```bash
+# Run tests
+pytest tests/ -v
+
+# Type checking
+mypy spatial_memory/ --ignore-missing-imports
+
+# Linting
+ruff check spatial_memory/ tests/
+```
+
+## Project Structure
+
+```
+spatial-memory-mcp/
+├── spatial_memory/          # Main package
+│   ├── __init__.py         # Public API exports
+│   ├── __main__.py         # Entry point (shows status until Phase 2)
+│   ├── config.py           # Settings with DI pattern
+│   ├── py.typed            # PEP 561 marker for type checking
+│   └── core/
+│       ├── __init__.py     # Core module exports
+│       ├── database.py     # LanceDB wrapper
+│       ├── embeddings.py   # Embedding service
+│       ├── errors.py       # Exception hierarchy
+│       ├── models.py       # Pydantic data models
+│       └── utils.py        # Shared utilities
+├── tests/                   # Test suite
+│   ├── conftest.py         # Pytest fixtures
+│   ├── test_config.py
+│   ├── test_database.py
+│   ├── test_embeddings.py
+│   └── test_models.py
+├── .env.example            # Example configuration
+├── pyproject.toml          # Package configuration
+├── CLAUDE.md               # Instructions for Claude Code AI assistant
+├── SECURITY.md             # Security policy and guidelines
+├── CHANGELOG.md            # Version history
+└── README.md               # Project overview
+```
+
+> **Note**: The `__main__.py` entry point currently displays a status message. The MCP server will be implemented in Phase 2.
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run specific test file
+pytest tests/test_database.py -v
+
+# Run tests matching a pattern
+pytest tests/ -k "test_remember" -v
+
+# Run with coverage
+pytest tests/ --cov=spatial_memory --cov-report=html
+```
+
+### Test Categories
+
+| File | Purpose |
+|------|---------|
+| `test_config.py` | Configuration loading, validation, environment variables |
+| `test_database.py` | LanceDB operations, CRUD, filtering, SQL injection prevention |
+| `test_embeddings.py` | Embedding service, local and API backends |
+| `test_models.py` | Pydantic model validation, serialization |
+
+### Writing Tests
+
+#### Use Fixtures
+
+```python
+# tests/conftest.py provides these fixtures:
+
+def test_with_temp_storage(temp_storage):
+    """temp_storage provides an isolated database directory."""
+    # Database operations here are isolated
+    pass
+
+def test_with_mock_embeddings(mock_embedding_service):
+    """mock_embedding_service avoids real embedding computation."""
+    vector = mock_embedding_service.embed("test")
+    assert len(vector) == 384
+```
+
+#### Test Naming Convention
+
+```python
+def test_<function>_<scenario>_<expected_outcome>():
+    """Tests should follow this naming pattern."""
+    pass
+
+# Examples:
+def test_remember_valid_content_returns_memory_id():
+    pass
+
+def test_recall_empty_query_raises_validation_error():
+    pass
+```
+
+#### Testing Errors
+
+```python
+import pytest
+from spatial_memory.core.errors import ValidationError
+
+def test_invalid_input_raises_validation_error():
+    with pytest.raises(ValidationError) as exc_info:
+        # Code that should raise
+        pass
+    assert "expected message" in str(exc_info.value)
+```
+
+## Code Style
+
+### Python Version
+
+- Use Python 3.10+ features (union types with `|`, match statements, etc.)
+- Type hints are required for all public functions
+
+### Formatting & Linting
+
+```bash
+# Check for issues
+ruff check spatial_memory/ tests/
+
+# Auto-fix issues
+ruff check --fix spatial_memory/ tests/
+```
+
+### Type Checking
+
+```bash
+mypy spatial_memory/ --ignore-missing-imports
+```
+
+### Documentation
+
+- All public functions need docstrings
+- Use Google-style docstrings:
+
+```python
+def remember(content: str, namespace: str = "default") -> str:
+    """Store a memory in vector space.
+
+    Args:
+        content: The text content to remember.
+        namespace: Namespace for isolation.
+
+    Returns:
+        The UUID of the created memory.
+
+    Raises:
+        ValidationError: If content is empty or too long.
+        StorageError: If database operation fails.
+    """
+```
+
+## Pull Request Process
+
+1. **Fork** the repository at https://github.com/arman-tech/spatial-memory-mcp
+2. **Create a branch** for your feature: `git checkout -b feature/my-feature`
+3. **Write tests** for new functionality
+4. **Ensure all tests pass**: `pytest tests/ -v`
+5. **Ensure no lint errors**: `ruff check spatial_memory/ tests/`
+6. **Ensure type checking passes**: `mypy spatial_memory/`
+7. **Commit** with clear messages
+8. **Push** to your fork
+9. **Open a Pull Request** with:
+   - Clear description of changes
+   - Reference to related issues
+   - Test coverage for new code
+
+## Error Handling
+
+### Exception Hierarchy
+
+```
+SpatialMemoryError (base)
+├── MemoryNotFoundError    # Memory ID doesn't exist
+├── NamespaceNotFoundError # Namespace doesn't exist
+├── EmbeddingError         # Embedding generation failed
+├── StorageError           # Database operation failed
+├── ValidationError        # Input validation failed
+├── ConfigurationError     # Invalid configuration
+├── ClusteringError        # Clustering operation failed
+└── VisualizationError     # Visualization generation failed
+```
+
+### When to Use Each
+
+```python
+from spatial_memory.core.errors import (
+    ValidationError,
+    StorageError,
+    MemoryNotFoundError,
+)
+
+def my_function(memory_id: str):
+    # Input validation
+    if not memory_id:
+        raise ValidationError("memory_id cannot be empty")
+
+    # Database operations
+    try:
+        result = db.get(memory_id)
+    except Exception as e:
+        raise StorageError(f"Database error: {e}")
+
+    # Not found
+    if result is None:
+        raise MemoryNotFoundError(memory_id)
+```
+
+## Configuration
+
+### Adding New Settings
+
+1. Add the field to `Settings` class in `config.py`:
+
+```python
+class Settings(BaseSettings):
+    # ... existing fields ...
+
+    my_new_setting: int = Field(
+        default=10,
+        ge=1,
+        le=100,
+        description="Description of what this does",
+    )
+```
+
+2. Add to `.env.example`:
+
+```bash
+# Description of what this does
+# SPATIAL_MEMORY_MY_NEW_SETTING=10
+```
+
+3. Add tests in `test_config.py`
+
+## Questions?
+
+- Open a GitHub issue for bugs or feature requests
+- Check existing issues before creating new ones
+- See [SECURITY.md](SECURITY.md) for reporting security vulnerabilities