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

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.9.0}/.env.example

@@ -96,6 +96,16 @@
 # Days without access before decay starts
 # SPATIAL_MEMORY_DECAY_DAYS_THRESHOLD=30
 
+# =============================================================================
+# AUTO-DECAY SETTINGS
+# =============================================================================
+
+# Decay function: exponential (default), linear, or step
+# - exponential: Smooth decay following 2^(-t/half_life), best for most use cases
+# - linear: Constant rate decay reaching 0 at 2x half_life
+# - step: Discrete drops at half_life intervals (1.0 -> 0.5 -> 0.25)
+# SPATIAL_MEMORY_AUTO_DECAY_FUNCTION=exponential
+
 # =============================================================================
 # CLUSTERING (HDBSCAN)
 # =============================================================================

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.9.0}/.gitignore

@@ -138,6 +138,7 @@ cython_debug/
 # OS
 .DS_Store
 Thumbs.db
+nul
 
 # Project specific
 *.lancedb/
@@ -145,6 +146,16 @@ Thumbs.db
 data/
 memories/
 .spatial-memory/
+.spatial-memory-test/
+.demo-memory/
+temp_test/
+stubs/
+
+# Internal development docs (not for public repo)
+ISSUES-TRACKER.md
+PHASE*_PLAN.md
+LIFECYCLE_PHASE_PLAN.md
+*-SERVER-PLAN*.md
 
 # Secrets
 .env.local

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.9.0}/CHANGELOG.md

@@ -11,6 +11,88 @@ 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.9.0] - 2026-02-02
+
+### Breaking Changes
+- **Stricter Namespace Validation**: Namespaces now follow DNS label conventions
+  - Must start with a letter (a-z, A-Z)
+  - Can only contain letters, numbers, dashes, and underscores
+  - Maximum 63 characters (was 256)
+  - **Dots no longer allowed** - use underscores instead (e.g., `ns_v1` not `ns.v1`)
+  - **Numeric start no longer allowed** - must start with letter
+
+### Added
+- **Getting Started Tutorial**: New `docs/GETTING_STARTED.md` with step-by-step guide
+- **Dependency Lock File**: `requirements.lock` with 79 pinned packages for reproducible builds
+- **PyPI Metadata**: Added Documentation, Changelog, and Bug Tracker URLs to pyproject.toml
+
+### Changed
+- **Consolidated Namespace Validation**: Single canonical pattern across all modules
+  - `validation.py` now exports `NAMESPACE_PATTERN` used by `import_security.py`
+  - Consistent error messages with clear format requirements
+- **mypy Configuration**: Replaced outdated `stubs/` directory with module overrides
+  - External libraries (lancedb, pyarrow, hdbscan, etc.) now use `ignore_missing_imports`
+  - All 49 source files pass strict mypy checks
+
+### Fixed
+- Resolved mypy configuration issue where deleted `stubs/` directory was still referenced
+
+## [1.8.0] - 2026-02-02
+
+### Added
+- **Unified Decay System**: Auto-decay and manual decay now use the same algorithm
+  - New `SPATIAL_MEMORY_AUTO_DECAY_FUNCTION` config option to choose decay function
+  - Supported functions: `exponential` (default), `linear`, `step`
+  - Consistent behavior regardless of code path (auto-decay vs manual `decay` tool)
+  - Adaptive half-life based on access count and importance
+- New `decay_function` field in `AutoDecayConfig` model
+
+### Changed
+- `DecayManager` now uses `calculate_decay_factor()` from `lifecycle_ops.py` instead of a separate implementation
+- Auto-decay effective half-life now considers both access count (1.5× per access) and importance factor (1 + importance)
+
+### Fixed
+- **Type Safety**: Resolved all mypy errors in main source code (49 source files)
+  - Added proper type annotations for numpy operations returning `Any`
+  - Fixed protocol type assignments in factory.py
+  - Added `__all__` exports to service modules
+  - Fixed type narrowing issues with optional database connections
+- **Code Quality**: Resolved all ruff linting errors in test files (45 issues)
+  - Fixed import ordering (E402) by moving `pytestmark` after imports
+  - Removed unused variable assignments (F841)
+  - Fixed lines exceeding 100 characters (E501)
+
+### Documentation
+- Updated `docs/CONFIGURATION.md` with `SPATIAL_MEMORY_AUTO_DECAY_FUNCTION` option
+- Updated `.env.example` with decay function configuration examples
+
+## [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

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

