Vault guide for agents

Loofah (loofah) is a local-first knowledge and note-taking app that began with meeting transcription. Its vault can hold recorded meetings, standalone notes, imported material, and work an agent creates from other authorized sources. The vault is a plain folder of Markdown and JSON files and the only source of truth — there is no database or cloud copy. A copy of this page is kept at the vault root as AGENTS.md. Full, current documentation lives at https://loofah.io/ — machine-readable indexes at https://loofah.io/llms.txt and https://loofah.io/llms-full.txt.

Vault structure

<vault>/
  AGENTS.md              this file (auto-regenerated)
  config.json            app configuration
  settings.json          app settings
  tags.json  tasks.json  people.json  events.json  calendars.json
  templates/  humans/  organizations/
  .trash/                soft-deleted files, kept by date; recoverable
  sessions/<id>/         one session per directory; may be a meeting or standalone note
    _meta.json           identity + metadata; its presence marks a session
    notes.md             the user's note (legacy vaults: _memo.md)
    transcript.json      speaker-labeled transcript
    tasks.json           session tasks
    audio.mp3|wav|ogg    the recording, with audio.peaks.json waveform cache
    enhanced/<uuid>.md   AI-generated documents (summaries)
    attachments/         files embedded in the note

Ownership rules:

Inside a session directory the app owns exactly the names above. Any other file is a user attachment: leave it alone, and never claim unknown files as app content.
Dot-prefixed files (.tmp-*, .DS_Store, .trash/) are never content.
Do not create or rename files under the app-owned names; use the CLI to write.

Authorship

_meta.json may carry an optional author field. When it is absent the note was written by the vault owner; when set (a free-form name such as claude-code) the note was written by someone else, and the app marks it as not written by the owner. Next to author, an optional skill field records the skill (a named, reusable instruction set such as meeting-summarizer) the author ran to produce the note, if any.

Rules for agents:

Always pass --author <your-agent-name> when creating a session with loofah sessions new or loofah import. Pick one stable name (for example claude-code) and keep using it.
If a skill produced the note, also pass --skill <skill-name> so the session records which skill was used. Use the skill’s stable name; omit the flag when no skill was involved.
Write your own notes as new sessions with --author set. When asked to edit an existing note, never add, change, or remove its author or skill — editing the owner’s note does not make it yours.

Reading session data

Use Loofah’s typed, read-only interfaces for session data. Do not use find, grep, rg, filesystem crawling, or direct SQLite queries to find or read sessions.

Prefer the loofah MCP tools when they are available:

list_meetings to resolve a session ID
get_meeting for notes, summaries, and action items
get_meeting_transcript for the full speaker-labeled transcript

The MCP tool names retain meeting for compatibility even when the session is a standalone note.

If MCP is unavailable, use the loofah CLI with --json:

(meetings is a compatibility alias for sessions while deprecation is phased in.)

loofah --json sessions list --query "planning"
loofah --json sessions get SESSION_ID
loofah --json sessions transcript SESSION_ID

The CLI discovers Loofah’s vault from the platform application-data directory, following the vault_path redirect in its global.json when the vault has been relocated. Use --vault-path ABSOLUTE_VAULT_DIR only when the user explicitly provides a non-default vault path; do not crawl the filesystem to find one. Never guess a session ID. Fetch a transcript only when notes and summaries do not contain the needed context.

The loofah CLI

Run loofah doctor first to verify the CLI can reach the vault (it also repairs a missing or stale AGENTS.md). Always pass --json for machine-readable output.

Command	Purpose
`doctor`	Check CLI and vault access without changing data.
`sessions list`	List sessions, optionally filtered with `--query`.
`sessions search`	Full-text search across titles, notes, summaries, and transcripts.
`sessions get`	Metadata, note, summaries, and action items for one session.
`sessions new`	Create a standalone note and print its id; pass `--author` when writing as an agent, plus `--skill` when a skill produced the note.
`sessions note`	Show a session’s note, or edit it with `--set` / `--append`.
`sessions transcript`	The full speaker-labeled transcript.
`sessions tag add`	Add tags to a session, registering new ones in the vault.
`sessions tag remove`	Remove tags from a session.
`sessions path`	Print the absolute path of a session directory.
`sessions attach`	Store a file as a note attachment and print its id.
`sessions export`	Export a session to Markdown or JSON.
`import`	Import an audio file as a new session or into an existing one.
`transcribe`	Transcribe a session’s audio with the configured on-device model.
`mcp`	Run the read-only MCP server over stdio.
`tags list`	List every tag registered in the vault.

Per-command flags are documented at https://loofah.io/reference/cli/.