# rkunnamp/mcp-memory-service architecture

> Architecture diagram of the GitHub repository rkunnamp/mcp-memory-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rkunnamp/mcp-memory-service
- Repository: https://github.com/rkunnamp/mcp-memory-service

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Layer
  Client["Claude Desktop Client"]:::client
  click Client "https://github.com/rkunnamp/mcp-memory-service/blob/main/claude_config/claude_desktop_config.json"

  %% Edge Layer (optional)
  Worker["Cloudflare Worker (Edge)"]:::edge
  click Worker "https://github.com/rkunnamp/mcp-memory-service/blob/main/cloudflare_worker/src/index.ts"

  %% Service Layer
  subgraph "MCP Memory Service"  
    direction TB
    Server["Server (server.py)"]:::service
    click Server "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/server.py"
    Config["Config (config.py)"]:::service
    click Config "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/config.py"
    Models["Models (memory.py)"]:::service
    click Models "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/models/memory.py"
    subgraph "Storage Backends"
      direction TB
      BaseStorage["Storage Base (base.py)"]:::service
      click BaseStorage "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/storage/base.py"
      ChromaStorage["ChromaDB Backend (chroma.py)"]:::service
      click ChromaStorage "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/storage/chroma.py"
    end
    subgraph "Utils"
      direction TB
      DBUtils["db_utils.py"]:::service
      click DBUtils "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/utils/db_utils.py"
      Debug["debug.py"]:::service
      click Debug "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/utils/debug.py"
      Hashing["hashing.py"]:::service
      click Hashing "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/utils/hashing.py"
      Detection["system_detection.py"]:::service
      click Detection "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/utils/system_detection.py"
      TimeParser["time_parser.py"]:::service
      click TimeParser "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/utils/time_parser.py"
      Utils["utils.py"]:::service
      click Utils "https://github.com/rkunnamp/mcp-memory-service/blob/main/src/mcp_memory_service/utils/utils.py"
    end
  end

  %% External Components
  Embedding["Embedding Engine\n(Sentence Transformers)"]:::external

  %% Persistence Layer
  ChromaDB["ChromaDB\n(Vector Store)"]:::storage
  Backup["Backup Storage\n(File-system)"]:::storage

  %% Dev & Ops
  subgraph "Dev & Ops" 
    direction TB
    Install["install.py"]:::devops
    click Install "https://github.com/rkunnamp/mcp-memory-service/blob/main/install.py"
    InstallWin["scripts/install_windows.py"]:::devops
    click InstallWin "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/install_windows.py"
    WrapperPy["memory_wrapper.py"]:::devops
    click WrapperPy "https://github.com/rkunnamp/mcp-memory-service/blob/main/memory_wrapper.py"
    WrapperUV["memory_wrapper_uv.py"]:::devops
    click WrapperUV "https://github.com/rkunnamp/mcp-memory-service/blob/main/memory_wrapper.py"
    RunUV["run-with-uv.sh"]:::devops
    click RunUV "https://github.com/rkunnamp/mcp-memory-service/blob/main/run-with-uv.sh"
    BackupScript["backup_memories.py"]:::devops
    click BackupScript "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/backup_memories.py"
    CleanupScript["cleanup_memories.py"]:::devops
    click CleanupScript "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/cleanup_memories.py"
    CleanupMd["cleanup_memories.md"]:::devops
    click CleanupMd "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/cleanup_memories.md"
    Migration1["mcp-migration.py"]:::devops
    click Migration1 "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/mcp-migration.py"
    Migration2["migrate_tags.py"]:::devops
    click Migration2 "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/migrate_tags.py"
    Migration3["migrate_timestamps.py"]:::devops
    click Migration3 "https://github.com/rkunnamp/mcp-memory-service/blob/main/scripts/migrate_timestamps.py"
  end

  %% CI/CD & Deployment
  Dockerfile["Dockerfile"]:::devops
  click Dockerfile "https://github.com/rkunnamp/mcp-memory-service/tree/main/Dockerfile"
  DockerCompose["docker-compose.yml"]:::devops
  click DockerCompose "https://github.com/rkunnamp/mcp-memory-service/blob/main/docker-compose.yml"
  ComposePyPath["docker-compose.pythonpath.yml"]:::devops
  click ComposePyPath "https://github.com/rkunnamp/mcp-memory-service/blob/main/docker-compose.pythonpath.yml"
  ComposeUV["docker-compose.uv.yml"]:::devops
  click ComposeUV "https://github.com/rkunnamp/mcp-memory-service/blob/main/docker-compose.uv.yml"
  ReleaseCI[".github/workflows/release.yml"]:::devops
  click ReleaseCI "https://github.com/rkunnamp/mcp-memory-service/blob/main/.github/workflows/release.yml"

  %% Flows
  Client -- "MCP/HTTP" --> Worker
  Client -- "MCP/HTTP" --> Server
  Worker -- "MCP/HTTP" --> Server
  Server -- "embed →" --> Embedding
  Embedding -- "vectors" --> ChromaDB
  Server -- "store/retrieve" --> ChromaDB
  Server -- "backup snapshots" --> Backup
  Server -- "optimize/cleanup" --> ChromaDB
  Server -- "responses" --> Client

  %% Styles
  classDef client fill:#D0E7FF,stroke:#037DD6,color:#037DD6;
  classDef edge fill:#E0F7FA,stroke:#00ACC1,color:#006064;
  classDef service fill:#E8F5E9,stroke:#43A047,color:#2E7D32;
  classDef storage fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
  classDef external fill:#F3E5F5,stroke:#8E24AA,color:#6A1B9A;
  classDef devops fill:#ECEFF1,stroke:#607D8B,color:#455A64;
```
