Letta Filesystem

Letta’s filesystem allow you to easily connect your agents to external files, for example: research papers, reports, medical records, or any other data in common text formats (.pdf, .txt, .md, .json, etc.). To upload a file, you must create a folder (with a name and description) to upload files to, which can be done through the ADE or API.

Once a file has been uploaded to a folder, the agent can access it using a set of file tools. The file is automatically chunked and embedded to allow the agent to use semantic search to find relevant information in the file (in addition to standard text-based search).

File tools

When a folder is attached to an agent, Letta automatically attaches a set of file tools to the agent:

• open_file: Open a file to a specific location
• grep_file: Search a file using a regular expression
• search_file: Search a file using semantic (embedding-based) search

To detach these tools from your agent, simply detach all your folders, the file tools will be automatically removed.

Creating a folder

ADE

To create a folder click the “Filesystem” tab in the bottom-left of the ADE, then click the “create folder” button. When you create a folder inside the ADE, it will be automatically attached to your agent.

API / SDK

To create a folder, you will need to specify a unique name as well as an EmbeddingConfig:

1
// get an available embedding_config
2
const embeddingConfigs = await client.embeddingModels.list()
3
const embeddingConfig = embeddingConfigs[0];
4
5
// create the folder
6
const folder = await client.folders.create({
7
    name: "my_folder",
8
    embeddingConfig: embeddingConfig
9
});

Now that you’ve created the folder, you can start loading data into the folder.

Uploading a file into a folder

ADE

Click the “Filesystem” tab in the bottom-left of the ADE to view your attached folders. To upload a file, simply drag and drop the file into the folders tab, or click the upload (+) button.

API / SDK

Uploading a file to a folder will create an async job for processing the file, which will split the file into chunks and embed them.

1
// upload a file into the folder
2
const uploadJob = await client.folders.files.upload(
3
    createReadStream("my_file.txt"),
4
    folder.id,
5
);
6
console.log("file uploaded")
7
8
// wait until the job is completed
9
while (true) {
10
    const job = await client.jobs.retrieve(uploadJob.id);
11
    if (job.status === "completed") {
12
        break;
13
    } else if (job.status === "failed") {
14
        throw new Error(`Job failed: ${job.metadata}`);
15
    }
16
    console.log(`Job status: ${job.status}`);
17
    await new Promise((resolve) => setTimeout(resolve, 1000));
18
}

Once the job is completed, you can list the files and the generated passages in the folder:

1
// list files in the folder
2
const files = await client.folders.files.list(folder.id);
3
console.log(`Files in folder: ${files}`);
4
5
// list passages in the folder
6
const passages = await client.folders.passages.list(folder.id);
7
console.log(`Passages in folder: ${passages}`);

Listing available folders

You can view available folders by listing them:

1
// list folders
2
const folders = await client.folders.list();

Connecting a folder to an agent

When you attach a folder to an agent, the files inside the folder will become visible inside the agent’s context window. By default, only a limited “window” of the file will be visible to prevent context window overflow - the agent can use the file tools to browse through the files and search for information.

Attaching the folder

ADE

When you create a folder inside the ADE, it will be automatically attached to your agent. You can also attach existing folders by clicking the “attach existing” button in the filesystem tab.

API / SDK

You can attach a folder to an agent by specifying both the folder and agent IDs:

1
await client.agents.folders.attach(agent.id, folder.id);

Note that your agent and folder must be configured with the same embedding model, to ensure that the agent is able to search across a common embedding space for archival memory.

Detaching the folder

ADE

To detach a folder from an agent, click the “detach” button in the folders tab.

API / SDK

Detaching a folder will remove the files from the agent’s context window:

1
await client.agents.folders.detach(agent.id, folder.id);