# nevamind-ai/memu architecture

> Architecture diagram of the GitHub repository nevamind-ai/memu, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nevamind-ai/memu
- Repository: https://github.com/nevamind-ai/memu

## Overview

##### Project type and purpose
- MemU is an open-source “memory framework” specialized for AI companions. It provides:
- SDKs (Python & JavaScript/TypeScript) for client integration
- A self-hostable server (FastAPI) exposing REST endpoints
- A pluggable memory engine that organizes, retrieves, and evolves conversation memories
- Multiple LLM client adapters (OpenAI, Azure, OpenRouter, Deepseek, etc.)

##### File structure to infer architecture
- Top-level: Docker/Docker-Compose files, CI workflows, Makefile, README, licenses
- memu/ directory:
- config/ → YAML/​prompt configs for activities, events, profiles
- llm/ → adapter implementations for various LLM providers
- memory/ → core memory engine (agents, actions, embeddings, file manager)
- sdk/ → language-specific client libraries (python & javascript)
- server/ → FastAPI-based HTTP server (routers, services, CLI entrypoint)
- utils/ → logging helper
- example/ demonstrates client usage and a test server
- docs/ contains API reference

##### README insights
- Confirms layering: client → API → memory engine → LLM backends
- Mentions “memory as file system,” “knowledge graph,” “self-reflection,” “adaptive forgetting” → memory engine responsibilities
- Highlights cloud (hosted) vs. self-hosting (local) modes

##### Main components & interactions
A. Client Layer
- Your application + SDK (Python/JS)
- Calls MemU REST API (HTTPS)
B. API Layer (Server)
- FastAPI router (memory endpoints, task endpoints)
- Middleware (auth via API_KEY, logging)
- Service layer (MemoryService, TaskService)
C. Core Memory Engine
- MemoryAgent & RecallAgent coordinate actions
- Actions pipeline (add_activity_memory, cluster_memories, link_related_memories, update_memory_with_suggestions, run_theory_of_mind, generate_suggestions)
- Embedding module & FileManager (folder/file store for documents)
- Config loader (prompts, thresholds from YAML/TXT)
D. LLM & Vector Backends
- LLMClient adapters (openai_client, azure_openai_client, openrouter_client, deepseek_client, custom_client)
- Embedding store (in-memory or external vector DB if configured)
E. Infrastructure & Orchestration
- Docker container(s) for memu-server
- docker-compose for full stack (server + optional vector DB)
- CLI entrypoint for self-hosted setup

##### Architectural patterns & principles
- Layered architecture: clear separation of Client, API, Services, Engine, Backends
- Plugin/Adapter pattern for LLM providers and memory actions
- Command/Action pipeline in memory engine for extensibility
- Configuration-driven prompts and behaviors (YAML/TXT)
- File-system–based “database” abstraction with pluggable persistence

