spatial-memory-mcp 1.6.0__tar.gz → 1.6.2__tar.gz

spatial_memory_mcp-1.6.2/CHANGELOG.md

@@ -0,0 +1,158 @@
+# 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
+- Medium severity architectural improvements (MED-ARCH-001 through MED-ARCH-004)
+- Migration system (MED-DB-005)
+
+## [1.6.2] - 2026-02-02
+
+### Added
+- Technical highlights documentation (`docs/TECHNICAL_HIGHLIGHTS.md`) with Mermaid diagrams
+  - Cognitive memory model vs traditional storage
+  - SLERP algorithm for journey tool
+  - Temperature-based random walks for wander tool
+  - HDBSCAN clustering for regions tool
+  - UMAP projection for visualize tool
+  - ONNX Runtime optimization
+  - scipy integration for efficient similarity calculations
+
+### Fixed
+- Fixed 46 ruff linting errors across codebase
+  - Import sorting and formatting
+  - Lines exceeding 100 characters
+  - Unused variables and imports
+  - Import ordering issues
+
+## [1.6.1] - 2026-02-02
+
+### Added
+- `spatial-memory instructions` CLI command to view the MCP instructions injected into Claude's context
+
+### Changed
+- Updated CLAUDE.md to be contributor documentation (removed stale claude-memory references)
+
+## [1.6.0] - 2026-02-02
+
+### Fixed
+
+#### Critical Issues
+- **CRIT-001**: Fixed consolidation data loss window - implemented add-before-delete pattern with pending status marker
+- **CRIT-002**: Fixed journey N+1 query pattern - plumbed `include_vector` parameter through search pipeline
+
+#### High Severity Issues
+- **HIGH-001**: Fixed sequential DB calls in wander (resolved via CRIT-002)
+- **HIGH-002**: Fixed O(n²) similarity calculation in visualize - replaced with `scipy.spatial.distance.cdist` vectorized operation
+- **HIGH-003**: Fixed inefficient batch search - implemented native LanceDB batch search
+- **HIGH-004**: Fixed duplicate embedding generation in extract - batch embed upfront with `embed_batch()`
+- **HIGH-005**: Fixed sequential updates in decay - added `update_batch()` method
+- **HIGH-006**: Fixed sequential fetches in reinforce - added `get_batch()` method
+- **HIGH-007**: Fixed non-atomic batch insert - added `PartialBatchInsertError` with rollback capability
+- **HIGH-008**: Fixed rename_namespace lacking rollback - track renamed IDs with `_rollback_namespace_rename()`
+- **HIGH-009**: Fixed consolidation loading entire namespace - added streaming `_consolidate_chunked()`
+- **HIGH-010**: Fixed file lock on NFS/SMB - added detection and startup warning
+
+#### Medium Severity Issues
+- **MED-SEC-002**: Fixed memory exhaustion in JSON/CSV export - implemented streaming export
+- **MED-CQ-001**: Fixed `forget_batch` returning incorrect IDs
+- **MED-CQ-002**: Added missing `backend` to `EmbeddingServiceProtocol`
+- **MED-CQ-003**: Fixed rate limiter token consumption issue
+- **MED-CQ-004**: Fixed embedding cache leak in batch operations
+- **MED-DB-001**: Added missing index to idempotency table
+- **MED-DB-003**: Fixed `get_namespace_stats()` loading all records
+- **MED-DB-004**: Added vector dimension validation at insert
+
+#### Low Severity Issues
+- **LOW-001**: Made embedding cache size configurable (was hardcoded 1000)
+- **LOW-002**: Standardized datetime handling in lifecycle.py
+- **LOW-003**: Extracted magic numbers in retry logic to constants
+- **LOW-004**: Added Literal type validation for `index_type`
+- **LOW-006**: Fixed `validate_namespace` docstring mismatch
+- **LOW-007**: Normalized mock embedding vectors in conftest.py
+- **LOW-008**: Documented content validation security approach
+- **LOW-009**: Added metadata depth validation
+- **LOW-010**: Sanitized paths in error messages
+- **LOW-011**: Added proactive connection health check
+- **LOW-012**: Fixed `close()` to remove from connection pool
+- **LOW-013**: Implemented auto-compaction scheduling
+- **LOW-014**: Cached stop words set (was recreated per call)
+- **LOW-015**: Improved cache key hashing
+
+### Added
+- `get_batch()` method for bulk memory retrieval
+- `update_batch()` method returning `(success_count, failed_ids)` tuple
+- Native LanceDB batch vector search
+- `PartialBatchInsertError` exception with `succeeded_ids` for recovery
+- `atomic=True` parameter to `insert_batch()` with rollback capability
+- Streaming consolidation with configurable `consolidate_chunk_size`
+- NFS/SMB filesystem detection in `core/filesystem.py`
+- Config option `acknowledge_network_filesystem_risk` to suppress warnings
+
+### Changed
+- Refactored `database.py` into separate manager modules for maintainability
+- Improved type safety across async operations
+
+### Closed (By Design)
+- **MED-SEC-001**: No namespace-level authorization - single-developer local use is intended
+- **MED-DB-002**: `get_namespaces()` loads all values - TTL caching is sufficient
+- **LOW-005**: Duplicate local imports - intentional circular import avoidance
+
+## [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.6.2/CLAUDE.md

