# bai-lab/memoryos architecture

> Architecture diagram of the GitHub repository bai-lab/memoryos, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bai-lab/memoryos
- Repository: https://github.com/bai-lab/memoryos

## Overview

##### Project type and purpose
- MemoryOS is a full-stack, modular “memory operating system” for AI agents.
- It consists of:
- A core Python library (memoryos-pypi) implementing hierarchical memory management (short-, mid-, long-term).
- A microservice API server (memoryos-mcp) exposing endpoints (add_memory, retrieve_memory, get_user_profile).
- An optional vector-DB–backed variant (memoryos-chromadb).
- A web-based demo/playground (memoryos-playground).
- Evaluation scripts and a Docker deployment.

##### File structure
Top-level:
- Dockerfile, docs/, README.md, Paper-MemoryOS.pdf
- eval/ – benchmarking and reproduction scripts
- memoryos-chromadb/ – vector-DB storage provider implementation
- memoryos-mcp/ – MCP server, config.json, mcp.json, server_new.py, test scripts
- memoryos-playground/ – Flask (or similar) demo (“memdemo”) with templates, static data, app.py
- memoryos-pypi/ – core library modules: long_term.py, mid_term.py, short_term.py, retriever.py, updater.py, prompts.py, utils.py, memoryos.py

##### README for additional insights
- Confirms four core modules: Storage, Updating, Retrieval, Generation
- Describes plug-and-play support for multiple LLMs and embedding providers
- Details multiple “modes” (PyPI library, MCP server, Chromadb storage, Docker, Playground)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer" 
        direction TB
        UI_Playground["Web UI (Playground)"]:::ui
        UI_CLI["CLI / VSCode Extension"]:::ui
    end

    %% MCP Server
    subgraph "MCP Server" 
        direction TB
        API_Server["MemoryOS-MCP Server"]:::server
    end

    %% Core Library
    subgraph "Core MemoryOS Library" 
        direction TB
        STM["ShortTermMemory"]:::core
        MTM["MidTermMemory"]:::core
        LTM["LongTermMemory"]:::core
        UPD["Updater"]:::core
        RTR["Retriever"]:::core
        ORC["Orchestrator (memoryos.py)"]:::core
    end

    %% Storage Backends
    subgraph "Storage Backends"
        direction TB
        LocalFS["Local Filesystem / JSON / SQLite"]:::storage
        ChromaDB["ChromaDB Vector DB"]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLM["LLM Providers"]:::external
        EMB["Embeddings API / Service"]:::external
    end

    %% Eval & Reproduction
    subgraph "Eval & Reproduction"
        direction TB
        EvalScripts["Evaluation Scripts"]:::eval
    end

    %% Containerization
    Docker["Docker Image"]:::other

    %% Data Flows
    UI_Playground -->|"HTTP / WebSocket"| API_Server
    UI_CLI -->|"HTTP / gRPC"| API_Server
    API_Server -->|"Invokes"| ORC
    ORC -->|"write_memory"| STM
    STM -->|"promote"| UPD
    UPD -->|"to Mid/Long-term"| MTM
    UPD -->|"to Mid/Long-term"| LTM
    ORC -->|"retrieve_memory"| RTR
    RTR -->|"read from"| STM
    RTR -->|"read from"| MTM
    RTR -->|"read from"| LTM
    ORC -->|"summary / generation"| LLM
    LLM -->|"response"| ORC
    ORC -->|"send result"| API_Server
    API_Server -->|"HTTP response"| UI_Playground
    API_Server -->|"HTTP response"| UI_CLI
    ORC -->|"persist"| LocalFS
    ORC -->|"persist"| ChromaDB
    ORC -->|"embedding_request"| EMB
    EvalScripts -->|"calls"| ORC
    EvalScripts -->|"calls"| LLM
    Docker --- API_Server
    Docker --- UI_Playground
    Docker --- EvalScripts

    %% Click Events - Core Library
    click STM "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/short_term.py"
    click MTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/mid_term.py"
    click LTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/long_term.py"
    click UPD "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/updater.py"
    click RTR "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/retriever.py"
    click ORC "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/memoryos.py"
    click LocalFS "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/utils.py"
    click EMB "https://github.com/bai-lab/memoryos/blob/main/memoryos-pypi/utils.py"

    %% Click Events - MCP Server
    click API_Server "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/server_new.py"
    click API_Server "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/config.json"
    click API_Server "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/mcp.json"
    click STM "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/memoryos/short_term.py"
    click MTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/memoryos/mid_term.py"
    click LTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/memoryos/long_term.py"
    click UPD "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/memoryos/updater.py"
    click RTR "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/memoryos/retriever.py"
    click ORC "https://github.com/bai-lab/memoryos/blob/main/memoryos-mcp/memoryos/memoryos.py"

    %% Click Events - ChromaDB Variant
    click ChromaDB "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/storage_provider.py"
    click ChromaDB "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/utils.py"
    click STM "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/short_term.py"
    click MTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/mid_term.py"
    click LTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/long_term.py"
    click UPD "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/updater.py"
    click RTR "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/retriever.py"
    click ORC "https://github.com/bai-lab/memoryos/blob/main/memoryos-chromadb/memoryos.py"

    %% Click Events - Playground
    click UI_Playground "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/memdemo/app.py"
    click UI_Playground "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/memdemo/templates/index.html"
    click UI_Playground "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/memdemo/sample_conversations.json"
    click UI_Playground "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/memdemo/start_demo.sh"
    click STM "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/short_term.py"
    click MTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/mid_term.py"
    click LTM "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/long_term.py"
    click UPD "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/updater.py"
    click RTR "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/retriever.py"
    click ORC "https://github.com/bai-lab/memoryos/blob/main/memoryos-playground/memoryos.py"

    %% Click Events - Eval
    click EvalScripts "https://github.com/bai-lab/memoryos/blob/main/eval/main_loco_parse.py"
    click EvalScripts "https://github.com/bai-lab/memoryos/blob/main/eval/short_term_memory.py"
    click EvalScripts "https://github.com/bai-lab/memoryos/blob/main/eval/mid_term_memory.py"
    click EvalScripts "https://github.com/bai-lab/memoryos/blob/main/eval/long_term_memory.py"
    click EvalScripts "https://github.com/bai-lab/memoryos/blob/main/eval/retrieval_and_answer.py"
    click EvalScripts "https://github.com/bai-lab/memoryos/blob/main/eval/utils.py"

    %% Click Events - Docker & Docs
    click Docker "https://github.com/bai-lab/memoryos/tree/main/Dockerfile"
    click LocalFS "https://github.com/bai-lab/memoryos/blob/main/Paper-MemoryOS.pdf"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef storage fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef server fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef ui fill:#80deea,stroke:#00838f,color:#004d40
    classDef eval fill:#f0f4c3,stroke:#c0ca33,color:#827717
    classDef other fill:#f5f5f5,stroke:#9e9e9e,color:#212121
```
