Omniscio

KMS note summaries (AI auto-summary + drift lifecycle)

A one-paragraph AI précis stored inside each note's own file, wrapped in a comment block so any Markdown editor round-trips it untouched. Omniscio notices when a note has drifted away from its summary, shows that state on the note itself, and can quietly refresh stale summaries on a timer.

On this page

What it is

Omniscio can generate a short AI summary for any note in a KMS vault, store it inside the note file itself as an HTML-comment marker block, detect when the note has drifted away from its summary, and (opt-in) quietly regenerate stale summaries on a timer. The full slice is live: Settings controls, the background drift detection, the opt-in periodic worker, the four IPC operations, and the per-note in-editor chip + right-click menu that surfaces the lifecycle to the user.

A note summary is a one-paragraph, ≤300-character plain-text précis of a note's content, written by a small, low-cost AI model. It is not stored in a database column or a sidecar file — it is embedded directly at the top of the note's own Markdown body, wrapped in a pair of HTML comments so it round-trips cleanly through any Markdown editor (Omniscio's editor, Obsidian, VS Code, plain Notepad) without the editor mangling it or the user tripping over it.

The point of the feature is that a vault of hundreds of notes becomes skimmable: every note carries a current one-liner of what it's about, and Omniscio keeps those one-liners honest — when you meaningfully edit a note, its summary is flagged "stale", and (if you opt in) a background worker rewrites it within minutes. If you hand-write your own summary into the marker, Omniscio notices and locks it so the AI never overwrites your words.

Everything here is gated by the master nothariEnabled setting (Settings → Features → Enable Vault) — with one exception worth knowing. With the Vault off, no drift is tracked, none of the IPC operations do anything, and the chip is gone, but the automatic background refresh has its own switch and keeps running while the Vault is off: if you turned on Auto-regenerate stale summaries, the timer keeps finding stale notes, keeps making paid AI calls, and keeps rewriting summary blocks into note files until you switch that toggle off too. Turn both off to stop all summary spending. The AI-spend portion is additionally gated: summary generation only happens when the user has opted into the periodic worker, clicks the in-editor chip's Regenerate now action, or runs the bulk-seed (a separate sub-PR), and every call is metered against a daily dollar cap.

Where to find it

User-visible surface (the summary chip)

When a note has a summary marker, the KMS status bar at the bottom of the editor pane carries a small chip on its left edge that reflects the current lifecycle state at a glance. A note with no marker (none) gets a muted Regenerate now chip, so the first summary can be generated from the note itself rather than only from the whole-vault bulk seed in Settings. Hovering the chip surfaces a one-line tooltip explaining the state (e.g. "Summary up to date", "Drift 42% · Regen pending", "Locked — you edited this summary"); see the table above for the per-state mapping.

The chip's status bar slot was chosen because no tag chip row exists in the editor today (verified 2026-05-19 — TagChip grep under features/kms/ returns zero matches). When a tag row lands above the status bar in a later sub-PR, the chip moves up to sit next to the tags.

Single-click behavior depends on the current state:

  • stale — the most common action. A click invokes kms:generate-summary { force: false } and the chip flips to the optimistic generating state until the next push lands; if the call fails the chip re-fetches the real state and a toast surfaces the reason (cost cap, rate limit, missing API-key account, etc.).
  • current / user_edited / cost_capped — a click opens the chip menu rather than firing any destructive default. There is no "single-click force regenerate" path because forcing always crosses a confirm dialog.
  • generating — a click is a no-op (an IPC is already in flight; a second one would either duplicate spend or be rejected by the per-account mutex).

Right-click always opens the chip menu, in every state, so the menu items are reachable even when the chip isn't actionable on a left click.

The chip menu lists, in order:

  1. Regenerate now — kms:generate-summary { force: false, bypassHashSkip: true }. The bypass is what makes the item act on the current chip it is normally opened from: without it the matching marker hash short-circuits to the cached summary and no model call is made. It leaves the lock alone. Disabled when the chip is generating. On a locked note (user_edited) this returns user-edited-locked and the toast surfaces a hint pointing the user at the Force regenerate item below.
  2. Force regenerate (override lock) — only shown when the chip is user_edited. Confirms first ("Forced regen will overwrite your hand-edited summary. Continue?"), then invokes kms:generate-summary { force: true }. This is the only single action that crosses the lock; the explicit confirm is the human-intent gate that the backend's force:true flag stands in for at the contract level.
  3. Mark / Unmark as user-edited — toggles kms:set-summary-user-edited. The label flips on the current state. No confirm — the action is reversible.
  4. Clear summary marker — destructive (red label). Confirms first, then invokes kms:clear-summary, which strips the marker from the note body and resets the lifecycle columns; the next push reports state: 'none' and the chip drops back to its Regenerate now form, matching the confirmation's "You can regenerate later" promise.

All chip actions reconcile via the same kms:summary-updated push the IPC handlers emit. The renderer ignores pushes whose noteId doesn't match the active note, so a burst of pushes during a bulk-seed run (a separate sub-PR) cannot stomp the active chip's state. The optimistic generating value is always replaced by whatever the next push reports — there is no path where the chip stays stuck in "generating" once the backend has resolved the call.

How it behaves

What the marker block looks like

A summarised note's body begins with exactly this shape:

<!-- kms:summary v=1 hash=3f9a…<64 hex chars total>…b1 -->
A one-paragraph paraphrase of the note, 300 characters or fewer, no line breaks, no Markdown, no "Summary:" prefix.
<!-- /kms:summary -->

# The rest of the note's real content starts here…

Anatomy:

  • v=1 — marker format version. The current writer only ever emits v=1. If Omniscio reads a marker with a different version number (a note touched by a newer app build), it treats the note as locked (user_edited) and refuses to regenerate or overwrite it — a forward-compatibility fence so an older build can't clobber a newer format. An explicit "Clear summary" is the only thing that removes a v≠1 marker.
  • hash=<64 hex> — a SHA-256 "canonical hash" of the note's body with the marker block stripped out. This is the drift fingerprint (see below). It is not a hash of the raw bytes — the body is first canonicalised: CRLF→LF, runs of spaces/tabs collapsed, trailing whitespace trimmed, 3+ blank lines collapsed to 2, and every image (![alt](url)) replaced by a token derived from the URL only. The effect: reformatting, re-wrapping, or editing image alt-text does not count as drift; changing actual prose or swapping an image URL does.
  • The middle line — the AI summary itself. Always one paragraph, ≤300 characters, paraphrased (never quotes the body), no headings/lists/Markdown, no leading/trailing whitespace, no "Summary:" / "This note is about" preamble. An empty or unintelligible note yields a single descriptive word (e.g. Empty.).
  • The marker sits at the very top; the user's original content follows after one blank line. Stripping the marker (the "Clear" action) removes the block and that separator newline, leaving the original body untouched.

Because the summary lives in the file, it travels with the note: sync the vault folder to another machine or open it in another editor and the summary is just there, as a comment, invisible in rendered Markdown.

Drift lifecycle — the four states

Every note row carries four bookkeeping columns (added by migration v200 on the nothari_notes table): summary_hash, summary_generated_at, summary_drift_state, and summary_user_edited. Together they resolve to one of four user-facing states (plus two transient ones the status probe can report):

State Meaning Chip cue
none No marker in the note, or the note was never summarised. Muted dot, label "Regenerate now", tooltip "Rebuild this note's AI summary now."
current A marker is present and the note's canonical hash still matches the hash stored in the marker — the summary is up to date. Green dot, label "Up to date", tooltip "Summary up to date".
stale The note's content has changed since the summary was written (canonical hash no longer matches). The summary is now out of date. Amber pulsing dot, label "Stale", tooltip "Drift N% · Regen pending" (or just "Regen pending" when no percent is available).
user_edited The summary is locked. Either the user hand-edited the text inside the marker, or explicitly marked the note user-edited, or the marker is a future format version. Omniscio will never auto-overwrite it. Muted grey dot, label "Locked", tooltip "Locked — you edited this summary".
generating (transient) A regeneration is in flight. Inline spinner, label "Generating", tooltip "Generating…". Renderer-side optimistic — cleared by the next kms:summary-updated push.
cost_capped (saved) The daily AI budget for this account is exhausted, so a wanted regeneration was refused. Saved on the note, so it survives closing and reopening it; it clears on the next successful summary, or flips to stale as soon as the note's content changes. Red dot, label "Budget reached", tooltip "Daily AI budget reached. Raise in Settings → Optional Features."

How a note moves between states:

  • → current: a successful generate writes a fresh marker, stores the new hash, stamps summary_generated_at, and clears the lock.
  • current → stale: handled automatically on save. When the editor writes a note body whose canonical hash diverges from the stored summary_hash (and the note isn't locked), Omniscio flips it to stale. This is idempotent — an already-stale note doesn't re-flip on subsequent saves — and the summary service's own writes are exempt (they pass an internal suppressSummaryDriftDetection flag) so a regeneration doesn't trip drift on itself.
  • anything → user_edited (locked): also automatic on save — if the text inside the marker block changes, Omniscio reads that as "the human is curating this summary themselves" and locks it. If both a body edit and a marker edit land in one save, the marker-edit wins (lock takes precedence over stale). The lock can also be set explicitly (see "Manual control" below).
  • user_edited → current/stale (unlock): explicitly unlocking recomputes the state — it compares the live canonical hash against the stored summary_hash and lands on current if they match, stale if they don't (no stored hash → current).

The lock is enforced in one place — the summary service's generate call — so every path that can write a summary (the chip's Regenerate, the CLI generate action, and the bulk seed) refuses to touch a locked note. The chip and the CLI report user-edited/user-edited-locked; a bulk run quietly skips the note and carries on with the rest of the vault. Only an explicit Force regenerate (force: true) crosses the lock. The background regen worker also skips locked notes before it ever calls the service.

Phase-6 drift is binary. Omniscio stores only the canonical hash alongside the marker, not the original canonical text, so it can answer "did this change?" (hash compare) but not "by how much?". The driftPercent carried by some internal types is therefore 0 or 1 today, and the status probe deliberately omits it rather than fabricating a precise-looking number. A later sub-PR can persist the canonical text to make drift a continuous percentage.

Automatic background behavior (the live user surface today)

Two things happen without any per-note UI:

  1. Drift detection on save — always on (when KMS is enabled). Editing a note's content silently flips its summary to stale; editing the summary text itself silently locks it. No spend, no network — this is just hash bookkeeping.

  2. Periodic auto-regeneration — opt-in, off by default. A background worker wakes on a timer, finds notes that are stale and not locked and outside their per-note cooldown, and regenerates their summaries (which costs AI spend). It only ever touches notes in the currently configured vault, and it stops the moment the Vault itself is switched off — a folder you switched away from is never sent to the model, and nothing is written back into it. It is controlled entirely from Settings → Features:

    • Auto-regenerate stale summaries (kms-auto-regen-enabled) — the master switch for the worker. Default off: until you turn it on you pay nothing and the timer never even queries the database.
    • Scan interval (kms-auto-regen-interval) — how often the worker wakes, in minutes. Default 5 minutes. Range 1 minute – 24 hours.
    • Per-note cooldown (kms-auto-regen-cooldown) — minimum time between two regenerations of the same note, in minutes. Default 15 minutes. Range 1 minute – 24 hours. This stops a note that keeps drifting from being rewritten every single scan.

    (Internally these are stored as milliseconds — nothariAutoRegenIntervalMs / nothariAutoRegenPerNoteCooldownMs, defaults 300 000 / 900 000, Zod-bounded [60 000, 86 400 000]. The minutes ↔ ms conversion is the UI's job; the two minute inputs are disabled until the toggle is on.)

    Worker behavior you can't tune (deliberately not knobs): at most 2 regenerations run concurrently (a higher number raises the parallel provider request burst — the per-account check-plus-reservation still holds the daily cap, but each extra lane is another simultaneous call to the model; lower would crawl after a bulk import), and at most 50 stale notes are picked up per scan (a huge backlog is chipped away one scan at a time rather than pinning the app). The first scan is deferred one full interval after app launch so a boot-time backlog doesn't fire during startup. The worker only ever reads drift state and asks the summary service to regenerate — it never writes the drift columns itself, keeping the producer (save-time detection) and consumer (worker) cleanly separated.

Manual control (IPC surface)

Four IPC operations back the chip and any other consumer (CLI, mobile when it lands). Documented here so the contract is unambiguous independent of the chip's rendering.

Channel (string) Input Result
kms:generate-summary { noteId, force?, bypassHashSkip? } { ok:true, hash, summary, costUsd } · or { ok:false, error: 'cost-cap-hit' | 'rate-limit' | 'no-apikey-account' | 'not-found' | 'user-edited-locked' }
kms:get-summary-status { noteId } { state: 'none'|'current'|'stale'|'user_edited'|'generating'|'cost_capped', lastGeneratedAt? }
kms:clear-summary { noteId } { ok:true } · or { ok:false, error:'not-found' }
kms:set-summary-user-edited { noteId, flagged } { ok:true } · or { ok:false, error:'not-found' }

Behavioral contract:

  • Generate with force: false (the polite path) regenerates only if needed and respects the lock — calling it on a locked note returns user-edited-locked and does nothing. bypassHashSkip: true is the second, narrower switch: it skips only the "already current" short-circuit, so an up-to-date note is rebuilt, and it still respects the lock (a locked note comes back user-edited-locked). It is what the chip's Regenerate now sends. With force: true (a deliberate human "force regenerate this now" from the chip) it bypasses both the "already current" short-circuit and the lock: a forced regen on a locked note is read as explicit intent to replace the user's own text, so it overwrites and clears the lock. A missing note always returns not-found, never user-edited-locked.
  • Generate is single-flight per note AND per operation. Concurrent calls for one note with the same (force, bypassHashSkip) pair await the first call instead of firing a second billed model call; the pair is part of the coalescing key precisely because a polite generation, a hash-skipping one and a forced one are three different operations. Merging them would hand a Regenerate now the polite call's cached short-circuit — a silent no-op, the very symptom bypassHashSkip exists to remove. The key is cleared on settle, so a failed generate never poisons a retry.
  • Get-status is the chip's paint-on-mount probe. It is the only operation that can report cost_capped, because that fact lives in the drift columns the periodic worker keys off — reading the same source guarantees the chip and the worker agree on a note's state. Because the value is a saved column rather than a momentary answer, it survives closing and reopening the note, and clears on the next successful summary. It is not sticky beyond that: save an edit to the note's content and save-time drift detection replaces it with stale, without waiting for a summary.
  • Clear strips the marker block from the note body (any version, including a future v≠1 marker — Clear is explicit user intent so the forward-compat fence doesn't apply) and resets the four columns to pristine. It is non-destructive to the rest of the note. It always reports success if the note exists, because the user-visible promise ("the summary is gone from my note") is kept even if the secondary column reset hiccups.
  • Set-user-edited toggles the lock. flagged: true locks (user_edited); flagged: false unlocks and recomputes current/stale from the hash. Unlike Generate's best-effort column writeback, this is the user's explicit intent, so a failure surfaces as an error envelope rather than a false success.

Every state change — generate, clear, lock/unlock — emits a kms:summary-updated push ({ noteId, state, hash?, driftPercent? }). The chip and the Settings spend display reconcile on it; the push is forwarded to mobile/web inbox clients too (wired now to avoid a second plumbing edit when the mobile note UI lands). The IPC handlers themselves never emit the push — the summary service does, so each change fires exactly once.

Vocabulary note for implementers. The service layer speaks note-not-found / user-edited; the IPC contract speaks not-found / user-edited-locked. The rename happens only at the handler boundary so the two vocabularies never leak into each other (the periodic worker and other non-IPC callers keep the stable service words).

Summarize the whole vault (bulk seed)

One note at a time is fine for a few notes; the Vault bulk-seed card does the whole vault in one run. It lives at Settings → Features → The Vault → Vault bulk-seed (with advanced features shown).

  • Per-run cost cap — how much the run may spend, in dollars. Default $5, adjustable from $1 to $50.
  • Start bulk-seed — writes a summary for every note in the configured vault that has no up-to-date one. Notes you have locked as user-edited are skipped, not overwritten.
  • Cancel — stops the run at the next note boundary; it is not an instant abort.
  • Progress and Spend show on the card: 12 of 240 notes done, and dollars spent against the cap.

The run also stops when the shared daily Vault AI budget (default $2.00 — the same pot per-note summaries draw on) is reached, or when the per-run cap is. The card names the limit that stopped it: Stopped: this run reached its own cost cap when the per-run cap did, and Stopped: today's summary spending limit was reached when the daily budget did (a run recorded before the app tracked which cap fired keeps the plain Stopped: cost cap hit). Pressing Cancel shows Stopped: cancelled.

A run does not survive a restart. The next launch marks an interrupted run cancelled, and starting again skips the notes already done, so a second run costs only the remainder. Starting a bulk seed needs no Anthropic API-key account; if nothing can pay for the first summary, the run stops and the card says Stopped: no AI account could make summaries.

Cost cap behavior

Summary generation calls a paid AI model, so it is metered:

  • Per-account, per-day dollar cap. Default $2.00, configurable (nothariSummaryCostCapUsd, range $0.50–$50.00, in the same Settings → Features area). The "day" boundary is local midnight, matching Omniscio's other daily caps so they don't disagree across the UTC line.
  • The cap counts three spending sources against the one budget: ordinary per-note summary spend, bulk-seed spend, and the Vault editor's own AI (cost-log sources haiku-nothari-summary + haiku-nothari-bulk + kms-editor-ai), so no path can hide spend from another — and a busy stretch in the Vault editor uses up the day's summary budget too, until it rolls over at local midnight.
  • A bulk-seed run ALSO has its own per-run cap (nothariBulkSeedCostCapUsd, default $5). It does not replace the daily cap: both apply, and the run stops at whichever is reached first. Either cap stops the run with the same terminal reason, cost-cap-hit, and the terminal progress push and the status read also carry stoppedBy — per-run-cap when the run reached its own cap, daily-cap when the daily limit is what bound it — so the bulk-seed card can name the limit that actually fired. That distinction is what the person reading it needs: raising the per-run cap changes nothing when the daily limit is what tripped. A run recorded before stoppedBy existed has none, and the card keeps the plain "cost cap hit" label rather than guessing which cap it was.
  • The Settings spend readout covers the same three sources, and every one resolves the spent-against account the same way (resolveKmsAiAccountId in the ledger), so the cap gate and the readout can never disagree.
  • The check is pre-flight and strict (spent >= cap blocks) and runs inside a per-account lock that also takes an in-memory worst-case reservation (the call's projected input cost plus its output-token ceiling). The lock covers only the check and the reservation — the model call, the cost-ledger write and the marker writeback all run outside it, so two generations for the same account actually overlap on the network instead of queueing behind one another. Two generations for the SAME note still queue, on a per-note lock that wraps the whole generation: the second re-reads the note once the first has written, finds the fresh summary and answers from it at no cost instead of paying for a second call on an unchanged body. Concurrency is therefore real, and the reservation is what keeps the cap honest: a burst of concurrent generations can't all pass the check before any has recorded its cost, because each in-flight call holds its worst-case cost in the gate — call N sees the committed spend of calls 1…N-1 plus the reservation of any still running. The reservation is released in a finally the moment the call records its real cost (and on a thrown call), so it never lingers past the round-trip.
  • It fails open for a bounded window: if the spend query errors (transient DB issue), the call is allowed rather than the feature being silently starved — over-charging during a brief blip is preferred to a confusing dead feature, and the post-call ledger insert remains the source of truth. The concession is 60 seconds per account, opened by the first unreadable check and never re-opened by failure: if the ledger stays unreadable past that window the gate closes and the call is refused, so a permanently broken spend query can no longer leave the cap switched off for the rest of the day.
  • When the cap is hit: kms:generate-summary returns cost-cap-hit, and kms:get-summary-status reports cost_capped (the red-dot state). Auto-regen simply stops making progress until either spend rolls over at local midnight or the user raises the cap; nothing is lost — the stale notes are picked up on a later scan.
  • Who pays — no Claude API key of your own is needed. A summary is paid the same way as session titles and the other built-in AI helpers: your own AI keys first, then your Omniscio credits. If you have an Anthropic API-key account, the spend, the lock and the daily cap all count against that account. Without one, they all count against one shared "unknown" account (UNKNOWN_ACCOUNT_ID, the label the cost ledger records a keyless charge under), so the daily cap still applies and the Settings spend readout shows the real figure.
  • When nothing can pay for the call, kms:generate-summary returns no-apikey-account and the chip shows its "needs a key" message.
  • Bulk seed needs no up-front API-key check. It starts on the same terms a single summary runs on — a subscription login with no Anthropic key included — and if the first note's generate comes back no-apikey-account the run stops there with that stop reason (the terminal status/push carry stopped: 'no-apikey-account') instead of failing its way through the whole vault.

The model is OpenRouter's openai/gpt-5.6-luna unless you change it. The Vault Summary model setting (kmsSummaryModel, under Settings → Sessions → Per-feature AI models) does move note summaries to another model: the service resolves that setting against the model catalog and falls back to Luna only when it is empty or names a model the catalog does not know. Summary spend follows whichever model is chosen.

Privacy + safety contract

  • No spend without opt-in. A fresh install never generates a summary: the periodic worker is off by default and there is no other automatic generation path. Drift detection (hash bookkeeping) is free and local.
  • The user's words are never overwritten silently by the app itself. A hand-edited or explicitly-locked summary is user_edited and is skipped by both the worker and the polite (force:false) generate path. In the app, only a deliberate forced regenerate replaces locked text, and even then it's a conscious chip click, never the background timer. An agent acting over the CLI control server can do more than this list used to say: clearing a note's summary and unlocking a locked one both apply immediately with no approval card, and a cleared summary — hand-written text included — is not saved to the note's History, so it cannot be brought back. A forced regenerate is approval-gated, and its card names the note and, when the summary is locked and hand-edited, says the new AI summary will replace it.
  • Daily dollar ceiling, fail-safe both ways. Spend is capped per account per local-midnight day, the cap-check plus an in-flight worst-case reservation is serialized so a concurrent burst cannot bust it, and a DB hiccup fails open through a bounded 60-second window rather than dead (silent starvation) — with the gate closing again if the hiccup does not clear.
  • The summary lives in the user's own file under their configured vault root — Omniscio writes it through the same resolveInsideVault() path-validated writer as every other KMS edit (see KMS — mobile, sync and internals "Privacy + safety contract"). Clearing a summary is non-destructive to the rest of the note.
  • Forward-compatible. An older Omniscio build that meets a newer marker format locks the note instead of clobbering it.
  • kms.md — the KMS vault editor this feature lives inside (vault setup, the nothariEnabled master toggle, the safe-write contract, the file watcher).

Last verified 2026-10-21