@@ -173,7 +173,7 @@ Auto-indexing triggers at 10K+ memories using IVF_PQ. Sub-linear search complexi
 | Visualization | Yes | No | No | No |
 | Enterprise Features | Full Suite | Minimal | Basic | Basic |
 | External Dependencies | None (embedded) | PostgreSQL | Varies | File-based |
-| Test Coverage | 1,360 tests | Minimal | Unknown | Unknown |
+| Test Coverage | 1,400+ tests | Minimal | Unknown | Unknown |
 
 **mcp-mem0**: 3 tools, 4 commits, requires PostgreSQL infrastructure.
 
@@ -211,8 +211,8 @@ Navigate between concepts. Discover intermediate ideas. Visualize knowledge stru
 - **Interpolation**: SLERP (Spherical Linear Interpolation)
 - **Architecture**: Clean architecture with dependency injection
 - **Type Safety**: Full type hints, mypy strict mode
-- **Test Suite**: 1,360 passing tests
-- **Version**: 1.6.2
+- **Test Suite**: 1,400+ passing tests
+- **Version**: 1.7.0
 
 ---
 

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

@@ -1,9 +1,12 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.6.2
+Version: 1.9.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
+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
@@ -48,7 +51,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.2** — Production-ready with 1,360 tests passing.
+> **Version 1.8.0** — Production-ready with 1,400+ tests passing.
 
 ## Supported Platforms
 
@@ -64,6 +67,7 @@ Spatial Memory MCP Server provides persistent, semantic memory for LLMs through
 - **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
 
@@ -112,7 +116,7 @@ Connection pooling, circuit breakers, per-agent rate limiting, request tracing,
 - **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
-- **1360 tests** including security edge cases
+- **1400+ tests** including security edge cases
 
 ## Roadmap
 
@@ -123,7 +127,7 @@ 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 | Complete | v1.6.0 on PyPI |
+| Phase 6: Polish & Release | Complete | v1.8.0 on PyPI |
 
 ## Installation
 
@@ -248,6 +252,11 @@ cp .env.example .env
 | `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
 
@@ -459,6 +468,7 @@ See [SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md](SPATIAL-MEMORY-ARCHITECTURE-DIAGRA
 | 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 |

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.9.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.2** — Production-ready with 1,360 tests passing.
+> **Version 1.8.0** — Production-ready with 1,400+ tests passing.
 
 ## Supported Platforms
 
@@ -22,6 +22,7 @@ Spatial Memory MCP Server provides persistent, semantic memory for LLMs through
 - **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
 
@@ -70,7 +71,7 @@ Connection pooling, circuit breakers, per-agent rate limiting, request tracing,
 - **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
-- **1360 tests** including security edge cases
+- **1400+ tests** including security edge cases
 
 ## Roadmap
 
@@ -81,7 +82,7 @@ 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 | Complete | v1.6.0 on PyPI |
+| Phase 6: Polish & Release | Complete | v1.8.0 on PyPI |
 
 ## Installation
 
@@ -206,6 +207,11 @@ cp .env.example .env
 | `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
 
@@ -417,6 +423,7 @@ See [SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md](SPATIAL-MEMORY-ARCHITECTURE-DIAGRA
 | 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 |

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.9.0}/docs/API.md

@@ -1,6 +1,6 @@
 # Spatial Memory MCP Server - API Reference
 
-Complete reference documentation for all 21 MCP tools provided by the Spatial Memory server.
+Complete reference documentation for all 22 MCP tools provided by the Spatial Memory server.
 
 ## Table of Contents
 
