Writer Protocol

Change kinds

upsert — full content replacement. Creates the note if it doesn't exist; overwrites it if it does. expectedHash controls concurrency (see below).

patch — exact-string find/replace within the note's current content. The server reads the in-memory content, calls strings.Index(content, find), substitutes one occurrence, and saves. Rules:

• find must appear exactly once; zero occurrences → UpdateNotesPatchNotFoundPayload; two or more occurrences → UpdateNotesPatchNotFoundPayload (the find field echoes the ambiguous string back to the caller)
• The note must already exist; patching a non-existent path → ErrorPayload { message: "note not found: {path}" }
• find == replace after substitution → InsertNote detects identical content and skips creating a new version (idempotent)
• replace may be empty string (deletes the found substring)
• find is a literal string, not a regular expression

hide — soft-deletes the path (sets hidden_at / hidden_by). Does NOT trigger webhooks from updateNotes (see code comment in internal/case/updatenotes/resolve.go); use the standalone hideNotes mutation when webhook notification is required.

Three upsert modes

Hash algorithm: SHA-256 of the note's raw byte content, encoded as base64url with padding.

Go (server, internal/case/updatenotes/resolve.go and internal/case/insertnote/resolve.go):

base64.URLEncoding.EncodeToString(sha256.Sum256([]byte(content)))

JavaScript (client, templates/kanban/src/api.ts):

const buf = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(content))
const hash = btoa(String.fromCharCode(...new Uint8Array(buf)))
  .replace(/\+/g, '-')
  .replace(/\//g, '_')
// btoa produces standard base64 with '=' padding; the replacements yield base64url
// This is identical to Go's base64.URLEncoding (which also keeps '=' padding)

Obsidian sync plugin (trip2g_obsidian_plugin/main.ts)

Calls pushNotes with all changed notes (no skipCommit), then calls hideNotes for paths that exist on the server but were deleted locally. Does not use updateNotes. Auth: X-API-Key header, URL {apiUrl}/graphql.

memcli (cli/memcli)

The up command runs trip2g-sync --watch as a background process, which drives the same Obsidian sync plugin code path (pushNotes). The daily and log subcommands write Markdown files directly to the vault folder on disk; the watcher picks up the changes and syncs via pushNotes.

Kanban board (templates/kanban/src/api.ts)

Uses updateNotes exclusively — upsert for card creation and full-board saves, patch for in-place card edits (title, status changes). Auth: admin session cookie (credentials: 'include'). Endpoint: /_system/graphql. Implements the full rebase-on-HashMismatch loop.

Web editor (assets/ui/editor/pane/pane.view.ts)

Uses updateNotes upsert with expectedHash: "" for the "create new file" flow as the server-side race guard against creating over an existing note. A client-side path-existence check provides the fast UX pre-reject; the empty-hash sentinel is the authoritative server guarantee behind it.

AI agents (via change webhooks)

When a change webhook fires with pass_api_key: true, the delivery payload includes api_token (a shortapitoken JWT with scoped read_patterns / write_patterns). Agents can use this token to call updateNotes or pushNotes directly for programmatic writes.

Agents that return changes synchronously in their HTTP response body use the webhook agent response format (internal/webhookutil/agentresponse.go). This is a separate code path from the GraphQL mutations: the server parses changes and calls InsertNote directly. The current format supports only full content replacement:

{
  "status": "ok",
  "message": "Linted 3 files",
  "changes": [
    {
      "path": "blog/post.md",
      "content": "# Fixed post\n\nCorrected content.",
      "expected_hash": "base64url-sha256-of-previous-content"
    }
  ]
}

This response format does not yet support patch or hide operations. For those, agents should use the shortapitoken to call updateNotes directly via /_system/graphql.

Create a note (fail if it already exists)

mutation CreateNote($i: UpdateNotesInput!) {
  updateNotes(input: $i) {
    __typename
    ... on UpdateNotesSuccessPayload { paths }
    ... on UpdateNotesHashMismatchPayload { path actualHash }
    ... on ErrorPayload { message }
  }
}

{
  "i": {
    "changes": [{
      "upsert": {
        "path": "inbox/new-idea.md",
        "content": "---\nfree: true\n---\n\n# New Idea\n\nContent here.",
        "expectedHash": ""
      }
    }]
  }
}

Returns HashMismatchPayload (with actualHash set to the real hash) if the note already exists.

Edit one line (patch)

{
  "i": {
    "changes": [{
      "patch": {
        "path": "todo/sprint.md",
        "find": "- [ ] Deploy v2.0",
        "replace": "- [x] Deploy v2.0"
      }
    }]
  }
}

Anchor-marker append (sequential inserts via sentinel)

Keep a $INBOX$ sentinel in the note. Each insert prepends the new entry above the sentinel and re-places the sentinel so the next call finds it:

{
  "i": {
    "changes": [{
      "patch": {
        "path": "inbox.md",
        "find": "$INBOX$",
        "replace": "## 2026-06-28 09:15\nNew thought.\n\n$INBOX$"
      }
    }]
  }
}

Successive patches accumulate above the sentinel, which stays in place as the insertion point.

Bulk sync (Obsidian plugin path)

{
  "input": {
    "updates": [
      { "path": "notes/a.md", "content": "..." },
      { "path": "notes/b.md", "content": "..." }
    ]
  }
}

Omit skipCommit (or set false) to fire webhooks immediately. Use skipCommit: true + a subsequent commitNotes call to batch the entire vault load as a single atomic publish.

Rebase on HashMismatch

let result = await updateNotes([patchChange(path, find, replace, expectedHash)])
if ('hashMismatch' in result) {
  const fetched = await fetchNoteContent(path)         // re-read from server
  const newContent = applyEdit(fetched.content, ...)   // rebase the edit
  const newHash = await sha256Base64(fetched.content)
  result = await updateNotes([upsertChange(path, newContent, newHash)])
}

The kanban template's updateNotes function in templates/kanban/src/api.ts implements exactly this pattern.

Delete (hide)

mutation HideNotes($input: HideNotesInput!) {
  hideNotes(input: $input) {
    ... on HideNotesPayload { success }
    ... on ErrorPayload { message }
  }
}

{ "input": { "paths": ["drafts/abandoned.md"] } }

Use hideNotes (not updateNotes hide) when you need webhooks to fire on removal.