spatial-memory-mcp 1.6.1__tar.gz → 1.7.0__tar.gz

{spatial_memory_mcp-1.6.1 → spatial_memory_mcp-1.7.0}/.gitignore

@@ -138,6 +138,7 @@ cython_debug/
 # OS
 .DS_Store
 Thumbs.db
+nul
 
 # Project specific
 *.lancedb/

{spatial_memory_mcp-1.6.1 → spatial_memory_mcp-1.7.0}/CHANGELOG.md

@@ -11,6 +11,52 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Medium severity architectural improvements (MED-ARCH-001 through MED-ARCH-004)
 - Migration system (MED-DB-005)
 
+## [1.7.0] - 2026-02-02
+
+### Added
+- **Auto-Decay Feature**: Automatic time-based importance decay during recall operations
+  - Memories automatically lose importance over time if not accessed (exponential decay)
+  - `effective_importance` field added to `recall` and `hybrid_recall` responses
+  - Results re-ranked by `similarity × effective_importance` to favor recent memories
+  - Background persistence thread batches and saves decay updates to database
+  - Configurable via environment variables:
+    - `SPATIAL_MEMORY_AUTO_DECAY_ENABLED` (default: true)
+    - `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED` (default: true)
+    - `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_BATCH_SIZE` (default: 100)
+    - `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_FLUSH_INTERVAL_SECONDS` (default: 5.0)
+    - `SPATIAL_MEMORY_AUTO_DECAY_MIN_CHANGE_THRESHOLD` (default: 0.01)
+    - `SPATIAL_MEMORY_AUTO_DECAY_MAX_QUEUE_SIZE` (default: 10000)
+  - Access count slows decay: frequently accessed memories stay relevant longer
+  - Minimum importance floor prevents memories from decaying to zero
+- Configuration documentation (`docs/CONFIGURATION.md`)
+  - Complete reference for all environment variables
+  - Examples for `.mcp.json`, Claude Desktop, and `.env` files
+  - Auto-decay configuration guide
+- Test script for verifying auto-decay (`scripts/test_auto_decay.py`)
+
+### Changed
+- `MemoryResultDict` and `HybridMemoryDict` response types now include optional `effective_importance` field
+- `MemoryResult` and `HybridMemoryMatch` models now include `last_accessed` and `access_count` fields
+
+## [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_mcp-1.6.1 → spatial_memory_mcp-1.7.0}/MARKETING.md

@@ -212,7 +212,7 @@ Navigate between concepts. Discover intermediate ideas. Visualize knowledge stru
 - **Architecture**: Clean architecture with dependency injection
 - **Type Safety**: Full type hints, mypy strict mode
 - **Test Suite**: 1,360 passing tests
-- **Version**: 1.6.0
+- **Version**: 1.6.2
 
 ---
 

