Lettuce Docs Tags Graph

AGENTS.md

#docs#agents#reference
~4 min read

AGENTS.md

AGENTS.md at your vault root is read by agents automatically on connection. It’s the single highest-leverage file in your vault for agent quality.

Why bother

Out of the box, an agent connecting to Lettuce has the tools but no vault context. It doesn’t know:

AGENTS.md is where you write that down. It’s surfaced on every agent session start (via get_vault_info, see below), so updating it propagates immediately.

The scaffold

lettuce agents init

This writes a curated starter AGENTS.md at your vault root, generated from the vault’s actual state (its top-level folders and most-used tags). Edit it freely — lettuce agents init refuses to overwrite an existing file unless you pass --force.

lettuce wiki init --agents writes the same tailored AGENTS.md as part of scaffolding an LLM wiki (alongside CLAUDE.md, index.md, and the rest).

The scaffold includes:

# Vault conventions

You're connected to a Lettuce vault. This file documents the conventions
the human expects you to follow.

## Folders

- `Inbox/` — raw captures. Triage daily. Move to a real home or archive.
- `Projects/` — active work. One note per project. Frontmatter:
  - `status: active | paused | shipped | archived`
  - `started: YYYY-MM-DD`
- `Daily/` — daily notes, one per date.
- `Archive/` — anything no longer relevant. Move, don't delete.
- `attachments/` — images and PDFs. Never link directly; embed.

## Tags

- `#project/<slug>` for projects.
- `#status/<state>` for status.
- `#area/<topic>` for life areas (work, garden, code, ...).
- Don't invent top-level tags without asking.

## Editing

- Prefer a propose-only token over a write token. Trust will grow. (A propose-only
  token's `apply_edits`/`write_note` calls become reviewable proposals automatically.)
- Don't rename notes silently — propose, never apply.

## Style

- Sentence-case headings ("My project", not "My Project").
- ISO dates (`2026-05-28`), never `5/28/26`.
- Bullets, not prose paragraphs, for lists.

## When to ask

- Before creating a top-level folder.
- Before deleting anything.
- Before touching files in `Sealed/` or `Personal/`.

This is opinionated. Replace any of it that doesn’t match how you work.

What agents do with it

On connection, agents call get_vault_info, whose response includes the vault’s agent brief. That brief is the vault-root AGENTS.md and the LLM-wiki maintainer guide (CLAUDE.md, written by lettuce wiki init) concatenated — so an agent sees both your vault etiquette and the wiki workflow in one read. If only one of the two files exists, only that one is surfaced. Agents inject the brief into their working context and proceed from there.

If you change AGENTS.md mid-session, well-behaved agents will re-read it (via another get_vault_info call); less-behaved ones won’t until the next session.

The brief is read from the vault root only — per-folder AGENTS.md files are not surfaced. Put folder-specific conventions in the root AGENTS.md under a heading for that folder.

Versioning

AGENTS.md is just a note. Commit it to git. Diff it like any other file. Reverting a bad convention change is git revert.

What to put in AGENTS.md

Good content:

Bad content: