LangChain DeepAgents Quick Guide – FileSystem Middleware Gives AI Agents System‑Level Memory Management

When an agent repeatedly calls tools such as web search or RAG retrieval, the returned information can quickly fill the limited context window, causing performance degradation or loss of important instructions. The FileSystem middleware is introduced to let agents archive important data and retrieve it later, effectively extending the agent's memory.

The middleware gives an agent file‑management capabilities by exposing four tools ( ls, read_file, write_file, edit_file) that operate on a virtual file system, allowing the agent to keep a private notebook that persists across interactions.

Installation

pip install deepagents

Basic usage

After importing the necessary classes, the middleware is added to the create_agent call:

from langchain.agents import create_agent
from langchain_deepagents import FileSystemMiddleware

agent = create_agent(
    model=model,
    middlewares=[
        FileSystemMiddleware(
            backend=None,
            system_prompt="Write to the filesystem when...",
            custom_tool_descriptions={
                "ls": "Use the ls tool when...",
                "read file": "Use the read file tool to..."
            }
        )
    ]
)

The middleware automatically provides the four file‑operation tools listed above.

Parameter overview

backend (optional): selects the storage mode; this is the core configuration of the middleware.

system_prompt (optional): lets developers override the default system prompt that guides when the agent should use file operations.

custom_tool_descriptions (optional): customizes the description of each tool for specific scenarios.

Backend options

The backend parameter can be set to one of four built‑in backends, each offering a different memory lifetime:

FileSystemBackend – local disk

Provides direct access to the host file system. The root_dir limits the accessible directory and virtual_mode can hide absolute paths for safety.

from deepagents.backends import FilesystemBackend

agent = create_agent(
    model=model,
    middlewares=[FileSystemMiddleware(backend=FilesystemBackend(root_dir="./data", virtual_mode=True))]
)

StateBackend – thread‑level short‑term memory

Embeds a virtual file system into the agent's runtime state; files exist only for the lifetime of the current thread, acting like a temporary scratchpad.

from deepagents.backends import StateBackend

agent = create_agent(
    model=model,
    middlewares=[FileSystemMiddleware(backend=lambda runtime: StateBackend(runtime))]
)

StoreBackend – cross‑thread long‑term memory

Uses a shared store object (e.g., InMemoryStore or a database) so that files persist across threads and sessions.

from deepagents.backends import StoreBackend
from langgraph.store.memory import InMemoryStore

store = InMemoryStore()
agent = create_agent(
    model=model,
    store=store,
    middlewares=[FileSystemMiddleware(backend=lambda runtime: StoreBackend(runtime))]
)

CompositeBackend – mixed routing

Combines multiple backends by routing file paths based on a routes dictionary. The default backend handles paths without a matching prefix.

from deepagents.backends import CompositeBackend, StateBackend, StoreBackend

composite_backend = lambda runtime: CompositeBackend(
    default=StateBackend(runtime),
    routes={"/memories/": StoreBackend(runtime)}
)

agent = create_agent(
    model=model,
    store=store,
    middlewares=[FileSystemMiddleware(backend=composite_backend)]
)

When a file path starts with /memories/, the middleware strips the prefix and stores the file in the StoreBackend; otherwise it uses the StateBackend. This decouples logical paths seen by the agent from physical storage locations.

Practical examples

Using StateBackend, an agent writes test.txt and reads it back within the same thread, demonstrating temporary memory that disappears after the thread ends.

With StoreBackend, two agents created in separate threads share the same InMemoryStore; the second agent can read the file written by the first, proving cross‑thread persistence.

Using CompositeBackend, one thread writes /memories/preferences.txt and another thread reads it via the shared store, showing how mixed storage enables both short‑term drafts and long‑term shared knowledge.

Choosing the right backend

StateBackend : suitable for transient data needed only during a single conversation.

StoreBackend : ideal for user preferences, global configuration, or knowledge bases that must survive across sessions.

FileSystemBackend : best when interacting with external systems or storing large unstructured files on disk.

CompositeBackend : enables layered memory strategies, routing temporary files to StateBackend and important data to StoreBackend or FileSystemBackend.

Understanding these storage mechanisms helps developers design agents that balance memory persistence, security, and performance.

Conclusion

The FileSystem middleware equips LangChain DeepAgents with flexible file‑based memory through four backend modes—StateBackend (thread‑level short‑term), StoreBackend (cross‑thread long‑term), FileSystemBackend (disk persistence), and CompositeBackend (hybrid routing)—allowing agents to manage context windows effectively from temporary drafts to durable knowledge.