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

{spatial_memory_mcp-1.6.2 → 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.2 → spatial_memory_mcp-1.7.0}/CHANGELOG.md

@@ -11,6 +11,33 @@ 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.6.2
+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

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.

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spatial-memory-mcp"
-version = "1.6.2"
+version = "1.7.0"
 description = "Spatial bidirectional persistent memory MCP server for LLMs - vector-based semantic memory as a navigable landscape"
 readme = "README.md"
 license = {text = "MIT"}

spatial_memory_mcp-1.7.0/scripts/test_auto_decay.py

@@ -0,0 +1,288 @@
+#!/usr/bin/env python
+"""Manual test script to verify auto-decay feature is working.
+
+Run from the project root:
+    python scripts/test_auto_decay.py
+
+This script demonstrates:
+1. Decay calculation based on memory age
+2. Access count slowing decay
+3. Re-ranking of results by effective importance
+"""
+
+import sys
+from pathlib import Path
+
+# Ensure we use the local development version, not installed package
+project_root = Path(__file__).parent.parent
+sys.path.insert(0, str(project_root))
+
+from datetime import timedelta
+
+from spatial_memory.core.models import AutoDecayConfig
+from spatial_memory.core.utils import utc_now
+from spatial_memory.services.decay_manager import DecayManager
+
+
+def print_header(title: str) -> None:
+    """Print a section header."""
+    print(f"\n{'='*60}")
+    print(f"  {title}")
+    print(f"{'='*60}\n")
+
+
+def test_basic_decay() -> None:
+    """Test that older memories have lower effective importance."""
+    print_header("Test 1: Basic Decay by Age")
+
+    config = AutoDecayConfig(
+        enabled=True,
+        persist_enabled=False,
+        half_life_days=30.0,
+        min_importance_floor=0.1,
+        access_weight=0.0,  # Disable access count effect for this test
+    )
+    decay_manager = DecayManager(repository=None, config=config)
+
+    now = utc_now()
+    results = [
+        {
+            "id": "1",
+            "content": "Fresh memory (just now)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": now,
+            "access_count": 0,
+        },
+        {
+            "id": "2",
+            "content": "30-day old memory (1 half-life)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": now - timedelta(days=30),
+            "access_count": 0,
+        },
+        {
+            "id": "3",
+            "content": "60-day old memory (2 half-lives)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": now - timedelta(days=60),
+            "access_count": 0,
+        },
+        {
+            "id": "4",
+            "content": "90-day old memory (3 half-lives)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": now - timedelta(days=90),
+            "access_count": 0,
+        },
+    ]
+
+    processed = decay_manager.apply_decay_to_results(results, rerank=False)
+
+    print("All memories have same similarity (0.9) and stored importance (1.0)")
+    print("Half-life: 30 days\n")
+
+    for r in processed:
+        eff = r["effective_importance"]
+        decay_pct = (1.0 - eff) * 100
+        print(f"  {r['content']}")
+        print(f"    effective_importance: {eff:.4f} ({decay_pct:.1f}% decayed)")
+        print()
+
+    # Verify decay is working
+    assert processed[0]["effective_importance"] > processed[1]["effective_importance"]
+    assert processed[1]["effective_importance"] > processed[2]["effective_importance"]
+    assert processed[2]["effective_importance"] > processed[3]["effective_importance"]
+    print("PASS: Older memories have lower effective importance")
+
+
+def test_access_count_slows_decay() -> None:
+    """Test that frequently accessed memories decay slower."""
+    print_header("Test 2: Access Count Slows Decay")
+
+    config = AutoDecayConfig(
+        enabled=True,
+        persist_enabled=False,
+        half_life_days=30.0,
+        min_importance_floor=0.1,
+        access_weight=0.3,  # Each access adds 30% to half-life
+    )
+    decay_manager = DecayManager(repository=None, config=config)
+
+    now = utc_now()
+    past = now - timedelta(days=30)  # 30 days ago
+
+    results = [
+        {
+            "id": "1",
+            "content": "Rarely accessed (0 times)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": past,
+            "access_count": 0,
+        },
+        {
+            "id": "2",
+            "content": "Sometimes accessed (10 times)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": past,
+            "access_count": 10,
+        },
+        {
+            "id": "3",
+            "content": "Frequently accessed (50 times)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": past,
+            "access_count": 50,
+        },
+    ]
+
+    processed = decay_manager.apply_decay_to_results(results, rerank=False)
+
+    print("All memories are 30 days old with same similarity and stored importance")
+    print("access_weight: 0.3 (each access adds 30% to effective half-life)\n")
+
+    for r in processed:
+        eff = r["effective_importance"]
+        access = r["access_count"]
+        effective_half_life = 30.0 * (1.0 + 0.3 * access)
+        print(f"  {r['content']}")
+        print(f"    access_count: {access}")
+        print(f"    effective_half_life: {effective_half_life:.1f} days")
+        print(f"    effective_importance: {eff:.4f}")
+        print()
+
+    # Verify access count slows decay
+    assert processed[2]["effective_importance"] > processed[1]["effective_importance"]
+    assert processed[1]["effective_importance"] > processed[0]["effective_importance"]
+    print("PASS: Frequently accessed memories decay slower")
+
+
+def test_reranking() -> None:
+    """Test that results are re-ranked by similarity * effective_importance."""
+    print_header("Test 3: Re-ranking by Adjusted Score")
+
+    config = AutoDecayConfig(
+        enabled=True,
+        persist_enabled=False,
+        half_life_days=30.0,
+        min_importance_floor=0.1,
+        access_weight=0.0,
+    )
+    decay_manager = DecayManager(repository=None, config=config)
+
+    now = utc_now()
+
+    # Old memory has higher similarity but will be outranked due to decay
+    results = [
+        {
+            "id": "old",
+            "content": "Old but highly similar",
+            "similarity": 0.95,  # Higher similarity
+            "importance": 1.0,
+            "last_accessed": now - timedelta(days=60),  # 60 days old
+            "access_count": 0,
+        },
+        {
+            "id": "new",
+            "content": "Fresh but less similar",
+            "similarity": 0.70,  # Lower similarity
+            "importance": 1.0,
+            "last_accessed": now,  # Just accessed
+            "access_count": 0,
+        },
+    ]
+
+    print("Before re-ranking (by similarity):")
+    print(f"  1. Old memory: similarity=0.95")
+    print(f"  2. Fresh memory: similarity=0.70\n")
+
+    processed = decay_manager.apply_decay_to_results(results, rerank=True)
+
+    print("After re-ranking (by similarity * effective_importance):")
+    for i, r in enumerate(processed, 1):
+        adj_score = r["similarity"] * r["effective_importance"]
+        print(f"  {i}. {r['content']}")
+        print(f"     similarity: {r['similarity']:.2f}")
+        print(f"     effective_importance: {r['effective_importance']:.4f}")
+        print(f"     adjusted_score: {adj_score:.4f}")
+        print()
+
+    # The fresh memory should now rank first despite lower similarity
+    assert processed[0]["id"] == "new", "Fresh memory should rank first after decay"
+    print("PASS: Fresh memory outranks old memory after decay adjustment")
+
+
+def test_minimum_floor() -> None:
+    """Test that importance never goes below the minimum floor."""
+    print_header("Test 4: Minimum Importance Floor")
+
+    config = AutoDecayConfig(
+        enabled=True,
+        persist_enabled=False,
+        half_life_days=30.0,
+        min_importance_floor=0.1,  # 10% floor
+        access_weight=0.0,
+    )
+    decay_manager = DecayManager(repository=None, config=config)
+
+    now = utc_now()
+
+    results = [
+        {
+            "id": "1",
+            "content": "Very old memory (1 year)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": now - timedelta(days=365),
+            "access_count": 0,
+        },
+        {
+            "id": "2",
+            "content": "Ancient memory (5 years)",
+            "similarity": 0.9,
+            "importance": 1.0,
+            "last_accessed": now - timedelta(days=365 * 5),
+            "access_count": 0,
+        },
+    ]
+
+    processed = decay_manager.apply_decay_to_results(results, rerank=False)
+
+    print(f"Minimum importance floor: {config.min_importance_floor}")
+    print()
+
+    for r in processed:
+        eff = r["effective_importance"]
+        print(f"  {r['content']}")
+        print(f"    effective_importance: {eff:.4f}")
+        print()
+
+    # Verify floor is respected
+    for r in processed:
+        assert r["effective_importance"] >= config.min_importance_floor
+    print(f"PASS: All effective_importance values >= {config.min_importance_floor}")
+
+
+def main() -> None:
+    """Run all tests."""
+    print("\n" + "=" * 60)
+    print("  AUTO-DECAY FEATURE VERIFICATION")
+    print("=" * 60)
+
+    test_basic_decay()
+    test_access_count_slows_decay()
+    test_reranking()
+    test_minimum_floor()
+
+    print_header("ALL TESTS PASSED!")
+    print("The auto-decay feature is working correctly.\n")
+
+
+if __name__ == "__main__":
+    main()

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.7.0}/spatial_memory/__init__.py