@@ -0,0 +1,102 @@
+# Spatial Memory MCP - Contributor Guide
+
+This document helps AI assistants (and human contributors) work effectively on this codebase.
+
+## Project Overview
+
+**spatial-memory-mcp** is a persistent semantic memory MCP server for LLMs. It provides vector-based memory storage with spatial navigation capabilities using LanceDB and sentence-transformers.
+
+## Architecture
+
+```
+spatial_memory/
+├── server.py           # MCP server, tool handlers, instructions injection
+├── factory.py          # Dependency injection, service instantiation
+├── config.py           # Settings (Pydantic), environment configuration
+├── core/               # Core infrastructure
+│   ├── database.py     # LanceDB wrapper, CRUD operations
+│   ├── embeddings.py   # Sentence-transformer embedding service
+│   ├── models.py       # Pydantic data models (Memory, etc.)
+│   ├── errors.py       # Exception hierarchy
+│   ├── validation.py   # Input validation, security checks
+│   ├── security.py     # Security utilities
+│   ├── db_*.py         # Database utilities (search, indexes, migrations)
+│   └── spatial_ops.py  # SLERP, vector operations
+├── services/           # Business logic layer
+│   ├── memory.py       # Core memory operations (remember, recall, forget)
+│   ├── spatial.py      # Spatial operations (journey, wander, regions)
+│   ├── lifecycle.py    # Decay, reinforce, consolidate, extract
+│   ├── export_import.py# Import/export functionality
+│   └── utility.py      # Stats, namespaces, health
+├── adapters/           # External service adapters
+├── ports/              # Interface definitions
+└── tools/              # MCP tool definitions
+```
+
+## Key Commands
+
+```bash
+# Run tests (unit tests only by default)
+pytest tests/ -v
+
+# Run all tests including integration
+pytest tests/ -v -m ""
+
+# Run integration tests only
+pytest tests/ -v -m integration
+
+# Type checking
+mypy spatial_memory/
+
+# Linting
+ruff check spatial_memory/ tests/
+
+# Format code
+ruff format spatial_memory/ tests/
+
+# Run the server directly
+python -m spatial_memory
+```
+
+## Test Markers
+
+- `@pytest.mark.unit` - Fast tests with mocked dependencies
+- `@pytest.mark.integration` - Tests with real database/embeddings (slower)
+- `@pytest.mark.slow` - Tests taking >1 second
+- `@pytest.mark.requires_model` - Tests needing the embedding model loaded
+
+## Configuration
+
+Settings via environment variables or `.env` file:
+- `SPATIAL_MEMORY_PATH` - Database storage location (default: `.spatial-memory/`)
+- `SPATIAL_MEMORY_EMBEDDING_MODEL` - Model name (default: `all-MiniLM-L6-v2`)
+- `SPATIAL_MEMORY_LOG_LEVEL` - Logging level
+- See `config.py` and `.env.example` for full list
+
+## Code Style
+
+- Line length: 100 characters
+- Python 3.10+ (use modern syntax: `|` unions, etc.)
+- Type hints required (strict mypy)
+- Ruff for linting/formatting
+
+## Important Patterns
+
+1. **Dependency Injection**: Services receive dependencies via constructor, not global imports
+2. **Async Throughout**: All database and service methods are async
+3. **Pydantic Models**: Use for data validation and serialization
+4. **Error Hierarchy**: Custom exceptions in `core/errors.py`
+
+## MCP Tool Categories
+
+The server exposes these tool groups:
+- **Memory**: `remember`, `recall`, `hybrid_recall`, `nearby`, `forget`
+- **Spatial**: `journey`, `wander`, `regions`, `visualize`
+- **Lifecycle**: `decay`, `reinforce`, `extract`, `consolidate`
+- **Admin**: `stats`, `namespaces`, `export_memories`, `import_memories`
+
+## Notes
+
+- MCP server instructions are auto-injected via `_get_server_instructions()` in `server.py`
+- Database uses LanceDB (embedded vector database)
+- Embeddings default to ONNX-optimized sentence-transformers for performance

