Melian
Core Systems / The Woven Thread

The Woven Thread

From ink on paper to threads in the loom, handwritten thoughts find their way into the weave.

Overview

Melian bridges the physical and digital worlds through her task system. Handwritten notes on a Remarkable tablet are scanned via OCR, parsed into structured tasks, and synced to an Obsidian vault. Follow-up jobs ensure nothing falls through the cracks.

Tasks are addressed by line number (the 1-based position of a task in the markdown file is its stable ID). All tool calls and API endpoints use line numbers to reference specific tasks.

Task Interface

export interface Task {
  line: number;              // 1-based line number, stable ID
  text: string;
  completed: boolean;
  created: string | null;    // ISO date
  due: string | null;
  completedDate: string | null;
  tags: string[];
}

export type TaskFilter = "all" | "pending" | "completed" | "overdue" | "backlog";

Tasks are stored in standard Obsidian markdown checkbox format with optional metadata:

- [ ] Review the API design doc 📅 2026-04-18 #work
- [ ] Send feedback to the team ➕ 2026-04-17
- [x] Update the deployment script ✅ 2026-04-16

The Pipeline

The Remarkable pipeline moves handwriting into structured tasks in five steps:

  1. Remarkable Tablet: you write tasks by hand on the tablet
  2. OCR: Google Cloud Vision extracts text from the handwriting image
  3. Parsing: Melian structures the raw OCR output into Task objects, inferring due dates and tags from natural-language phrases
  4. Obsidian Sync: tasks are written to your Obsidian vault as markdown checkboxes in the standard format
  5. Follow-up Scheduling: tasks with due dates get a reminder job created automatically; Melian handles the scheduling without further input

The sync is bidirectional. Tasks completed or modified in Obsidian are reflected in Melian's task view on the next read.

Tools

Tool Parameter Type Required Description
tasks_list filter "all" | "pending" | "completed" | "overdue" | "backlog" no (defaults to "pending") Return tasks matching the filter
tasks_add text string yes Task description
due string no ISO date (YYYY-MM-DD)
tags string[] no Tags to attach
tasks_complete line number yes Mark a task complete by line number
tasks_search query string yes Search task text
tasks_backlog line number yes Move a task to the backlog
tasks_unbacklog line number yes Restore a task from the backlog

API

Method Path Description
GET /tasks/today Categorized view: overdue, due today, upcoming
GET /tasks/list?filter=<filter> List tasks with a TaskFilter
POST /tasks/:line/complete Mark task at line as complete
POST /tasks/:line/backlog Move task at line to backlog
POST /tasks/:line/unbacklog Restore task at line from backlog

Obsidian Integration

Melian reads and writes the vault markdown file directly, with no plugin required. The file is read fresh on each tool call so edits made in Obsidian are immediately visible. Writes append to the file or perform line-targeted replacements using the 1-based line number as the address.

The backlog state is represented by the #backlog tag, keeping the file valid markdown that renders correctly in Obsidian while preserving the semantic state Melian needs.