How rkunnamp/mcp-memory-service works
Project Type and Purpose
• Type: A standalone microservice (MCP server) providing semantic memory and persistent storage for Claude Desktop clients.
• Purpose: Exposes an HTTP/MCP protocol interface to store, retrieve, and manage “memories” using vector embeddings (via Sentence Transformers) and ChromaDB.
Main Architectural Components
a. Claude Desktop Client
– Initiates memory operations (store, retrieve, delete) via MCP protocol.
– Configured with claude_desktop_config.json or wrapper scripts.
b. Cloudflare Worker (optional edge component)
– Written in TypeScript (cloudflare_worker/src/index.ts).
– Can proxy or pre-process requests from the client before hitting the memory service.
c. MCP Memory Service (Python)
– Core package under src/mcp_memory_service/.
– Sub-components:
• Server (server.py): HTTP/MCP entry point.
• Config (config.py): Reads environment variables.
• Models: Data schemas (e.g., memory.py).
• Storage: Pluggable backends (chroma.py, base classes).
• Utils: Helpers (time parsing, hashing, debug).
d. Embedding Engine
– Sentence Transformers library invoked by the service.
– Hardware-aware (CUDA, MPS, ONNX, DirectML) via environment flags.
e. ChromaDB Vector Store
– Local or mounted volume (MCP_MEMORY_CHROMA_PATH).
– Provides persistent storage of embeddings and metadata.
f. Backup Storage
– File-system folder (MCP_MEMORY_BACKUPS_PATH): automatic snapshot backups.
g. Helper Scripts & Wrappers
– Installers (install.py, scripts/install_windows.py).
– Runners (memory_wrapper.py, uv_wrapper.py, run-with-uv.sh).
– Migration, health-check, and debug tools under scripts/.
h. Deployment & Orchestration
– Dockerfile + docker-compose variants.
– .github/workflows/release.yml for CI/CD.
Relationships and Data Flows
1. Claude Desktop → (HTTP/MCP) → Cloudflare Worker → (HTTP/MCP) → MCP Memory Service
2. MCP Memory Service
• On write: → Embedding Engine → ChromaDB
• On read: ChromaDB → Service → Claude Desktop
• On backup: Service → Backup Storage
• On optimize/cleanup: Service → ChromaDB
Architectural Patterns & Design Principles
– Microservice boundary around mcp_memory_service Python package.
– Layered structure within the service: API layer, business-logic layer, persistence layer.
– Pluggable storage backends (Strategy pattern).
– Async I/O (async/await) for all I/O operations.
– Containerized deployment; CI/CD via GitHub Actions.
– Hardware feature detection and graceful fallback.
Technologies, Frameworks & Libraries to Annotate
– Python 3.10+, FastAPI or custom TCP server (if applicable)
– Sentence Transformers (for embedding)
– ChromaDB (vector database)
– Docker & Docker-Compose
– Cloudflare Workers (TypeScript)
– PyTorch / ONNX / DirectML / MPS (hardware backends)
– UV package manager (alternative runtime)