---
title: "02 Folders and Subfolders"
canonical_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/ee296c64-ecda-49e9-a03f-1834eb1746d1
md_url: https://mdflow.cz/share/c/h0L7MvX5Cy5sST3qPnApqHOmrQ36JTVy169qJMtDMya9Kc30zm04cg9OuPSSPwvj/ee296c64-ecda-49e9-a03f-1834eb1746d1.md
visibility: public
---

# Folders and Subfolders

Folders hold your documents. They live inside a workspace and can nest as deeply as you need.

## The basics

- **Create, rename and delete** folders from the sidebar.
- **Nest** folders inside folders to build a tree.
- **Name a subfolder as you create it.**
- **Move** a folder to a different parent — or to the top level — with the "Move to…" picker.
- **Collapse and expand** folders in the sidebar. The collapse state is remembered in your browser.
- Folders and documents are listed in **alphabetical order**.

If a folder name already exists in the same place, MDflow appends a numeric suffix rather than refusing or overwriting.

## Deleting a folder

Deleting a folder **removes the documents inside it**, after a confirmation warning. There is no trash and no undo. Uploaded images belonging to those documents are cleaned up too.

## Folder descriptions — the feature worth using

Every folder can have an optional description, up to 5,000 characters. It is easy to skip. Don't.

A description does two jobs:

**1. It tells people what belongs here.** Useful for you in six months, and essential if you share the folder as part of a collection.

**2. It is the primary retrieval signal for AI agents.** This is the part that surprises people.

When an AI agent asks MDflow for context on a topic, MDflow ranks **folder descriptions above folder names and document titles**. A folder called `Notes` with no description is nearly invisible to an agent. The same folder described as *"Meeting notes from weekly product syncs, including decisions and action items for the mobile team"* becomes findable. See [03 MCP Servers](/doc/aad78a27-0654-4781-b4b7-6ced0b14dbfc).

If you use MDflow with Claude, ChatGPT, Cursor, or your own scripts, writing good folder descriptions is the single highest-leverage thing you can do to make retrieval work.

### What a good description looks like

Describe **what is inside and why**, in the words someone would search for:

> Invoices and receipts for the consulting business, filed by client. Includes issued invoices, payment confirmations, and expense receipts needed for the annual tax return.

Not:

> Stuff.

## The description cascade

Descriptions compound down the tree. When an agent fetches a folder or a document, MDflow returns its **compounded description** — the cascade from the workspace, down through each parent folder, to the item itself.

So a document in `Work → Clients → Acme → Contracts` arrives with the full chain of context, not just its own title. You get this for free by describing each level once.

## Nesting is for humans, not retrieval

One nuance: nesting does **not** aggregate content for retrieval. Each folder is ranked on its **own** description. A well-described parent does not make its vaguely-described children findable.

So describe folders at whatever level actually holds documents, rather than relying on a good description at the top of the tree to cover everything beneath it.

## Where folders sit in the hierarchy

Folders belong to exactly one workspace (see [01 Workspaces](/doc/ffdfed0b-680d-4018-9727-f36b0f9d6cb0)). Moving a folder between workspaces is possible in the web app (it takes its documents and subfolders with it), but not through the API or MCP server, which only reparent within the same workspace. See [02 HTTP API](/doc/bdb63d7f-857f-42ef-b13f-aa4d139e7cf8).