Skip to main content
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

FlagDefaultWhat It ControlsImpact When Disabled
store_mediaTrueImages, videos, audio, files uploaded by usersMedia not persisted to database
store_tool_messagesTrueTool calls and their results (also removes corresponding assistant messages)Tool execution details not stored, saves significant space
store_history_messagesFalseHistorical messages from previous runsOld 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,
)
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.
  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. 
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,
)

​
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. 
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=True,
)

​
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: 
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
)
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