# Long-Term Memory Architecture Components in Chapter 3: A Three-Dimensional Design

> Explore the three-dimensional long-term memory architecture from Chapter 3. Discover how AI agents achieve scalability and persistence through distinct storage, format, and cognitive types.

- Repository: [Bojie Li/ai-agent-book](https://github.com/bojieli/ai-agent-book)
- Tags: deep-dive
- Published: 2026-08-23

---

**Chapter 3 of the bojieli/ai-agent-book defines a three-dimensional long-term memory architecture that separates storage location, storage format, and cognitive memory types to enable scalable, persistent AI agents.**

The repository’s [`chapter3/README.en.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/README.en.md) introduces a comprehensive framework for implementing durable agent memory that survives across sessions. This architecture organizes long-term memory into three orthogonal dimensions—where to store data, how to structure it, and what cognitive category it represents—allowing developers to mix and match components based on their specific persistence requirements.

## The Three Dimensions of Long-Term Memory Architecture

The design presented in [`chapter3/README.en.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/README.en.md) segments memory systems along three independent axes. Each dimension addresses a distinct concern: physical location, data format, and cognitive content.

### Where to Store: Storage Tiers

The first dimension defines the physical or logical storage location, determining the lifecycle and accessibility of the memory.

**Trajectory** serves as an immutable log of a single agent run, functioning as the raw event stream. This component provides immediate context for the current turn and is never rewritten, ensuring a complete audit trail of the agent’s execution path.

**User Long-Term Memory** operates as a persistent key-value store bound to a specific user ID. According to the source code analysis, this tier holds distilled facts, preferences, and summaries across multiple sessions, updated via explicit tool calls rather than automatic logging.

**Business State** represents developer-defined high-level task state (e.g., “awaiting payment”). This component enables event-driven agents to track workflow progress independently of conversation history, storing structured application state separate from organic user interactions.

### How to Store: The Four Storage Formats

The second dimension defines the structural representation of the stored knowledge, detailed in the “Four Storage Formats” section of [`chapter3/user_memory/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/user_memory/README.md).

**Simple Notes** store atomic “fact-only” lines (e.g., `email: john@example.com`). These entries offer O(1) read/write performance with minimal overhead, though they sacrifice relationship context between facts.

**Enhanced Notes** preserve whole-paragraph prose to maintain narrative richness. While this format captures conversational context and nuance, it incurs higher storage costs and proves more difficult to update programmatically.

**JSON Cards** implement a three-level nested key-value schema (`category → subcategory → key`). This structure enables partial updates and deterministic look-up operations while imposing a fixed taxonomy on the stored data.

**Advanced JSON Cards** extend the base JSON format by adding `backstory`, `person`, `relationship`, and timestamp fields to each card. As implemented in [`memory/advanced_json.py`](https://github.com/bojieli/ai-agent-book/blob/main/memory/advanced_json.py), this format captures contextual metadata, disambiguates entities, and supports proactive agent services by maintaining relationship graphs and temporal information.

### What to Store: Cognitive Memory Types

The third dimension categorizes memory by cognitive content type, mirroring human memory classification.

**Episodic Memory** records specific events (e.g., “booked ANA flight to Tokyo”). This type serves as the direct analogue of a conversation turn and proves useful for timeline queries and recalling particular interaction instances.

**Semantic Memory** stores abstracted facts distilled from multiple episodes (e.g., “user prefers window seats”). This component enables generalization across interactions, reducing redundancy by extracting enduring preferences from transient events.

**Procedural Memory** encodes learned procedures or workflows (e.g., “search → confirm seat → apply loyalty number”). This type supports automatic multi-step action execution, allowing agents to retrieve and replay complex task sequences.

## Implementing the Advanced JSON Card Format

The [`memory/advanced_json.py`](https://github.com/bojieli/ai-agent-book/blob/main/memory/advanced_json.py) module provides concrete implementations for reading and writing the most sophisticated storage format. The following examples demonstrate the practical application of the three-dimensional architecture, combining **User Long-Term Memory** (where), **Advanced JSON Card** (how), and **Semantic Memory** (what).

To persist a user preference with full contextual metadata:

```python
from memory.advanced_json import write_card

card = {
    "person": "user",
    "relationship": "self",
    "key": "preferences.seat",
    "value": "window",
    "backstory": "User mentioned a preference while booking a flight to Tokyo.",
    "timestamp": "2025-06-01T12:34:00Z",
}
write_card(card)  # Persists to the per-user JSON file in USER_LONG_TERM_DIR

```

To retrieve stored facts using the structured key schema:

```python
from memory.advanced_json import find_cards

matches = find_cards(
    key="preferences.seat",
    person="user",
    relationship="self"
)

if matches:
    print("User prefers:", matches[0]["value"])

# → User prefers: window

```

For hybrid retrieval combining structured storage with semantic search, the `retrieval-pipeline` experiment demonstrates vector-based recall:

```python

# Assume the card text has been indexed into the vector store

query = "Which seat does the user like?"
docs = retriever.search(query, top_k=3)   # returns the matching JSON card text

answer = llm.generate(context=docs, question=query)
print(answer)  # "The user prefers window seats."

```

## Memory Compression and Organization Mechanisms

Beyond the three-dimensional storage model, the architecture includes a **memory compression pipeline** that maintains bounded storage while preserving useful knowledge. This pipeline, referenced in [`chapter3/README.en.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/README.en.md), implements a three-stage process: importance scoring of raw memories, clustering of related facts, and abstraction into generalized semantic knowledge. This mechanism ensures that User Long-Term Memory remains performant even after extended agent operation, automatically distilling high-fidelity episodic records into compact semantic entries.

The [`chapter3/structured-index/IMPLEMENTATION_GUIDE.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/structured-index/IMPLEMENTATION_GUIDE.md) further details how structured indexes like RAPTOR and GraphRAG sit atop these long-term memory layers, while implementations such as [`chapter3/memobase/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/memobase/README.md) and [`chapter3/mem0/README.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/mem0/README.md) provide concrete frameworks mapping to the architecture’s dimensions.

## Summary

- The long-term memory architecture in Chapter 3 organizes persistence along three dimensions: **where** to store (Trajectory, User Long-Term Memory, Business State), **how** to store (Simple Notes, Enhanced Notes, JSON Cards, Advanced JSON Cards), and **what** to store (Episodic, Semantic, Procedural).
- **Advanced JSON Cards** provide the richest storage format with relationship tracking and timestamps, implemented in [`memory/advanced_json.py`](https://github.com/bojieli/ai-agent-book/blob/main/memory/advanced_json.py) through functions like `write_card()` and `find_cards()`.
- **User Long-Term Memory** persists across sessions via explicit tool calls, while **Trajectory** maintains immutable execution logs for the current run only.
- A **memory compression pipeline** automatically manages storage bounds by abstracting episodic records into semantic knowledge.
- Reference implementations in `chapter3/memobase/` and `chapter3/mem0/` demonstrate practical applications of this three-dimensional design.

## Frequently Asked Questions

### What is the difference between Trajectory and User Long-Term Memory in the Chapter 3 architecture?

**Trajectory** represents an immutable log of the current agent run—a raw event stream that provides immediate context but never persists beyond the session. **User Long-Term Memory** is a persistent key-value store bound to a user ID that holds distilled facts and preferences across multiple sessions, updated explicitly via tool calls rather than automatic logging.

### When should I use Advanced JSON Cards instead of Simple Notes?

Use **Advanced JSON Cards** when you need to capture relationship context, temporal metadata, and provenance through fields like `backstory`, `person`, and `timestamp`. Choose **Simple Notes** for atomic facts requiring O(1) read/write performance where storage overhead must remain minimal and relationship tracking is unnecessary.

### How does the three-dimensional architecture improve AI agent performance?

By separating *where* data lives, *how* it is structured, and *what* cognitive type it represents, the architecture allows developers to optimize each dimension independently. For example, procedural knowledge can be stored as JSON Cards in User Long-Term Memory for fast retrieval, while the raw trajectory maintains an immutable audit trail—reducing latency for common queries while preserving complete observability.

### What is the memory compression pipeline mentioned in Chapter 3?

The **memory compression pipeline** is a three-stage process (importance scoring → clustering → abstraction) that keeps long-term stores bounded while preserving useful knowledge. It automatically distills high-fidelity episodic memories into compact semantic facts, ensuring the User Long-Term Memory does not grow indefinitely as described in [`chapter3/README.en.md`](https://github.com/bojieli/ai-agent-book/blob/main/chapter3/README.en.md).