core/docs/ICD/notes.md

Notes

Obsidian-style knowledge graph with [[wikilinks]], backlinks, graph visualization, and folder organization. Notes are user-scoped (personal notebook). Future: channel-scoped notes for workflow artifacts.

CRUD

GET    /notes                       → paginated list of noteListItem
POST   /notes                       ← { "title", "content", "folder" }
GET    /notes/:id                   → full note object
PUT    /notes/:id                   ← { "title", "content", "folder" }
DELETE /notes/:id

Note object:

{
  "id": "uuid",
  "user_id": "uuid",
  "title": "Meeting Notes",
  "content": "# Meeting Notes\n\nDiscussed [[Project Alpha]]...",
  "folder": "work",
  "source_message_id": "uuid|null",
  "created_at": "...",
  "updated_at": "..."
}

source_message_id links a note back to the chat message that created it (provenance for AI-generated notes).

noteListItem is the same but with content truncated or omitted.

Search

Full-text search:

GET /notes/search?q=project+alpha

Uses plainto_tsquery (Postgres) or LIKE fallback (SQLite). Returns { "data": [searchResult objects] } with match highlights.

Title search (lightweight, for wikilink autocomplete):

GET /notes/search-titles?q=proj

Returns { "data": [{ "id", "title" }] }.

Graph

Full graph topology:

GET /notes/graph

{
  "nodes": [{ "id": "uuid", "title": "Note Title" }],
  "edges": [{ "source": "uuid", "target": "uuid" }],
  "unresolved": [{ "source": "uuid", "target_title": "Missing Note" }]
}

Edges are directed: source contains [[target_title]]. Unresolved edges have a target_title but no matching note (dangling wikilink). When a note with that title is created, the edge auto-resolves.

Backlinks (who links to this note):

GET /notes/:id/backlinks

Returns { "data": [note objects] } — all notes containing [[this note's title]].

Folders

GET /notes/folders

Returns { "folders": ["work", "personal", "archive"] } — distinct folder values across all user notes.

Bulk Operations

POST /notes/bulk-delete

{ "ids": ["uuid-1", "uuid-2"] }

---