# Agent Memory Systems: MemGPT and Hybrid Memory (Mem0) Architecture Explained

> Explore agent memory systems like MemGPT and Mem0's hybrid architecture. Understand the prompt buffer, archival store, and multi-tier memory fusion for advanced AI.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: deep-dive
- Published: 2026-06-24

---

**MemGPT employs a two-tier design with a prompt buffer and archival store, while Mem0 uses a three-tier fusion of vector, key-value, and graph stores governed by a weighted relevance-importance-recency scoring function.**

In the `rohitg00/ai-engineering-from-scratch` curriculum, agent memory systems bridge the gap between stateless language models and complex, multi-turn interactions. These implementations demonstrate how to extend context windows beyond token limits using tiered storage architectures. Both MemGPT and Mem0 are built with pure Python standard library components, making them accessible educational foundations for production-ready agent engineering.

## What is Agent Memory?

An **agent memory system** serves as the bridge between a stateless language model core and the stateful world it interacts with. It stores facts, context, and embeddings so that later steps can retrieve relevant information without re-prompting the model for everything.

The curriculum presents two contrasting designs that illustrate the spectrum of trade-offs between simplicity, scalability, and retrieval quality:

| Design | Core Idea | Components | Typical Use Case |
|--------|-----------|------------|------------------|
| **MemGPT** | Two-tier prompt buffer (core) plus archival storage | `MainContext` (FIFO messages) + `ArchivalStore` (searchable records) | Simple agents needing short chat windows with long-term lookup |
| **Mem0** | Three-tier fusion with weighted scoring | `VectorStore` + `KVStore` + `GraphStore` with fusion function | Complex agents reasoning over heterogeneous data and relationships |

Both designs run without external dependencies, using only Python data structures to simulate production-grade memory layers.

## MemGPT: Two-Tier Virtual Context

**File:** [`phases/14-agent-engineering/07-memory-virtual-context-memgpt/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/07-memory-virtual-context-memgpt/code/main.py)

The MemGPT implementation models a **virtual context** that divides memory into hot and cold tiers. This separation allows the agent to maintain a fixed-size conversational window while retaining access to an unlimited historical archive.

### MainContext and the Prompt Buffer

The `MainContext` class maintains a **fixed-size** list of recent `Message` objects, defaulting to `max_messages=4`. When the buffer overflows, oldest messages move to an `evicted` list, preserving searchable history without consuming prompt tokens. This buffer acts as the "working memory" rendered directly into the LLM prompt.

### ArchivalStore for Long-Term Retrieval

`ArchivalStore` manages a list of `ArchivalRecord` structs with simple incremental RIDs (`a001`, `a002`, etc.). Search operates via **token overlap**, a lightweight proxy for vector similarity that requires no external embedding models. This store holds Facts, user preferences, and conversation history evicted from the main buffer.

### MemoryTools and the Agent Loop

The `MemoryTools` class exposes operations that an agent invokes through function calling:

- `core_memory_append` / `core_memory_replace` – Mutate the prompt buffer in real-time
- `archival_memory_insert` / `archival_memory_search` – Write and read the long-term store
- `conversation_search` – Query recent and evicted messages for specific terms

The `run_scripted_agent` function demonstrates the ReAct pattern: the LLM emits `ToolCall` objects, the system dispatches the corresponding `MemoryTools` method, and returns observation strings that are prepended to the next prompt completion.

### MemGPT Implementation Example

```python
from phases.14_agent_engineering.07_memory_virtual_context_memgpt.code.main import (
    MainContext, ArchivalStore, MemoryTools, ToolCall, run_scripted_agent)

# Initialize contexts

main_ctx = MainContext(max_messages=3)
archival = ArchivalStore()
tools = MemoryTools(main_ctx, archival)

# Simulate conversation

main_ctx.append("user", "Hi, I'm Ava.")
main_ctx.append("assistant", "Nice to meet you, Ava!")

# Agent script: store long-term fact and update core prompt

script = [
    ToolCall("core_memory_append", {"section": "persona", "text": "friendly researcher"}),
    ToolCall("archival_memory_insert",
              {"text": "Ava works on agent engineering curricula", "tags": ("profile",)}),
]

observations = run_scripted_agent(tools, script)
print("\n".join(observations))

# Search archival store later

print("\nArchival hits for 'agent engineering':")
print(tools.archival_memory_search("agent engineering"))

```

The output shows the core buffer containing three recent messages while the archival store retains the long-term fact, searchable by token overlap.

## Hybrid Memory (Mem0): Vector, KV, and Graph Fusion

**File:** [`phases/14-agent-engineering/09-hybrid-memory-mem0/code/main.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/14-agent-engineering/09-hybrid-memory-mem0/code/main.py)

Mem0 implements a **three-tier hybrid architecture** that combines dense retrieval, structured facts, and relational data into a unified scoring layer. This design supports agents that must reason over heterogeneous information types simultaneously.

### Component Stores

The system comprises three specialized storage backends:

- **`VectorStore`** – Approximate similarity search using token overlap as a proxy for dense embeddings. Stores `Record` objects keyed by RID.
- **`KVStore`** – Direct lookup of typed facts using composite keys (`KVKey(user_id, fact_type, entity)`). Optimized for exact retrieval of structured information.
- **`GraphStore`** – Directed edge storage (`Edge(subject, relation, obj)`) with validity flags to handle updates and provenance tracking.

