Deep Agents Memory

<overview>

Deep Agents use pluggable backends for file operations and memory:

Short-term (StateBackend): Persists within a single thread, lost when thread ends Long-term (StoreBackend): Persists across threads and sessions Hybrid (CompositeBackend): Route different paths to different backends

FilesystemMiddleware provides tools: ls, read_file, write_file, edit_file, glob, grep

</overview>

<backend-selection>

</backend-selection>

<ex-default-state-backend>

<python>

Default StateBackend stores files ephemerally within a thread.

from deepagents import create_deep_agent
agent = create_deep_agent()  # Default: StateBackendresult = agent.invoke({    "messages": [{"role": "user", "content": "Write notes to /draft.txt"}]}, config={"configurable": {"thread_id": "thread-1"}})# /draft.txt is lost when thread ends

</python>

<typescript>

Default StateBackend stores files ephemerally within a thread.

import { createDeepAgent } from "deepagents";
const agent = await createDeepAgent();  // Default: StateBackendconst result = await agent.invoke({  messages: [{ role: "user", content: "Write notes to /draft.txt" }]}, { configurable: { thread_id: "thread-1" } });// /draft.txt is lost when thread ends

</typescript>

</ex-default-state-backend>

<ex-composite-backend-for-hybrid>

<python>

Configure CompositeBackend to route paths to different storage backends.

from deepagents import create_deep_agentfrom deepagents.backends import CompositeBackend, StateBackend, StoreBackendfrom langgraph.store.memory import InMemoryStore
store = InMemoryStore()
composite_backend = lambda rt: CompositeBackend(    default=StateBackend(rt),    routes={"/memories/": StoreBackend(rt)})
agent = create_deep_agent(backend=composite_backend, store=store)
# /draft.txt -> ephemeral (StateBackend)# /memories/user-prefs.txt -> persistent (StoreBackend)

</python>

<typescript>

Configure CompositeBackend to route paths to different storage backends.

import { createDeepAgent, CompositeBackend, StateBackend, StoreBackend } from "deepagents";import { InMemoryStore } from "@langchain/langgraph";
const store = new InMemoryStore();
const agent = await createDeepAgent({  backend: (config) => new CompositeBackend(    new StateBackend(config),    { "/memories/": new StoreBackend(config) }  ),  store});
// /draft.txt -> ephemeral (StateBackend)// /memories/user-prefs.txt -> persistent (StoreBackend)

</typescript>

</ex-composite-backend-for-hybrid>

<ex-cross-session-memory>

<python>

Files in /memories/ persist across threads via StoreBackend routing.

# Using CompositeBackend from previous exampleconfig1 = {"configurable": {"thread_id": "thread-1"}}agent.invoke({"messages": [{"role": "user", "content": "Save to /memories/style.txt"}]}, config=config1)
config2 = {"configurable": {"thread_id": "thread-2"}}agent.invoke({"messages": [{"role": "user", "content": "Read /memories/style.txt"}]}, config=config2)# Thread 2 can read file saved by Thread 1

</python>

<typescript>

Files in /memories/ persist across threads via StoreBackend routing.

// Using CompositeBackend from previous exampleconst config1 = { configurable: { thread_id: "thread-1" } };await agent.invoke({ messages: [{ role: "user", content: "Save to /memories/style.txt" }] }, config1);
const config2 = { configurable: { thread_id: "thread-2" } };await agent.invoke({ messages: [{ role: "user", content: "Read /memories/style.txt" }] }, config2);// Thread 2 can read file saved by Thread 1

</typescript>

</ex-cross-session-memory>

<ex-filesystem-backend-local-dev>

<python>

Use FilesystemBackend for local development with real disk access and human-in-the-loop.

from deepagents import create_deep_agentfrom deepagents.backends import FilesystemBackendfrom langgraph.checkpoint.memory import MemorySaver
agent = create_deep_agent(    backend=FilesystemBackend(root_dir=".", virtual_mode=True),  # Restrict access    interrupt_on={"write_file": True, "edit_file": True},    checkpointer=MemorySaver())
# Agent can read/write actual files on disk

</python>

<typescript>

Use FilesystemBackend for local development with real disk access and human-in-the-loop.

import { createDeepAgent, FilesystemBackend } from "deepagents";import { MemorySaver } from "@langchain/langgraph";
const agent = await createDeepAgent({  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),  interruptOn: { write_file: true, edit_file: true },  checkpointer: new MemorySaver()});

</typescript>

Security: Never use FilesystemBackend in web servers - use StateBackend or sandbox instead.