@@ -1,6 +1,6 @@
 """Spatial Memory MCP Server - Vector-based semantic memory for LLMs."""
 
-__version__ = "1.6.2"
+__version__ = "1.7.0"
 __author__ = "arman-tech"
 
 # Re-export core components for convenience

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.7.0}/spatial_memory/adapters/lancedb_repository.py

@@ -606,6 +606,8 @@ class LanceDBMemoryRepository:
             tags=record.get("tags", []),
             importance=record["importance"],
             created_at=record["created_at"],
+            last_accessed=record.get("last_accessed"),
+            access_count=record.get("access_count", 0),
             metadata=record.get("metadata", {}),
             vector=vector,
         )

{spatial_memory_mcp-1.6.2 → spatial_memory_mcp-1.7.0}/spatial_memory/config.py

@@ -593,6 +593,43 @@ class Settings(BaseSettings):
         description="Maximum queue depth when backpressure is enabled",
     )
 
+    # =========================================================================
+    # v1.6.3: Auto-Decay Settings
+    # =========================================================================
+
+    auto_decay_enabled: bool = Field(
+        default=True,
+        description="Enable automatic decay calculation during recall operations",
+    )
+    auto_decay_persist_enabled: bool = Field(
+        default=True,
+        description="Persist decay updates to database (disable for read-only scenarios)",
+    )
+    auto_decay_persist_batch_size: int = Field(
+        default=100,
+        ge=10,
+        le=1000,
+        description="Batch size for persisting decay updates to database",
+    )
+    auto_decay_persist_flush_interval_seconds: float = Field(
+        default=5.0,
+        ge=1.0,
+        le=60.0,
+        description="Interval between background flush operations for decay updates",
+    )
+    auto_decay_min_change_threshold: float = Field(
+        default=0.01,
+        ge=0.001,
+        le=0.1,
+        description="Minimum importance change to trigger database persistence (1% default)",
+    )
+    auto_decay_max_queue_size: int = Field(
+        default=10000,
+        ge=1000,
+        le=100000,
+        description="Maximum queue size for pending decay updates (backpressure control)",
+    )
+
     model_config = {
         "env_prefix": "SPATIAL_MEMORY_",
         "env_file": ".env",