User Memory

The User Memory Store captures unstructured observations about users: preferences, behaviors, and context that don't fit into structured profile fields.

Aspect	Value
Scope	Per user
Persistence	Long-term
Default mode	Always
Supported modes	Always, Agentic

Setup

pip install agno openai sqlalchemy "psycopg[binary]" pgvector
export OPENAI_API_KEY="your-api-key"

The examples use a local PostgreSQL database on port 5532. With Docker running, start it using:

Run PgVector

docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

Later configuration fragments reuse the imports and db from the first complete example.

Basic Usage

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.learn import LearningMachine
from agno.models.openai import OpenAIResponses

db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    learning=LearningMachine(user_memory=True),
)

# Session 1: Share preferences
agent.print_response(
    "I prefer code examples over explanations. Also, I'm working on a machine learning project.",
    user_id="alice@example.com",
    session_id="session_1",
)

# Session 2: Memory is recalled
agent.print_response(
    "Explain async/await in Python",
    user_id="alice@example.com",
    session_id="session_2",
)

The agent knows to include code examples and may relate to ML context.

Always Mode

Memories are extracted concurrently with the main model call from its input snapshot.

from agno.learn import LearningMachine, LearningMode, UserMemoryConfig

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    learning=LearningMachine(
        user_memory=UserMemoryConfig(mode=LearningMode.ALWAYS),
    ),
)

The tradeoff is an extra LLM call per interaction.

Agentic Mode

The agent receives a tool to manage memories explicitly.

from agno.learn import LearningMachine, LearningMode, UserMemoryConfig

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    learning=LearningMachine(
        user_memory=UserMemoryConfig(mode=LearningMode.AGENTIC),
    ),
)

agent.print_response(
    "Remember that I always want to see error handling in code examples.",
    user_id="alice@example.com",
)

Available tool: update_user_memory (supports add, update, and delete operations). Clearing all memories requires enable_clear_memories=True.

The tradeoff is that the agent may miss implicit observations.

What Gets Captured

Good for User Memory	Better for User Profile
"Prefers detailed explanations"	Name: "Alice Chen"
"Working on ML project"	Company: "Acme Corp"
"Struggles with async code"	Role: "Data Scientist"
"Uses VS Code"	Timezone: "PST"

Memory Data Model

Field	Description
`user_id`	User this memory belongs to
`memories`	List of memory entries (`id`, `content`, optional metadata)
`agent_id`	Agent context for audit trail
`team_id`	Team context for audit trail
`created_at`	When created
`updated_at`	Last update

Accessing Memories

lm = agent.learning_machine

# Get all memories
memories = lm.user_memory_store.get(user_id="alice@example.com")
if memories:
    for memory in memories.memories:
        print(f"- {memory.get('content')}")

# Debug output
lm.user_memory_store.print(user_id="alice@example.com")

Context Injection

Relevant memories are injected into the system prompt:

<user_memory>
- Prefers code examples over explanations
- Working on a machine learning project
- Uses Python 3.11
- Prefers concise responses
</user_memory>

The Curator does not operate on the User Memory Store. lm.curator.prune() and lm.curator.deduplicate() read the User Profile store, which has no memories field, so both calls return 0 without removing any user memories. To remove memories, use the agentic update_user_memory tool, which supports delete operations.

Combining with User Profile

Use both stores for comprehensive user understanding:

from agno.learn import LearningMachine

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    learning=LearningMachine(
        user_profile=True,  # Structured: name, company
        user_memory=True,   # Unstructured: preferences, context
    ),
)