FileSystem

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

filesystem_agent.py

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

FileSystem connects a storage backend to one namespace.
fs.tools() gives the agent file tools.
fs.instructions() provides conventions for maintaining durable notes.
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

Backend	Configuration	Use it for
SQLite	`FileSystem(SqliteDb(db_file="tmp/filesystem.db"))`	Local development
Postgres	`FileSystem(PostgresDb(db_url=...))`	Deployed applications and multiple workers
Local disk	`FileSystem(LocalFileSystem(root="tmp/agent-files"))`	Files you want to inspect with an editor or shell

SQLite and Postgres store one row per namespace and path. Postgres uses the fs schema and agno_fs table by default. 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.

Namespaces scope files inside a backend. Enforce user authorization and backend access in your application.

Operational Defaults

Constraint	Default
Content	UTF-8 text
Paths	Relative paths such as `notes/decisions.md`
File size	1,000,000 bytes
Namespace size	20,000,000 bytes across all files
Whole-file `read_file`	100,000 characters
`list_files` result	200 files and 200 directories
`check_lines` input	200 records per call
Replacement writes	Last writer wins unless application code passes `expected_version`
Deletion	Excluded from the default agent tool surface

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.

Feature	Purpose
`agno.fs.FileSystem`	Durable text the agent writes and maintains for future runs
`FilesystemContextProvider`	Read-only queries over an existing local directory
`LocalFileSystemTools`	Direct reads and writes in a host directory
`Workspace`	Root-scoped local file operations and shell execution

Developer Resources

Getting Started

Attach FileSystem, use it from Python, and switch storage backends.

Durable Records

Deduplicate recurring work with exact processed-record sets.

Working State

Resume long-running work from durable checkpoints.

Namespaces

Isolate users and share one store between agents.

FileSystem source

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

How FileSystem Works

Choose a Backend

Operational Defaults

Use One File Toolkit

Developer Resources

Getting Started

Durable Records

Working State

Namespaces

​How FileSystem Works

​Choose a Backend

​Isolate or Share Files

​Operational Defaults

​Use One File Toolkit

​Developer Resources

Getting Started

Durable Records

Working State

Namespaces

How FileSystem Works

Choose a Backend

Isolate or Share Files

Operational Defaults

Use One File Toolkit

Developer Resources