# jktfe/myaimemory-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/jktfe/myaimemory-mcp
- Repository: https://github.com/jktfe/myaimemory-mcp

## Overview

##### Main Components
- Client Interfaces & Command-Line Tools:
– The CLI (exposed via files like src/cli.ts and unified CLI commands) and direct scripts (e.g., direct-server.ts, direct-mcp.ts) that trigger memory updates.
– Shell scripts and Docker integration (Dockerfile, start-server.sh, etc.) which reflect deployment options.
- Transport Layer:
– Two main transport strategies are supported: HTTP (e.g., HttpTransport.ts, start-http-server.sh) and stdio (e.g., StdioTransport.ts).
– Indicate this layer as managing communication between client commands and the MCP server.
- Core MCP Engine:
– Includes core server components (e.g., ServerFactory.ts, MCP server implementations in src/core/server) that manage MCP communication.
– Handlers (DirectRequestHandler.ts, ToolHandlers.ts) which parse and process memory commands.
– Service Factories and services (e.g., PlatformService.ts, TemplateService.ts, CustomPlatformService.ts) for managing memory updates and platform synchronization.
- Memory Management Modules:
– Template Parser and Template Storage (templateParser.ts, templateStorage.ts) for converting between markdown format and structured memory objects.
– Memory Cache Service (MemoryCommandProcessor.ts) implementing caching with TTL-based strategies.
- Platform Synchronizers:
– Components responsible for interfacing with external systems (e.g., ClaudeDesktop, Windsurf, and possibly ClaudeWeb) are evident from the README and the file organization in services and platform-related utilities.
- Configuration & Environment:
– Support files like .env.example, config.json, and scripts (update-config.js, setupConfig.ts) indicate where system configuration is managed.

##### Relationships and Data/Control Flow
- User or system administrator triggers a memory update via the CLI or directly (using natural language commands described in the README).
- The input flows to the MCP server entry point (either via HTTP or stdio).
- The server then invokes the appropriate handler (DirectRequestHandler or ToolHandlers) to process the natural language command.
- The handler interacts with the core services: the Template Parser converts the markdown template to structured memory, and the Template Storage and Memory Cache Service handle local caching and persistence.
- Platform synchronizers (through PlatformService and associated adapters) push updates to configured endpoints (Claude Desktop, Claude Code, Windsurf, etc.).
- The overall system responds with confirmations and/or error messages, and the caching mechanism ensures high performance.

##### Architectural Patterns and Design Principles
- Modular Design: The separation between core modules (handlers, server, services, transport) ensures separation of concerns.
- Pluggable Transport Strategies: Using different transport methods (HTTP vs. stdio) allows the system to serve multiple integration scenarios.
- Command and Event Handling: Natural language commands are parsed and routed through dedicated handlers that update defined memory sections.
- Local-First and Security-Oriented: Emphasis on local data storage combined with robust testing (__tests__ folder) and controlled configuration (.env, .gitignore).

