v1.11.4

What's New

Namespace Refinement

• 7 new signal patterns: testing, performance, environment, dependency, api, procedure, workflow
• 3 new namespaces: context, procedures, references (replacing captured and definitions)
• Default fallback namespace changed from "captured" to "notes"
• Definition pattern tightened to require "X is a/an/the Y" structure, eliminating false positives

CLI Subcommands

• Added consolidate and namespaces CLI subcommands

Documentation

• Updated README, benchmarks, and tool test coverage
• Added logo assets

Testing

• 2,565 tests pass, 13 skipped

v1.11.2

What's New

Cross-Corpus Similarity Engine

• New discover_connections MCP tool — find semantically similar memories across namespaces/projects using ANN-based search
• New corpus_bridges MCP tool — discover cross-namespace semantic links for admin reporting
• 3 pluggable scoring strategies: vector_only, vector_content, vector_metadata
• Replaced broken O(n²) _consolidate_chunked with efficient ANN-based candidate discovery

Async Rate Limiter

• Converted RateLimiter.wait() from sync time.sleep() to async asyncio.sleep(), fixing event loop blocking
• Atomic _acquire_or_estimate() eliminates TOCTOU race condition between acquire and wait estimation
• Protocol-based ports (AsyncRateLimiterPort, AsyncAgentRateLimiterPort) following Dependency Inversion Principle

Unified Hooks CLI

• Single dispatcher.py replaces 5 separate hook entry points
• Cursor auto-config via init_client.py and plugin mode support

Bug Fixes

• Added missing @with_process_lock/@with_write_lock decorators to import_from_parquet, set_memory_ttl, cleanup_expired_memories
• Fixed delete_batch tracking actual count instead of default 1

v1.10.1

What's New in v1.10.0 → v1.10.1

Cognitive Offloading & Hook Scripts (v1.10.0)

• Automatic memory capture via Claude Code hooks — PostToolUse captures decisions/errors during tool use, PreCompact and Stop capture transcript text at session boundaries
• Multi-client support for 5 AI coding clients (Claude Code, Cursor, Windsurf, Antigravity, VS Code Copilot)
• Plugin packaging — zero-config Claude Code plugin with hooks and MCP server config
• setup_hooks MCP tool and CLI — generates client-specific hook configuration
• Queue-based memory pipeline — Maildir-style atomic queue for hook-to-server delivery
• Signal detection — pattern-based classification into 3 tiers
• Secret redaction — single-pass detection for passwords, API keys, tokens, private keys

