Highlights

• LLM profiles now expose only provider, endpoint, model, context window, and
  genuine model capabilities. The internal model registry resolves compatible
  request adapters, token counters, reasoning controls, and output-token field
  names automatically.

Artifacts

Desktop bundles built from v0.3.7.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.7 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• Chat delivery is now durable: every public event is committed before SSE
  delivery, frames carry resumable cursors, desktop and CLI clients reconnect
  automatically, and explicit cancellation is independent from viewer
  disconnects.

• Tool calls expose replay-stable turn/index identifiers without leaking or
  replacing provider-side identifiers used for model tool-result pairing.

• Session and completed-task collection APIs support stable keyset pagination,
  backed by composite indexes that also keep bounded retention scans fast.

• Optional document, storage-byte, ingest-backlog, and concurrent-chat gates
  reject excess work with HTTP 429 before expensive processing begins.

• Relation mining, section embeddings, task cleanup, and event cleanup now
  have explicit read, candidate, page, batch, and retention bounds.

• PostgreSQL can run through transaction-pooled proxies with disabled asyncpg
  statement caching and globally unique prepared-statement names.

• Managed deployments can migrate once with marginalia-db-prepare, disable
  runtime schema DDL on API/worker replicas, use /live for liveness and
  /ready for bounded database/storage readiness checks, and run queue-only
  workers without periodic scheduling.

• Prompt-cache reporting distinguishes whole-prompt coverage from eligible
  prefix reuse, and finalization keeps cache-affecting request parameters
  stable across execution rounds.

• Compatible-provider tool arguments receive bounded, semantics-safe JSON
  repair; ambiguous malformed calls are rejected and can be corrected up to
  two times instead of executing with invented values.

• Durable event replay waits for the persisted terminal event when conversation
  completion and event commits race, avoiding prematurely closed streams.

• Legacy CLI SSE streams without durable conversation identities still finish
  cleanly, while identified turns continue reconnecting until a terminal event.

• Desktop backend overrides are now verified against Marginalia's /health
  response before they are saved. Ollama and LM Studio model endpoints can no
  longer be mistaken for the GUI backend, and a bad existing override can be
  cleared from the startup screen to restore the bundled backend.

• The Settings page no longer exposes or persists the bundled sidecar's
  ephemeral runtime port as a user-configured remote backend.

Artifacts

Desktop bundles built from v0.3.6.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.6 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• Agent execution now has an explicit evidence-gathering checkpoint before
  final composition. Once research is closed, tools are disabled and the
  model receives up to two bounded attempts to return a complete answer.

• Source citations selected at the checkpoint are validated against successful
  read_files output. Entry IDs, exact visible quotes, and PDF page or PPTX
  slide positions must all be supported by evidence from the current turn.

• Final answers no longer lose article-source anchors when the model emits body
  markers without their definitions. The runtime assigns stable markers and
  appends verified definitions deterministically before display-link rewriting.

• Model-written definitions for assigned markers are replaced with the
  validated manifest, and missing body markers receive a compact source
  fallback so every verified citation remains reachable.

Artifacts

Desktop bundles built from v0.3.5.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.5 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• Long text and Office documents now produce stable, named sections; oversized
  inputs are indexed in bounded concurrent chunks with file-level summaries,
  coverage metadata, and deterministic heuristic fallbacks.

• Citation links now retain complete source locators: PDF page plus verified
  quote, DOCX block plus quote, PPTX slide plus quote, and XLSX sheet plus
  cell or row plus quote. The desktop viewer preserves and consumes every
  locator field together.

• Agent replay now validates stored tool history strictly, keeps provider
  prompt prefixes append-only, applies per-tool timeouts, canonicalizes tool
  schemas, and reports cache-eligible hit/reuse metrics in live and replay APIs.

• Agent tool fan-out now uses a bounded rolling pool, configurable with
  AGENT_MAX_PARALLEL_TOOL_CALLS, so one model response cannot open an
  unbounded number of database sessions or retain every tool result at once.

• Scanned-PDF visual question answering caps each read to five pages, sends at
  most three page images per provider request, enforces serialized payload and
  render-size budgets, and falls back to single-page calls when a model does
  not support multiple images.

• PDF, DOCX, and PPTX question reads now preserve readable source text before
  considering OCR or document vision. Visual inspection is reserved for
  requested ranges without readable text, while image reads fall back to their
  persisted descriptions when a live vision call fails.

• Embedding and rerank HTTP connections are reused within each event loop.
  Provider responses are validated for vector count/dimensions and usable
  rerank results before they enter the semantic index or ranking pipeline.