##### Relevant Technologies
- Languages & Framework: TypeScript is the primary language; Node.js runtime environment.
- Testing: Jest structure indicated by __tests__ folder and jest.config.js.
- Containerization: Dockerfile indicates a containerized deployment option.
- Scripting: Extensive use of shell scripts for various startup, sync, and permission fixing tasks.
- External API Integration: Optional use of Anthropic API as shown by environment variable ENABLE_ANTHROPIC.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLI["CLI Interface"]
        DirectCmd["Direct Command Scripts"]
    end

    %% Transport Layer
    subgraph "Transport Layer"
        HTTP["HTTP Transport"]
        STDIO["Stdio Transport"]
    end

    %% Core MCP Engine
    subgraph "Core MCP Engine"
        %% Request Handlers
        subgraph "Request Handlers"
            DirectHandler["Direct Request Handler"]
            ToolHandler["Tool Handlers"]
        end
        %% Server Components
        subgraph "Server Components"
            ServerFactory["Server Factory"]
            MCPServer["MCP Server"]
        end
        %% Service Modules
        subgraph "Service Modules"
            ServiceFactory["Service Factory"]
            PlatformService["Platform Service"]
            CustomPlatformService["Custom Platform Service"]
            TemplateService["Template Service"]
            CustomTemplateService["Custom Template Service"]
        end
        %% Memory Management Modules
        subgraph "Memory Management Modules"
            TemplateParser["Template Parser"]
            TemplateStorage["Template Storage"]
            MemoryCache["Memory Cache Service"]
        end
    end

    %% Platform Synchronizers
    subgraph "Platform Synchronizers"
        PlatformSync["Platform Synchronizers"]
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        EnvConfig["Environment Config"]
        JSONConfig["Configuration JSON"]
        ConfigSetup["Config Setup"]
    end

    %% Deployment & Testing
    subgraph "Deployment & Testing"
        Docker["Docker & Deployment"]
        Testing["Testing & Scripts"]
    end

    %% Data Flow
    CLI -->|"triggers"| HTTP
    CLI -->|"triggers"| STDIO
    DirectCmd -->|"triggers"| HTTP
    DirectCmd -->|"triggers"| STDIO

    HTTP -->|"routes to"| DirectHandler
    STDIO -->|"routes to"| ToolHandler

    DirectHandler -->|"calls"| ServerFactory
    ToolHandler -->|"calls"| ServerFactory

    ServerFactory -->|"instantiates"| MCPServer
    MCPServer -->|"invokes"| ServiceFactory

    ServiceFactory -->|"creates"| PlatformService
    ServiceFactory -->|"creates"| TemplateService
    ServiceFactory -->|"creates"| CustomPlatformService
    ServiceFactory -->|"creates"| CustomTemplateService

    TemplateService -->|"uses"| TemplateParser
    TemplateService -->|"uses"| TemplateStorage
    TemplateService -->|"uses"| MemoryCache

    PlatformService -->|"triggers"| PlatformSync
    CustomPlatformService -->|"triggers"| PlatformSync

    EnvConfig -->|"configures"| HTTP
    EnvConfig -->|"configures"| STDIO
    JSONConfig -->|"feeds"| ConfigSetup
    ConfigSetup -->|"configures"| ServerFactory

    Docker -->|"deploys"| HTTP
    Docker -->|"deploys"| STDIO
    Testing -->|"validates"| ServerFactory

    %% Click Events for CLI Interface & Command-Line Tools
    click CLI "https://github.com/jktfe/myaimemory-mcp/blob/main/src/cli.ts"
    click DirectCmd "https://github.com/jktfe/myaimemory-mcp/blob/main/src/direct-mcp.ts"

    %% Click Events for Transport Layer
    click HTTP "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/transport/HttpTransport.ts"
    click STDIO "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/transport/StdioTransport.ts"

    %% Click Events for Core MCP Engine - Server Components
    click ServerFactory "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/server/ServerFactory.ts"
    click MCPServer "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/server/McpServer.ts"

    %% Click Events for Core MCP Engine - Request Handlers
    click DirectHandler "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/handlers/DirectRequestHandler.ts"
    click ToolHandler "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/handlers/ToolHandlers.ts"

    %% Click Events for Core MCP Engine - Service Modules
    click ServiceFactory "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/services/ServiceFactory.ts"
    click PlatformService "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/services/PlatformService.ts"
    click CustomPlatformService "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/services/CustomPlatformService.ts"
    click TemplateService "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/services/TemplateService.ts"
    click CustomTemplateService "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/services/CustomTemplateService.ts"

    %% Click Events for Memory Management Modules
    click TemplateParser "https://github.com/jktfe/myaimemory-mcp/blob/main/src/templateParser.ts"
    click TemplateStorage "https://github.com/jktfe/myaimemory-mcp/blob/main/src/templateStorage.ts"
    click MemoryCache "https://github.com/jktfe/myaimemory-mcp/blob/main/src/core/utils/MemoryCommandProcessor.ts"

    %% Click Event for Platform Synchronizers
    click PlatformSync "https://github.com/jktfe/myaimemory-mcp/blob/main/src/platformSync.ts"

    %% Click Events for Configuration & Environment
    click EnvConfig "https://github.com/jktfe/myaimemory-mcp/blob/main/.env.example"
    click JSONConfig "https://github.com/jktfe/myaimemory-mcp/blob/main/config.json"
    click ConfigSetup "https://github.com/jktfe/myaimemory-mcp/blob/main/src/setupConfig.ts"

    %% Styling Classes
    class CLI,DirectCmd client
    class HTTP,STDIO transport
    class DirectHandler,ToolHandler,ServerFactory,MCPServer,ServiceFactory,PlatformService,CustomPlatformService,TemplateService,CustomTemplateService core
    class TemplateParser,TemplateStorage,MemoryCache memory
    class PlatformSync platform
    class EnvConfig,JSONConfig,ConfigSetup config
    class Docker,Testing deploy

    %% Class Definitions with Colors
    classDef client fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef transport fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef core fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef memory fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef platform fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef config fill:#FCF3CF,stroke:#7D6608,stroke-width:2px;
    classDef deploy fill:#E8DAEF,stroke:#6C3483,stroke-width:2px;
```
