Now I have comprehensive information about the Mem0 codebase. Let me create a detailed architectural overview:

Mem0 Architecture Overview

Based on my analysis of the mem0ai/mem0 repository, here’s a comprehensive high-level overview of how Mem0 works:

What is Mem0?

Mem0 is an intelligent memory layer for AI applications that enables persistent, personalized memory across conversations, sessions, and agents. It’s like a knowledge management system that bridges user interactions with AI models, remembering preferences, facts, and context over time.

Key differentiators:

⚡ +26% Accuracy vs. OpenAI Memory (LOCOMO benchmark)
🚀 91% Faster responses than full-context approaches
💰 90% Fewer Tokens used, reducing API costs

Core Architecture Components

1. Three-Tier Memory System

┌─────────────────────────────────────────────────┐
│          USER-LEVEL MEMORY                       │
│   (Long-term preferences, history, profile)     │
├─────────────────────────────────────────────────┤
│         SESSION-LEVEL MEMORY                     │
│    (Conversation within a session/date)         │
├─────────────────────────────────────────────────┤
│      CONVERSATION-LEVEL MEMORY                   │
│     (Current interaction context)               │
└─────────────────────────────────────────────────┘

Each layer manages different temporal scopes:

User memories: Persist across all interactions (long-term)
Session memories: Scoped to a specific session/time window
Conversation memories: Current exchange context

2. Dual Storage Architecture

Mem0 uses a dual-layer storage approach for flexibility:

┌──────────────────────────────────────────────┐
│      VECTOR STORE (Primary)                   │
│  - Embeddings for semantic search             │
│  - Fast similarity matching                   │
│  - Supported: Pinecone, Weaviate, Chroma,    │
│    Milvus, Qdrant, Redis, Elasticsearch,    │
│    OpenSearch, Azure, AWS Bedrock            │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│    GRAPH STORE (Optional)                     │
│  - Entity relationships & knowledge graphs     │
│  - Structured knowledge representation         │
│  - Supported: Neo4j, Memgraph, Neptune,      │
│    AWS Neptune, Kuzu                         │
└──────────────────────────────────────────────┘

┌──────────────────────────────────────────────┐
│    HISTORY DB (SQLite by default)             │
│  - Tracks all memory operations (ADD, UPDATE, │
│    DELETE) with full audit trail              │
└──────────────────────────────────────────────┘

Memory Processing Pipeline

Step-by-Step: How `memory.add()` Works

User Input (Messages)
    │
    ▼
┌─────────────────────────────────────────────┐
│ 1. EXTRACTION (LLM-powered)                 │
│                                              │
│ - LLM analyzes conversation for key facts   │
│ - If infer=True: Extracts structured facts  │
│ - If infer=False: Stores raw text as-is     │
│                                              │
│ Output: List of facts/memories              │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│ 2. CONFLICT RESOLUTION                      │
│                                              │
│ - Query existing memories for duplicates    │
│ - Detect contradictions between old & new   │
│ - Latest truth wins (newer overrides older) │
│ - Only runs when infer=True                 │
│                                              │
│ Decides action: ADD / UPDATE / DELETE / NONE│
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│ 3. STORAGE                                   │
│                                              │
│ - Generate embeddings for facts             │
│ - Store in vector database                  │
│ - Optional: Extract entities → graph store  │
│ - Index metadata, categories, timestamps    │
│ - Track operation in history DB             │
│                                              │
│ Output: Memory object with ID, hash, etc    │
└─────────────────────────────────────────────┘
    │
    ▼
Memory Object Created

Processing Modes:

Async (default): Returns immediately with status “PENDING”, processes in background via webhooks
Sync: Waits for full processing, returns complete memory object

Memory Retrieval Pipeline

Step-by-Step: How `memory.search()` Works

Query (Natural Language)
    │
    ▼
┌─────────────────────────────────────────────┐
│ 1. QUERY PROCESSING                         │
│                                              │
│ - Clean & enrich natural language query     │
│ - Apply user/agent/session scoping filters  │
│ - Optional: Rewrite for better embedding    │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│ 2. VECTOR SEARCH                            │
│                                              │
│ - Generate embedding for query              │
│ - Find semantically similar memories        │
│ - Use cosine similarity scoring             │
│ - Return top-K results (configurable)       │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│ 3. FILTERING & RERANKING                    │
│                                              │
│ - Apply threshold filters (remove low score)│
│ - Rerank using optional reranker models     │
│ - Apply metadata filters (categories, etc)  │
│ - Sort by relevance and timestamp           │
└─────────────────────────────────────────────┘
    │
    ▼
