FileSystem

FileSystem gives an agent a durable text store for working notes it writes and maintains.

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

fs = FileSystem(SqliteDb(db_file="tmp/filesystem.db"))

agent = Agent(
    model=OpenAIResponses(id="gpt-5.5"),
    tools=[fs.tools()],
    instructions=[
        "You are a note-keeping assistant.",
        fs.instructions(),
    ],
)

if __name__ == "__main__":
    if fs.read("notes/decisions.md") is None:
        agent.print_response(
            "Record this decision in notes/decisions.md: "
            "Use SQLite for local development and Postgres in production."
        )
        print("Run this file again to recall the decision in a new process.")
    else:
        agent.print_response(
            "Which database did we choose for local development? "
            "Check your files before answering."
        )

Install the dependencies, set OPENAI_API_KEY, and run the file twice:

uv pip install -U "agno[openai,sqlite]"
python filesystem_agent.py
python filesystem_agent.py

The first process writes notes/decisions.md. The second process connects to the same SQLite database and reads the decision from the same namespace.

How FileSystem Works

1. FileSystem connects a storage backend to one namespace.
2. fs.tools() gives the agent file tools.
3. fs.instructions() provides conventions for maintaining durable notes.
4. Files remain available to later FileSystem instances that reopen the same persistent storage and normalized namespace.

Compose fs.instructions() with your application instructions as shown above. fs.tools() leaves instruction placement under your control. Set add_instructions=True on the toolkit when automatic placement fits your application.

The agent retrieves files on demand with search_content and read_file. File content enters model context only through tool results.

Choose a Backend

SQLite and Postgres store one row per namespace and path. Postgres uses the fs schema and agno_fs table by default.

Isolate or Share Files

FileSystem instances can isolate and group files by namespaces. The default namespace is "default".

Use a templated namespace for user-facing agents:

fs = FileSystem(
    SqliteDb(db_file="tmp/filesystem.db"),
    namespace="assistant/{user_id}",
)

{user_id} resolves from run_context.user_id. {agent_id} and {team_id} resolve from the injected agent and team IDs. A missing value blocks the file operation. Model-supplied tool arguments cannot select another namespace.

Namespaces are lowercased and encoded as URL-safe identifiers. Map each identity to a stable ID that does not differ only by case, such as an internal UUID.

Use the same static namespace to share files deliberately:

producer_fs = FileSystem(db, namespace="research/decisions")
consumer_fs = FileSystem(db, namespace="research/decisions")

consumer_tools = consumer_fs.tools(read_only=True)
consumer_instructions = consumer_fs.instructions(read_only=True)

read_only=True limits the tools available to the model. Direct Python methods on the FileSystem object remain available to application code.

Operational Defaults

Set max_file_bytes and max_namespace_bytes on FileSystem to change the storage limits. Coordinate concurrent read-modify-write edits to the same file. append(unique=True) filters duplicate lines within one check-and-append flow. The check and append are not atomic against concurrent writers, including writers in the same process. Namespace usage checks and writes are also separate operations, so strict quota enforcement requires application-level coordination between concurrent writers.

Keep secrets, passwords, and API keys out of FileSystem content.

Use One File Toolkit

FileSystem shares tool names such as read_file, write_file, and list_files with other file-oriented toolkits. Agno keeps the first registration for each tool name and logs a warning for later duplicates.

Remember to only attach one file-like toolkit to an agent. Wrap one toolkit in a sub-agent when an application needs both FileSystem and a local workspace.

Developer Resources

• FileSystem source