</ex-filesystem-backend-local-dev>

<ex-store-in-custom-tools>

<python>

Access the store directly in custom tools for long-term memory operations.

from langchain.tools import tool, ToolRuntimefrom langchain.agents import create_agentfrom langgraph.store.memory import InMemoryStore
@tooldef get_user_preference(key: str, runtime: ToolRuntime) -> str:    """Get a user preference from long-term storage."""    store = runtime.store    result = store.get(("user_prefs",), key)    return str(result.value) if result else "Not found"
@tooldef save_user_preference(key: str, value: str, runtime: ToolRuntime) -> str:    """Save a user preference to long-term storage."""    store = runtime.store    store.put(("user_prefs",), key, {"value": value})    return f"Saved {key}={value}"
store = InMemoryStore()
agent = create_agent(    model="gpt-4.1",    tools=[get_user_preference, save_user_preference],    store=store)

</python>

</ex-store-in-custom-tools>

<boundaries>

What Agents CAN Configure

• Backend type and configuration
• Routing rules for CompositeBackend
• Root directory for FilesystemBackend
• Human-in-the-loop for file operations

What Agents CANNOT Configure

• Tool names (ls, read_file, write_file, edit_file, glob, grep)
• Access files outside virtual_mode restrictions
• Cross-thread file access without proper backend setup

</boundaries>

<fix-storebackend-requires-store>

<python>

StoreBackend requires a store instance.

# WRONGagent = create_deep_agent(backend=lambda rt: StoreBackend(rt))
# CORRECTagent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())

</python>

<typescript>

StoreBackend requires a store instance.

// WRONGconst agent = await createDeepAgent({ backend: (c) => new StoreBackend(c) });
// CORRECTconst agent = await createDeepAgent({ backend: (c) => new StoreBackend(c), store: new InMemoryStore() });

</typescript>

</fix-storebackend-requires-store>

<fix-statebackend-files-dont-persist>

<python>

StateBackend files are thread-scoped - use same thread_id or StoreBackend for cross-thread access.

# WRONG: thread-2 can't read file from thread-1agent.invoke({"messages": [...]}, config={"configurable": {"thread_id": "thread-1"}})  # Writeagent.invoke({"messages": [...]}, config={"configurable": {"thread_id": "thread-2"}})  # File not found!

</python>

<typescript>

StateBackend files are thread-scoped - use same thread_id or StoreBackend for cross-thread access.

// WRONG: thread-2 can't read file from thread-1await agent.invoke({ messages: [...] }, { configurable: { thread_id: "thread-1" } });  // Writeawait agent.invoke({ messages: [...] }, { configurable: { thread_id: "thread-2" } });  // File not found!

</typescript>

</fix-statebackend-files-dont-persist>

<fix-path-prefix-for-persistence>

<python>

Path must match CompositeBackend route prefix for persistence.

# With routes={"/memories/": StoreBackend(rt)}:agent.invoke(...)  # /prefs.txt -> ephemeral (no match)agent.invoke(...)  # /memories/prefs.txt -> persistent (matches route)

</python>

<typescript>

Path must match CompositeBackend route prefix for persistence.

// With routes: { "/memories/": StoreBackend }:await agent.invoke(...);  // /prefs.txt -> ephemeral (no match)await agent.invoke(...);  // /memories/prefs.txt -> persistent (matches route)

</typescript>

</fix-path-prefix-for-persistence>

<fix-production-store>

<python>

Use PostgresStore for production (InMemoryStore lost on restart).

# WRONG                              # CORRECTstore = InMemoryStore()              store = PostgresStore(connection_string="postgresql://...")

</python>

<typescript>

Use PostgresStore for production (InMemoryStore lost on restart).

// WRONG                                    // CORRECTconst store = new InMemoryStore();          const store = new PostgresStore({ connectionString: "..." });

</typescript>

</fix-production-store>

<fix-filesystem-backend-needs-virtual-mode>

<python>

Enable virtual_mode=True to restrict path access (prevents ../ and ~/ escapes).

backend = FilesystemBackend(root_dir="/project", virtual_mode=True)  # Secure

</python>

</fix-filesystem-backend-needs-virtual-mode>

<fix-longest-prefix-match>

<python>

CompositeBackend matches longest prefix first.

routes = {"/mem/": StoreBackend(rt), "/mem/temp/": StateBackend(rt)}# /mem/file.txt -> StoreBackend, /mem/temp/file.txt -> StateBackend (longer match)

</python>

</fix-longest-prefix-match>