Vault structure
Vault structure
A Lettuce vault is any folder containing one or more .md files. There’s no required layout. This page describes what Lettuce recognises — what it tracks, what it ignores, and what’s safe to put anywhere.
What’s a note
Anything ending in .md. Subfolders are walked recursively. Hidden files and directories (starting with .) are ignored — except for .lettuce/ itself.
my-vault/
├── Inbox/
│ ├── 2026-05-28 random thought.md
│ └── todo for tuesday.md
├── Projects/
│ ├── Lettuce.md
│ └── Garden 2026.md
├── attachments/
│ ├── pruning-shears.jpg
│ └── tomato-trellis.pdf
├── .lettuce/
│ ├── order.json
│ └── triggers.yml
└── AGENTS.md
Everything in this tree is fine — Lettuce will show the .md files in the sidebar, ignore attachments/ for the sidebar but happily embed images from it via , and read .lettuce/ for vault-local config.
What’s a folder
A real filesystem folder. Lettuce doesn’t have “virtual” folders or tag-based folders. Move a file in Finder and Lettuce sees it on the next scan. Move a folder in Lettuce and Finder sees it instantly.
What’s tracked
Lettuce maintains a few indices in memory (no on-disk database):
| Index | Contents | Cost to rebuild |
|---|---|---|
| Link index | from → to for every [[wikilink]] |
~5ms per 1000 notes |
| Tag index | tag → [notes] for every #tag |
~3ms per 1000 notes |
| Mention scanner | @agent references for [[Agent reference/04 Read tools#agent_mentions |
agent_mentions]] |
| Outline | Headings per note, for fast read_outline |
computed on access |
All of these rebuild on launch and incrementally on each save. There’s no “reindex” button you’ll ever need.
What’s not tracked
Git status — Lettuce doesn’t run
gitor read.gitignore. Use the CLI or your favourite git client.File timestamps — Lettuce uses
mtimefor “Modified” sorting but doesn’t write it back; nothing in Lettuce updatesmtimeunless you actually change the file.Symlinks — followed for reading; if you put a symlink at
<vault>/external.md, it’s treated as a regular note. Symlinks to directories are walked once (cycles are detected).Binary files —
.png,.jpg,.pdf, etc. are not indexed but are referenceable via Markdown image / file syntax.
What’s special
These names trigger Lettuce behaviour anywhere in the vault:
| Name | What it does |
|---|---|
AGENTS.md (vault root) |
Read by agents on connection |
index.md (vault root) |
Used as the published site’s home page |
.lettuce/ |
Vault-local config — see Core concepts/02 The .lettuce directory |
Files without published: true |
Excluded from the published site (publishing is opt-in) |
Multiple vaults
Lettuce can have many vaults open at once (File → New Window). Each window has its own vault. The MCP server serves all currently-open vaults; agents pick a vault by name in tool calls (see vault arg in Agent reference/04 Read tools).
The trash
Deleting a note (Note → Move to Trash, or right-click in the sidebar) is a soft delete: the file moves into a hidden .trash/ folder inside the vault, keeping its original path — it does not go to the macOS Trash. The sidebar’s Trash section lists what’s there, newest first; Restore puts a note back where it came from (renaming if the spot is taken), Delete Permanently removes one item for good, and Empty Trash clears everything (irreversible). Agent deletes (delete_note) land in the same trash and are restorable from the same place — an agent can’t hard-delete your notes by default.
Related
Core concepts/02 The .lettuce directory — the vault-local config dir
Core concepts/03 Frontmatter — YAML keys Lettuce understands
Core concepts/04 Wikilinks, backlinks, and the graph — how notes connect