Release · 2026-08-28T19:23:32+02:00 · By Threadnote

Threadnote 4.5.0

Threadnote 4.5 makes native code graphs portable between local installations and makes source-backed memory easier to recover when graph evidence is missing, moved, or being rebuilt. It also hardens large Workset catalogs, stale-worktree cleanup, Manager naming, performance gates, telemetry renewal, and development installs while keeping legacy recall intact.

What's new

Carry a verified graph between machines

Portable graph checkpoints are manual, offline, and account-free:

threadnote graph index
threadnote graph checkpoint export --output ./threadnote-graph.cgcp
threadnote graph checkpoint inspect \
  --input ./threadnote-graph.cgcp \
  --expected-digest sha256:<digest>
threadnote graph checkpoint verify \
  --input ./threadnote-graph.cgcp \
  --expected-digest sha256:<digest>
threadnote graph checkpoint import \
  --input ./threadnote-graph.cgcp \
  --expected-digest sha256:<digest>

Export produces deterministic artifacts from an exact ready graph at a clean commit. Checkpoints omit raw source-file bytes, absolute local paths, configured remote credential material, and worktree identities, but they do contain source-derived names, signatures, and documentation. Treat them as potentially sensitive architecture data.
inspect authenticates the artifact and its bounded framing without inflating graph records; verify additionally checks compressed records, ordering, counts, coverage, and logical integrity.
Import never fetches source or executes repository code. The source commit must already exist in the same local repository.
An exact clean checkout activates the imported graph directly. Dirty or descendant checkouts rebuild with the imported graph as a compatible base; divergent history keeps it inactive for later reuse.

Obtain the expected digest independently from the checkpoint file, just as you would for a release archive.

Recover explicitly when evidence or cached state is unavailable

An MCP citation write that reaches a missing, stale, or deferred graph now fails before changing memory and returns a structured memory-code-citation-write-recovery receipt with writeApplied: false and indexingStarted: false.
Local citation recovery directs the caller to threadnote graph index --no-vectors; Workset-routed references return an explicit threadnote workset prepare <name> action. Retry the same write after the selected graph is ready.
A uniquely relocated citation keeps its memory fresh while returning a stale-link warning. Changed or deleted evidence makes the memory stale; unavailable, ambiguous, or incomplete evidence remains unknown.
Graph indexing automatically falls back to extraction without cached-fact reuse when a cached fact has disappeared, avoiding an unnecessary manual full rebuild.
Repository-relative citation paths are graph locators, not arbitrary tracked-file readers. A tracked file outside the exact-current graph inventory is rejected with bounded guidance to choose a graph-indexed path or stable handle.
MCP schemas now advertise the same eight-code-reference limit enforced by memory writes, so clients can reject an oversized codeRefs array before invoking remember_context or review_session_context.
Deleted-worktree snapshots are reclaimed even if Git later recycles the same administrative worktree name. Ambiguous or malformed state remains protected rather than guessed at.

Keep Worksets bounded and Manager understandable

Streaming and full-catalog Workset writers now share one lazy routing-projection paginator. It preserves order, enforces the 8 MiB and 512-symbol page limits consistently, computes each symbol's storage charge once, and rejects a single oversized symbol instead of emitting an invalid page.
The 8 MiB boundary regression now exercises the production paginator directly. Remaining SQLite-heavy projection coverage runs in the serialized heavy-state lane without longer timeouts or weaker assertions.
Manager labels a repository-root workspace with its declared project name instead of "."; nested workspace labels remain unchanged.
The website Home, Pro Tips, and FAQ explain portable checkpoints, stale-link semantics, legacy recall, optional Worksets, and Manager's isolated graph preparation and bounded member concurrency.

Keep upgrades and performance evidence explicit

An opt-in from an earlier telemetry schema no longer silently carries forward to schema v5. Threadnote surfaces the renewal after update, while noninteractive updates keep telemetry off until the user explicitly runs:
```
threadnote telemetry enable --apply
```
The development installer tolerates one bounded recall-index projection race during strict doctor verification while continuing to fail closed for unrelated doctor errors.
The governed production performance ratchet still applies every reviewed static limit first. If an allowlisted single-observation wall-clock gate fails on a heterogeneous hosted runner, CI brackets the exact protected base with candidate measurements on that runner and applies a bounded drift-corrected comparison. CPU, RSS, work, storage, correctness, graph-shape, dispersion, relative, and hard-objective guards remain fail-closed.
Reviewed maintenance updates refresh JOSE, PostgreSQL, node-llama-cpp, Vite and React build tooling, happy-dom, Vitest, coverage, and React DOM types while keeping Bun runtime and Bun types aligned at 1.3.14.

Upgrade to Threadnote 4.5

Existing standalone installations upgrade with:

threadnote update

Portable checkpoint operations affect only Threadnote's disposable graph store. Existing schema-v1, schema-v2, schema-v3, unversioned, and otherwise uncited memories continue through normal recall; no citation migration is required, and missing precise citations yield coarse or unknown freshness instead of empty results. A Workset remains optional for local repository recall, graph use, citation capture, Context Brief, and checkpoints. It is an explicit prepared boundary for cross-repository evidence.