Memory Systems

Why Memory Matters

Imagine a customer support agent that forgets every conversation the moment it ends. A user asks about their order. The agent looks it up, gives an answer. The user follows up five minutes later — and the agent has no idea who they are or what they asked. That is a stateless tool, not an agent.

Memory gives agents continuity. It lets them remember what happened, learn from outcomes, and share information with other agents. The three types of memory serve different purposes, and a well-designed agent uses all three.

Three Types of Agent Memory

Here are the three types of memory, their characteristics, and when to use each:

Memory in Code

Here is a practical memory system in Python. Short-term is a list. Long-term is a database table. Shared is a key-value store accessible to all agents:

class AgentMemory:
    def __init__(self, agent_name, db):
        self.agent_name = agent_name
        self.db = db
        self.short_term = []  # dies when session ends

    # Short-term: fast, ephemeral
    def remember_now(self, fact):
        self.short_term.append(fact)

    # Long-term: persists across sessions
    def remember_forever(self, key, value):
        self.db.execute(
            "INSERT INTO agent_memory (agent, key, value) "
            "VALUES (%s, %s, %s) ON CONFLICT (agent, key) "
            "DO UPDATE SET value = %s",
            [self.agent_name, key, value, value]
        )

    # Shared: visible to ALL agents
    def share(self, key, value, category="session"):
        self.db.execute(
            "INSERT INTO brain_context (key, value, category) "
            "VALUES (%s, %s, %s) ON CONFLICT (key) "
            "DO UPDATE SET value = %s",
            [key, value, category, value]
        )

    def recall_shared(self, key):
        return self.db.execute(
            "SELECT value FROM brain_context WHERE key = %s",
            [key]
        )

remember_now() stores in a Python list — gone when the process ends. remember_forever() writes to a database — survives forever. share() writes to the shared brain — any agent can read it.

The Context Window Problem

Every LLM has a context window — the maximum amount of text it can process at once. Claude's context window is up to 200K tokens (~150K words). That sounds like a lot, but a busy agent can fill it fast:

This is not a theoretical problem — it is the single most common cause of agent "amnesia." An agent that works perfectly for 20 minutes suddenly forgets your name, your goal, or what it was doing. The fix is always the same: write critical state to long-term or shared memory before context overflows.

Vector Memory and Semantic Search

Simple key-value memory works when you know exactly what to look up. But what if you need to find memories by meaning rather than exact key?

Vector embeddings convert text into numerical arrays that capture semantic meaning. Similar concepts end up near each other in vector space. This lets agents search their memory the way humans do — by association, not exact match.

Supabase supports vector search natively via pgvector. You store embeddings alongside your brain_context rows, then query with cosine similarity. This is the foundation of RAG (Retrieval-Augmented Generation), covered in depth in the RAG & Vector Search course.

Querying Agent Memory

To read from agent memory, you use SQL queries against the appropriate table. Here are common query patterns:

-- Read all shared memories in a category
SELECT * FROM brain_context WHERE category = 'identity';

-- Read a specific agent's long-term memories
SELECT * FROM agent_memory WHERE agent = 'atlas';

-- Find a specific key
SELECT value FROM brain_context WHERE key = 'session.active_work';

SELECT * means "get all columns." FROM names the table. WHERE filters rows by a condition. Use brain_context for shared memory and agent_memory for an individual agent's long-term storage.

Memory Lifecycle Management

Memory without management becomes noise. Over time, an unmanaged memory store accumulates stale, conflicting, and irrelevant entries that degrade agent performance. Three strategies keep memory clean:

Memory Architecture Patterns

Different use cases call for different memory architectures. Here are the three most common patterns:

Most production agent systems use the hybrid pattern. It gives you the speed of key-value lookups for routine reads and the intelligence of semantic search for complex queries.

Memory Anti-Patterns

Common mistakes that degrade agent memory performance: