Messages API

The Messages API manages archived markdown documents under the workspace-relative archives/ key prefix. Production frontend code uses getBackend().messages; the shipped cloud-primary adapter reads and writes the encrypted workspace model, not a local workspace directory.

Data Structures

MessageMeta

Returned by messages_list. Represents metadata for a single archived message.

interface MessageMeta {
  filename: string;         // e.g. "20250308-143045-hello.md"
  title: string;            // From frontmatter `title`, or filename stem
  heading: string | null;   // First H1/H2/H3 heading from body (parsed, not frontmatter)
  tags: string[];           // From frontmatter `tags` array, or []
  date: string | null;      // From frontmatter `date`, or extracted from filename
  createdAt: string | null; // From frontmatter `created_at`, or null
  updatedAt: string | null; // From frontmatter `updated_at`, or null
  sidebarPosition: number;  // From frontmatter `sidebar_position`, default 0
  modifiedAt: string;       // ISO 8601 timestamp (RFC 3339)
  body?: string;            // Markdown body (only when includeBody is true)
  snippet?: string;         // Truncated body (first ~100 chars, when includeBody is false)
}

The title field falls back to the filename stem (without .md) when frontmatter has no title key. The date field first checks frontmatter, then attempts to extract a date from the filename pattern YYYYMMDD-*.md (or the legacy YYYYMMDD-HHMMSS-*.md).

Local-engine compatibility operations

messages_list

List all archived messages.

const messages = await invoke<MessageMeta[]>('messages_list', {
  includeBody: false,
});

Returns: MessageMeta[] — sorted by updated_at descending (newest first), falling back to modified_at for files without updated_at frontmatter.

Behavior:

• Reads all .md files from <project_root>/archives/

• Excludes files starting with index (e.g., index.md)

• Parses YAML frontmatter for title, date, and sidebar_position

• Returns an empty array if the archives directory doesn't exist

messages_read

Read the full content of a single message file.

const content = await invoke<string | null>('messages_read', {
  filename: '20250308-143045-hello.md',
});

Returns: string | null — the file content, or null if the file doesn't exist.

Security: The filename is validated through safe_path() to prevent directory traversal. Paths like ../secret.md are rejected.

messages_write

Write content to an existing message file.

const success = await invoke<boolean>('messages_write', {
  filename: '20250308-143045-hello.md',
  content: '---\ntitle: Hello\n---\nUpdated body',
});

Returns: boolean — true on success, false on write failure or path traversal attempt.

messages_delete

Delete a message file.

await invoke<void>('messages_delete', {
  filename: '20250308-143045-hello.md',
});

Returns: Result<(), String> (resolves with no value on success). Throws on path traversal or unexpected filesystem errors.

messages_create

Create a new message with an auto-generated filename.

const filename = await invoke<string>('messages_create', {
  name: 'Weekly report',
  content: '---\ntitle: Weekly report\n---\nDraft content here',
});
// filename: "20250308-143045-weekly-report.md"

Returns: Result<string, string> — the generated filename on success.

Filename generation: The name is slugified (lowercased, non-alphanumeric chars replaced with hyphens, consecutive hyphens collapsed) and prefixed with a date stamp: YYYYMMDD-slug.md. Non-ASCII names (e.g., Japanese) produce YYYYMMDD-untitled.md.

Behavior: Creates the archives/ directory if it doesn't exist.

messages_list_light

List archived messages with filename and frontmatter metadata only (no body or snippet). Faster than messages_list for large archives because it skips body parsing entirely.

const messages = await invoke<MessageMeta[]>('messages_list_light');

No parameters.

Returns: MessageMeta[] — same shape as messages_list, but body and snippet are always absent.

Use case: Populates the message list panel on startup, where only titles and dates are needed.

messages_create_in_dir

Create a new message in a specific subdirectory within the archives (or any directory under the workspace root).

const filename = await invoke<string>('messages_create_in_dir', {
  relDir: 'archives/2025',
  name: 'Quarterly review',
  content: '---\ntitle: Quarterly review\n---\nContent here',
});
// filename: "20250308-quarterly-review.md"

Returns: Result<string, string> — the generated filename on success.

Behavior: Creates the target directory if it doesn't exist. Filename generation follows the same YYYYMMDD-slug.md pattern as messages_create.

messages_rename (historical)

This retired call shape records how the old local command renamed a message within the archives directory. It is not exposed by the current BackendAPI or the local HTTP fallback.

const newName = await invoke<string>('messages_rename', {
  oldFilename: '20250308-143045-hello.md',
  newFilename: '20250308-143045-updated-hello.md',
});

Returns: Result<string, string> — the new filename on success, error message on failure.

Security: Both filenames are validated through safe_path(). Returns error if the source file doesn't exist or the target file already exists.

Change notifications

Production callers subscribe through backend.messages.onChanged(callback). Cloud adapters derive that notification from committed workspace changes.

messages:changed (local-engine compatibility)

The pnpm dev:rest fallback emits this SSE event when a local markdown file in archives/ is created or modified. It is not a Tauri event consumed by the cloud-primary renderer. See the File Watchers page for details on the retained watcher implementation.

const unsubscribe = backend.messages.onChanged((filename) => {
  console.log("Changed:", filename);
});

unsubscribe();

The local SSE payload is: