spatial-memory-mcp 1.0.2__tar.gz → 1.5.3__tar.gz

{spatial_memory_mcp-1.0.2 → spatial_memory_mcp-1.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spatial-memory-mcp
-Version: 1.0.2
+Version: 1.5.3
 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.5.3/docs/MCP_SERVER_INSTRUCTIONS.md

@@ -0,0 +1,96 @@
+# MCP Server Instructions: Auto-Injected AI Behavioral Guidelines
+
+## Discovery
+
+When users install an MCP server, the server can provide **instructions** that are automatically injected into Claude's system prompt. This enables MCP servers to define behavioral guidelines that Claude follows without requiring users to manually configure anything.
+
+## Technical Implementation
+
+The MCP Python SDK's `Server` class accepts an `instructions` parameter:
+
+```python
+from mcp.server import Server
+
+server = Server(
+    name="spatial-memory",
+    version="1.5.3",
+    instructions="""
+Your behavioral instructions here...
+"""
+)
+```
+
+These instructions are:
+- Sent during the MCP initialize handshake
+- Automatically concatenated into Claude's system prompt
+- Displayed under "# MCP Server Instructions" in Claude's context
+- Require **zero user action** - fully automatic
+
+## Why This Matters
+
+### The Problem
+- Users install MCP servers but don't know optimal usage patterns
+- AI assistants use tools reactively rather than proactively
+- Knowledge capture requires manual effort ("save this to memory")
+- Each session starts from scratch without prior context
+
+### The Solution
+Server-provided instructions enable:
+1. **Zero cognitive load** - Claude handles memory mechanics automatically
+2. **Proactive behavior** - Claude recognizes memory-worthy moments
+3. **Consistent UX** - All users get the same optimized experience
+4. **Seamless context** - Previous learnings auto-load at session start
+
+## Comparison of Approaches
+
+| Approach | Auto-loaded? | User Action Required | Scope |
+|----------|--------------|---------------------|-------|
+| `~/.claude/CLAUDE.md` | Yes | User must create/edit | Global |
+| `<project>/CLAUDE.md` | Yes | User must create/edit | Project |
+| MCP `instructions` param | Yes | **None** | Per-server |
+
+## spatial-memory-mcp Instructions
+
+The following instructions are injected when spatial-memory-mcp connects:
+
+```
+## Spatial Memory System
+
+You have access to a persistent semantic memory system. Use it proactively.
+
+### Session Start
+At conversation start, call `recall` with the user's apparent task/context to load relevant memories. Present insights naturally: "Based on previous work..." not "The database returned...".
+
+### Recognizing Memory-Worthy Moments
+After these events, ask "Save this? y/n" (minimal friction):
+- Decisions: "Let's use X approach...", "We decided..."
+- Solutions: "The fix was...", "It failed because..."
+- Patterns: "This pattern works...", "The trick is..."
+- Discoveries: "I found that...", "Important:..."
+
+### Saving Memories
+When confirmed, save with:
+- **Detailed content**: Future agents need full context
+- **Contextual namespace**: Project name, "decisions", "errors", etc.
+- **Descriptive tags**: Technologies, concepts, patterns involved
+
+### Synthesizing Answers
+When recalling memories, present as natural knowledge:
+- Good: "In previous sessions, you decided to use PostgreSQL for..."
+- Bad: "Here are the query results: [{id: '...', content: '...'}]"
+
+### Auto-Extract
+For significant problem-solving conversations, offer to use `extract` to automatically capture key learnings.
+```
+
+## Implementation Location
+
+- **File**: `spatial_memory/server.py`
+- **Line**: Server initialization (~340)
+- **Parameter**: `instructions`
+
+## Related Files
+
+- `spatial_memory/server.py` - Server implementation
+- `CLAUDE.md` - Project-level instructions (for contributors)
+- `docs/MCP_SERVER_INSTRUCTIONS.md` - This document

{spatial_memory_mcp-1.0.2 → spatial_memory_mcp-1.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spatial-memory-mcp"
-version = "1.0.2"
+version = "1.5.3"
 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.0.2 → spatial_memory_mcp-1.5.3}/spatial_memory/__init__.py

@@ -1,97 +1,97 @@
-"""Spatial Memory MCP Server - Vector-based semantic memory for LLMs."""
-
-__version__ = "1.0.1"
-__author__ = "arman-tech"
-
-# Re-export core components for convenience
-# Adapters
-from spatial_memory.adapters.lancedb_repository import LanceDBMemoryRepository
-from spatial_memory.config import Settings, get_settings
-from spatial_memory.core import (
-    ClusterInfo,
-    ClusteringError,
-    ConfigurationError,
-    # Core services
-    Database,
-    EmbeddingError,
-    EmbeddingService,
-    Filter,
-    FilterGroup,
-    FilterOperator,
-    JourneyStep,
-    # Models
-    Memory,
-    MemoryNotFoundError,
-    MemoryResult,
-    MemorySource,
-    NamespaceNotFoundError,
-    # Errors
-    SpatialMemoryError,
-    StorageError,
-    ValidationError,
-    VisualizationCluster,
-    VisualizationData,
-    VisualizationEdge,
-    VisualizationError,
-    VisualizationNode,
-)
-
-# Server
-from spatial_memory.server import SpatialMemoryServer, create_server
-
-# Services
-from spatial_memory.services.memory import (
-    ForgetResult,
-    MemoryService,
-    NearbyResult,
-    RecallResult,
-    RememberBatchResult,
-    RememberResult,
-)
-
-__all__ = [
-    # Version info
-    "__version__",
-    "__author__",
-    # Configuration
-    "Settings",
-    "get_settings",
-    # Errors
-    "SpatialMemoryError",
-    "MemoryNotFoundError",
-    "NamespaceNotFoundError",
-    "EmbeddingError",
-    "StorageError",
-    "ValidationError",
-    "ConfigurationError",
-    "ClusteringError",
-    "VisualizationError",
-    # Models
-    "Memory",
-    "MemorySource",
-    "MemoryResult",
-    "ClusterInfo",
-    "JourneyStep",
-    "VisualizationNode",
-    "VisualizationEdge",
-    "VisualizationCluster",
-    "VisualizationData",
-    "Filter",
-    "FilterOperator",
-    "FilterGroup",
-    # Core services
-    "Database",
-    "EmbeddingService",
-    # Services
-    "MemoryService",
-    "RememberResult",
-    "RememberBatchResult",
-    "RecallResult",
-    "NearbyResult",
-    "ForgetResult",
-    # Adapters
-    "LanceDBMemoryRepository",
-    # Server
-    "SpatialMemoryServer",
-    "create_server",
-]
+"""Spatial Memory MCP Server - Vector-based semantic memory for LLMs."""
+
+__version__ = "1.5.3"
+__author__ = "arman-tech"
+
+# Re-export core components for convenience
+# Adapters
+from spatial_memory.adapters.lancedb_repository import LanceDBMemoryRepository
+from spatial_memory.config import Settings, get_settings
+from spatial_memory.core import (
+    ClusterInfo,
+    ClusteringError,
+    ConfigurationError,
+    # Core services
+    Database,
+    EmbeddingError,
+    EmbeddingService,
+    Filter,
+    FilterGroup,
+    FilterOperator,
+    JourneyStep,
+    # Models
+    Memory,
+    MemoryNotFoundError,
+    MemoryResult,
+    MemorySource,
+    NamespaceNotFoundError,
+    # Errors
+    SpatialMemoryError,
+    StorageError,
+    ValidationError,
+    VisualizationCluster,
+    VisualizationData,
+    VisualizationEdge,
+    VisualizationError,
+    VisualizationNode,
+)
+
+# Server
+from spatial_memory.server import SpatialMemoryServer, create_server
+
+# Services
+from spatial_memory.services.memory import (
+    ForgetResult,
+    MemoryService,
+    NearbyResult,
+    RecallResult,
+    RememberBatchResult,
+    RememberResult,
+)
+
+__all__ = [
+    # Version info
+    "__version__",
+    "__author__",
+    # Configuration
+    "Settings",
+    "get_settings",
+    # Errors
+    "SpatialMemoryError",
+    "MemoryNotFoundError",
+    "NamespaceNotFoundError",
+    "EmbeddingError",
+    "StorageError",
+    "ValidationError",
+    "ConfigurationError",
+    "ClusteringError",
+    "VisualizationError",
+    # Models
+    "Memory",
+    "MemorySource",
+    "MemoryResult",
+    "ClusterInfo",
+    "JourneyStep",
+    "VisualizationNode",
+    "VisualizationEdge",
+    "VisualizationCluster",
+    "VisualizationData",
+    "Filter",
+    "FilterOperator",
+    "FilterGroup",
+    # Core services
+    "Database",
+    "EmbeddingService",
+    # Services
+    "MemoryService",
+    "RememberResult",
+    "RememberBatchResult",
+    "RecallResult",
+    "NearbyResult",
+    "ForgetResult",
+    # Adapters
+    "LanceDBMemoryRepository",
+    # Server
+    "SpatialMemoryServer",
+    "create_server",
+]

{spatial_memory_mcp-1.0.2 → spatial_memory_mcp-1.5.3}/spatial_memory/config.py

@@ -480,6 +480,111 @@ class Settings(BaseSettings):
         description="Maximum alpha for hybrid search (1.0=pure vector)",
     )
 