##### Elements
- Blue: external systems (OpenAI, Azure, vector DB)
- Green: core MemU modules (memory engine, services)
- Yellow: SDK boundaries
- Gray: configuration & file storage

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client Layer"
        A1["Your App"]:::external
        A2["Python SDK"]:::sdk
        A3["JS/TS SDK"]:::sdk
    end

    subgraph "API Layer"
        B1["FastAPI Server"]:::server
        subgraph "Middleware"
            B2["Auth & Logging"]:::server
        end
        subgraph "Routers"
            B3["Memory Router"]:::server
            B4["Task Router"]:::server
        end
        subgraph "Services"
            B5["MemoryService"]:::core
            B6["TaskService"]:::core
        end
    end

    subgraph "Memory Engine"
        C1["MemoryAgent"]:::core
        C2["RecallAgent"]:::core
        subgraph "Actions Pipeline"
            C3["add_activity_memory"]:::core
            C4["cluster_memories"]:::core
            C5["link_related_memories"]:::core
            C6["update_memory_with_suggestions"]:::core
            C7["run_theory_of_mind"]:::core
            C8["generate_suggestions"]:::core
        end
        C9["Embeddings Module"]:::core
        C10["FileManager"]:::storage
        C11["Config Loader"]:::storage
    end

    subgraph "LLM & Vector Backends"
        D1["OpenAI"]:::external
        D2["Azure OpenAI"]:::external
        D3["OpenRouter"]:::external
        D4["Deepseek"]:::external
        D5["Custom LLM"]:::external
        D6["Vector DB (optional)"]:::external
    end

    subgraph "Deployment"
        E1["Docker & Compose"]:::infra
        E2["CLI Entrypoint"]:::infra
    end

    A1 -->|"uses"| A2
    A1 -->|"uses"| A3
    A2 -->|"HTTP POST /memorize"| B1
    A3 -->|"HTTP POST /memorize"| B1
    B1 --> B2
    B1 --> B3
    B1 --> B4
    B3 -->|"calls"| B5
    B4 -->|"calls"| B6
    B5 --> C1
    B6 --> C1
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    C5 --> C6
    C6 --> C7
    C7 --> C8
    C1 --> C9
    C5 --> C10
    C1 --> C11
    C3 --> D1
    C3 --> D2
    C3 --> D3
    C3 --> D4
    C3 --> D5
    C9 --> D6
    E1 --> B1
    E1 --> D6
    E2 --> B1

    click A2 "https://github.com/nevamind-ai/memu/tree/main/memu/sdk/python"
    click A3 "https://github.com/nevamind-ai/memu/tree/main/memu/sdk/javascript/src"
    click B2 "https://github.com/nevamind-ai/memu/blob/main/memu/server/middleware.py"
    click B3 "https://github.com/nevamind-ai/memu/blob/main/memu/server/routers/memory.py"
    click B5 "https://github.com/nevamind-ai/memu/blob/main/memu/server/services/memory_service.py"
    click B6 "https://github.com/nevamind-ai/memu/blob/main/memu/server/services/task_service.py"
    click C1 "https://github.com/nevamind-ai/memu/blob/main/memu/memory/memory_agent.py"
    click C2 "https://github.com/nevamind-ai/memu/blob/main/memu/memory/recall_agent.py"
    click C3 "https://github.com/nevamind-ai/memu/tree/main/memu/memory/actions"
    click C4 "https://github.com/nevamind-ai/memu/tree/main/memu/memory/actions"
    click C5 "https://github.com/nevamind-ai/memu/tree/main/memu/memory/actions"
    click C6 "https://github.com/nevamind-ai/memu/tree/main/memu/memory/actions"
    click C7 "https://github.com/nevamind-ai/memu/tree/main/memu/memory/actions"
    click C8 "https://github.com/nevamind-ai/memu/tree/main/memu/memory/actions"
    click C9 "https://github.com/nevamind-ai/memu/blob/main/memu/memory/embeddings.py"
    click C10 "https://github.com/nevamind-ai/memu/blob/main/memu/memory/file_manager.py"
    click C11 "https://github.com/nevamind-ai/memu/tree/main/memu/config"
    click D1 "https://github.com/nevamind-ai/memu/blob/main/memu/llm/openai_client.py"
    click D2 "https://github.com/nevamind-ai/memu/blob/main/memu/llm/azure_openai_client.py"
    click D3 "https://github.com/nevamind-ai/memu/blob/main/memu/llm/openrouter_client.py"
    click D4 "https://github.com/nevamind-ai/memu/blob/main/memu/llm/deepseek_client.py"
    click D5 "https://github.com/nevamind-ai/memu/blob/main/memu/llm/custom_client.py"
    click E1 "https://github.com/nevamind-ai/memu/tree/main/Dockerfile"
    click E1 "https://github.com/nevamind-ai/memu/blob/main/docker-compose.yml"
    click E2 "https://github.com/nevamind-ai/memu/blob/main/memu/server/cli.py"

    classDef external fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef sdk fill:#FFFFB2,stroke:#000,stroke-width:1px
    classDef server fill:#B2FFB2,stroke:#000,stroke-width:1px
    classDef core fill:#7CFC00,stroke:#000,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef infra fill:#E6E6FA,stroke:#000,stroke-width:1px
```
