Working with Memories

Customize how memories are created, control context inclusion, share memories across agents, and use memory tools for advanced workflows.

The basic memory setup covers most use cases, but sometimes you need more control. This guide covers advanced patterns for customizing memory behavior, controlling what gets stored, and building complex multi-agent systems with shared memory.

Customizing the Memory Manager

The MemoryManager controls which LLM creates and updates memories, plus how those memories are generated. You can customize it to use a specific model, add privacy rules, or change how memories are extracted:

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.memory import MemoryManager
4from kern.models.openai import OpenAIResponses
5
6# Setup your database
7db = SqliteDb(db_file="kern.db")
8
9# Setup your Memory Manager, to adjust how memories are created
10memory_manager = MemoryManager(
11    db=db,
12    # Select the model used for memory creation and updates. If unset, the default model of the Agent is used.
13    model=OpenAIResponses(id="gpt-5.2"),
14    # You can also provide additional instructions
15    additional_instructions="Don't store the user's real name",
16)
17
18# Now provide the adjusted Memory Manager to your Agent
19agent = Agent(
20    db=db,
21    memory_manager=memory_manager,
22    update_memory_on_run=True,
23)
24
25agent.print_response("My name is John Doe and I like to play basketball on the weekends.")
26
27agent.print_response("What's do I do in weekends?")

In this example, the memory manager will store memories about hobbies, but won't include the user's actual name. This is useful for healthcare, legal, or other privacy-sensitive applications.

Memories and Context

When enabled, memories about the current user are automatically added to the agent's context on each request. But in some scenarios, like when you're building analytics on memories or want the agent to explicitly search for memories using tools, you might want to store memories without auto-including them.

Use add_memories_to_context=False to collect memories in the background while keeping the agent's context lean:

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3
4# Setup your database
5db = SqliteDb(db_file="kern.db")
6
7# Setup your Agent with Memory
8agent = Agent(
9    db=db,
10    update_memory_on_run=True, # This enables Memory for the Agent
11    add_memories_to_context=False, # This disables adding memories to the context
12)

Memory Optimization

As users accumulate memories over time, and these memories are added to your context on each request, token costs can grow significantly. Memory optimization helps reduce these costs by combining multiple memories into fewer, more efficient memories while preserving all the key information.

When to optimize:

Users with 50+ memories
Before high-cost operations
Periodic maintenance for long-running applications

1from kern.memory.strategies.types import MemoryOptimizationStrategyType
2
3# Optimize memories for a user
4optimized = agent.memory_manager.optimize_memories(
5    user_id="user_123",
6    strategy=MemoryOptimizationStrategyType.SUMMARIZE,
7    apply=True,  # Set to False to preview without saving
8)

See the Memory Optimization guide for detailed usage and best practices.

Using Memory Tools

Instead of automatic memory management, you can give your agent explicit tools to create, retrieve, update, and delete memories. This approach gives the agent more control and reasoning ability, so it can decide when to store something versus when to search for existing memories.

When to use Memory Tools:

You want the agent to reason about whether something is worth remembering
You need fine-grained control over memory operations (create, update, delete separately)
You're building a system where the agent should explicitly search memories rather than having them auto-loaded

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.models.openai import OpenAIResponses
4from kern.tools.memory import MemoryTools
5
6# Create a database connection
7db = SqliteDb(
8    db_file="tmp/memory.db"
9)
10
11memory_tools = MemoryTools(
12    db=db,
13)
14
15agent = Agent(
16    model=OpenAIResponses(id="gpt-5.2"),
17    tools=[memory_tools],
18    markdown=True,
19)
20
21if __name__ == "__main__":
22    agent.print_response(
23        "My name is John Doe and I like to hike in the mountains on weekends. "
24        "I like to travel to new places and experience different cultures. "
25        "I am planning to travel to Africa in December. ",
26        user_id="john_doe@example.com",
27        stream=True
28    )
29
30    # This won't use the session history, but instead will use the memory tools to get the memories
31    agent.print_response("What have you remembered about me?", stream=True, user_id="john_doe@example.com")

See the Memory Tools documentation for more details.

Sharing Memory Between Agents

In multi-agent systems, you often want agents to share knowledge about users. For example, a support agent might learn a user's preferences, and a sales agent should be aware of them too. This is simple in Kern: just connect multiple agents to the same database.

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3
4# Setup your database
5db = SqliteDb(db_file="kern.db")
6
7# Setup your Agents with the same database and Memory enabled
8agent_1 = Agent(db=db, update_memory_on_run=True)
9agent_2 = Agent(db=db, update_memory_on_run=True)
10
11# The first Agent will create a Memory about the user name here:
12agent_1.print_response("Hi! My name is John Doe")
13
14# The second Agent will be able to retrieve the Memory about the user name here:
15agent_2.print_response("What is my name?")

All agents connected to the same database automatically share memories for each user. This works across agent types, teams, and workflows, as long as they use the same user_id.

Developer Resources

View Examples
View Cookbook