┌─────────────────────────────────────────────┐
│ 4. GRAPH ENRICHMENT (Optional)              │
│                                              │
│ - Search related entities in graph store    │
│ - Return entity relationships in results    │
│ - Does NOT reorder vector hits automatically│
└─────────────────────────────────────────────┘
    │
    ▼
Results with Memories + Entities

Memory Types

Mem0 supports three types of memories, each extracted differently:

class MemoryType(Enum):
    SEMANTIC = "semantic_memory"       # Facts, preferences, knowledge
    EPISODIC = "episodic_memory"       # Events, conversations, timestamps
    PROCEDURAL = "procedural_memory"   # How-to, processes, workflows

Semantic Memory (Default)

Stores facts: “User likes Python”, “Prefers dark theme”
Extracted from general conversation context
No temporal binding required

Episodic Memory

Stores events: “User attended meeting on 2025-03-19”
Tied to specific time/context
Useful for conversation history

Procedural Memory

Stores workflows: “User’s workflow: 1) Write code 2) Test 3) Deploy”
How-to information and processes
Less common but available via custom prompt

Memory Object Structure

Every memory stored has this structure:

{
  "id": "uuid-123",                    // Unique identifier
  "memory": "User prefers Python",     // The actual memory text
  "hash": "md5-hash",                  // Content hash for deduplication
  "created_at": "2025-03-19T10:30Z",   // Creation timestamp
  "updated_at": "2025-03-19T11:45Z",   // Last update time
  "categories": ["preferences", "tech"], // Auto-generated categories
  "metadata": {                        // Custom metadata
    "user_id": "user_123",
    "agent_id": "agent_456",
    "session_id": "session_789",
    "custom_field": "value"
  },
  "score": 0.89,                       // Relevance score (search results only)
  "memory_type": "semantic_memory"     // Type of memory
}

Memory Lifecycle

CREATE ──→ ACTIVE ──→ UPDATE ──→ ACTIVE
  │         (stored,      (reindex,
  │          indexed)      ranked)
  │                            │
  ▼                            ▼
DELETE                    EXPIRED
(permanent)          (not retrieved
                      but stored)
                            │
                            ▼
                         DELETE
                      (permanent)

Operations:

Operation	Method	Effect
Add	`memory.add(messages)`	Create new memory or trigger conflict resolution
Update	`memory.update(memory_id, text)`	Modify existing memory, reindex
Delete	`memory.delete(memory_id)`	Soft delete (still in DB), removes from search
Search	`memory.search(query)`	Find semantically similar memories
History	`memory.history(memory_id)`	Get audit trail of all changes
Get All	`memory.get_all()`	List all user’s memories with pagination

Key Components in Codebase

Main Memory Class (`mem0/memory/main.py`)

The core Memory class handles:

add(): Extract facts, resolve conflicts, store
search(): Find relevant memories
update(): Modify existing memory
delete(): Remove memory
history(): Retrieve change log
get_all(): List memories

Configuration (`mem0/configs/`)

MemoryConfig:
  - vector_store: VectorStoreConfig   # Where to store embeddings
  - llm: LlmConfig                    # Which LLM for extraction
  - embedder: EmbedderConfig          # Embedding model
  - graph_store: GraphStoreConfig     # Entity relationship storage
  - reranker: RerankerConfig          # Optional reranking model
  - history_db_path: str              # SQLite history location

Supported LLMs (`mem0/llms/`)

OpenAI (GPT-4, GPT-3.5)
Anthropic (Claude)
Groq, Together, Ollama
Google Generative AI
Azure OpenAI
And more via LiteLLM

Supported Embedders (`mem0/embeddings/`)

OpenAI Embeddings
HuggingFace models
Cohere
Azure OpenAI Embeddings
And more

Vector Stores (`mem0/vector_stores/`)

Cloud: Pinecone, Weaviate, AWS Bedrock
Self-hosted: Milvus, Qdrant, Chroma, Redis, Elasticsearch, OpenSearch
In-memory: Chroma (default for quick start)

Graph Stores (`mem0/graphs/`)

Neo4j: Full-featured graph database
Memgraph: Fast graph database
Kuzu: Embedded graph database
Neptune: AWS graph database

Prompts in Memory Extraction

Fact Extraction Prompt (`mem0/configs/prompts.py`)

The LLM uses a detailed prompt to extract facts:

"You are a Personal Information Organizer...

Types of Information to Remember:
1. Store Personal Preferences (food, products, activities)
2. Maintain Important Personal Details (names, dates)
3. Track Plans and Intentions (events, goals)
4. Remember Service Preferences (dining, travel)
5. Monitor Health & Wellness Preferences
6. Store Professional Details (job, career goals)
7. Miscellaneous Information (books, movies, brands)"

