Lettuce Docs Tags Graph

The .lettuce directory

#docs#concepts#reference
~4 min read

The .lettuce directory

Vault-local config lives in <vault>/.lettuce/. Everything in this folder is plain text, human-editable, version-controllable, and optional — Lettuce works fine without any of it.

.lettuce/
├── order.json           # manual sidebar ordering
├── triggers.yml         # file:created automations (splice an AI directive)
├── schedules.yml        # daily/weekly directives + maintenance runs
├── schedule-state.json  # last-fired times per schedule rule (so none double-fires)
├── lint-state.json      # dedup ledger for filed semantic-lint directives
├── proposals/           # pending agent proposals (one file per proposal)
│   ├── 7f3c2a9e-....json
│   └── ...
├── agent-edits.json     # revertible agent-edit timeline (persisted across restarts)
├── vectors.json         # note-level embedding index (when embeddings configured)
└── passages.json        # chunk-level embedding index (for `answer`)

order.json — manual sidebar order

Lettuce stores manual sort order here when you drag items in the sidebar. It maps folder paths to ordered child names:

{
  "/": ["Inbox", "Projects", "Daily", "Archive"],
  "/Projects": ["Lettuce.md", "Garden 2026.md", "Reading list.md"]
}

Names not in the list fall back to alphabetical at the end. Safe to edit by hand — Lettuce reloads on save.

Tip

Commit order.json to git so your sidebar order survives a clone-to-another-machine.

triggers.yml — file-creation automations

A YAML list of rules. Each rule is exactly {when, prompt}, where when is file:created:<glob> or file:changed:<glob> and prompt is the instruction. When a matching note is created (or, for file:changed, edited by a human), Lettuce splices a > [!ai] <prompt> directive into it — the connected agent does the actual work when it picks the directive up. See the full reference at Vault automation/01 Triggers. Quick taste:

- when: "file:created:Daily/*.md"
  prompt: "Summarize yesterday's note and link any new people mentioned."

schedules.yml — time-driven directives

A YAML list of rules. Each rule fires daily: "HH:MM" or weekly: "<Day> HH:MM" and, by default, splices a > [!ai] <prompt> directive into the target note (the agent does the work when it sees the directive via pending_directives). An optional action: runs a maintenance pass instead (e.g. lint-semantic or maintain). target accepts {{date}}, {{year}}, and {{week}} tokens. The SchedulePoller checks every 60s while lettuce serve (or the app) is running, and last-fired times are tracked in .lettuce/schedule-state.json so a rule never double-fires. See Vault automation/02 Schedules. Quick taste:

- daily: "07:00"
  target: "Daily/{{date}}.md"
  prompt: "Triage everything in Inbox/ created in the last 24 hours."

proposals/ — pending proposals

When an agent’s key is proposeOnly, its write tools don’t touch the vault directly — they write one JSON file per proposal here. The filename is the proposal’s lowercase UUID (<id>.json). A stored proposal is always pending; accepting or rejecting it deletes the file. Format:

{
  "id": "7f3c2a9e-1b2c-4d5e-8f90-a1b2c3d4e5f6",
  "agentLabel": "claude-desktop",
  "timestamp": "2026-05-28T09:12:34Z",
  "tool": "write_note",
  "argsJSON": "{...}",
  "preview": {
    "path": "Inbox/random thought.md",
    "before": "...",
    "after": "...",
    "operation": "modify"
  }
}

Proposals filed together (e.g. a multi-page ingest) share a batchId so you review them as one unit. Don’t edit these files by hand — use the proposals UI or Agent reference/06 Suggestion tools.

agent-edits.json — revertible edit timeline

Every write an agent makes through the API is recorded here as an AgentEdit (path, before/after content, agent label, timestamp, reviewed flag) so the Agent Edits inspector tab can show a diff and offer a one-click Revert. A move/rename also stores its source path and the inbound link rewrites it triggered, so reverting a move relocates the file back and undoes the relinks in one step. The log is capped at the most recent 200 edits and persists across restarts (it’s reloaded when the vault opens). Reverting restores the prior content directly and does not itself add a new edit.

Note

There is no per-call request log file. Agent writes are captured in agent-edits.json (above), and server-side errors print to the lettuce serve process’s stderr. To review activity as data, use the recent_activity MCP tool (which parses log.md) or the Agents sidebar.

Git-friendly

Most of .lettuce/ is worth committing (order.json, triggers.yml, schedules.yml). The machine-local / regenerable bits are better excluded:

.lettuce/schedule-state.json   # local last-fired state
.lettuce/vectors.json          # large; rebuilt by `lettuce embed`
.lettuce/passages.json