### Fusion Scoring Algorithm

The `Mem0.search` method implements a **weighted fusion** that computes final record scores as:

```

score = w_relevance·relevance + w_importance·importance + w_recency·recency

```

The algorithm executes four steps:

1. Retrieve a large candidate set from the vector store (`top_k * 3`)
2. Compute recency decay based on insertion timestamp (`_recency_score`)
3. Combine weighted terms and filter to best `top_k`
4. Enrich results with KV and graph facts not present in vector hits

The `Mem0Config` class exposes hyperparameters `w_relevance`, `w_importance`, `w_recency`, and `recency_halflife_s` to tune the balance between semantic match, confidence, and temporal freshness.

### Scope Isolation and Security

Mem0 prevents cross-user data leakage through **scope isolation**. The `add` method tags records with `user_id` and `scope` (session or global). The `search` method filters the candidate set by these tags before applying the fusion algorithm, ensuring that queries from user "ava" cannot surface records belonging to user "bob".

### Mem0 Implementation Example

```python
from phases.14_agent_engineering.09_hybrid_memory_mem0.code.main import (
    Mem0, Mem0Config)

mem = Mem0(Mem0Config(w_relevance=0.6, w_importance=0.3, w_recency=0.1))

# Add records with heterogeneous modalities

mem.add(
    "Ava prefers citation-heavy, terse writing",
    user_id="ava", importance=0.7,
    kv_triples=(("writing_style", "terse_citation_heavy"),),
    graph_triples=(("ava", "has_preference", "terse_citation_heavy"),)
)

mem.add(
    "Ava lives in Berlin",
    user_id="ava", importance=0.5,
    kv_triples=(("city", "Berlin"),),
    graph_triples=(("ava", "lives_in", "Berlin"),)
)

# Fuse-search across all stores

results = mem.search("where does Ava live", user_id="ava", top_k=3)
for score, rec in results:
    print(f"{score:.3f} → {rec.rid}: {rec.text}")

```

The fused ranking reflects vector relevance, importance weighting, and recency decay. Adding a later record "Ava moved to Lisbon" automatically promotes that result for the same query due to the recency term.

## Comparing MemGPT and Mem0

| Feature | MemGPT | Mem0 |
|---------|--------|------|
| **Tier Count** | 2 (prompt buffer + archival) | 3 (vector + KV + graph) |
| **Search Model** | Token-overlap similarity | Token-overlap + exact KV + graph traversal |
| **Scoring** | Simple relevance ratio | Weighted linear combination (relevance, importance, recency) |
| **Temporal Handling** | None (archival is unordered) | Explicit recency decay (`recency_halflife_s`) |
| **Relations** | Flat text only | Graph edges for relational queries |
| **Complexity** | ~100 LOC | ~200 LOC |
| **Use Case** | Simple conversational agents | Multi-modal reasoning agents |

MemGPT provides the minimal viable architecture for stateful agents, while Mem0 offers richer retrieval semantics for agents requiring structured reasoning and temporal awareness.

## Summary

- **MemGPT** implements a **two-tier** virtual context with a fixed-size prompt buffer (`MainContext`) and searchable `ArchivalStore`, using token overlap for retrieval.
- **Mem0** provides a **three-tier hybrid** architecture combining `VectorStore`, `KVStore`, and `GraphStore` with a configurable fusion scoring function.
- Both systems are **pure Python** implementations in the `rohitg00/ai-engineering-from-scratch` repository, requiring no external dependencies.
- **Scope isolation** in Mem0 prevents cross-user data leakage through `user_id` filtering during the search phase.
- Start with MemGPT for simple agent loops, then graduate to Mem0 for heterogeneous data fusion and temporal reasoning.

## Frequently Asked Questions

### What is the difference between MemGPT and Mem0?

MemGPT uses a **two-tier** architecture separating immediate context (prompt buffer) from long-term storage (archival), while Mem0 employs a **three-tier** fusion of vector, key-value, and graph stores. Mem0 adds importance weighting and recency decay scoring, whereas MemGPT relies solely on token-overlap relevance. MemGPT suits simple conversational agents, while Mem0 targets complex reasoning tasks requiring structured data and relationship traversal.

### How does the fusion scoring algorithm work in Mem0?

The fusion algorithm calculates a composite score using three weighted components: **relevance** (token overlap similarity), **importance** (explicit confidence score), and **recency** (time-decayed freshness). The `Mem0Config` class defines weights `w_relevance`, `w_importance`, and `w_recency` that sum to determine final ranking. This allows developers to prioritize recent facts over semantically similar but older information, or vice versa.

### Why use a two-tier system like MemGPT instead of retrieving everything?

A two-tier system optimizes for **latency and cost**. The prompt buffer (`MainContext`) lives in memory and renders instantly, while the archival store only surfaces specific records when the agent explicitly searches. This prevents token limits from being exhausted by irrelevant history and eliminates expensive retrieval operations for every turn. The ReAct pattern in `run_scripted_agent` lets the LLM decide when to access long-term memory versus using immediate context.

### How does Mem0 prevent data leakage between users?

Mem0 implements **scope isolation** by tagging every `Record` with a `user_id` and optional `scope` value during the `add` operation. The `search` method filters the candidate set by these attributes before applying the fusion scoring, ensuring that queries from one user cannot retrieve records belonging to another. This multi-tenancy support is critical for production agents handling sensitive data across multiple sessions.