• Ingest task outcomes now report extraction, vision, intelligence, embedding,
  status-persistence, and total-pipeline stage durations. Throughput reporting
  distinguishes scheduled reprocessing from ordinary uploads without changing
  the underlying task kind.

• The provider diagnostics action now sends a real image to the vision profile
  and validates enabled embedding and rerank providers as well as chat models.

• Retrieval evaluation now includes a concurrent load runner with throughput,
  latency percentiles, quality metrics, and enforceable thresholds.

• Default task-worker and ingest-LLM concurrency are both four, while remaining
  independently configurable for workload and provider limits.

• LLM profiles now carry explicit dialect, context-window, tokenizer, vision,
  tool, temperature, and output-token-parameter capabilities. Token-aware
  request compaction keeps conversation history within the resolved model
  window without modifying stored turns.

• Prompt-cache metrics now include a configurable three-state SLO verdict:
  met, breached, or insufficient data.

• Whole-library semantic rebuilds page through database entries, and confident
  scoped section matches backfill locators for lexical recall candidates.

• Task deliveries now carry a unique owner token. Heartbeats, completion,
  retry, and stale-lease recovery use owner-and-lease compare-and-swap checks;
  loss of ownership cancels the old handler, and periodic ticks use time-slot
  dedup keys so every completed tick leaves a distinct successor.

• Worker retries use configurable bounded exponential backoff. Database
  bootstrap also collapses legacy duplicate active tasks before installing the
  active-dedup constraint, preserving the most executable delivery.

• Upload limits are enforced while multipart bytes stream through ASGI, before
  framework spooling. File bytes are counted exactly, non-file multipart data
  is bounded separately, and an obviously oversized Content-Length is
  rejected without consuming the body.

• Upload commit ambiguity is compensated safely: local partial files are
  removed, bounded S3 multipart writes abort on failure, object deletions are
  persisted as retryable tasks, and soft-deleted database rows are never
  reused as live content-addressed uploads.

• A duplicate upload now resumes failed ingest or schedules a per-file semantic
  refresh for ready content. Refreshes reuse vectors only when provider,
  model, dimensions, and section text hash all match the current index.

• PostgreSQL deployments serialize conflicting tool scopes and concurrent
  turns for one session with transaction advisory locks, while retaining the
  lightweight in-process locks used by SQLite.

• Late-page PDF visual reads render only the requested page range; image size,
  page count, serialized request size, and multi-image compatibility remain
  bounded independently.

• Settings connection probes use a small but provider-compatible output
  budget instead of a one-token cap rejected by some reasoning models.

• Answer-language instructions now stay anchored to the current user's
  original question even when retrieved evidence or runtime messages use a
  different language.

• Semantic indexing ignores generated placeholder-only section titles while
  preserving real OCR and text headings.

• Legacy databases with duplicate active task dedup keys upgrade without
  manual repair, and configurable retry delays remain capped even after many
  attempts.

• PPTX reads no longer discard earlier slide text merely because a later slide
  is empty, and empty vision-provider responses are surfaced as explicit
  errors instead of synthetic answer text.

Artifacts

Desktop bundles built from v0.3.4.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.4 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• Multimodal chat input: paste or drag images into the chat composer to ask
  about your library together with a picture. Images ride the current turn
  only (never re-sent in history, so token cost stays flat) and render in the
  transcript. MARGINALIA_CHAT_VISION (auto|on|off, default auto) probes the
  chat model once per model and, for a text-only model, routes images through
  the vision profile as an injected description — automating the manual
  "describe the image first" workaround. Per-turn caps via
  MARGINALIA_CHAT_IMAGE_MAX_COUNT / MARGINALIA_CHAT_IMAGE_MAX_BYTES. Pasted
  images are persisted per turn and re-displayed as thumbnails when a session's
  transcript is reloaded (UI only — still never re-sent to the model).

• POST /v1/settings/llm/test probes each configured LLM profile with a tiny
  chat call (bounded by a timeout) so a mistyped key/base-URL/model is caught
  at config time; a "Test connection" button surfaces per-profile status. A
  settings PUT that first makes required profiles valid now auto-reprocesses
  ingests that failed before a key existed.

• OCR_MAX_PAGES (default 300) caps scanned-PDF OCR and records an
  ocr_page_cap partial-coverage reason when it trips.

• Transient provider failures (rate limits, 5xx/529 overload, timeouts) are
  retried with bounded exponential backoff honoring Retry-After, so a brief
  overload no longer discards a whole agent turn's accumulated tool work.

• CPU-bound document parsing (PDF/DOCX/PPTX/spreadsheet) runs off the event
  loop, keeping the API responsive and worker heartbeats alive during large
  ingests.

• GUI search tokenizes multi-word queries and ranks results instead of
  matching one contiguous phrase; the per-hit related-entries walk is limited
  to the top hits so latency no longer scales with match count.