{spatial_memory_mcp-1.6.1 → spatial_memory_mcp-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.6.1
+Version: 1.7.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
@@ -48,7 +48,7 @@ Description-Content-Type: text/markdown
 
 A vector-based spatial memory system that treats knowledge as a navigable landscape, not a filing cabinet.
 
-> **Version 1.6.1** — Production-ready with 1,360 tests passing.
+> **Version 1.6.2** — Production-ready with 1,360 tests passing.
 
 ## Supported Platforms
 

{spatial_memory_mcp-1.6.1 → spatial_memory_mcp-1.7.0}/README.md

@@ -6,7 +6,7 @@
 
 A vector-based spatial memory system that treats knowledge as a navigable landscape, not a filing cabinet.
 
-> **Version 1.6.1** — Production-ready with 1,360 tests passing.
+> **Version 1.6.2** — Production-ready with 1,360 tests passing.
 
 ## Supported Platforms
 

spatial_memory_mcp-1.7.0/docs/CONFIGURATION.md

@@ -0,0 +1,245 @@
+# Configuration Guide
+
+Spatial Memory MCP Server is configured via environment variables with the `SPATIAL_MEMORY_` prefix.
+
+## Configuration Methods
+
+### 1. `.mcp.json` (Recommended for MCP Clients)
+
+Create a `.mcp.json` file in your project root:
+
+```json
+{
+  "mcpServers": {
+    "spatial-memory": {
+      "command": "spatial-memory",
+      "env": {
+        "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "true",
+        "SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED": "false",
+        "SPATIAL_MEMORY_LOG_LEVEL": "INFO"
+      }
+    }
+  }
+}
+```
+
+### 2. Claude Desktop Configuration
+
+Edit `claude_desktop_config.json`:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "spatial-memory": {
+      "command": "spatial-memory",
+      "env": {
+        "SPATIAL_MEMORY_MEMORY_PATH": "/path/to/storage",
+        "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+### 3. Environment Variables
+
+```bash
+# Export before running
+export SPATIAL_MEMORY_AUTO_DECAY_ENABLED=true
+export SPATIAL_MEMORY_LOG_LEVEL=DEBUG
+spatial-memory
+```
+
+Or inline:
+
+```bash
+SPATIAL_MEMORY_AUTO_DECAY_ENABLED=false spatial-memory
+```
+
+### 4. `.env` File
+
+Create a `.env` file in your working directory:
+
+```env
+SPATIAL_MEMORY_MEMORY_PATH=./.spatial-memory
+SPATIAL_MEMORY_LOG_LEVEL=INFO
+SPATIAL_MEMORY_AUTO_DECAY_ENABLED=true
+SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED=true
+```
+
+---
+
+## Configuration Reference
+
+### Storage
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_MEMORY_PATH` | `./.spatial-memory` | Path to LanceDB storage directory |
+| `SPATIAL_MEMORY_ACKNOWLEDGE_NETWORK_FILESYSTEM_RISK` | `false` | Suppress network filesystem warnings |
+
+### Embedding Model
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Model name or `openai:model-name` |
+| `SPATIAL_MEMORY_EMBEDDING_DIMENSIONS` | `384` | Vector dimensions (auto-detected) |
+| `SPATIAL_MEMORY_EMBEDDING_BACKEND` | `auto` | Backend: `auto`, `onnx`, or `pytorch` |
+
+### OpenAI (Optional)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_OPENAI_API_KEY` | `null` | OpenAI API key for embeddings |
+| `SPATIAL_MEMORY_OPENAI_EMBEDDING_MODEL` | `text-embedding-3-small` | OpenAI model to use |
+
+### Server
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `SPATIAL_MEMORY_LOG_FORMAT` | `text` | Log format: `text` or `json` |
+
+### Memory Defaults
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_DEFAULT_NAMESPACE` | `default` | Default namespace for memories |
+| `SPATIAL_MEMORY_DEFAULT_IMPORTANCE` | `0.5` | Default importance (0.0-1.0) |
+
+### Limits
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_MAX_BATCH_SIZE` | `100` | Max memories per batch operation |
+| `SPATIAL_MEMORY_MAX_RECALL_LIMIT` | `100` | Max results from recall |
+| `SPATIAL_MEMORY_MAX_JOURNEY_STEPS` | `20` | Max steps in journey |
+| `SPATIAL_MEMORY_MAX_WANDER_STEPS` | `20` | Max steps in wander |
+
+---
+
+## Auto-Decay Settings
+
+Auto-decay automatically reduces the importance of memories over time, favoring recently accessed memories in search results.
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SPATIAL_MEMORY_AUTO_DECAY_ENABLED` | `true` | Enable decay calculation during recall |
+| `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED` | `true` | Save decayed values to database |
+| `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_BATCH_SIZE` | `100` | Batch size for persistence |
+| `SPATIAL_MEMORY_AUTO_DECAY_PERSIST_FLUSH_INTERVAL_SECONDS` | `5.0` | How often to flush updates (seconds) |
+| `SPATIAL_MEMORY_AUTO_DECAY_MIN_CHANGE_THRESHOLD` | `0.01` | Min change to trigger persist (1%) |
+| `SPATIAL_MEMORY_AUTO_DECAY_MAX_QUEUE_SIZE` | `10000` | Max queued updates |
+
+### How Auto-Decay Works
+
+1. **Exponential Decay**: `effective_importance = importance × 2^(-days_since_access / half_life)`
+2. **Default Half-Life**: 30 days (memory loses 50% importance after 30 days without access)
+3. **Access Count Bonus**: Frequently accessed memories decay slower
+4. **Minimum Floor**: Importance never drops below 10%
+
+### Example Configurations
+
+**Disable auto-decay entirely:**
+```json
+{
+  "env": {
+    "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "false"
+  }
+}
+```
+
+**Enable decay calculation but don't persist changes:**
+```json
+{
+  "env": {
+    "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "true",
+    "SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED": "false"
+  }
+}
+```
+
+**Aggressive persistence (frequent flushes):**
+```json
+{
+  "env": {
+    "SPATIAL_MEMORY_AUTO_DECAY_PERSIST_FLUSH_INTERVAL_SECONDS": "1.0",
+    "SPATIAL_MEMORY_AUTO_DECAY_MIN_CHANGE_THRESHOLD": "0.001"
+  }
+}
+```
+
+---
+
+## Full Example: `.mcp.json`
+
+```json
+{
+  "mcpServers": {
+    "spatial-memory": {
+      "command": "spatial-memory",
+      "env": {
+        "SPATIAL_MEMORY_MEMORY_PATH": "./my-project-memory",
+        "SPATIAL_MEMORY_LOG_LEVEL": "INFO",
+        "SPATIAL_MEMORY_DEFAULT_NAMESPACE": "project",
+        "SPATIAL_MEMORY_DEFAULT_IMPORTANCE": "0.5",
+        "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "true",
+        "SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+## Full Example: Claude Desktop
+
+```json
+{
+  "mcpServers": {
+    "spatial-memory": {
+      "command": "spatial-memory",
+      "env": {
+        "SPATIAL_MEMORY_MEMORY_PATH": "/Users/me/memories",
+        "SPATIAL_MEMORY_EMBEDDING_MODEL": "openai:text-embedding-3-small",
+        "SPATIAL_MEMORY_OPENAI_API_KEY": "sk-...",
+        "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "true"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Advanced Settings
+
+For power users, additional settings are available for:
+
+- **Indexing**: `SPATIAL_MEMORY_VECTOR_INDEX_THRESHOLD`, `SPATIAL_MEMORY_AUTO_CREATE_INDEXES`, `SPATIAL_MEMORY_INDEX_TYPE`
+- **Full-Text Search**: `SPATIAL_MEMORY_ENABLE_FTS_INDEX`, `SPATIAL_MEMORY_FTS_LANGUAGE`
+- **Rate Limiting**: `SPATIAL_MEMORY_RATE_LIMIT_PER_AGENT_ENABLED`, `SPATIAL_MEMORY_RATE_LIMIT_PER_AGENT_RATE`
+- **Circuit Breaker**: `SPATIAL_MEMORY_CIRCUIT_BREAKER_ENABLED`, `SPATIAL_MEMORY_CIRCUIT_BREAKER_FAILURE_THRESHOLD`
+- **Caching**: `SPATIAL_MEMORY_RESPONSE_CACHE_ENABLED`, `SPATIAL_MEMORY_RESPONSE_CACHE_MAX_SIZE`
+- **Manual Decay** (via `decay` tool): `SPATIAL_MEMORY_DECAY_DEFAULT_HALF_LIFE_DAYS`, `SPATIAL_MEMORY_DECAY_MIN_IMPORTANCE_FLOOR`
+- **Export/Import**: `SPATIAL_MEMORY_EXPORT_ALLOWED_PATHS`, `SPATIAL_MEMORY_IMPORT_MAX_FILE_SIZE_MB`
+
+See the full list in [`spatial_memory/config.py`](../spatial_memory/config.py).
+
+---
+
+## Verifying Configuration
+
+Check that your settings are applied by enabling debug logging:
+
+```json
+{
+  "env": {
+    "SPATIAL_MEMORY_LOG_LEVEL": "DEBUG"
+  }
+}
+```
+
+Then check the server logs for configuration values at startup.