spatial-memory-mcp 1.6.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of spatial-memory-mcp might be problematic. Click here for more details.

Files changed (54) hide show
  1. spatial_memory/__init__.py +97 -0
  2. spatial_memory/__main__.py +270 -0
  3. spatial_memory/adapters/__init__.py +7 -0
  4. spatial_memory/adapters/lancedb_repository.py +878 -0
  5. spatial_memory/config.py +728 -0
  6. spatial_memory/core/__init__.py +118 -0
  7. spatial_memory/core/cache.py +317 -0
  8. spatial_memory/core/circuit_breaker.py +297 -0
  9. spatial_memory/core/connection_pool.py +220 -0
  10. spatial_memory/core/consolidation_strategies.py +402 -0
  11. spatial_memory/core/database.py +3069 -0
  12. spatial_memory/core/db_idempotency.py +242 -0
  13. spatial_memory/core/db_indexes.py +575 -0
  14. spatial_memory/core/db_migrations.py +584 -0
  15. spatial_memory/core/db_search.py +509 -0
  16. spatial_memory/core/db_versioning.py +177 -0
  17. spatial_memory/core/embeddings.py +557 -0
  18. spatial_memory/core/errors.py +317 -0
  19. spatial_memory/core/file_security.py +702 -0
  20. spatial_memory/core/filesystem.py +178 -0
  21. spatial_memory/core/health.py +289 -0
  22. spatial_memory/core/helpers.py +79 -0
  23. spatial_memory/core/import_security.py +432 -0
  24. spatial_memory/core/lifecycle_ops.py +1067 -0
  25. spatial_memory/core/logging.py +194 -0
  26. spatial_memory/core/metrics.py +192 -0
  27. spatial_memory/core/models.py +628 -0
  28. spatial_memory/core/rate_limiter.py +326 -0
  29. spatial_memory/core/response_types.py +497 -0
  30. spatial_memory/core/security.py +588 -0
  31. spatial_memory/core/spatial_ops.py +426 -0
  32. spatial_memory/core/tracing.py +300 -0
  33. spatial_memory/core/utils.py +110 -0
  34. spatial_memory/core/validation.py +403 -0
  35. spatial_memory/factory.py +407 -0
  36. spatial_memory/migrations/__init__.py +40 -0
  37. spatial_memory/ports/__init__.py +11 -0
  38. spatial_memory/ports/repositories.py +631 -0
  39. spatial_memory/py.typed +0 -0
  40. spatial_memory/server.py +1141 -0
  41. spatial_memory/services/__init__.py +70 -0
  42. spatial_memory/services/export_import.py +1023 -0
  43. spatial_memory/services/lifecycle.py +1120 -0
  44. spatial_memory/services/memory.py +412 -0
  45. spatial_memory/services/spatial.py +1147 -0
  46. spatial_memory/services/utility.py +409 -0
  47. spatial_memory/tools/__init__.py +5 -0
  48. spatial_memory/tools/definitions.py +695 -0
  49. spatial_memory/verify.py +140 -0
  50. spatial_memory_mcp-1.6.1.dist-info/METADATA +499 -0
  51. spatial_memory_mcp-1.6.1.dist-info/RECORD +54 -0
  52. spatial_memory_mcp-1.6.1.dist-info/WHEEL +4 -0
  53. spatial_memory_mcp-1.6.1.dist-info/entry_points.txt +2 -0
  54. spatial_memory_mcp-1.6.1.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,140 @@
