User Memory

Unstructured observations about users.

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 (with optional curation)
Default mode	Always
Supported modes	Always, Agentic

Basic Usage

1from kern.agent import Agent
2from kern.db.postgres import PostgresDb
3from kern.learn import LearningMachine
4from kern.models.openai import OpenAIResponses
5
6agent = Agent(
7    model=OpenAIResponses(id="gpt-5.2"),
8    db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
9    learning=LearningMachine(user_memory=True),
10)
11
12# Session 1: Share preferences
13agent.print_response(
14    "I prefer code examples over explanations. Also, I'm working on a machine learning project.",
15    user_id="alice@example.com",
16    session_id="session_1",
17)
18
19# Session 2: Memory is recalled
20agent.print_response(
21    "Explain async/await in Python",
22    user_id="alice@example.com",
23    session_id="session_2",
24)

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

Always Mode

Memories are extracted automatically after each response.

1from kern.learn import LearningMachine, LearningMode, UserMemoryConfig
2
3agent = Agent(
4    model=OpenAIResponses(id="gpt-5.2"),
5    db=db,
6    learning=LearningMachine(
7        user_memory=UserMemoryConfig(mode=LearningMode.ALWAYS),
8    ),
9)

Tradeoff: extra LLM call per interaction.

Agentic Mode

The agent receives tools to manage memories explicitly.

1from kern.learn import LearningMachine, LearningMode, UserMemoryConfig
2
3agent = Agent(
4    model=OpenAIResponses(id="gpt-5.2"),
5    db=db,
6    learning=LearningMachine(
7        user_memory=UserMemoryConfig(mode=LearningMode.AGENTIC),
8    ),
9)
10
11agent.print_response(
12    "Remember that I always want to see error handling in code examples.",
13    user_id="alice@example.com",
14)

Available tool: update_user_memory (supports add, update, delete, and clear operations)

Tradeoff: 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

1lm = agent.get_learning_machine()
2
3# Get all memories
4memories = lm.user_memory_store.get(user_id="alice@example.com")
5if memories:
6    for memory in memories.memories:
7        print(f"- {memory.get('content')}")
8
9# Debug output
10lm.user_memory_store.print(user_id="alice@example.com")

Context Injection

Relevant memories are injected into the system prompt:

1<user_memory>
2- Prefers code examples over explanations
3- Working on a machine learning project
4- Uses Python 3.11
5- Prefers concise responses
6</user_memory>

Curation

Over time, memories accumulate. Use the Curator to maintain them:

1lm = agent.get_learning_machine()
2
3# Remove memories older than 90 days
4lm.curator.prune(user_id="alice@example.com", max_age_days=90)
5
6# Remove duplicates
7lm.curator.deduplicate(user_id="alice@example.com")

Combining with User Profile

Use both stores for comprehensive user understanding:

1from kern.learn import LearningMachine
2
3agent = Agent(
4    model=OpenAIResponses(id="gpt-5.2"),
5    db=db,
6    learning=LearningMachine(
7        user_profile=True,  # Structured: name, company
8        user_memory=True,   # Unstructured: preferences, context
9    ),
10)