+    # =========================================================================
+    # v1.5.3 Phase 1: Observability Settings
+    # =========================================================================
+
+    include_request_meta: bool = Field(
+        default=False,
+        description="Include _meta object in responses (request_id, timing, etc.)",
+    )
+    log_include_trace_context: bool = Field(
+        default=True,
+        description="Add [req=][agent=] trace context to log messages",
+    )
+    include_timing_breakdown: bool = Field(
+        default=False,
+        description="Include timing_ms breakdown in _meta (requires include_request_meta)",
+    )
+
+    # =========================================================================
+    # v1.5.3 Phase 2: Efficiency Settings
+    # =========================================================================
+
+    warm_up_on_start: bool = Field(
+        default=True,
+        description="Pre-load embedding model on startup for faster first request",
+    )
+    response_cache_enabled: bool = Field(
+        default=True,
+        description="Enable response caching for idempotent operations",
+    )
+    response_cache_max_size: int = Field(
+        default=1000,
+        ge=100,
+        le=100000,
+        description="Maximum number of cached responses (LRU eviction)",
+    )
+    response_cache_default_ttl: float = Field(
+        default=60.0,
+        ge=1.0,
+        le=3600.0,
+        description="Default TTL in seconds for cached responses",
+    )
+    response_cache_regions_ttl: float = Field(
+        default=300.0,
+        ge=60.0,
+        le=3600.0,
+        description="TTL in seconds for regions() responses (expensive operation)",
+    )
+    idempotency_enabled: bool = Field(
+        default=True,
+        description="Enable idempotency key support for write operations",
+    )
+    idempotency_key_ttl_hours: float = Field(
+        default=24.0,
+        ge=1.0,
+        le=168.0,
+        description="Hours to remember idempotency keys (max 7 days)",
+    )
+
+    # =========================================================================
+    # v1.5.3 Phase 3: Resilience Settings
+    # =========================================================================
+
+    rate_limit_per_agent_enabled: bool = Field(
+        default=True,
+        description="Enable per-agent rate limiting",
+    )
+    rate_limit_per_agent_rate: float = Field(
+        default=25.0,
+        ge=1.0,
+        le=1000.0,
+        description="Maximum operations per second per agent",
+    )
+    rate_limit_max_tracked_agents: int = Field(
+        default=20,
+        ge=1,
+        le=1000,
+        description="Maximum number of agents to track for rate limiting (LRU eviction)",
+    )
+    circuit_breaker_enabled: bool = Field(
+        default=True,
+        description="Enable circuit breaker for external dependencies",
+    )
+    circuit_breaker_failure_threshold: int = Field(
+        default=5,
+        ge=1,
+        le=100,
+        description="Number of consecutive failures before circuit opens",
+    )
+    circuit_breaker_reset_timeout: float = Field(
+        default=60.0,
+        ge=5.0,
+        le=600.0,
+        description="Seconds to wait before attempting half-open state",
+    )
+    backpressure_queue_enabled: bool = Field(
+        default=False,
+        description="Enable backpressure queue for overload protection (future)",
+    )
+    backpressure_queue_max_size: int = Field(
+        default=100,
+        ge=10,
+        le=10000,
+        description="Maximum queue depth when backpressure is enabled",
+    )
+
     model_config = {
         "env_prefix": "SPATIAL_MEMORY_",
         "env_file": ".env",

{spatial_memory_mcp-1.0.2 → spatial_memory_mcp-1.5.3}/spatial_memory/core/__init__.py

@@ -1,5 +1,10 @@
 """Core components for Spatial Memory MCP Server."""
 
+from spatial_memory.core.circuit_breaker import (
+    CircuitBreaker,
+    CircuitOpenError,
+    CircuitState,
+)
 from spatial_memory.core.database import Database
 from spatial_memory.core.embeddings import EmbeddingService
 from spatial_memory.core.rate_limiter import RateLimiter
@@ -37,6 +42,15 @@ from spatial_memory.core.models import (
     VisualizationNode,
 )
 from spatial_memory.core.utils import to_aware_utc, to_naive_utc, utc_now, utc_now_naive
+from spatial_memory.core.tracing import (
+    RequestContext,
+    TimingContext,
+    clear_context,
+    format_context_prefix,
+    get_current_context,
+    request_context,
+    set_context,
+)
 
 __all__ = [
     # Errors - Base
@@ -80,4 +94,16 @@ __all__ = [
     "utc_now_naive",
     "to_naive_utc",
     "to_aware_utc",
+    # Tracing
+    "RequestContext",
+    "TimingContext",
+    "get_current_context",
+    "set_context",
+    "clear_context",
+    "request_context",
+    "format_context_prefix",
+    # Circuit Breaker
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "CircuitState",
 ]