composite

Protocol for pluggable memory backends (single, unified).

Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.

All file data is represented as dicts with the following structure:

{
    "content": str,  # Text content (utf-8) or base64-encoded binary
    "encoding": str,  # "utf-8" for text, "base64" for binary data
    "created_at": str,  # ISO format timestamp
    "modified_at": str,  # ISO format timestamp
}

Result from backend edit operations.

Result of code execution.

Simplified schema optimized for LLM consumption.

Result of a single file download operation.

The response is designed to allow partial success in batch operations.

The errors are standardized using FileOperationError literals for certain recoverable conditions for use cases that involve LLMs performing file operations.

Structured file listing info.

Minimal contract used across backends. Only path is required. Other fields are best-effort and may be absent depending on backend.

Result of a single file upload operation.

The response is designed to allow partial success in batch operations.

The errors are standardized using FileOperationError literals for certain recoverable conditions for use cases that involve LLMs performing file operations.

Result from backend glob operations.

A single match from a grep search.

Result from backend grep operations.

Result from backend ls operations.

Result from backend read operations.

Extension of BackendProtocol that adds shell command execution.

Designed for backends running in isolated environments (containers, VMs, remote hosts).

Adds execute()/aexecute() for shell commands and an id property.

See BaseSandbox for a base class that implements all inherited file operations by delegating to execute().

Result from backend write operations.

Backend that stores files in agent state (ephemeral).

Uses LangGraph's state management and checkpointing. Files persist within a conversation thread but not across threads. State is automatically checkpointed after each agent step.

Reads and writes go through LangGraph's CONFIG_KEY_READ / CONFIG_KEY_SEND so that state updates are queued as proper channel writes rather than returned as files_update dicts.

Routes file operations to different backends by path prefix.

Matches paths against route prefixes (longest first) and delegates to the corresponding backend. Unmatched paths use the default backend.