1
+ """Verify spatial-memory installation and dependencies.
2
+
3
+ Run: python -m spatial_memory.verify
4
+ """
5
+
6
+ import contextlib
7
+ import io
8
+ import logging
9
+ import os
10
+ import sys
11
+ import warnings
12
+
13
+
14
+ def _suppress_noise() -> None:
15
+ """Suppress noisy warnings and logs from dependencies."""
16
+ warnings.filterwarnings("ignore")
17
+ # Suppress verbose loggers
18
+ for logger_name in [
19
+ "sentence_transformers",
20
+ "optimum",
21
+ "huggingface_hub",
22
+ "transformers",
23
+ ]:
24
+ logging.getLogger(logger_name).setLevel(logging.ERROR)
25
+ # Suppress HF symlink warnings on Windows
26
+ os.environ["HF_HUB_DISABLE_SYMLINKS_WARNING"] = "1"
27
+
28
+
29
+ def main() -> int:
30
+ """Verify installation and print status."""
31
+ _suppress_noise()
32
+
33
+ print("Spatial Memory MCP - Installation Verification")
34
+ print("=" * 50)
35
+
36
+ errors = []
37
+ onnx_available = False
38
+
39
+ # Check core dependencies
40
+ print("\nChecking core dependencies...")
41
+
42
+ try:
43
+ import lancedb # noqa: F401
44
+ print(" [OK] lancedb")
45
+ except ImportError as e:
46
+ print(f" [FAIL] lancedb: {e}")
47
+ errors.append("lancedb")
48
+
49
+ try:
50
+ import sentence_transformers # noqa: F401
51
+ print(" [OK] sentence-transformers")
52
+ except ImportError as e:
53
+ print(f" [FAIL] sentence-transformers: {e}")
54
+ errors.append("sentence-transformers")
55
+
56
+ try:
57
+ import mcp # noqa: F401
58
+ print(" [OK] mcp")
59
+ except ImportError as e:
60
+ print(f" [FAIL] mcp: {e}")
61
+ errors.append("mcp")
62
+
63
+ try:
64
+ import hdbscan # noqa: F401
65
+ print(" [OK] hdbscan")
66
+ except ImportError as e:
67
+ print(f" [FAIL] hdbscan: {e}")
68
+ errors.append("hdbscan")
69
+
70
+ try:
71
+ import umap # noqa: F401
72
+ print(" [OK] umap-learn")
73
+ except ImportError as e:
74
+ print(f" [FAIL] umap-learn: {e}")
75
+ errors.append("umap-learn")
76
+
77
+ # Check ONNX Runtime (optional but recommended)
78
+ print("\nChecking ONNX Runtime (for faster embeddings)...")
79
+
80
+ try:
81
+ import onnxruntime # noqa: F401
82
+ print(" [OK] onnxruntime")
83
+ except ImportError:
84
+ print(" [WARN] onnxruntime not installed")
85
+
86
+ # Suppress "Multiple distributions" message from optimum
87
+ with contextlib.redirect_stdout(io.StringIO()):
88
+ try:
89
+ import optimum.onnxruntime # noqa: F401
90
+ optimum_ok = True
91
+ except ImportError:
92
+ optimum_ok = False
93
+
94
+ if optimum_ok:
95
+ print(" [OK] optimum")
96
+ else:
97
+ print(" [WARN] optimum not installed")
98
+
99
+ # Check embedding service
100
+ print("\nChecking embedding service...")
101
+
102
+ try:
103
+ from spatial_memory.core.embeddings import EmbeddingService, _is_onnx_available
104
+
105
+ onnx_available = _is_onnx_available()
106
+ print(f" ONNX Runtime available: {onnx_available}")
107
+
108
+ # Suppress model loading messages
109
+ with contextlib.redirect_stdout(io.StringIO()), \
110
+ contextlib.redirect_stderr(io.StringIO()):
111
+ svc = EmbeddingService()
112
+ backend = svc.backend
113
+ dimensions = svc.dimensions
114
+ vec = svc.embed("test")
115
+
116
+ print(f" Active backend: {backend}")
117
+ print(f" Embedding dimensions: {dimensions}")
118
+ print(f" Embedding test: OK (shape: {vec.shape})")
119
+
120
+ except Exception as e:
121
+ print(f" [FAIL] Embedding service error: {e}")
122
+ errors.append("embedding-service")
123
+
124
+ # Summary
125
+ print("\n" + "=" * 50)
126
+ if errors:
127
+ print(f"FAILED: {len(errors)} issue(s) found")
128
+ print(f"Missing: {', '.join(errors)}")
129
+ print("\nTry: pip install -e \".[dev]\"")
130
+ return 1
131
+ else:
132
+ print("SUCCESS: All dependencies verified!")
133
+ if not onnx_available:
134
+ print("\nTip: Install ONNX for 2-3x faster embeddings:")
135
+ print(" pip install sentence-transformers[onnx]")
136
+ return 0
137
+
138
+
139
+ if __name__ == "__main__":
140
+ sys.exit(main())
@@ -0,0 +1,499 @@
1
+ Metadata-Version: 2.4
2
+ Name: spatial-memory-mcp
3
+ Version: 1.6.1
4
+ Summary: Spatial bidirectional persistent memory MCP server for LLMs - vector-based semantic memory as a navigable landscape
5
+ Project-URL: Homepage, https://github.com/arman-tech/spatial-memory-mcp
6
+ Project-URL: Repository, https://github.com/arman-tech/spatial-memory-mcp
7
+ Author: arman-tech
8
+ License: MIT
9
+ License-File: LICENSE
10
+ Keywords: embeddings,llm,mcp,memory,semantic-search,spatial,vector
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: License :: OSI Approved :: MIT License
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Requires-Python: >=3.10
20
+ Requires-Dist: filelock>=3.12.0
21
+ Requires-Dist: hdbscan>=0.8.33
22
+ Requires-Dist: lancedb>=0.27.0
23
+ Requires-Dist: mcp>=1.0.0
24
+ Requires-Dist: numpy>=1.24.0
25
+ Requires-Dist: pydantic-settings>=2.0.0
26
+ Requires-Dist: pydantic>=2.0.0
27
+ Requires-Dist: sentence-transformers[onnx]>=2.2.0
28
+ Requires-Dist: umap-learn>=0.5.5
29
+ Provides-Extra: dev
30
+ Requires-Dist: mypy>=1.0.0; extra == 'dev'
31
+ Requires-Dist: prometheus-client>=0.20.0; extra == 'dev'
32
+ Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
33
+ Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
34
+ Requires-Dist: pytest>=7.0.0; extra == 'dev'
35
+ Requires-Dist: ruff>=0.1.0; extra == 'dev'
36
+ Provides-Extra: metrics
37
+ Requires-Dist: prometheus-client>=0.20.0; extra == 'metrics'
38
+ Provides-Extra: openai
39
+ Requires-Dist: openai>=1.0.0; extra == 'openai'
40
+ Requires-Dist: tiktoken>=0.5.0; extra == 'openai'
41
+ Description-Content-Type: text/markdown
42
+
43
+ # Spatial Memory MCP Server
44
+
45
+ [![PyPI version](https://badge.fury.io/py/spatial-memory-mcp.svg)](https://pypi.org/project/spatial-memory-mcp/)
46
+ [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
47
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
48
+
49
+ A vector-based spatial memory system that treats knowledge as a navigable landscape, not a filing cabinet.
50
+
51
+ > **Version 1.6.1** — Production-ready with 1,360 tests passing.
52
+
53
+ ## Supported Platforms
54
+
55
+ - **Windows 11**
56
+ - **macOS** (latest)
57
+ - **Linux** (Fedora, Ubuntu, Linux Mint)
58
+
59
+ ## Overview
60
+
61
+ Spatial Memory MCP Server provides persistent, semantic memory for LLMs through the Model Context Protocol (MCP). Unlike traditional keyword-based memory systems, it uses vector embeddings to enable:
62
+
63
+ - **Semantic Search**: Find memories by meaning, not just keywords
64
+ - **Spatial Navigation**: Discover connections through `journey` and `wander` operations
65
+ - **Auto-Clustering**: `regions` automatically groups related concepts
66
+ - **Cognitive Dynamics**: Memories consolidate, decay, and reinforce like human cognition
67
+ - **Visual Understanding**: Generate Mermaid/SVG/JSON visualizations of your knowledge space
68
+ - **Hybrid Search**: Combine vector similarity with full-text search
69
+
70
+ ## Why Spatial Memory?
71
+
72
+ ### Zero Cognitive Load
73
+ **You never think about memory. Claude handles everything automatically.**
74
+
75
+ - Auto-loads relevant context at session start
76
+ - Recognizes memory-worthy moments and asks "Save this? y/n"
77
+ - Synthesizes answers naturally—no raw JSON, no memory IDs
78
+ - MCP instructions inject automatically—zero configuration
79
+
80
+ ### Cognitive Architecture, Not Storage
81
+ Other memory systems store embeddings. Spatial Memory implements how memory actually works:
82
+
83
+ - **Decay**: Memories fade over time (Ebbinghaus forgetting curve)
84
+ - **Reinforcement**: Frequently accessed memories grow stronger
85
+ - **Consolidation**: Similar memories merge intelligently
86
+ - **Extraction**: Auto-capture facts, decisions, patterns from conversations
87
+
88
+ ### Spatial Navigation (Unique Innovation)
89
+ Navigate knowledge like a landscape, not a filing cabinet:
90
+
91
+ | Tool | What It Does |
92
+ |------|-------------|
93
+ | **Journey** | SLERP between two memories—discover what's conceptually in between |
94
+ | **Wander** | Random walk exploration—find unexpected connections |
95
+ | **Regions** | HDBSCAN clustering—see how your knowledge self-organizes |
96
+ | **Visualize** | UMAP projection—view your memory space in 2D/3D |
97
+
98
+ ### 22 Tools vs. 3-6 in Competitors
99
+ Full lifecycle management: core operations, spatial navigation, memory lifecycle, hybrid search, namespace management, data import/export, and health/stats monitoring.
100
+
101
+ ### Enterprise-Ready
102
+ Connection pooling, circuit breakers, per-agent rate limiting, request tracing, response caching, and defense-in-depth security (path traversal prevention, SQL injection detection, input validation).
103
+
104
+ > *See [MARKETING.md](MARKETING.md) for the complete comparison with competitors.*
105
+
106
+ ## Features
107
+
108
+ - **22 MCP tools** across 4 categories (core, spatial, lifecycle, utility)
109
+ - **Clean Architecture** with ports/adapters pattern for testability
110
+ - **LanceDB** vector storage with automatic indexing
111
+ - **Dual embedding support**: Local (sentence-transformers) or OpenAI API
112
+ - **ONNX Runtime** by default for 2-3x faster embeddings
113
+ - **Enterprise features**: Connection pooling, retry logic, batch operations
114
+ - **Comprehensive security**: Path validation, SQL injection prevention, input sanitization
115
+ - **1360 tests** including security edge cases
116
+
117
+ ## Roadmap
118
+
119
+ | Phase | Status | Features |
120
+ |-------|--------|----------|
121
+ | Phase 1: Foundation | Complete | Config, Database, Embeddings, Models, Errors |
122
+ | Phase 2: Core Operations | Complete | `remember`, `recall`, `nearby`, `forget` |
123
+ | Phase 3: Spatial Operations | Complete | `journey`, `wander`, `regions`, `visualize` |
124
+ | Phase 4: Lifecycle Operations | Complete | `consolidate`, `extract`, `decay`, `reinforce` |
125
+ | Phase 5: Utilities | Complete | `stats`, `namespaces`, `export`, `import`, `hybrid_recall` |
126
+ | Phase 6: Polish & Release | Complete | v1.6.0 on PyPI |
127
+
128
+ ## Installation
129
+
130
+ ### From PyPI (Recommended)
131
+
132
+ ```bash
133
+ pip install spatial-memory-mcp
134
+
135
+ # Or with uv
136
+ uv pip install spatial-memory-mcp
137
+ ```
138
+
139
+ ### Development Setup
140
+
141
+ ```bash
142
+ git clone https://github.com/arman-tech/spatial-memory-mcp.git
143
+ cd spatial-memory-mcp
144
+ pip install -e ".[dev]"
145
+ ```
146
+
147
+ ### With OpenAI Support
148
+
149
+ ```bash
150
+ # From PyPI
151
+ pip install spatial-memory-mcp[openai]
152
+
153
+ # From source
154
+ pip install -e ".[dev,openai]"
155
+ ```
156
+
157
+ ### Verify Installation
158
+
159
+ After installation, verify that all dependencies are correctly installed:
160
+
161
+ ```bash
162
+ python -m spatial_memory.verify
163
+ ```
164
+
165
+ Or manually check:
166
+
167
+ ```python
168
+ # Run in Python interpreter
169
+ from spatial_memory.core.embeddings import EmbeddingService, _is_onnx_available
170
+ print(f"ONNX available: {_is_onnx_available()}")
171
+ svc = EmbeddingService()
172
+ print(f"Backend: {svc.backend}, Dimensions: {svc.dimensions}")
173
+ ```
174
+
175
+ Expected output with ONNX Runtime (default):
176
+ ```
177
+ ONNX available: True
178
+ Backend: onnx, Dimensions: 384
179
+ ```
180
+
181
+ If ONNX shows as unavailable, reinstall with:
182
+ ```bash
183
+ pip install --force-reinstall "sentence-transformers[onnx]"
184
+ ```
185
+
186
+ ### CLI Commands
187
+
188
+ The `spatial-memory` CLI provides several commands:
189
+
190
+ ```bash
191
+ # Start the MCP server (default)
192
+ spatial-memory serve
193
+
194
+ # View the MCP instructions injected into Claude's context
195
+ spatial-memory instructions
196
+
197
+ # Run database migrations
198
+ spatial-memory migrate --status # Check migration status
199
+ spatial-memory migrate --dry-run # Preview migrations
200
+ spatial-memory migrate # Apply pending migrations
201
+
202
+ # Show version
203
+ spatial-memory --version
204
+ ```
205
+
206
+ The `instructions` command is useful for understanding what behavioral guidelines are automatically injected when the MCP server connects to Claude.
207
+
208
+ ### Optional Performance Dependencies
209
+
210
+ For best performance, install these optional dependencies:
211
+
212
+ ```bash
213
+ # ONNX Runtime - 2-3x faster embeddings, 60% less memory
214
+ pip install onnxruntime
215
+
216
+ # Or install with sentence-transformers ONNX support
217
+ pip install "sentence-transformers[onnx]"
218
+
219
+ # scipy - Optimized pairwise similarity calculations
220
+ # Used by visualize, regions, and consolidate operations
221
+ pip install scipy
222
+ ```
223
+
224
+ **Performance comparison:**
225
+
226
+ | Component | Without | With | Benefit |
227
+ |-----------|---------|------|---------|
228
+ | ONNX Runtime | PyTorch inference | ONNX inference | 2-3x faster embeddings |
229
+ | scipy | numpy matrix ops | scipy.cdist | Faster similarity calculations |
230
+
231
+ Both are optional - the system includes fallbacks that use numpy when these aren't available.
232
+
233
+ ## Configuration
234
+
235
+ Copy `.env.example` to `.env` and customize:
236
+
237
+ ```bash
238
+ cp .env.example .env
239
+ ```
240
+
241
+ ### Key Configuration Options
242
+
243
+ | Variable | Default | Description |
244
+ |----------|---------|-------------|
245
+ | `SPATIAL_MEMORY_MEMORY_PATH` | `./.spatial-memory` | LanceDB storage directory |
246
+ | `SPATIAL_MEMORY_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Embedding model (local or `openai:*`) |
247
+ | `SPATIAL_MEMORY_EMBEDDING_BACKEND` | `auto` | Backend: `auto`, `onnx`, or `pytorch` |
248
+ | `SPATIAL_MEMORY_OPENAI_API_KEY` | - | Required only for OpenAI embeddings |
249
+ | `SPATIAL_MEMORY_LOG_LEVEL` | `INFO` | Logging verbosity |
250
+ | `SPATIAL_MEMORY_AUTO_CREATE_INDEXES` | `true` | Auto-create vector indexes |
251
+
252
+ ### Embedding Models
253
+
254
+ **Local models** (no API key required):
255
+ - `all-MiniLM-L6-v2` - Fast, good quality (384 dimensions)
256
+ - `all-mpnet-base-v2` - Slower, better quality (768 dimensions)
257
+
258
+ **OpenAI models** (requires API key):
259
+ - `openai:text-embedding-3-small` - Fast, cost-effective (1536 dimensions)
260
+ - `openai:text-embedding-3-large` - Best quality (3072 dimensions)
261
+
262
+ ### Embedding Backend
263
+
264
+ By default, local models use **ONNX Runtime** for 2-3x faster inference and 60% less memory:
265
+
266
+ | Backend | Speed | Memory | Notes |
267
+ |---------|-------|--------|-------|
268
+ | ONNX Runtime (default) | 2-3x faster | 60% less | Optimized for CPU inference |
269
+ | PyTorch | Baseline | Baseline | Full flexibility |
270
+
271
+ Configure via environment variable:
272
+ ```bash
273
+ # Auto-detect (default) - uses ONNX if available
274
+ SPATIAL_MEMORY_EMBEDDING_BACKEND=auto
275
+
276
+ # Force specific backend
277
+ SPATIAL_MEMORY_EMBEDDING_BACKEND=onnx
278
+ SPATIAL_MEMORY_EMBEDDING_BACKEND=pytorch
279
+ ```
280
+
281
+ ## Usage
282
+
283
+ Add to your Claude Desktop config (`claude_desktop_config.json`):
284
+
285
+ ```json
286
+ {
287
+ "mcpServers": {
288
+ "spatial-memory": {
289
+ "command": "python",
290
+ "args": ["-m", "spatial_memory"],
291
+ "env": {
292
+ "SPATIAL_MEMORY_MEMORY_PATH": "/path/to/memory/storage"
293
+ }
294
+ }
295
+ }
296
+ }
297
+ ```
298
+
299
+ ## Available Tools (22 Total)
300
+
301
+ For complete API documentation including parameters, return types, and examples, see [docs/API.md](docs/API.md).
302
+
303
+ ### Core Operations
304
+
305
+ | Tool | Description |
306
+ |------|-------------|
307
+ | `remember` | Store a memory with optional tags, importance, and metadata |
308
+ | `remember_batch` | Store multiple memories efficiently in a single operation |
309
+ | `recall` | Find memories semantically similar to a query with optional filters |
310
+ | `nearby` | Find memories spatially close to a specific memory by ID |
311
+ | `forget` | Remove a memory by ID |
312
+ | `forget_batch` | Remove multiple memories by IDs |
313
+
314
+ ### Spatial Operations
315
+
316
+ | Tool | Description |
317
+ |------|-------------|
318
+ | `journey` | Interpolate a path between two memories using SLERP, discovering concepts along the way |
319
+ | `wander` | Random walk through memory space for serendipitous discovery |
320
+ | `regions` | Discover conceptual regions via HDBSCAN clustering with auto-generated labels |
321
+ | `visualize` | Generate 2D visualization (JSON coordinates, Mermaid diagrams, or SVG) |
322
+
323
+ ### Lifecycle Operations
324
+
325
+ | Tool | Description |
326
+ |------|-------------|
327
+ | `decay` | Reduce importance of stale/unused memories based on time or access patterns |
328
+ | `reinforce` | Boost importance of useful memories |
329
+ | `extract` | Auto-extract memorable facts, decisions, and insights from text |
330
+ | `consolidate` | Find and merge similar/duplicate memories with configurable strategies |
331
+
332
+ ### Utility Operations
333
+
334
+ | Tool | Description |
335
+ |------|-------------|
336
+ | `stats` | Get comprehensive database statistics (counts, storage, indexes) |
337
+ | `namespaces` | List all namespaces with memory counts |
338
+ | `delete_namespace` | Delete a namespace and all its memories |
339
+ | `rename_namespace` | Rename a namespace |
340
+ | `export_memories` | Export memories to Parquet, JSON, or CSV format |
341
+ | `import_memories` | Import memories from exported files with validation |
342
+ | `hybrid_recall` | Combined vector + full-text search with configurable weighting |
343
+ | `health` | Check system health status |
344
+
345
+ ## Tool Examples
346
+
347
+ ### Remember a Memory
348
+
349
+ ```
350
+ Store this: "Use repository pattern for database access in this project"
351
+ Tags: architecture, patterns
352
+ Importance: 0.8
353
+ ```
354
+
355
+ ### Semantic Recall
356
+
357
+ ```
358
+ What do I know about database patterns?
359
+ ```
360
+
361
+ ### Journey Between Concepts
362
+
363
+ ```
364
+ Show me a journey from "React components" to "database design"
365
+ ```
366
+ This reveals intermediate concepts like state management, data flow, API design, etc.
367
+
368
+ ### Discover Regions
369
+
370
+ ```
371
+ What conceptual regions exist in my memories?
372
+ ```
373
+ Returns auto-clustered groups with labels and representative memories.
374
+
375
+ ### Apply Memory Decay
376
+
377
+ ```
378
+ Decay unused memories (dry run first to preview)
379
+ ```
380
+
381
+ ### Export for Backup
382
+
383
+ ```
384
+ Export all memories to parquet format
385
+ ```
386
+
387
+ ## Security Features
388
+
389
+ - **Path Traversal Prevention**: All file operations validate paths against allowed directories
390
+ - **Symlink Attack Protection**: Optional symlink blocking for sensitive environments
391
+ - **SQL Injection Prevention**: 13 patterns covering major attack vectors
392
+ - **Input Validation**: Pydantic models validate all inputs
393
+ - **Error Sanitization**: Internal errors return reference IDs, not stack traces
394
+ - **Secure Credential Handling**: API keys stored as SecretStr
395
+
396
+ ## Deployment Considerations
397
+
398
+ ### Network Filesystems (NFS/SMB/CIFS)
399
+
400
+ Spatial Memory uses file-based locking to prevent data corruption when multiple processes access the same storage. **File locking does not work reliably on network filesystems** such as NFS, SMB/CIFS, or SSHFS.
401
+
402
+ If the storage path is on a network filesystem, you will see a warning at startup:
403
+
404
+ ```
405
+ WARNING: Storage path appears to be on a network filesystem (nfs).
406
+ File-based locking does not work reliably on network filesystems.
407
+ Running multiple instances against this storage may cause data corruption.
408
+ ```
409
+
410
+ **Recommendations:**
411
+ 1. **Use local storage** (default: `./.spatial-memory`) for reliable operation
412
+ 2. **Single instance only**: If you must use network storage, ensure only one MCP server instance accesses it
413
+ 3. **Acknowledge the risk**: Set `SPATIAL_MEMORY_ACKNOWLEDGE_NETWORK_FS_RISK=true` to suppress the warning
414
+
415
+ ## Development
416
+
417
+ ### Running Tests
418
+
419
+ ```bash
420
+ # All tests
421
+ pytest tests/ -v
422
+
423
+ # Fast unit tests only
424
+ pytest tests/ -m unit -v
425
+
426
+ # Security-specific tests
427
+ pytest tests/ -k "security or injection" -v
428
+ ```
429
+
430
+ ### Type Checking
431
+
432
+ ```bash
433
+ mypy spatial_memory/ --ignore-missing-imports
434
+ ```
435
+
436
+ ### Linting
437
+
438
+ ```bash
439
+ ruff check spatial_memory/ tests/
440
+ ```
441
+
442
+ ## Architecture
443
+
444
+ The project follows Clean Architecture principles:
445
+
446
+ ```
447
+ spatial_memory/
448
+ ├── core/ # Domain logic (database, embeddings, models, errors)
449
+ ├── services/ # Application services (memory, spatial, lifecycle)
450
+ ├── adapters/ # Infrastructure (LanceDB repository)
451
+ ├── ports/ # Protocol interfaces
452
+ └── server.py # MCP server entry point
453
+ ```
454
+
455
+ See [SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md](SPATIAL-MEMORY-ARCHITECTURE-DIAGRAMS.md) for visual architecture documentation.
456
+
457
+ ## Documentation
458
+
459
+ | Document | Description |
460
+ |----------|-------------|
461
+ | [docs/API.md](docs/API.md) | Complete API reference for all 22 tools |
462
+ | [docs/BENCHMARKS.md](docs/BENCHMARKS.md) | Performance benchmarks and test results |
463
+ | [docs/METRICS.md](docs/METRICS.md) | Prometheus metrics documentation |
464
+ | [docs/troubleshooting.md](docs/troubleshooting.md) | Troubleshooting guide |
465
+
466
+ ## Troubleshooting
467
+
468
+ ### Common Issues
469
+
470
+ **Model download fails**: The first run downloads the embedding model (~80MB). Ensure internet connectivity.
471
+
472
+ **Permission errors**: Check that `SPATIAL_MEMORY_MEMORY_PATH` is writable.
473
+
474
+ **OpenAI errors**: Verify `SPATIAL_MEMORY_OPENAI_API_KEY` is set correctly.
475
+
476
+ **Import validation errors**: Use `dry_run=true` first to preview validation issues.
477
+
478
+ ## Contributing
479
+
480
+ Contributions welcome! Please:
481
+ 1. Fork the repository
482
+ 2. Create a feature branch
483
+ 3. Add tests for new functionality
484
+ 4. Ensure all tests pass
485
+ 5. Submit a pull request
486
+
487
+ ## Security
488
+
489
+ For security vulnerabilities, please email directly rather than opening a public issue.
490
+
491
+ ## For Claude Code Users
492
+
493
+ When the MCP server connects, behavioral instructions are **automatically injected** into Claude's context—no configuration needed. Run `spatial-memory instructions` to view what gets injected.
494
+
495
+ For contributors working on this codebase, [CLAUDE.md](CLAUDE.md) provides project-specific guidance for AI assistants.
496
+
497
+ ## License
498
+
499
+ MIT - See [LICENSE](LICENSE)
@@ -0,0 +1,54 @@
1
+ spatial_memory/__init__.py,sha256=EyatcPsUmrDMaTwxNlGjbZ8FFBK_ug2jkNLE2xNJvz4,2154
2
+ spatial_memory/__main__.py,sha256=mqjUT_XvNiRNgB1knAK2NNEfe1Jz5d5Idsv4UBNatZc,8297
3
+ spatial_memory/config.py,sha256=SvG67Z8Hjw0XAFzVn59lLm-_Pz5dzL-c4Dli3_mtG0M,22537
4
+ spatial_memory/factory.py,sha256=iuVKeE0q9SrDo816k2H744nELFeq7vVOdg4puHxCFOM,15806
5
+ spatial_memory/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
6
+ spatial_memory/server.py,sha256=4a4WbS_Us0OiLfRyt5Mj3WU9rMCdMRbU6ziWajG-72I,45779
7
+ spatial_memory/verify.py,sha256=4p4KQYRUBrKGax66n629hvb9Ul8sR2yXXnfyZLpNk-o,3939
8
+ spatial_memory/adapters/__init__.py,sha256=xNPQCOYVsTP2ogMEcYGbxGJYH9pdksB66MZ7ctK6KbM,187
9
+ spatial_memory/adapters/lancedb_repository.py,sha256=NwZQ-SGPTe82cFbOYtYERPRvY3eujz5iCd7EOaLiDfE,31247
10
+ spatial_memory/core/__init__.py,sha256=wG6fws4AIF3X1vJdWA2_w2bMQo4ZXez_BYtcYvFGQvY,3033
11
+ spatial_memory/core/cache.py,sha256=QqG0hhpaDH0mzBLIEinGP3WkKsb70QfCLMGpptguWIM,10038
12
+ spatial_memory/core/circuit_breaker.py,sha256=zxqnOWiAnx_S7oX44UY57ihpk7V27fzW6rYgBn1BWp8,10734
13
+ spatial_memory/core/connection_pool.py,sha256=ienTFQ-tFYwkaWD2_lcs9T8uYXL45OMpzCX5V-l_MMk,7617
14
+ spatial_memory/core/consolidation_strategies.py,sha256=_PGdVuz4Kkf96cdIEPieGTOfubgOc6PoUYuXfJRwBd8,12805
15
+ spatial_memory/core/database.py,sha256=3Llo2FLznQA2zUYf5r1JFnht61bPZQGTGeZ2IVhxDMI,118227
16
+ spatial_memory/core/db_idempotency.py,sha256=B0EYdZFZYmQ7s101RviswySta7Qp7TZ2fiqWES_djyw,7978
17
+ spatial_memory/core/db_indexes.py,sha256=p1glBuna81yY8bu8hhJkR6AhuzeZgaAaeKnsd3Oe4No,20115
18
+ spatial_memory/core/db_migrations.py,sha256=x-_dXZrtfZZQwb4d3ZW32zw1-CzbDLC7Y33fdsvQM5Y,19138
19
+ spatial_memory/core/db_search.py,sha256=XnNpqI2oto9EKbmp7bYBxeaxGfblJicR9KazvZKfhbg,19866
20
+ spatial_memory/core/db_versioning.py,sha256=7LGWQO6EiwIgw-C5e81xG4jEO34b5y95Ag6uoVrU7Xw,5984
21
+ spatial_memory/core/embeddings.py,sha256=g_C8rmrNH8qTroPcg-aYJo5Z6NR_YqGN050Iryytx5c,20892
22
+ spatial_memory/core/errors.py,sha256=mGQlPNNiNOdErYPXdEQXM1_-IeueUB_jtgdt8P8lzUQ,8799
23
+ spatial_memory/core/file_security.py,sha256=kHIYEnZIRFz94FxCJ7oOHiaihgQRB1rsOHHmJprHNhU,25766
24
+ spatial_memory/core/filesystem.py,sha256=aE8BvM8tyIMbjtaiyG0Si0F1c85jxAwa3IM5I_kvkME,5602
25
+ spatial_memory/core/health.py,sha256=Xq9TYfmBN3YLjYOrpFWtvbR1-fQbSrP1oorSVjRHOSg,9145
26
+ spatial_memory/core/helpers.py,sha256=nxLXGfkpydWzEgMj8PkdX9gVvybN2aCH-CfbEkq6U_w,1931
27
+ spatial_memory/core/import_security.py,sha256=DiG0BsX65JGGf6B1T855SVz1TZB1ViI3JXRi1uW03sQ,13296
28
+ spatial_memory/core/lifecycle_ops.py,sha256=P8jc4JGBF39ayNikgLu0I3kGcJ3ph0VsvAHSxjp35FI,35836
29
+ spatial_memory/core/logging.py,sha256=JfFRzHmhZ2BPNSJiKIHGjfUeskFVo8Bj7nOKznvv0kU,6542
30
+ spatial_memory/core/metrics.py,sha256=8B26sAd2y6xrpaJr8mNgOAMzAZDd1uXOvAGxz_1nhfY,5383
31
+ spatial_memory/core/models.py,sha256=VX61h5_pnsIQ5w5LjpElhVTW4UAa0RKadnrtLLOQb94,17353
32
+ spatial_memory/core/rate_limiter.py,sha256=5A3YI6C0_YrWZeSBBxF7Eu5HUD8rodS45301730doF0,10582
33
+ spatial_memory/core/response_types.py,sha256=VhfQLpTxgdJf3CYPtQALvh4KmaUbHzVAT_qtRVtoQgs,10603
34
+ spatial_memory/core/security.py,sha256=fjIYqsyzK4qqm7sI8FNEE2xx9WjNJnrAslOBLVRVwgs,19759
35
+ spatial_memory/core/spatial_ops.py,sha256=_xNrZzrbL7w2uAMJkQZEtTMjERQpo04cuSUoTNebiew,13360
36
+ spatial_memory/core/tracing.py,sha256=9O3WdUJfCl2sohYWlaQETrCO7_P_N3qY_MqSAnpQPl0,8438
37
+ spatial_memory/core/utils.py,sha256=YvvU3EbbAicR732LkHMM5-u4wvBaJ4G9DigBaB2CoI4,3438
38
+ spatial_memory/core/validation.py,sha256=A8a5PF7X8Veg8S176UFEqkZDBlWILbQM-5wtAMOgG3U,13476
39
+ spatial_memory/migrations/__init__.py,sha256=wljoV_u2PPx-dH6JOPmjEP5xEbwoM9HQ1WYDZr7PW58,1072
40
+ spatial_memory/ports/__init__.py,sha256=Lq9ht9AS4VwPbMojtd_FYkA7lUuCXmYHwv6sweJi9AQ,243
41
+ spatial_memory/ports/repositories.py,sha256=oJMU7UHoj4YudyeOQaSkI9A2z81L3Vn2q7hm3RILfXI,19920
42
+ spatial_memory/services/__init__.py,sha256=epaF3aHxK2sgGVMp6rS_fxMMAvDVPxjaWm1n4hKOMWU,1564
43
+ spatial_memory/services/export_import.py,sha256=2vZnFvX1deV-Zdj0HGkc2My8Oy1BrFJL8Peep25iUKI,38190
44
+ spatial_memory/services/lifecycle.py,sha256=asxFBp06qfnaZJpAph6Dm6i7kN1cREXuoopkjuOMvwc,42937
45
+ spatial_memory/services/memory.py,sha256=MZ9NMNXBRYEA39vzT5gAB7PXJrGFwC-D98SLZe7Z50Q,12944
46
+ spatial_memory/services/spatial.py,sha256=3UMPm4mRQ42oXNwLUEYp4SAinnGX4dwOnWaK9CkVViA,42552
47
+ spatial_memory/services/utility.py,sha256=89rn1gNJwNQIhrWjmVS3RKP5AQuCvjswFeefMp7yK-4,14950
48
+ spatial_memory/tools/__init__.py,sha256=ZhFZp5j8HA4Qx5pVcRmgTcBbqY3X5TmgMNpSkyAMqJA,127
49
+ spatial_memory/tools/definitions.py,sha256=Ueg_BrRGJcp_jnQD95DiYFPkxU419XPkbjzQFDG3jtY,25397
50
+ spatial_memory_mcp-1.6.1.dist-info/METADATA,sha256=b2_4u74BbHYT3xCq7sDRZNd0TupGiJtQsc6k5w54x3E,16772
51
+ spatial_memory_mcp-1.6.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
52
+ spatial_memory_mcp-1.6.1.dist-info/entry_points.txt,sha256=nJ4RJBB9SvhNktJdikcAS27fSwtKekpgPR4GTy2r1cE,64
53
+ spatial_memory_mcp-1.6.1.dist-info/licenses/LICENSE,sha256=g65vrroU3yJxekbYV8xmDj7KFrXAg89eCM8vcWrpKmU,1095
54
+ spatial_memory_mcp-1.6.1.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.28.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any