# yashghogre/mem1 architecture

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

- Interactive diagram: https://gitdiagram.com/yashghogre/mem1
- Repository: https://github.com/yashghogre/mem1

## Overview

##### Project type and purpose
- This is an open-source Python tool/prototype that replicates the “Mem0” LLM memory architecture (per the Mem0 paper) and tries to extend or outperform it.
- It has two main code modules:
- **mem1/** – the core memory library (embedders, vector store, graph database, schemas, retrieval logic)
- **assistant/** – the orchestration/service layer (CLI entrypoint, config, infra adapters, utils, telemetry via Langfuse)

##### File structure
- **Top level**: Dockerfile, docker-compose.yml, justfile (CLI), .env, config.py, pyproject.toml
- **mem1/**:
- core.py – main memory pipeline
- infra/ (database adapters: Mongo, vector DB, graph DB; embedder; schema)
- utils/ (enums, models, prompts)
- **assistant/**:
- main.py – CLI/web server entrypoint
- infra/ (wrappers around mem1’s infra with dependency injection)
- deps/ (third-party integrations like Langfuse telemetry)
- utils/ (logging, context handling, special commands)

##### README for additional insights
- Uses Nix for environment, uv (uvu?) for dependency syncing, Docker Compose for MongoDB and vector DB services
- Runs as a long-lived Python process (CLI or API), connects to LLM via API (no local Llama now)
- Persists embeddings & metadata to vector store and primary DB, supports prompt augmentation

##### Components
a. **User/CLI** (just app) – initiates the run, issues prompts
b. **Docker Compose** – orchestrates MongoDB, vector DB (e.g., Qdrant/Pinecone emulator)
c. **Python Application** (assistant/main.py + assistant infra)
d. **Core Memory Library** (mem1/core.py + mem1/infra modules)
e. **Embedder & Inference**
- mem1.infra.embedder → calculates vector embeddings (via OpenAI API)
- mem1.infra.inference → wraps LLM API calls for response generation
f. **Datastores**
- **MongoDB** (document store for session history, schemas)
- **Vector DB** (nearest-neighbor search)
- **Graph DB** (optional knowledge graph for relationships)
g. **Telemetry/Logging** (Langfuse via assistant/deps)
h. **External LLM API** (OpenAI or other HTTP endpoint)

##### Relationships & data flows
- User→CLI→Python App
- App calls **mem1.core** for pipeline orchestration
- Core calls **embedder** → External LLM API (for embeddings)
- Core calls **inference** → External LLM API (for next-token generation)
- Core writes/reads to/from **Vector DB** and **MongoDB** / **Graph DB**
- App emits telemetry events via **Langfuse**
- Responses return back up chain to the user

##### Architectural patterns & design principles
- **Layered architecture**:
- Presentation/CLI layer (assistant/main.py)
- Service/orchestration layer (assistant/infra + utils)
- Core library layer (mem1/core + mem1/infra)
- Infrastructure adapters (datastores, LLM API)
- **Dependency injection** in assistant/infra to swap adapters during testing
- **Modular separation** of memory logic (mem1) vs. orchestration (assistant)
- **Externalize configuration** via .env and config.py
- **Containerized dependencies** (Mongo, vector DB) via Docker Compose

## Diagram (Mermaid)

```mermaid
graph TB

    subgraph "Startup"
        JF["justfile"]:::infra
        DC["docker-compose.yml"]:::infra
        JF -->|runs| DC
    end

    subgraph "Infrastructure Services"
        MDB["MongoDB"]:::infra
        VDB["Vector DB"]:::infra
        GDB["Graph DB"]:::infra
    end

    subgraph "Orchestration Layer"
        AM["assistant/main.py"]:::assistant
        subgraph "Assistant Infra"
            AI_DB["Database Adapter"]:::assistant
            AI_VDB["Vector DB Adapter"]:::assistant
            AI_EMB["Embedder Adapter"]:::assistant
            AI_INF["Inference Adapter"]:::assistant
        end
        AM --> AI_DB
        AM --> AI_VDB
        AM --> AI_EMB
        AM --> AI_INF
    end

    subgraph "Core Memory Library (mem1)"
        CM["mem1/core.py"]:::core
        subgraph "Memory Infra Adapters"
            DB_AD["MongoDB Adapter"]:::core
            VDB_AD["Vector DB Adapter"]:::core
            GDB_AD["Graph DB Adapter"]:::core
            EMB["Embedder"]:::core
            SCHEMA["Schema Definitions"]:::core
        end
        subgraph "mem1 Utils"
            EN["Enums"]:::core
            MDL["Models"]:::core
            PRM["Prompts"]:::core
        end
        CM --> DB_AD
        CM --> VDB_AD
        CM --> GDB_AD
        CM --> EMB
        CM --> SCHEMA
    end

    subgraph "Telemetry / Logging"
        LF["Langfuse"]:::external
    end

    subgraph "External APIs"
        LLM["LLM API (OpenAI)"]:::external
    end

    %% Data Flows
    JF -->|launch| AM
    AM -->|"orchestrate pipeline"| CM
    CM -->|"store/read"| DB_AD
    CM -->|"store/read"| VDB_AD
    CM -->|"store/read"| GDB_AD
    CM -->|"embeddings"| EMB
    EMB -->|request embeddings| LLM
    CM -->|"generate response"| LLM
    AM -->|emit telemetry| LF
    AI_DB --> MDB
    AI_VDB --> VDB
    AI_EMB --> EMB
    AI_INF --> LLM

    %% Click Events
    click CM "https://github.com/yashghogre/mem1/blob/main/mem1/core.py"
    click DB_AD "https://github.com/yashghogre/mem1/blob/main/mem1/infra/database.py"
    click VDB_AD "https://github.com/yashghogre/mem1/blob/main/mem1/infra/vectordb.py"
    click GDB_AD "https://github.com/yashghogre/mem1/blob/main/mem1/infra/graph_db.py"
    click EMB "https://github.com/yashghogre/mem1/blob/main/mem1/infra/embedder.py"
    click SCHEMA "https://github.com/yashghogre/mem1/blob/main/mem1/infra/schema.py"
    click EN "https://github.com/yashghogre/mem1/blob/main/mem1/utils/enums.py"
    click MDL "https://github.com/yashghogre/mem1/blob/main/mem1/utils/models.py"
    click PRM "https://github.com/yashghogre/mem1/blob/main/mem1/utils/prompts.py"
    click AM "https://github.com/yashghogre/mem1/blob/main/assistant/main.py"
    click AI_DB "https://github.com/yashghogre/mem1/tree/main/assistant/infra/database/"
    click AI_EMB "https://github.com/yashghogre/mem1/blob/main/assistant/infra/embedder.py"
    click AI_INF "https://github.com/yashghogre/mem1/blob/main/assistant/infra/inference.py"
    click AI_VDB "https://github.com/yashghogre/mem1/blob/main/assistant/infra/vector_db.py"
    click LF "https://github.com/yashghogre/mem1/blob/main/assistant/deps/langfuse.py"

    classDef core fill:#cce5ff,stroke:#005cbf,color:#005cbf
    classDef assistant fill:#d4edda,stroke:#155724,color:#155724
    classDef external fill:#fff3cd,stroke:#856404,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