{spatial_memory_mcp-1.6.0 → spatial_memory_mcp-1.6.2}/ISSUES-TRACKER.md

@@ -1,8 +1,8 @@
 # Spatial Memory MCP - Issues Tracker
 
 > Generated: 2026-02-01
-> Status: **All Phases Complete**
-> Last Updated: 2026-02-01
+> Status: **All Phases Complete - Released v1.6.0**
+> Last Updated: 2026-02-02
 
 ---
 
@@ -279,6 +279,7 @@ Remaining backlog items are Medium severity architectural improvements (refactor
 | 2026-02-01 | Phase 4 | ✅ Implemented MED-SEC-002, MED-CQ-001-004, MED-DB-001, MED-DB-003, MED-DB-004 | Claude |
 | 2026-02-01 | Phase 5 | ✅ Implemented LOW-001, LOW-003, LOW-014, LOW-015 | Claude |
 | 2026-02-01 | All | **All phases complete** - 1360 tests passing | Claude |
+| 2026-02-02 | All | **Released v1.6.0** - Pushed to repository | User |
 | 2026-02-01 | Phase A-C Backlog | ✅ Implemented remaining Low severity issues: | Claude |
 |  | LOW-002 | Standardized datetime handling in lifecycle.py |  |
 |  | LOW-004 | Added Literal type validation for index_type |  |

{spatial_memory_mcp-1.6.0 → spatial_memory_mcp-1.6.2}/MARKETING.md

@@ -40,7 +40,7 @@ The result? Developers interact with an AI that genuinely remembers—without wr
 
 ## This Is Not Storage. This Is Cognitive Architecture.
 
-Traditional vector databases store embeddings. Spatial Memory MCP implements a cognitive memory model inspired by human memory research.
+Traditional vector databases store embeddings. Spatial Memory MCP implements a cognitive memory model inspired by established memory research (see [References](#references)).
 
 ### Memory Decay (Ebbinghaus Forgetting Curve)
 Memories fade over time if not accessed—just like human memory. Choose exponential, linear, or step decay functions. Set half-life periods. Define importance floors. Memories that matter persist. Memories that don't, gracefully fade.
@@ -80,7 +80,7 @@ Project your memories into 2D or 3D space. Export as JSON, Mermaid diagrams, or
 
 ---
 
-## 21 Tools. Complete Lifecycle Management.
+## 22 Tools. Complete Lifecycle Management.
 
 | Category | Spatial Memory MCP | Typical Competitor |
 |----------|-------------------|-------------------|
@@ -93,7 +93,7 @@ Project your memories into 2D or 3D space. Export as JSON, Mermaid diagrams, or
 | Data Portability | export_memories, import_memories | None |
 | Administration | stats, health | Minimal |
 
-**21 production-ready tools** covering the complete memory lifecycle—from ingestion to navigation to maintenance to export.
+**22 production-ready tools** covering the complete memory lifecycle—from ingestion to navigation to maintenance to export.
 
 ---
 
@@ -116,9 +116,16 @@ Search for "authentication error handling" and find both semantically related se
 Production deployment demands production infrastructure.
 
 ### Connection Management
-- **Connection pooling** with LRU eviction
+- **Connection pooling** with LRU eviction and health checks
 - **Cross-process file locking** for multi-instance safety
 - **Circuit breaker pattern** prevents cascade failures
+- **NFS/SMB detection** warns about shared filesystem risks
+
+### Data Integrity
+- **Atomic batch operations** with rollback on failure
+- **Add-before-delete pattern** prevents data loss during consolidation
+- **Namespace rename rollback** recovers from partial failures
+- **Streaming consolidation** handles large namespaces safely
 
 ### Observability
 - **Request tracing** with correlation IDs
@@ -128,7 +135,7 @@ Production deployment demands production infrastructure.
 
 ### Security
 - **Path traversal prevention** — No filesystem escapes
-- **SQL injection detection** — 15+ attack patterns blocked
+- **SQL injection detection** — 13 patterns covering major attack vectors
 - **Input validation** — Pydantic models throughout
 - **Credential masking** — Sensitive data never logged
 - **Dry-run modes** — Preview destructive operations safely
@@ -155,7 +162,7 @@ Auto-indexing triggers at 10K+ memories using IVF_PQ. Sub-linear search complexi
 
 | Feature | Spatial Memory MCP | mcp-mem0 | mcp-memory-service | Memory Bank MCP |
 |---------|-------------------|----------|-------------------|-----------------|
-| Total Tools | 21 | 3 | ~6 | ~5 |
+| Total Tools | 22 | 3 | ~6 | ~5 |
 | Spatial Navigation | Yes | No | No | No |
 | Memory Decay | Yes | No | No | No |
 | Reinforcement | Yes | No | No | No |
@@ -165,8 +172,8 @@ Auto-indexing triggers at 10K+ memories using IVF_PQ. Sub-linear search complexi
 | SLERP Interpolation | Yes | No | No | No |
 | Visualization | Yes | No | No | No |
 | Enterprise Features | Full Suite | Minimal | Basic | Basic |
-| External Dependencies | SQLite only | PostgreSQL | Varies | File-based |
-| Test Coverage | 1,094 tests | Minimal | Unknown | Unknown |
+| External Dependencies | None (embedded) | PostgreSQL | Varies | File-based |
+| Test Coverage | 1,360 tests | Minimal | Unknown | Unknown |
 
 **mcp-mem0**: 3 tools, 4 commits, requires PostgreSQL infrastructure.
 
@@ -197,15 +204,15 @@ Navigate between concepts. Discover intermediate ideas. Visualize knowledge stru
 ## Technical Specifications
 
 - **Language**: Python 3.10+
-- **Database**: SQLite with LanceDB for vectors
+- **Database**: LanceDB (embedded vector database)
 - **Embedding**: ONNX Runtime with all-MiniLM-L6-v2
 - **Clustering**: HDBSCAN
 - **Projection**: UMAP
 - **Interpolation**: SLERP (Spherical Linear Interpolation)
 - **Architecture**: Clean architecture with dependency injection
 - **Type Safety**: Full type hints, mypy strict mode
-- **Test Suite**: 1,094 passing tests
-- **Development**: 5 completed phases
+- **Test Suite**: 1,360 passing tests
+- **Version**: 1.6.2
 
 ---
 
@@ -239,6 +246,18 @@ And it does all of this with zero cognitive load on developers. Claude handles m
 
 ---
 
+## References
+
+The cognitive memory model is inspired by established research:
+
+1. **Ebbinghaus, H. (1885)**. *Memory: A Contribution to Experimental Psychology*. The foundational research on the forgetting curve showing how memory retention decays exponentially over time. [Read the translation](https://psychclassics.yorku.ca/Ebbinghaus/index.htm)
+
+2. **Settles, B. & Meeder, B. (2016)**. *A Trainable Spaced Repetition Model for Language Learning*. Duolingo's half-life regression (HLR) algorithm for optimizing memory retention. [ACL Anthology](https://aclanthology.org/P16-1174/)
+
+3. **FSRS Algorithm**. Free Spaced Repetition Scheduler - a modern open-source algorithm for optimizing review intervals based on memory research. [GitHub](https://github.com/open-spaced-repetition/fsrs4anki)
+
+---
+
 **Spatial Memory MCP**
 
 *Knowledge as a navigable landscape, not a filing cabinet.*

{spatial_memory_mcp-1.6.0 → spatial_memory_mcp-1.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.6.0
+Version: 1.6.2
 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
@@ -42,9 +42,13 @@ 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.
 
-> **Project Status**: All phases complete. Production-ready with 1360 tests passing.
+> **Version 1.6.2** — Production-ready with 1,360 tests passing.
 
 ## Supported Platforms
 
@@ -91,7 +95,7 @@ Navigate knowledge like a landscape, not a filing cabinet:
 | **Regions** | HDBSCAN clustering—see how your knowledge self-organizes |
 | **Visualize** | UMAP projection—view your memory space in 2D/3D |
 
-### 21 Tools vs. 3-6 in Competitors
+### 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
@@ -101,7 +105,7 @@ Connection pooling, circuit breakers, per-agent rate limiting, request tracing,
 
 ## Features
 
-- **21 MCP tools** across 4 categories (core, spatial, lifecycle, utility)
+- **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
@@ -119,10 +123,19 @@ Connection pooling, circuit breakers, per-agent rate limiting, request tracing,
 | 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 | In Progress | PyPI release pending |
+| Phase 6: Polish & Release | Complete | v1.6.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
@@ -134,6 +147,10 @@ pip install -e ".[dev]"
 ### With OpenAI Support
 
 ```bash
+# From PyPI
+pip install spatial-memory-mcp[openai]
+
+# From source
 pip install -e ".[dev,openai]"
 ```
 
@@ -166,6 +183,28 @@ If ONNX shows as unavailable, reinstall with:
 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:
@@ -257,7 +296,7 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
 }
 ```
 
-## Available Tools (21 Total)
+## Available Tools (22 Total)
 
 For complete API documentation including parameters, return types, and examples, see [docs/API.md](docs/API.md).
 
@@ -301,6 +340,7 @@ For complete API documentation including parameters, return types, and examples,
 | `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
 
@@ -348,7 +388,7 @@ Export all memories to parquet format
 
 - **Path Traversal Prevention**: All file operations validate paths against allowed directories
 - **Symlink Attack Protection**: Optional symlink blocking for sensitive environments
-- **SQL Injection Prevention**: 15+ dangerous patterns detected and blocked
+- **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
@@ -418,7 +458,7 @@ See [SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md](SPATIAL-MEMORY-ARCHITECTURE-DIAGRA
 
 | Document | Description |
 |----------|-------------|
-| [docs/API.md](docs/API.md) | Complete API reference for all 21 tools |
+| [docs/API.md](docs/API.md) | Complete API reference for all 22 tools |
 | [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 |
@@ -450,7 +490,9 @@ For security vulnerabilities, please email directly rather than opening a public
 
 ## For Claude Code Users
 
-This project includes [CLAUDE.md](CLAUDE.md) with instructions for the Claude Code AI assistant to interact with the memory system.
+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
 

{spatial_memory_mcp-1.6.0 → spatial_memory_mcp-1.6.2}/README.md

@@ -1,8 +1,12 @@
 # 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.
 
-> **Project Status**: All phases complete. Production-ready with 1360 tests passing.
+> **Version 1.6.2** — Production-ready with 1,360 tests passing.
 
 ## Supported Platforms
 
@@ -49,7 +53,7 @@ Navigate knowledge like a landscape, not a filing cabinet:
 | **Regions** | HDBSCAN clustering—see how your knowledge self-organizes |
 | **Visualize** | UMAP projection—view your memory space in 2D/3D |
 
-### 21 Tools vs. 3-6 in Competitors
+### 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
@@ -59,7 +63,7 @@ Connection pooling, circuit breakers, per-agent rate limiting, request tracing,
 
 ## Features
 
-- **21 MCP tools** across 4 categories (core, spatial, lifecycle, utility)
+- **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
@@ -77,10 +81,19 @@ Connection pooling, circuit breakers, per-agent rate limiting, request tracing,
 | 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 | In Progress | PyPI release pending |
+| Phase 6: Polish & Release | Complete | v1.6.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
@@ -92,6 +105,10 @@ pip install -e ".[dev]"
 ### With OpenAI Support
 
 ```bash
+# From PyPI
+pip install spatial-memory-mcp[openai]
+
+# From source
 pip install -e ".[dev,openai]"
 ```
 
@@ -124,6 +141,28 @@ If ONNX shows as unavailable, reinstall with:
 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:
@@ -215,7 +254,7 @@ Add to your Claude Desktop config (`claude_desktop_config.json`):
 }
 ```
 
-## Available Tools (21 Total)
+## Available Tools (22 Total)
 
 For complete API documentation including parameters, return types, and examples, see [docs/API.md](docs/API.md).
 
@@ -259,6 +298,7 @@ For complete API documentation including parameters, return types, and examples,
 | `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
 
@@ -306,7 +346,7 @@ Export all memories to parquet format
 
 - **Path Traversal Prevention**: All file operations validate paths against allowed directories
 - **Symlink Attack Protection**: Optional symlink blocking for sensitive environments
-- **SQL Injection Prevention**: 15+ dangerous patterns detected and blocked
+- **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
@@ -376,7 +416,7 @@ See [SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md](SPATIAL-MEMORY-ARCHITECTURE-DIAGRA
 
 | Document | Description |
 |----------|-------------|
-| [docs/API.md](docs/API.md) | Complete API reference for all 21 tools |
+| [docs/API.md](docs/API.md) | Complete API reference for all 22 tools |
 | [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 |
@@ -408,7 +448,9 @@ For security vulnerabilities, please email directly rather than opening a public
 
 ## For Claude Code Users
 
-This project includes [CLAUDE.md](CLAUDE.md) with instructions for the Claude Code AI assistant to interact with the memory system.
+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