@@ -41,11 +41,11 @@ Complete reference documentation for all 21 MCP tools provided by the Spatial Me
 
 ### Tool Categories
 
-The 21 tools are organized into four categories:
+The 22 tools are organized into four categories:
 
 | Category | Tools | Purpose |
 |----------|-------|---------|
-| **Core** | 6 | Basic CRUD operations for memories |
+| **Core** | 7 | Basic CRUD operations for memories (includes health) |
 | **Spatial** | 4 | Navigation and exploration of memory space |
 | **Lifecycle** | 4 | Memory maintenance and evolution |
 | **Utility** | 7 | Administration, export/import, and hybrid search |

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.9.0}/docs/BENCHMARKS.md

@@ -23,7 +23,7 @@ Benchmark results for the Spatial Memory MCP Server on Windows 11.
 | **Latency** | Remember (single) | 8.4 ms mean |
 | **Latency** | Recall (limit=5) | 57 ms mean |
 | **Latency** | Nearby | 7.4 ms mean |
-| **Tool Coverage** | Functional tests | 18/21 passed (85.7%) |
+| **Tool Coverage** | Functional tests | 19/22 passed (86.4%) |
 
 ---
 
@@ -106,9 +106,9 @@ Benchmark results for the Spatial Memory MCP Server on Windows 11.
 
 ## Tool Functional Test Results
 
-All 21 tools were tested systematically. Results:
+All 22 tools were tested systematically. Results:
 
-### Passing Tools (18/21)
+### Passing Tools (19/22)
 
 | Category | Tool | Status | Latency |
 |----------|------|--------|---------|
@@ -124,6 +124,7 @@ All 21 tools were tested systematically. Results:
 | Lifecycle | reinforce | PASS | 12.5 ms |
 | Lifecycle | extract | PASS | 39.2 ms |
 | Lifecycle | consolidate | PASS | 8.1 ms |
+| Lifecycle | decay | PASS | ~10 ms |
 | Utility | stats | PASS | 8.3 ms |
 | Utility | namespaces | PASS | 6.5 ms |
 | Utility | delete_namespace | PASS | 1.1 ms |
@@ -131,15 +132,15 @@ All 21 tools were tested systematically. Results:
 | Utility | hybrid_recall | PASS | 5.7 ms |
 | Utility | health | PASS | 7.6 ms |
 
-### Failing Tools (3/21)
+### Failing Tools (3/22)
 
 | Tool | Error | Root Cause |
 |------|-------|------------|
 | journey | `distance_to_path` validation | Floating point precision (-4.89e-08) |
-| decay | Datetime subtraction error | Timezone naive vs aware mismatch |
 | export_memories | Path security violation | Test path under C:\Users blocked |
+| import_memories | Not tested | Missing from benchmark suite |
 
-**Note:** These failures are edge cases in test conditions, not fundamental issues. The journey and decay bugs should be fixed in a future patch.
+**Note:** These failures are edge cases in test conditions, not fundamental issues. The `decay` timezone bug was fixed in v1.7.0.
 
 ---
 

spatial_memory_mcp-1.9.0/docs/CONFIGURATION.md

@@ -0,0 +1,251 @@
+# 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 |
+| `SPATIAL_MEMORY_AUTO_DECAY_FUNCTION` | `exponential` | Decay function: `exponential`, `linear`, or `step` |
+
+### How Auto-Decay Works
+
+1. **Configurable Decay Function**: Choose from `exponential`, `linear`, or `step`
+   - `exponential`: Smooth decay following `2^(-t/half_life)`, best for most use cases
+   - `linear`: Constant rate decay reaching 0 at 2x half_life
+   - `step`: Discrete drops at half_life intervals (1.0 → 0.5 → 0.25)
+2. **Default Half-Life**: 30 days (memory loses 50% importance after 30 days without access)
+3. **Adaptive Half-Life**: Access count and importance affect decay rate
+   - Frequently accessed memories decay slower (1.5× half-life per access, up to 20)
+   - Higher importance memories also 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.