• Release artifacts (Docker image, desktop sidecar) install from the locked
  requirements exported from uv.lock, so shipped versions match what CI
  tested; CI gained a uv.lock drift gate and a Docker build check.

• Selective WebDAV publish no longer leaks the full folder/tag taxonomy or any
  sessions/conversations/journals — only the taxonomy and relations reachable
  from the selected entries ride along.

• Agent per-call token budgets are sized for reasoning models (plan 2048,
  execute 4096, vision-describe 4096), which spend most of their output budget
  on hidden reasoning before any visible text — the old smaller caps were
  consumed by reasoning and truncated the plan/answer/image description to
  empty ("can't read the image" even when the model and image were fine).

• The LLM test-connection probe treats a rate-limit (429) as reachable and no
  longer retry-storms it into a false timeout when several profiles share one
  provider account.

Artifacts

Desktop bundles built from v0.3.3.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.3 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

Hardening release from a full code audit: fixes for data-loss, correctness,
and safety defects across WebDAV sync, the mirror vault, ingest pipelines,
semantic recall, the agent runtime, the CLI/MCP surfaces, and the desktop app.

• WebDAV pull no longer clobbers newer local edits, resurrects locally
  deleted entries, or wipes local-only tag assignments: a minimal conflict
  guard skips rows whose local updated_at is newer, preserves newer local
  deletions, and merges tags instead of replacing them.

• WebDAV pull re-downloads remotely-changed file content instead of marking
  the stale local bytes as hydrated, so files.sha256 no longer diverges
  from the stored blob.

• WebDAV folder/catalog import handles children exported before their parent
  (no foreign-key crash), reconciles same-name folders across machines by
  (parent_id, name), and rejects path-shaped remote ids/names.

• WebDAV publish records and checks a library_id, refusing to overwrite an
  unrelated remote library, and a full publish now reads-and-merges the remote
  snapshot instead of dropping remote-only entries.

• Mirror uploads into a folder (GUI folder_id style) now write the file into
  the folder's directory instead of the vault root, and disk/DB name-collision
  suffixes agree.

• Folder rename/move relocates the on-disk mirror directory; renaming or moving
  a not-yet-hydrated WebDAV entry no longer 500s; and folder relocation is
  crash/partial-failure tolerant and runs off the event loop.

• scan/apply correctly handles moves to the vault root and no longer
  mis-attributes a deleted duplicate's file to another entry.

• Ingest is more robust: archives containing dangling/absolute symlinks or an
  inner tar in a subdirectory no longer crash; decompression bombs are refused
  from the declared sizes before extraction; and text files in cp1252/latin-1
  and similar legacy encodings decode correctly instead of as UTF-16 mojibake.

• Semantic index refreshes are serialized within and across processes, use
  unique temp files, cap embedded text length, avoid wiping a populated index
  on an empty entry set, avoid re-embedding the whole library on the first
  per-file refresh, and recover from a stale sqlite-vec sidecar.

• Agent runtime: bounded resume-history replay, a terminal branch for
  filtered/refused responses (no more burning the round budget), off-loop PDF
  quote location, escaped citation link text, and DSML text tool-call parsing
  gated to the providers that actually use it.

• Metadata search rescues short non-CJK terms (AI, Go), escapes %/_
  wildcards, and keeps short CJK terms in ranking; Postgres CJK search routes
  through ILIKE.

• CLI/MCP: SSE indentation is preserved in streamed answers; the MCP stdio
  server dispatches requests concurrently, ignores unknown notifications, and
  drains in-flight work on EOF; /ls lists entries; Ctrl-C during a chat turn
  cancels the turn instead of quitting; errors surface when the spinner is
  disabled; and ~ is expanded in upload paths.

• Security hardening: LocalStorage refuses path-escaping keys; LLM-supplied
  regexes in query_log/analyze_container run in a killable subprocess with
  a wall-clock timeout; folder-download zip members are sanitized against
  zip-slip; WebDAV routes no longer echo raw internal errors; and the server
  logs a warning when bound to a non-loopback host without a token.

• Desktop: token-protected backends load PDFs/images/EPUB/Office/downloads via
  authenticated blob URLs; external links and the Office print button work
  under Tauri; viewer toolbars and errors are localized; the "quote not found"
  banner is styled; a stale search-error banner clears; and a port-conflict on
  the fixed backend port surfaces an actionable error screen instead of an
  infinite spinner (attaching to an already-running backend still works).

• Alembic upgrade head succeeds on PostgreSQL when revision ids exceed 32
  characters; interrupted SQLite table rebuilds are recovered on next start;
  and the pooled connection is no longer left with foreign keys disabled.