Code Quality & Security (PRs #3, #4)

• 30 fixes across security, data integrity, performance, test gaps, and documentation
• Hardened queue file input validation, notification content sanitization
• _skip_field_validation optimization for internal inserts
• Protocol refactoring (ISP) — split 30-method protocol into 5 focused sub-protocols

Database Decomposition (PR #7)

• Extracted 8 manager classes from database.py god object
• Reduced database.py from ~3,770 LOC to ~1,875 LOC (50% reduction)
• Database class remains as a thin facade preserving the full public API

Bug Fixes (v1.10.1)

• Tilde expansion in memory_path config
• Queue writer default path now uses project-relative directory

Stats

• 2,304 tests passing (13 skipped), 3 OS × 4 Python versions
• 149 files changed, +29,333 / −2,341 lines since v1.9.3

Full Changelog: https://github.com/arman-tech/spatial-memory-mcp/blob/master/CHANGELOG.md

v1.9.3: Tiered Auto-Save Instructions

What's Changed

Tiered Auto-Save Instructions

Rewrote the MCP server instructions with a 3-tier memory save system that reduces cognitive load by guiding the LLM on when to save automatically vs when to ask:

• Tier 1 — Auto-save: Decisions with reasoning, bug fixes/solutions, error root causes, and architecture choices are saved immediately with a > Memorized: notification
• Tier 2 — Ask first: Patterns/learnings, preferences/conventions, configuration discoveries, and workarounds prompt the user before saving
• Tier 3 — Never save: Trivial observations, duplicates, speculative information, and temporary debugging steps are never saved

Additional Improvements

• Dedup guidance: Instructions now direct the LLM to check recall before saving to prevent duplicate memories
• Tool selection guide: Added a quick-reference guide for choosing between remember, recall, hybrid_recall, extract, nearby, regions, and journey
• Documentation sync: Updated docs/MCP_SERVER_INSTRUCTIONS.md to match the actual injected instructions

Full Changelog

Files changed: 8 files, +165 / -52 lines
Tests: 1,398 passed, 13 skipped

🤖 Generated with Claude Code

v1.9.2

Fixed

• Clamped similarity values to valid range: SpatialService._process_batch_results() now clamps similarity scores to [0.0, 1.0] range to ensure values are always within expected bounds, preventing potential issues with out-of-range similarity scores from vector search results.

---

Full Changelog: v1.9.1...v1.9.2

v1.9.1: Remove undeclared pandas dependency

Fixed

• Removed undeclared pandas dependency: batch_vector_search_native in db_search.py was using to_pandas() which required pandas (not declared in dependencies). Refactored to use Arrow operations (to_arrow().to_pylist()) consistent with the rest of the codebase.
  • Fixes "No module named 'pandas'" error when using journey tool
  • Improves performance by avoiding DataFrame conversion overhead
  • Reduces dependency footprint (pandas is ~50MB)

Installation

pip install spatial-memory-mcp==1.9.1

Full Changelog: v1.9.0...v1.9.1

v1.9.0 - Stricter Namespace Validation

Breaking Changes

• Namespace validation now follows 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

Changed

• Consolidated namespace validation to single canonical pattern across all modules
• Replaced outdated stubs/ directory with mypy module overrides
• All 49 source files pass strict mypy checks

Installation

pip install spatial-memory-mcp==1.9.0

Full Changelog

See CHANGELOG.md

v1.8.0: Unified Decay System

What's New in v1.8.0

🎯 Unified Decay System

Auto-decay and manual decay now use the same algorithm, ensuring consistent behavior regardless of code path.

New configuration option:

# Choose decay function: exponential (default), linear, or step
SPATIAL_MEMORY_AUTO_DECAY_FUNCTION=exponential

Decay functions:

Function	Behavior
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)

Adaptive half-life: The effective half-life now considers:

• Access count: 1.5× multiplier per access (frequently used memories decay slower)
• Importance factor: (1 + importance) multiplier

🔧 Code Quality Improvements

• Type Safety: Resolved all mypy errors in main source code (49 files)
• Linting: Resolved all ruff errors in test files (45 issues)
• Clean Codebase: Ready for open source contributions

📚 Documentation

• Updated docs/CONFIGURATION.md with decay function options
• Updated .env.example with configuration examples

✅ Test Results

• 1,393 tests passing
• mypy: Success (no issues)
• ruff: All checks passed

---

Full Changelog: v1.7.0...v1.8.0

v1.7.0 - Auto-Decay Feature

Auto-Decay Feature

Memories now automatically lose importance over time if not accessed, making recent and frequently-used memories more prominent in search results.

Highlights

• Automatic Decay: Exponential decay based on time since last access (default half-life: 30 days)
• Smart Re-ranking: Search results ranked by similarity × effective_importance
• Access Count Bonus: Frequently accessed memories decay slower
• Background Persistence: Decay updates batched and persisted efficiently
• Zero Configuration: Works out of the box with sensible defaults

New Response Field

recall and hybrid_recall now return effective_importance alongside importance:

{
  "memories": [{
    "content": "...",
    "similarity": 0.95,
    "importance": 1.0,
    "effective_importance": 0.5
  }]
}

Configuration

Configure via environment variables:

SPATIAL_MEMORY_AUTO_DECAY_ENABLED=true
SPATIAL_MEMORY_AUTO_DECAY_PERSIST_ENABLED=true

Or in .mcp.json:

{
  "mcpServers": {
    "spatial-memory": {
      "command": "spatial-memory",
      "env": {
        "SPATIAL_MEMORY_AUTO_DECAY_ENABLED": "true"
      }
    }
  }
}

See docs/CONFIGURATION.md for full configuration reference.

Installation

pip install --upgrade spatial-memory-mcp

Full Changelog

See CHANGELOG.md for complete details.

v1.6.2 - Technical Highlights & Linting Fixes

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

---

Full Changelog: v1.6.1...v1.6.2