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

spatial_memory_mcp-1.6.0/ISSUES-TRACKER.md

@@ -0,0 +1,302 @@
+# Spatial Memory MCP - Issues Tracker
+
+> Generated: 2026-02-01
+> Status: **All Phases Complete**
+> Last Updated: 2026-02-01
+
+---
+
+## Overview
+
+This document tracks all identified issues from the comprehensive codebase review and their resolutions.
+
+| Severity | Count | Status |
+|----------|-------|--------|
+| Critical | 2 | ✅ All Complete |
+| High | 10 | ✅ All Complete |
+| Medium | 18 | ✅ 8 Complete, 10 Backlog |
+| Low | 15+ | ✅ 4 Complete, 11+ Backlog |
+
+### Design Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| CRIT-001 Data Safety | Add-before-delete pattern | Simpler than soft-delete, no schema change required |
+| HIGH-010 Deployment | Single-machine only | Document limitation, detect and warn at startup |
+| MED-SEC-001 Multi-tenant | Not a priority | Current behavior is intended for single-developer local use |
+
+---
+
+## Critical Issues
+
+### CRIT-001: Consolidation Data Loss Window
+
+- **Location:** `spatial_memory/services/lifecycle.py:690-720`
+- **Description:** "merge_content" strategy deletes originals before adding merged memory. If add fails (e.g., embedding timeout), originals are permanently lost.
+- **Status:** ✅ COMPLETED (2026-02-01)
+- **Priority:** P0
+
+#### Solution Implemented
+Add-before-delete pattern with pending status marker in metadata.
+
+---
+
+### CRIT-002: Journey N+1 Query Pattern
+
+- **Location:** `spatial_memory/services/spatial.py:231-237`
+- **Description:** For each neighbor in journey results, `_get_vector_for_memory()` hits the database. 10-step journey with 3 neighbors = 30 extra DB calls.
+- **Status:** ✅ COMPLETED (2026-02-01)
+- **Priority:** P0
+
+#### Solution Implemented
+Plumbed `include_vector` parameter through search pipeline.
+
+---
+
+## High Severity Issues
+
+### HIGH-001: Sequential DB Calls in Wander
+- **Location:** `spatial_memory/services/spatial.py:331-383`
+- **Description:** 2 DB calls per step (search + get_with_vector)
+- **Status:** ✅ COMPLETED (2026-02-01) - Fixed as part of CRIT-002
+- **Priority:** P1
+
+---
+
+### HIGH-002: O(n²) Similarity in Visualize
+- **Location:** `spatial_memory/services/spatial.py:668-679`
+- **Description:** 124,750 pairwise similarity calculations for 500 memories
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Replaced O(n²) loop with `scipy.spatial.distance.cdist` vectorized operation. Falls back to numpy if scipy unavailable.
+
+---
+
+### HIGH-003: Inefficient Batch Search (Sequential)
+- **Location:** `spatial_memory/services/spatial.py:781-805`
+- **Description:** `_batch_vector_search` iterates and calls search individually
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Implemented native LanceDB batch search at database layer using `table.search([vec1, vec2, ...])`.
+
+---
+
+### HIGH-004: Duplicate Embedding Generation in Extract
+- **Location:** `spatial_memory/services/lifecycle.py:481-485, 781`
+- **Description:** Embedding generated twice - once for dedup check, once for storage
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Batch embed all candidates upfront with `embed_batch()`, pass vectors through dedup check and store operations.
+
+---
+
+### HIGH-005: Sequential Updates in Decay
+- **Location:** `spatial_memory/services/lifecycle.py:276-283`
+- **Description:** 500 individual writes instead of batch update
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Added `update_batch()` method returning `(success_count, failed_ids)` tuple.
+
+---
+
+### HIGH-006: Sequential Fetches in Reinforce
+- **Location:** `spatial_memory/services/lifecycle.py:348-387`
+- **Description:** 2 DB calls per memory (get + update)
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Added `get_batch()` method returning `{id: Memory}` dict. Combined with `update_batch()` for 2 calls total.
+
+---
+
+### HIGH-007: Batch Insert NOT Atomic
+- **Location:** `spatial_memory/core/database.py:1350`
+- **Description:** Partial failures leave orphaned records
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Added `PartialBatchInsertError` with `succeeded_ids` for recovery. Added `atomic=True` parameter to `insert_batch()` with rollback capability.
+
+---
+
+### HIGH-008: rename_namespace Lacks Rollback
+- **Location:** `spatial_memory/core/database.py:1684-1736`
+- **Description:** Partial renames leave namespace in mixed state
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Track renamed IDs during operation. On failure, `_rollback_namespace_rename()` reverts records to original namespace.
+
+---
+
+### HIGH-009: Consolidation Loads Entire Namespace
+- **Location:** `spatial_memory/services/lifecycle.py:573-577`
+- **Description:** Memory exhaustion risk for large namespaces
+- **Status:** ✅ COMPLETED (2026-02-02)
+- **Priority:** P1
+
+#### Solution Implemented
+Added `_consolidate_chunked()` for streaming consolidation with configurable `consolidate_chunk_size` (default: 200).
+
+---
+
+### HIGH-010: File Lock Doesn't Work on NFS/SMB
+- **Location:** `spatial_memory/core/database.py:239-388`
+- **Description:** Data corruption risk in shared filesystem
+- **Status:** ✅ COMPLETED (2026-02-01)
+- **Priority:** P1
+
+#### Solution Implemented
+Added `core/filesystem.py` with detection. Startup warning if NFS/SMB detected. Config `acknowledge_network_filesystem_risk` to suppress.
+
+---
+
+## Medium Severity Issues
+
+### Security
+
+| ID | Issue | Location | Status | Notes |
+|----|-------|----------|--------|-------|
+| MED-SEC-001 | No namespace-level authorization | server.py | Closed - By Design | Single-developer local use is intended |
+| MED-SEC-002 | Memory exhaustion in JSON/CSV export | export_import.py:616-695 | ✅ COMPLETED (2026-02-01) | Streaming export implemented |
+
+### Code Quality
+
+| ID | Issue | Location | Status |
+|----|-------|----------|--------|
+| MED-CQ-001 | forget_batch returns incorrect IDs | memory.py:407-412 | ✅ COMPLETED (2026-02-01) |
+| MED-CQ-002 | Missing backend in EmbeddingServiceProtocol | ports/repositories.py:543-581 | ✅ COMPLETED (2026-02-01) |
+| MED-CQ-003 | Rate limiter token consumption issue | rate_limiter.py:213-227 | ✅ COMPLETED (2026-02-01) |
+| MED-CQ-004 | Embedding cache leak in batch operations | embeddings.py:211-214 | ✅ COMPLETED (2026-02-01) |
+
+### Database
+
+| ID | Issue | Location | Status |
+|----|-------|----------|--------|
+| MED-DB-001 | Idempotency table missing index | database.py:3073-3081 | ✅ COMPLETED (2026-02-01) |
+| MED-DB-002 | get_namespaces() loads all values | database.py:2676 | ✅ CLOSED (Acceptable - TTL caching sufficient) |
+| MED-DB-003 | get_namespace_stats() loads all records | database.py:1839-1845 | ✅ COMPLETED (2026-02-01) |
+| MED-DB-004 | Vector dimension not validated at insert | database.py:1267-1336 | ✅ COMPLETED (2026-02-01) |
+| MED-DB-005 | No migration system | Project-wide | Backlog |
+
+### Architecture
+
+| ID | Issue | Location | Status |
+|----|-------|----------|--------|
+| MED-ARCH-001 | LifecycleService.consolidate complexity | lifecycle.py:520-752 | Backlog |
+| MED-ARCH-002 | SpatialMemoryServer.__init__ complexity | server.py:140-345 | Backlog |
+| MED-ARCH-003 | Tool handlers return untyped dicts | server.py:469-1012 | Backlog |
+| MED-ARCH-004 | Synchronous embedding in async context | server.py:355-423 | Backlog |
+
+---
+
+## Low Severity Issues
+
+| ID | Issue | Location | Status |
+|----|-------|----------|--------|
+| LOW-001 | Hardcoded embedding cache size (1000) | embeddings.py | ✅ COMPLETED (2026-02-01) |
+| LOW-002 | Inconsistent datetime handling | lifecycle.py | ✅ COMPLETED |
+| LOW-003 | Magic numbers in retry logic | database.py | ✅ COMPLETED (2026-02-01) |
+| LOW-004 | Missing validation for index_type | config.py | ✅ COMPLETED |
+| LOW-005 | Duplicate local imports | lancedb_repository.py | ✅ CLOSED (False Positive) |
+| LOW-006 | validate_namespace docstring mismatch | validation.py | ✅ COMPLETED |
+| LOW-007 | Test mocks return non-normalized vectors | conftest.py | ✅ COMPLETED |
+| LOW-008 | Memory content not validated for injection | validation.py | ✅ COMPLETED (Documented as by-design) |
+| LOW-009 | Metadata values not deeply validated | validation.py | ✅ COMPLETED |
+| LOW-010 | Exception messages may leak paths | Various | ✅ COMPLETED |
+| LOW-011 | Connection pool never validates health | connection_pool.py | ✅ COMPLETED |
+| LOW-012 | Database.close() doesn't remove from pool | database.py | ✅ COMPLETED |
+| LOW-013 | No automatic compaction scheduling | database.py | ✅ COMPLETED |
+| LOW-014 | Stop words set recreated per call | spatial.py | ✅ COMPLETED (2026-02-01) |
+| LOW-015 | MD5 for cache keys | embeddings.py | ✅ COMPLETED (2026-02-01) |
+
+---
+
+## Implementation Phases
+
+### Phase 1: Critical Issues + Quick Wins ✅ COMPLETE
+**Completed:** 2026-02-01
+**Issues:** CRIT-001, CRIT-002, HIGH-010
+
+### Phase 2: Batch Operations Infrastructure ✅ COMPLETE
+**Completed:** 2026-02-02
+**Issues:** HIGH-001, HIGH-003, HIGH-005, HIGH-006
+
+### Phase 3: Remaining High Severity ✅ COMPLETE
+**Completed:** 2026-02-02
+**Issues:** HIGH-002, HIGH-004, HIGH-007, HIGH-008, HIGH-009
+
+### Phase 4: Medium Severity ✅ COMPLETE
+**Completed:** 2026-02-01
+**Issues:** MED-SEC-002, MED-CQ-001-004, MED-DB-001, MED-DB-003, MED-DB-004
+
+### Phase 5: Low Severity ✅ COMPLETE
+**Completed:** 2026-02-01
+**Issues:** LOW-001, LOW-003, LOW-014, LOW-015
+
+---
+
+## Summary
+
+**All Critical, High, and most Low severity issues have been resolved.**
+
+| Category | Resolved | Backlog |
+|----------|----------|---------|
+| Critical | 2/2 | 0 |
+| High | 10/10 | 0 |
+| Medium | 8/18 | 8 (architecture items) |
+| Low | 15/15 | 0 |
+
+Remaining backlog items are Medium severity architectural improvements (refactoring, migration system) that don't affect functionality or data integrity.
+
+---
+
+## Change Log
+
+| Date | Issue | Change | Author |
+|------|-------|--------|--------|
+| 2026-02-01 | All | Initial tracking document created | Claude |
+| 2026-02-01 | All | Solution plans added for Critical and High severity | Claude |
+| 2026-02-01 | MED-SEC-001 | Closed as "By Design" - single-developer local use | Claude |
+| 2026-02-01 | HIGH-010 | Decision: Single-machine only with detection/warning | User |
+| 2026-02-01 | CRIT-001 | Decision: Add-before-delete pattern | User |
+| 2026-02-01 | CRIT-001 | ✅ Implemented add-before-delete pattern in consolidation | Claude |
+| 2026-02-01 | CRIT-002 | ✅ Plumbed include_vector through search pipeline (also fixes HIGH-001) | Claude |
+| 2026-02-01 | HIGH-010 | ✅ Added NFS/SMB detection and warning at startup | Claude |
+| 2026-02-02 | Phase 2 | ✅ Implemented batch operations: get_batch, update_batch, batch_vector_search | Claude |
+| 2026-02-02 | Phase 3 | ✅ Implemented scipy.cdist, batch embedding, atomic insert, namespace rollback, streaming consolidation | Claude |
+| 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-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 |  |
+|  | LOW-005 | Closed as FALSE POSITIVE (intentional circular import avoidance) |  |
+|  | LOW-006 | Fixed validate_namespace docstring |  |
+|  | 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 pool |  |
+|  | LOW-013 | Implemented auto-compaction |  |
+|  | MED-DB-002 | Closed as ACCEPTABLE (TTL caching sufficient) |  |
+
+---
+
+## References
+
+- [LanceDB Batch Search Documentation](https://docs.lancedb.com/search/vector-search)
+- [LanceDB merge_insert API](https://lancedb.github.io/lancedb/python/python/)
+- Code Review Report: Saved to spatial-memory namespace (memory ID: 55cd072b-8bc6-4426-a80b-fa07edaee7e7)

spatial_memory_mcp-1.6.0/MARKETING.md

@@ -0,0 +1,246 @@
+# Spatial Memory MCP
+
+## Knowledge as a Navigable Landscape, Not a Filing Cabinet
+
+**The first semantic memory system designed for how LLMs actually think.**
+
+---
+
+## The Problem with Memory Today
+
+Every AI memory solution asks the same question: "How do we store things so we can find them later?"
+
+Wrong question.
+
+The right question is: "How do we give AI systems memory that works like memory—with forgetting, reinforcement, association, and discovery?"
+
+Spatial Memory MCP answers that question.
+
+---
+
+## Zero Cognitive Load: Memory That Just Works
+
+Most memory systems require developers to explicitly manage storage, retrieval, and organization. Spatial Memory MCP takes a radically different approach.
+
+**You never think about memory. Claude handles everything automatically.**
+
+Here's how it works:
+
+1. **Automatic Context Loading** — Claude loads relevant memories at session start. No initialization code. No explicit queries.
+
+2. **Intelligent Recognition** — Claude recognizes memory-worthy moments in conversation and asks simply: "Save this decision? y/n"
+
+3. **Natural Synthesis** — When you ask about past context, Claude synthesizes answers naturally. No raw JSON. No memory IDs. Just knowledge.
+
+4. **MCP Instructions Injection** — Memory behaviors are injected directly into Claude's system prompt. Zero configuration required.
+
+The result? Developers interact with an AI that genuinely remembers—without writing a single line of memory management code.
+
+---
+
+## 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.
+
+### 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.
+
+### Reinforcement Learning
+Memories grow stronger through use. Every access, every retrieval, every reference boosts importance scores. Frequently needed knowledge rises to the surface. Additive, multiplicative, or explicit value boosts—you control the reinforcement dynamics.
+
+### Consolidation
+Similar memories merge intelligently. Four strategies available:
+- **keep_newest** — Preserve recent knowledge
+- **keep_oldest** — Maintain original context
+- **keep_highest_importance** — Prioritize what matters
+- **merge_content** — Synthesize into unified memories
+
+### Auto-Extraction
+Point the system at a conversation transcript. It extracts facts, decisions, and key information automatically. Pattern matching identifies what's worth remembering. Deduplication prevents redundancy.
+
+---
+
+## Spatial Navigation: The Innovation That Changes Everything
+
+Here's what makes Spatial Memory MCP fundamentally different: **knowledge exists in semantic space, and you can navigate it.**
+
+### Journey (SLERP Interpolation)
+Navigate between two memories using spherical interpolation. Discover what's conceptually *between* them. Start with "machine learning basics" and end with "production deployment"—Journey reveals the learning path: feature engineering, model validation, containerization, monitoring.
+
+### Wander (Temperature-Based Random Walk)
+Serendipitous exploration through memory space. Low temperature: focused, related concepts. High temperature: unexpected connections. Set a starting point or start anywhere. Let the system surprise you with what it finds.
+
+### Regions (HDBSCAN Clustering)
+Automatic topic discovery without predefined labels. The system identifies natural clusters in your knowledge base. Returns representative memories and auto-generated keywords for each region. See how your knowledge self-organizes.
+
+### Visualize (UMAP Projection)
+Project your memories into 2D or 3D space. Export as JSON, Mermaid diagrams, or SVG. See your knowledge landscape. Identify gaps. Understand relationships.
+
+**No other memory system offers this.** Competitors give you search. We give you exploration.
+
+---
+
+## 21 Tools. Complete Lifecycle Management.
+
+| Category | Spatial Memory MCP | Typical Competitor |
+|----------|-------------------|-------------------|
+| Core Operations | remember, recall, forget, nearby | 3-4 tools |
+| Batch Operations | remember_batch, forget_batch | None |
+| Spatial Navigation | journey, wander, regions, visualize | None |
+| Lifecycle Management | decay, reinforce, consolidate, extract | None |
+| Hybrid Search | hybrid_recall with tunable alpha | Single mode |
+| Namespace Management | namespaces, delete_namespace, rename_namespace | Basic or none |
+| 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.
+
+---
+
+## Hybrid Search: The Best of Both Worlds
+
+Semantic search finds conceptually similar content. Keyword search finds exact matches. Why choose?
+
+**Spatial Memory MCP's hybrid_recall** combines both with a tunable alpha parameter:
+
+- `alpha = 1.0` — Pure semantic search
+- `alpha = 0.5` — Balanced hybrid
+- `alpha = 0.0` — Pure keyword search
+
+Search for "authentication error handling" and find both semantically related security discussions AND exact keyword matches in error logs. One query. Complete results.
+
+---
+
+## Enterprise-Grade Infrastructure
+
+Production deployment demands production infrastructure.
+
+### Connection Management
+- **Connection pooling** with LRU eviction
+- **Cross-process file locking** for multi-instance safety
+- **Circuit breaker pattern** prevents cascade failures
+
+### Observability
+- **Request tracing** with correlation IDs
+- **Per-agent rate limiting** using token bucket algorithm
+- **Response caching** with configurable TTL
+- **Health endpoints** with detailed diagnostics
+
+### Security
+- **Path traversal prevention** — No filesystem escapes
+- **SQL injection detection** — 15+ attack patterns blocked
+- **Input validation** — Pydantic models throughout
+- **Credential masking** — Sensitive data never logged
+- **Dry-run modes** — Preview destructive operations safely
+
+---
+
+## Performance by Default
+
+### ONNX Runtime
+2.75x faster than PyTorch. 60% less memory. No GPU required. CPU inference that actually performs.
+
+### Intelligent Indexing
+Auto-indexing triggers at 10K+ memories using IVF_PQ. Sub-linear search complexity at scale. Configurable thresholds for your workload.
+
+### Efficient Defaults
+- **all-MiniLM-L6-v2** embedding model (~80MB)
+- Fast inference, quality embeddings
+- Batch operations for bulk ingestion
+- Connection pooling eliminates overhead
+
+---
+
+## Competitor Landscape
+
+| Feature | Spatial Memory MCP | mcp-mem0 | mcp-memory-service | Memory Bank MCP |
+|---------|-------------------|----------|-------------------|-----------------|
+| Total Tools | 21 | 3 | ~6 | ~5 |
+| Spatial Navigation | Yes | No | No | No |
+| Memory Decay | Yes | No | No | No |
+| Reinforcement | Yes | No | No | No |
+| Hybrid Search | Yes | No | Partial | No |
+| Batch Operations | Yes | No | No | No |
+| HDBSCAN Clustering | Yes | No | No | No |
+| 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 |
+
+**mcp-mem0**: 3 tools, 4 commits, requires PostgreSQL infrastructure.
+
+**mcp-memory-service**: No spatial navigation, no lifecycle management, limited cognitive features.
+
+**Memory Bank MCP**: Go-based, no cognitive memory model, basic CRUD operations.
+
+**basic-memory**: No vector search, file-based limitations, no semantic understanding.
+
+---
+
+## Use Cases
+
+### Development Teams
+Maintain architectural decisions across sessions. Remember why you chose that database, that API design, that authentication pattern. Never repeat the same discussion. Never lose hard-won context.
+
+### AI Agents
+Long-running agents that learn and adapt. Remember user preferences. Track conversation history. Build genuine relationships through persistent, intelligent memory.
+
+### Knowledge Management
+Transform organizational knowledge into a navigable landscape. Let teams explore connections they didn't know existed. Surface relevant context automatically.
+
+### Research and Analysis
+Navigate between concepts. Discover intermediate ideas. Visualize knowledge structures. Enable serendipitous discovery that filing systems can never provide.
+
+---
+
+## Technical Specifications
+
+- **Language**: Python 3.10+
+- **Database**: SQLite with LanceDB for vectors
+- **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
+
+---
+
+## Getting Started
+
+```bash
+# Install
+pip install spatial-memory-mcp
+
+# Or with UV
+uv pip install spatial-memory-mcp
+```
+
+Configure in Claude Desktop's MCP settings. The system injects its instructions automatically. Start a conversation. Claude remembers.
+
+No initialization code. No explicit memory calls. No cognitive overhead.
+
+**Just memory that works like memory should.**
+
+---
+
+## The Bottom Line
+
+Most AI memory systems are databases with an API. Spatial Memory MCP is a cognitive architecture.
+
+It decays. It reinforces. It consolidates. It discovers.
+
+It treats knowledge as a navigable landscape—not a filing cabinet.
+
+And it does all of this with zero cognitive load on developers. Claude handles memory. You handle what matters.
+
+---
+
+**Spatial Memory MCP**
+
+*Knowledge as a navigable landscape, not a filing cabinet.*
+
+[GitHub Repository](https://github.com/arman-tech/spatial-memory-mcp) | [Documentation](https://github.com/arman-tech/spatial-memory-mcp#readme) | [PyPI](https://pypi.org/project/spatial-memory-mcp/)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.0.3
+Version: 1.6.0
 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
@@ -44,7 +44,7 @@ Description-Content-Type: text/markdown
 
 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 1094 tests passing.
+> **Project Status**: All phases complete. Production-ready with 1360 tests passing.
 
 ## Supported Platforms
 
@@ -63,6 +63,42 @@ Spatial Memory MCP Server provides persistent, semantic memory for LLMs through
 - **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 |
+
+### 21 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
 
 - **21 MCP tools** across 4 categories (core, spatial, lifecycle, utility)
@@ -72,7 +108,7 @@ Spatial Memory MCP Server provides persistent, semantic memory for LLMs through
 - **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
-- **1094 tests** including security edge cases
+- **1360 tests** including security edge cases
 
 ## Roadmap
 
@@ -130,6 +166,31 @@ If ONNX shows as unavailable, reinstall with:
 pip install --force-reinstall "sentence-transformers[onnx]"
 ```
 
+### 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:
@@ -292,6 +353,25 @@ Export all memories to parquet format
 - **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