The Palace

File Palaces organises your documents using a spatial metaphor borrowed from the ancient mnemonic technique of the memory palace. Understanding this hierarchy helps you reason about how your data is stored, queried, and maintained.

The hierarchy

Palace
└── Wing            ← one per folder you add
    └── Room        ← one per sub-folder (or file category)
        └── Drawer  ← one per text chunk extracted from a file

Palace

The palace is the root of your local ChromaDB vector store. There is exactly one palace per File Palaces installation, stored at:

The palace directory contains ChromaDB's SQLite database and HNSW index files. You can back it up by copying the whole folder.

Wings

A Wing corresponds to a top-level folder you've added to File Palaces. Its name is a URL-safe slug derived from the folder name. Wings are the primary unit of organisation — every search and chat query can be scoped to one Wing.

Rooms

Rooms correspond to sub-folders within a Wing. They provide a second level of grouping. A Wing that points to ~/Documents/Work might have Rooms like projects, clients, and archive.

For files added directly to the Wing root (not inside any sub-folder), the Room name is derived from the file's extension or MIME type.

Drawers

A Drawer is a single text chunk extracted from a file. It stores:

• The verbatim extracted text (no LLM summarisation)
• The embedding vector (for semantic search)
• Metadata: source file path, Wing, Room, chunk index, character offsets

Chunks are ~512 tokens with a 50-token overlap between adjacent chunks. This overlap ensures that queries landing near a chunk boundary still retrieve relevant context.

Mining and the palace

When you add a Wing, the miner:

1. Walks the directory tree recursively
2. Identifies supported file types
3. Extracts text from each file
4. Splits text into overlapping chunks
5. Embeds each chunk with a local sentence-transformer model
6. Writes each chunk as a Drawer to ChromaDB under the correct Wing → Room path

The miner runs in a background thread pool — it never blocks the UI.

Live sync (watchdog)

File Palaces runs a filesystem watchdog observer on every active Wing. When a file changes, a debounced re-mine is queued for that file only (not the whole Wing). The debounce window is ~5 seconds to avoid thrashing during rapid saves.

When a file is deleted, its Drawers are removed from the palace.

Palace stats

The Palace Map panel (Ctrl+M / Cmd+M) shows live stats:

• Total Wings, Rooms, and Drawers
• Per-Wing file type breakdown
• Index size on disk
• Last-mined timestamp per Wing

You can also query stats via the API:

curl http://127.0.0.1:52731/palace

{
  "wings": 3,
  "rooms": 27,
  "drawers": 14203,
  "palace_path": "C:\\Users\\you\\AppData\\Roaming\\FilePalaces\\palace"
}

Backing up and migrating

To back up your palace, copy the entire palace directory to a safe location. To migrate to a new machine:

1. Install File Palaces and run it once (creates the palace directory)
2. Close the app
3. Copy your backed-up palace directory over the new one
4. Restart — your Wings and all indexed data are immediately available