---
title: Letta Filesystem (Deprecated) | Letta Docs
description: Store and manage files with the Letta Filesystem API.
---

**Letta Filesystem has been deprecated and disabled on the API.** The documentation below is preserved for reference only. Letta Filesystem is replaced by direct filesystem access and [context repositories](/letta-code/memory/index.md). Agents should read files locally using [Letta Code](/letta-code/index.md) or the [new SDK](/letta-agent-sdk/quickstart/index.md). For PDF extraction, see the [extracting-pdf-text skill](https://github.com/letta-ai/skills/tree/main/tools/extracting-pdf-text). For semantic search over local documents, use [qmd](https://github.com/tobi/qmd).

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.

```
graph TB
    subgraph "Folders"
        DS1[Folder 1<br/>Research Papers]
        DS2[Folder 2<br/>Medical Records]
    end

    subgraph "Files"
        F1[paper1.pdf]
        F2[paper2.pdf]
        F3[patient_record.txt]
        F4[lab_results.json]
    end

    subgraph "Letta Agents"
        A1[Agent 1]
        A2[Agent 2]
        A3[Agent 3]
    end

    DS1 --> F1
    DS1 --> F2
    DS2 --> F3
    DS2 --> F4

    A2 -.->|attached to| DS1
    A2 -.->|attached to| DS2
    A3 -.->|attached to| DS2
```

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).

If you’ve used [Claude Projects](https://www.anthropic.com/news/projects) before, you can think of a **folder** in Letta as a “project”, except in Letta you can connect a single agent to multiple projects (in Claude Projects, a chat session can only be associated with a single project).

## 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

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

- [TypeScript](#tab-panel-12)
- [Python](#tab-panel-13)

```
// create the folder with embedding handle
const folder = await client.folders.create({
  name: "my_folder",
  embedding: "openai/text-embedding-3-small",
});
```

```
# create the folder with embedding handle
folder = client.folders.create(
    name="my_folder",
    embedding="openai/text-embedding-3-small"
)
```

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

## Uploading a file into a folder

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.

- [TypeScript](#tab-panel-14)
- [Python](#tab-panel-15)

```
// upload a file into the folder
const uploadJob = await client.folders.files.upload(
  createReadStream("my_file.txt"),
  folder.id,
);
console.log("file uploaded");


// wait until the job is completed
while (true) {
  const job = await client.jobs.retrieve(uploadJob.id);
  if (job.status === "completed") {
    break;
  } else if (job.status === "failed") {
    throw new Error(`Job failed: ${job.metadata}`);
  }
  console.log(`Job status: ${job.status}`);
  await new Promise((resolve) => setTimeout(resolve, 1000));
}
```

```
# upload a file into the folder
job = client.folders.files.upload(
    folder_id=folder.id,
    file=open("my_file.txt", "rb")
)


# wait until the job is completed
while True:
    job = client.jobs.retrieve(job.id)
    if job.status == "completed":
        break
    elif job.status == "failed":
        raise ValueError(f"Job failed: {job.metadata}")
    print(f"Job status: {job.status}")
    time.sleep(1)
```

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

- [TypeScript](#tab-panel-16)
- [Python](#tab-panel-17)

```
// list files in the folder
const files = await client.folders.files.list(folder.id);
console.log(`Files in folder: ${files}`);


// list passages in the folder
const passages = await client.folders.passages.list(folder.id);
console.log(`Passages in folder: ${passages}`);
```

```
# list files in the folder
files = client.folders.files.list(folder_id=folder.id)
print(f"Files in folder: {files}")


# list passages in the folder
passages = client.folders.passages.list(folder_id=folder.id)
print(f"Passages in folder: {passages}")
```

## Listing available folders

You can view available folders by listing them:

- [TypeScript](#tab-panel-18)
- [Python](#tab-panel-19)

```
// list folders
const folders = await client.folders.list();
```

```
# list folders
folders = 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

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

- [TypeScript](#tab-panel-20)
- [Python](#tab-panel-21)

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

```
client.agents.folders.attach(agent_id=agent.id, folder_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

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

- [TypeScript](#tab-panel-22)
- [Python](#tab-panel-23)

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

```
client.agents.folders.detach(agent_id=agent.id, folder_id=folder.id)
```