Storage Control

As sessions accumulate data, your database can grow quickly. Agno 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

Storage control works identically for Agents and Teams. This page shows examples for both.

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.

When you optimise what messages you store in the database, it might cause hallucinations on the LLM, if any of the messages are essential to the conversation history. If you don’t rely too heavily on history, you can safely optimise storage.For example, if you remove tool call messages, it won’t be available in subsequent runs where history is enabled, which could cause the LLM to think that tool was never used.

Important: store_tool_messages=False removes tool-call and result pairsWhen you disable tool message storage, Agno removes both the tool result and the strips the tool call from the corresponding assistant message (message from the LLM). This is required to maintain valid message sequences that model providers expect.Your metrics will still show the actual tokens used, including the removed tool messages.

Storage Flags Reference

Flag	Default	What It Controls	Impact When Disabled
`store_media`	`True`	Images, videos, audio, files uploaded by users	Media not persisted to database
`store_tool_messages`	`True`	Tool calls and their results (also removes corresponding assistant messages)	Tool execution details not stored, saves significant space
`store_history_messages`	`True`	Historical messages from previous runs	Old history not stored, only current run persisted

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.).

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/agent.db"),
    store_media=False,
)

from agno.team import Team
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/team.db"),
    store_media=False,
)

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

Upload the file to your preferred storage service and keep the URL/ID
Pass that URL to the agent/team so it can fetch/process the file
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.

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    db=SqliteDb(db_file="tmp/agent.db"),
    store_tool_messages=False,
)

from agno.team import Team
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb
from agno.tools.hackernews import HackerNewsTools

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    db=SqliteDb(db_file="tmp/team.db"),
    store_tool_messages=False,
)

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

Disable History Storage

store_history_messages=False keeps the runtime behavior (history still reaches the LLM) but scrubs the historic messages before persistence. Only the non-history messages are written to the database.

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/agent.db"),
    add_history_to_context=True,
    num_history_runs=3,
    store_history_messages=False,
)

from agno.team import Team
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/team.db"),
    add_history_to_context=True,
    num_history_runs=3,
    store_history_messages=False,
)

When to Toggle It

Cost / storage: Reduce table size for high-volume deployments
Privacy: Avoid storing long-lived transcripts that contain sensitive data
Debugging current runs only: Keep just the latest interaction record

Combining Storage Flags

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

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/agent.db"),
    store_media=False,           # Media stored externally
    store_tool_messages=False,   # Tool results not needed
    store_history_messages=False, # Only current run persisted
)

from agno.team import Team
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/team.db"),
    store_media=False,           # Media stored externally
    store_tool_messages=False,   # Tool results not needed
    store_history_messages=False, # Only current run persisted
)

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.

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

Storage Control

How Storage Control Works

Storage Flags Reference

Disable Media Storage

Recommended Workflow

Disable Tool Storage

Considerations

Disable History Storage

When to Toggle It

Combining Storage Flags

Learn More

​How Storage Control Works

​Storage Flags Reference

​Disable Media Storage

​Recommended Workflow

​Disable Tool Storage

​Considerations

​Disable History Storage

​When to Toggle It

​Combining Storage Flags

​Learn More

How Storage Control Works

Storage Flags Reference

Disable Media Storage

Recommended Workflow

Disable Tool Storage

Considerations

Disable History Storage

When to Toggle It

Combining Storage Flags

Learn More