Storage Control

As sessions accumulate data, your database can grow quickly. Kern gives you fine-grained control over what gets persisted with three storage flags:

• store_media - Images, videos, audio, and file uploads
• store_tool_messages - Tool calls and their results
• store_history_messages - Historical messages from previous runs

How Storage Control Works

Think of these flags as filters for your database, not your agent. During a run, your agent or team sees everything: media, tool results, history. Everything works normally. The filtering only happens when saving to the database after the run finishes.

So you can turn off storing media or tool messages without breaking anything. Your agent still processes images, tools still run, history still flows to the model. You're just choosing what gets written to disk. Token metrics still reflect the real usage, even if you didn't persist all the data.

Storage Flags Reference

Disable Media Storage

Large media uploads (images, PDFs, audio) can dominate your session tables. Turn them off with store_media=False and store the original files elsewhere (S3, GCS, etc.).

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5agent = Agent(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/agent.db"),
8    store_media=False,
9)

1from kern.team import Team
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5team = Team(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/team.db"),
8    store_media=False,
9)

During a run the model still receives the media (and tools can still process it); the flag only affects what is written to the database afterward.

Recommended Workflow

1. Upload the file to your preferred storage service and keep the URL/ID
2. Pass that URL to the agent/team so it can fetch/process the file
3. Skip persisting the raw media via store_media=False

Disable Tool Storage

Tool calls can easily bloat storage (think web-scraped pages or large API payloads). Toggle store_tool_messages=False to remove both the tool result and the tool-call from the corresponding assistant message that triggered it from the persisted run. Metrics still show the real token usage.

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4from kern.tools.hackernews import HackerNewsTools
5
6agent = Agent(
7    model=OpenAIResponses(id="gpt-5.2"),
8    tools=[HackerNewsTools()],
9    db=SqliteDb(db_file="tmp/agent.db"),
10    store_tool_messages=False,
11)

1from kern.team import Team
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4from kern.tools.hackernews import HackerNewsTools
5
6team = Team(
7    model=OpenAIResponses(id="gpt-5.2"),
8    tools=[HackerNewsTools()],
9    db=SqliteDb(db_file="tmp/team.db"),
10    store_tool_messages=False,
11)

Considerations

• Removing tool messages keeps the provider-friendly message ordering intact (no stray tool roles)
• When auditing tool behavior later, re-run the tool or log its output somewhere else before the run completes
• Pair this with store_media=False when tools return binary payloads you don't need in the session record

History Storage

store_history_messages defaults to False to prevent database bloat. History still reaches the LLM during runs (via add_history_to_context), but historic messages are scrubbed before persistence. Only the current run's messages are written to the database.

Set store_history_messages=True if you need to persist complete conversation history.

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5agent = Agent(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/agent.db"),
8    add_history_to_context=True,
9    num_history_runs=3,
10    store_history_messages=True,
11)

1from kern.team import Team
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5team = Team(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/team.db"),
8    add_history_to_context=True,
9    num_history_runs=3,
10    store_history_messages=True,
11)

When to Enable It

• You need to inspect past conversations in the database
• You're debugging multi-run interactions
• Your agent relies heavily on historical context across sessions

Combining Storage Flags

You can use multiple flags together to optimize your storage strategy:

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5agent = Agent(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/agent.db"),
8    store_media=False,           # Media stored externally
9    store_tool_messages=False,   # Tool results not needed
10    store_history_messages=False, # Only current run persisted
11)

1from kern.team import Team
2from kern.models.openai import OpenAIResponses
3from kern.db.sqlite import SqliteDb
4
5team = Team(
6    model=OpenAIResponses(id="gpt-5.2"),
7    db=SqliteDb(db_file="tmp/team.db"),
8    store_media=False,           # Media stored externally
9    store_tool_messages=False,   # Tool results not needed
10    store_history_messages=False, # Only current run persisted
11)

Turn a flag off when you want to reduce storage footprint (e.g., large tool payloads you can always re-run, media living in S3, old history you don't need). Leave it on when you need full transcripts for audit/compliance, analytics, or agent coaching.

Learn More

• Sessions Overview
• Session Storage