Output Format:

{
  "facts": [
    "User likes Python",
    "Prefers dark theme",
    "Has meeting on March 20th"
  ]
}

Memory Update Prompt

When resolving conflicts between new and existing memories:

- Check if new fact is duplicate (NONE action)
- Check if new fact updates existing (UPDATE action)
- Check if new fact is completely new (ADD action)
- Check if old memory should be deleted (DELETE action)

Integration with LLM Applications

Typical Flow

from mem0 import Memory
from openai import OpenAI
 
memory = Memory()
openai_client = OpenAI()
 
def chat_with_memories(message: str, user_id: str):
    # 1. RETRIEVE: Get relevant memories
    relevant_memories = memory.search(
        query=message,
        user_id=user_id,
        limit=5
    )
    
    # 2. ENRICH: Add memories to prompt
    memories_text = "\n".join(
        f"- {mem['memory']}" 
        for mem in relevant_memories["results"]
    )
    
    system_prompt = f"""You are helpful AI.
User Memories:
{memories_text}"""
    
    # 3. GENERATE: Get response from LLM
    response = openai_client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": system_prompt},
            {"role": "user", "content": message}
        ]
    )
    
    # 4. STORE: Remember new information
    messages = [
        {"role": "user", "content": message},
        {"role": "assistant", "content": response.content}
    ]
    memory.add(messages, user_id=user_id)
    
    return response.content

Integration with Frameworks

Mem0 supports direct integration with:

LangChain: Via proxy wrapper
CrewAI: Memory backend for agents
LangGraph: State management integration
OpenAI Agents: Custom memory storage
Vercel AI SDK: Conversation memory
LlamaIndex: Document memory
OpenClaw: Auto-recall + auto-capture for Claude/agents

Performance Characteristics

Research Benchmarks (LOCOMO):

Accuracy: +26% vs OpenAI Memory
Speed: 91% faster than full-context retrieval
Cost: 90% fewer tokens than full context

Scaling Characteristics:

Handles millions of memories
Sub-100ms retrieval with proper indexing
Async processing for high-throughput
Multi-tenancy via user/agent/session scoping

Memo

Table of Contents

Mem0 Architecture Overview

What is Mem0?

Core Architecture Components

1. Three-Tier Memory System

2. Dual Storage Architecture

Memory Processing Pipeline

Step-by-Step: How `memory.add()` Works

Memory Retrieval Pipeline

Step-by-Step: How `memory.search()` Works

Memory Types

Semantic Memory (Default)

Episodic Memory

Procedural Memory

Memory Object Structure

Memory Lifecycle

Key Components in Codebase

Main Memory Class (`mem0/memory/main.py`)

Configuration (`mem0/configs/`)

Supported LLMs (`mem0/llms/`)

Supported Embedders (`mem0/embeddings/`)

Vector Stores (`mem0/vector_stores/`)

Graph Stores (`mem0/graphs/`)

Prompts in Memory Extraction

Fact Extraction Prompt (`mem0/configs/prompts.py`)

Memory Update Prompt

Integration with LLM Applications

Typical Flow

Integration with Frameworks

Performance Characteristics

Graph View

Memo

Table of Contents

Mem0 Architecture Overview

What is Mem0?

Core Architecture Components

1. Three-Tier Memory System

2. Dual Storage Architecture

Memory Processing Pipeline

Step-by-Step: How memory.add() Works

Memory Retrieval Pipeline

Step-by-Step: How memory.search() Works

Memory Types

Semantic Memory (Default)

Episodic Memory

Procedural Memory

Memory Object Structure

Memory Lifecycle

Key Components in Codebase

Main Memory Class (mem0/memory/main.py)

Configuration (mem0/configs/)

Supported LLMs (mem0/llms/)

Supported Embedders (mem0/embeddings/)

Vector Stores (mem0/vector_stores/)

Graph Stores (mem0/graphs/)

Prompts in Memory Extraction

Fact Extraction Prompt (mem0/configs/prompts.py)

Memory Update Prompt

Integration with LLM Applications

Typical Flow

Integration with Frameworks

Performance Characteristics

Graph View

Step-by-Step: How `memory.add()` Works

Step-by-Step: How `memory.search()` Works

Main Memory Class (`mem0/memory/main.py`)

Configuration (`mem0/configs/`)

Supported LLMs (`mem0/llms/`)

Supported Embedders (`mem0/embeddings/`)

Vector Stores (`mem0/vector_stores/`)

Graph Stores (`mem0/graphs/`)

Fact Extraction Prompt (`mem0/configs/prompts.py`)