• MARGINALIA_UPLOAD_MAX_BYTES caps POST /v1/upload (default 0 =
  unlimited); oversized uploads are rejected with 413 before the body is
  spooled to disk.

• glowpy is pinned to an exact commit instead of a moving branch.

• The unused cost_estimate / total_cost_estimate fields now surface as
  null rather than a misleading constant 0.

Artifacts

Desktop bundles built from v0.3.2.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.2 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• Added provider call TPS limiting for LLM, embedding, and rerank requests,
  with runtime settings overlay support.

• DOCX and PPTX embedded images can now be described by the vision profile,
  queried with read_files(question=...), and persisted for fallback reads.

• PDF, PPTX, and DOCX image descriptions are inserted back into native document
  positions before indexing: PDF figures per page, PPTX images per slide, and
  DOCX images near their source block.

• Embedding request batch size is capped at 10 for desktop and backend
  settings.

• Text-layer PDF readback now includes persisted figure descriptions for
  targeted page reads and pattern searches.

• Existing invalid overlay values such as embedding_batch_size > 10 are
  ignored instead of overriding safe defaults.

Artifacts

Desktop bundles built from v0.3.1.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.1 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• WebDAV knowledge-pack sync can publish and consume snapshots without
  syncing the live MARGINALIA_HOME directory.

• Desktop Library now provides separate WebDAV upload and download sync
  flows that list changed files and let users choose which entries to sync.

• Desktop Settings can save WebDAV connection details and sync lightweight
  remote status, showing the remote snapshot time and id.

• Follow-up chat turns now give the planner lightweight same-session context,
  so terse requests like "continue" or "expand that" stay on the prior topic
  instead of being mistaken for standalone small talk.

• EPUB citation links now carry quote locators and the desktop EPUB viewer
  searches the spine to jump to the cited passage.

• WebDAV JSONL metadata parsing now preserves Unicode line separators inside
  JSON strings and reports the affected metadata file and line on parse errors.

• WebDAV download sync now reuses existing local tags with the same name and
  facet, including case-only variants such as FAQ/faq, avoiding
  tags(name, facet) uniqueness failures when importing a remote snapshot.

• WebDAV metadata import now writes summarized_journal_ids as SQL NULL for
  reflect_turn journal rows, avoiding the journal integrity check failure
  exposed by existing remote snapshots.

• The WebDAV download sync dialog now uses a download icon instead of matching
  the upload sync icon.

Artifacts

Desktop bundles built from v0.3.0.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.3.0 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• Desktop backend discovery now verifies /health instead of only checking
  whether a local port is open, avoiding false reuse of unrelated local
  services.
• Packaged desktop builds now write early launcher diagnostics to
  <MARGINALIA_HOME>/logs/launcher.log, including skipped backend launches,
  missing bundled backend resources, and sidecar spawn failures.
• Packaged desktop builds now write frontend diagnostics to
  <MARGINALIA_HOME>/logs/frontend.log, including backend URL resolution,
  health-check delays, network failures, and uncaught frontend errors.
• Backend logs now include startup milestones, request failures, slow
  requests, upload diagnostics, and task runner lifecycle events.

Artifacts

Desktop bundles built from v0.2.11.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.2.11 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.

Highlights

• read_files deep reads now reopen original files or complete extracted
  text instead of ingest/index previews, with consistent heading, page, line,
  pattern, and offset behavior across EPUB, PDF, Office, email, and archive
  members.
• Desktop file viewers are split by format (PDF, Office, EPUB, email, image,
  archive) while keeping the Library toolbar entry point stable, reducing
  regressions between unrelated preview types.
• Desktop Office previews now allow the @silurus/ooxml WebAssembly and
  worker sources required by the Tauri/WebView2 runtime, avoiding a stuck
  loading state for DOCX/PPTX/XLSX files.
• Office previews now surface a timeout error if the embedded viewer never
  finishes initializing.
• Added regression coverage for continuing a loaded historical session with
  prior turns replayed into the execute phase.

Artifacts

Desktop bundles built from v0.2.10.
Desktop targets: Windows x64/arm64, macOS x64/arm64, Linux x64/arm64.
Linux targets include .deb, .rpm, and AppImage assets built on Ubuntu 22.04 runners.
Each bundle ships a self-contained Python runtime; no system Python required.
Docker image: ghcr.io/shenmintao/marginalia:v0.2.10 (linux/amd64, linux/arm64)

First-Launch Notes For Unsigned Binaries

• Windows: SmartScreen may say "Windows protected your PC". Click "More info" and then "Run anyway".
• macOS: Gatekeeper may refuse to open the .dmg. Run xattr -dr com.apple.quarantine /Applications/Marginalia.app after dragging it across.