# j3k0/mcp-brain-tools architecture

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

- Interactive diagram: https://gitdiagram.com/j3k0/mcp-brain-tools
- Repository: https://github.com/j3k0/mcp-brain-tools

## Overview

##### Main Components
- AI Conversation Memory Service – This is the core of the system that handles storing, updating, and retrieving conversation data.
- Knowledge Graph Engine – Represented by components (e.g., kg-client.ts, kg-inspection.ts) that manage entities and relationships.
- Elasticsearch Backend – The project relies on Elasticsearch (as noted by the badge and README) for persistent storage and smart search capabilities.
- Admin CLI Tools – Modules such as admin-cli.ts provide a command-line interface to manage the graph (search, backup, zone creation, etc.).
- Filesystem Module – Indicated in the src/filesystem directory, this likely manages file-based operations related to data ingestion or storage handling.
- Logger – The logger.ts helps in tracking and recording activities, which is crucial for debugging and monitoring.
- Legacy Components – The legacy folder contains older CLI utilities and test scripts which can be shown as legacy modules that might still interact with or influence the current system.

##### Relationships and Interactions
- Data Flow: Show how an incoming AI conversation or entity update flows from the AI service (ai-service.ts) into the knowledge graph and then is stored in Elasticsearch. Then, how search queries or memory recall requests traverse back from Elasticsearch to the AI service.
- Admin Operations: Indicate that the Admin CLI (admin-cli.ts) interacts directly with the Knowledge Graph Engine and Elasticsearch for maintenance tasks like search, entity lookup, backup, and zone management.
- Filesystem Interactions: Illustrate how the filesystem module might be used for import/export operations (e.g., loading JSON data or processing local files).
- Legacy Processing: Optionally, include how legacy modules provide support or backward compatibility and interact with updated modules.

##### Architectural Patterns and Design Principles
- Service-Oriented/Modular Design: Emphasize that components such as AI service logic, filesystem operations, and admin tools are separated into distinct modules. This modularity supports easier testing and extensibility.
- Client-Server Interaction: While there isn’t a separate frontend, the interaction flow from Claude Desktop (via the launch script/CLI integration) to the memory service can be captured.
- Layered Architecture: Separate the business logic (memory processing, entity creation/updates) from infrastructural specifics like connecting with Elasticsearch.
- Dependency & Integration: Highlight Node.js (as the runtime), and note that Docker and docker-compose files indicate containerized deployment for Elasticsearch and possibly for the service itself.

##### Relevant Technologies
- Node.js (version 18+)
- Elasticsearch (version 7.x)
- Docker & Docker Compose (for running Elasticsearch)
- Testing frameworks (Jest and Vitest as seen by jest.config and vitest.config)

- Annotations or notes about key functionalities such as “Contextual Recall”, “Entity Management”, and “Memory Zones” that highlight how the service differentiates between short-term and long-term memory.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Memory Service Layer
    subgraph "Memory Service Layer"
        A["AI Conversation Memory Service"]:::service
        KG["Knowledge Graph Engine"]:::service
        subgraph "Knowledge Graph Details"
            KGc["kg-client.ts"]:::service
            KGi["kg-inspection.ts"]:::service
        end
        L["Logger"]:::service
    end

    %% Administrative & Tools Layer
    subgraph "Administrative & Tools Layer"
        Admin["Admin CLI Tools"]:::admin
        FS["Filesystem Module"]:::admin
    end

    %% Persistent Storage
    subgraph "Persistent Storage"
        ES_Docker["Dockerfile"]:::storage
        ES_Compose["docker-compose.yml"]:::storage
    end

    %% Legacy Components
    subgraph "Legacy Components"
        Legacy["Legacy Modules"]:::legacy
    end

    %% External Initiator
    External["Claude Desktop / Launch Script"]:::external

    %% Connections / Data Flows
    External -->|"initiates"| A
    A -->|"updates"| KG
    KG -->|"stores"| ES_Docker
    KG -->|"stores"| ES_Compose
    Admin -->|"manages"| KG
    Admin -->|"operates"| ES_Docker
    Admin -->|"operates"| ES_Compose
    A -->|"logs"| L
    A -->|"fileOps"| FS
    ES_Docker -->|"returns"| A
    ES_Compose -->|"returns"| A
    Legacy -->|"supports"| A
    Legacy -->|"influences"| Admin

    %% Click Events
    click A "https://github.com/j3k0/mcp-brain-tools/blob/main/src/ai-service.ts"
    click KGc "https://github.com/j3k0/mcp-brain-tools/blob/main/src/kg-client.ts"
    click KGi "https://github.com/j3k0/mcp-brain-tools/blob/main/src/kg-inspection.ts"
    click ES_Docker "https://github.com/j3k0/mcp-brain-tools/tree/main/Dockerfile"
    click ES_Compose "https://github.com/j3k0/mcp-brain-tools/blob/main/docker-compose.yml"
    click Admin "https://github.com/j3k0/mcp-brain-tools/blob/main/src/admin-cli.ts"
    click FS "https://github.com/j3k0/mcp-brain-tools/tree/main/src/filesystem/"
    click L "https://github.com/j3k0/mcp-brain-tools/blob/main/src/logger.ts"
    click Legacy "https://github.com/j3k0/mcp-brain-tools/tree/main/legacy/"

    %% Styles
    classDef service fill:#AED6F1,stroke:#2E86C1,stroke-width:2px;
    classDef admin fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef storage fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef legacy fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef external fill:#EBDEF0,stroke:#8E44AD,stroke-width:2px;
```
