Conexus 7.6.1: the road from 5.0

Eighty-three releases in eleven weeks. The short version: the entire storage substrate was replaced under a running system, upgrades collapsed to one command, the agent workflow layer went from written convention to enforced mechanism, and the system learned to tell the truth about its own failures.

Upgrading is the same as it has been since 6.12:

uv tool upgrade conexus
nx upgrade

That second command is most of the story. The verb existed in 5.0, where it ran routine schema migrations; today it converges the package, the engine, and every data migration your install needs. If your install still carries an unmigrated Chroma-era store (it never ran nx guided-upgrade), the upgrade will stop and route you through the two-hop path: pin conexus==6.18.1, migrate there, then upgrade normally (the migration runbook has the full walk). The detector runs at every entry point, so you cannot miss it.

What follows is the feature arc from 5.0.0 (2026-05-24) to 7.6.1 (2026-08-11), grouped by theme rather than by release. The CHANGELOG has the per-release detail.

One substrate: Postgres everywhere

5.0 ran on ChromaDB for vectors and a family of SQLite databases for everything else: memory, plans, taxonomy, telemetry, the catalog, session scratch (the storage-tiers doc maps the T1/T2/T3 model). Each had its own locking story, its own daemon, its own failure modes. The 5.x line spent most of its patch releases fighting exactly that: WAL writer-lock contention, daemon crash-loops, single-writer races (RDR-128, RDR-129, RDR-140, RDR-149, and RDR-151 form a five-RDR arc of making SQLite multi-process behave).

6.0.0 replaced the substrate instead. T3 vector storage moved to PostgreSQL 17 + pgvector behind a native engine service (RDR-155), with nx guided-upgrade (RDR-159) as the one-command, validated, copy-not-move migration. The Chroma source stayed intact on disk as the rollback artifact. Over the 6.x line the seven SQLite T2 stores, the local catalog, session scratch, and even the streaming-PDF pipeline buffer followed (RDR-186), until 7.0.0 deleted the SQLite substrate (RDR-158) and the chromadb dependency outright. There is no hybrid mode. Local installs run a bundled, relocatable PG17 + pgvector; cloud installs talk to the managed service. Same schema, same engine, same code paths.

The payoff shows up everywhere downstream: tenant isolation is row-level security in one database rather than N file permissions, the catalog and the vectors share transactions, and the entire 5.x daemon-contention bug class is simply gone.

The engine

One engine, one identity, verified against the book by lamplight

The engine service is its own release artifact: a cosign-signed native binary (Linux amd64/arm64, macOS arm64) plus the signed PG bundle, acquired and verified by nx init --service with no hand-assembly. Since 6.10.1 the rule is ONE engine identity per release: the exact engine a release was built and gated against is the engine every install converges to, fresh installs and upgrades alike. A stale engine cannot silently keep serving after an upgrade; the post-upgrade pass sweeps it from the process table if it tries.

Work migrated steadily from the client into the engine:

  • Embedding is server-side. The client no longer embeds at all; the last client-side Voyage credential was retired in 7.3.0. Re-index runs skip embedding for unchanged chunks server-side (RDR-181, an 89% token reduction on a typical warm re-index), and local mode embeds with bge-768 on the engine.
  • Reranking is server-side (RDR-188): Voyage rerank in cloud mode, a local cross-encoder in local mode, with loud degrade reporting.
  • Garbage collection is SQL. The orphan sweep that used to read the whole corpus into Python and round-trip every embedding is now an anti-join UPDATE in the engine. Measured on this repo: pruning went from 548 seconds to under 50 (7.6.0).
  • Writes are atomic. As of 7.5.0 a document’s chunks and its catalog manifest land in one engine-side transaction per flush, with the superseded-vector sweep folded in and advisory gates closing the concurrent index-versus-sweep race.

One upgrade command

6.12.0 shipped RDR-185: nx upgrade walks a single ordered ladder that detects, converges, and verifies whatever your install actually needs. T2 schema, the Chroma-to-pgvector move, legacy chunk identity, embedder era: each rung is idempotent and resumable, your existing store is left byte-untouched as a rollback target, and a year-dormant install converges the same way a current one no-ops. The only decision it will not make for you is a billed re-embed, which prints a cost preview and waits (or takes --yes).

The honesty rules apply here too: since 7.5.0 a rung whose verification diagnostic cannot run reports failed-to-verify and stops, instead of recording success by absence of a problem signal.

Content addresses, all the way down

6.14.0 (RDR-180) fixed a foundational wobble: the chunk content address was historically the first half of the SHA-256 digest stored as hex text, while the citation grammar advertised the full digest. The chash is now the full 32-byte SHA-256, stored as raw bytes with a width CHECK, hex only on the wire. The upgrade ladder rehashes existing stores from stored text (no re-embed) and records every legacy id in a permanent alias map, so old references resolve forever. A whole class of width-confusion bugs became structurally impossible, and chash: citations resolve at the 256 bits they always claimed.

On top of that identity sits the index-run fence (RUNFENCE, 7.1.0; the architecture doc covers the mechanism): every index path brackets its work with begin/complete/fail records, an unfinished run reads as definitively stale, and manifests can no longer outrun their chunks. A failed or interrupted index cannot leave a document looking permanently fresh while silently truncated.

The trash has a lifecycle

Deletion grew up in 7.2.0. nx catalog delete tombstones; tombstoned documents vanish from every search and fetch surface (a 200x query speedup came out of getting the liveness predicates right); nx catalog purge-trash does the physical reclaim, dry-run first, with dry-run and execute evaluating one shared server-side population. Shared chunks are reference-counted: deleting one document can no longer corrupt another that shares identical chunk text (7.6.1). The orphan GC quarantines instead of deleting, restores automatically on re-reference, and refuses any sweep that would condemn more than a quarter of a collection.

Speed

A sampling of measured, matched-condition improvements across the line: repo indexing went from 3.5 s/file serial to 0.21 s/file in the file loop (batched catalog registration, cross-file chunk batching, bounded concurrency); the staleness cache build from ~110 s to ~9 s; catalog link generation 14x; a no-op taxonomy discover from 300 s to 0.6 s; warm re-index embed costs down 89% via the server-side skip; CI wall time halved by duration-balanced sharding. The 7.5.0 lock-contention arc alone recovered two to four minutes of lock wait per indexing run, nearly a minute of which was spent acquiring a process-wide mutex to do literally nothing.

Honesty as a feature

A red light that tells the truth is worth more than a wall of green that cannot fail

The largest single theme since 5.0 is not a feature but a discipline: no silent fallbacks for data-correctness problems. Dozens of entries in the changelog are the same fix in different clothes. A sweep that could not run used to report clean; now it reports that it could not check. A batch command that half-failed used to exit 0; nx index pdf --dir, nx index repo, and nx dt index now exit non-zero and name the damage. A stopword-only memory search used to return an indistinguishable empty result; it now returns a typed error. nx doctor had three checks that probed a retired substrate and passed unconditionally; they were rebuilt against the live engine. Delete counts are server-confirmed rather than request-echoed.

The same discipline extended to the product’s own release gates: the fresh-install gate provisions a scrubbed virgin HOME and asserts a zero-warning doctor; the sandbox shakedown exercises MinerU end-to-end and can actually fail; the migration rehearsal walks a real 6.0-era box across the eras unattended. Several of those gates turned out to be vacuous when audited, and un-vacuating them found real defects every time.

The conexus plugin: process became mechanical

The orchestration ledger: dispatch recorded by the machine, return settled by the machine, review a precondition of passage

The plugin is the half of the system that lives inside Claude Code: the skills, agents, and hooks that turn nexus from a storage layer into an agent operating discipline. It has its own changelog, and its arc since 5.0 is the same story as the substrate’s, one level up: conventions that lived in prose became mechanisms that fire.

The early 5.x line rebuilt the plumbing. Slash-command preambles moved out of fragile inlined bash into the tested nx CLI (RDR-130), argument quoting was hardened against injection across all 25 commands, and hook deny reasons started actually reaching the model instead of arriving as a bare “denied.” 5.8.0 added version lockstep (RDR-143): the plugin and CLI ship the same version through independent channels, and a SessionStart hook detects skew and self-heals it, ending the version-drift incident class.

Then the workflow discipline itself got encoded. 5.4.5 wired the stacked-reviewer pair (code review plus substantive critique, which catch disjoint defect classes) into every orchestration surface as a non-optional gate. The brainstorming gate was scoped precisely in 7.1.0: work with no design of record must gate; a locked memo, accepted RDR, or reviewed bead IS the approval, and re-gating designed work is the named anti-pattern.

The deepest piece is the orchestration ledger (RDR-184). Background subagents are the plugin’s power tool and its failure mode: an agent that finishes work and never reports is silent lost labor. The ledger gives every dispatch an EXPECT row and every completion a settlement. Getting it to actually fire took three releases of the honesty discipline applied to the plugin itself: the 7.0.0 pin mechanized EXPECT rows via a PreToolUse hook on the Agent tool (the hand-written convention was structurally unenforceable); 7.3.0 shipped the first SubagentStop completion guard that could ever fire (the original gate was satisfiable by zero of nineteen agents, and the audit said so); 7.5.0 replaced the guard’s lock-based credit accounting with atomic symlink claims after a race that let an agent stop unreported was traced to a check-then-act reap that no amount of tuning could fix.

7.3.0 made the review discipline mechanical too: bd close blocks on a missing review-completed marker, and git push is denied when outgoing commits on gated paths carry no review coverage. That check exists because a postmortem showed five commits reaching the integration branch unreviewed while the prose version of the rule watched it happen. And 7.6.0 extended the falsification discipline to the reviewers themselves: the test-validator agent must now break production code and watch each regression test go red before calling it verified, because three tests in one session had survived being read and judged sound while guarding nothing.

The rest, briefly

  • DEVONthink (5.5.0, RDR-139): nx dt capture pulls a URL, DOI, or file into DEVONthink and indexes it end to end; highlights, semantic links, and bibliographic gap-fill are opt-in layers.
  • Claude-assisted remediation (6.7.0, RDR-182): nx forensics and nx remediate, consent-gated and audited, with all diagnostic SQL passing a fail-closed aggregate-only lint.
  • Guided onboarding (5.7.0, RDR-144): nx init presents the bge-768 versus minilm-384 embedder choice with safe collection migration, instead of a silent packaging default.
  • Search surface: range operators in metadata filters, graph-hop search honoring where, multi-model corpora grouped per embedding model and merged, unattended taxonomy review (nx taxonomy review --auto), and nx answer-runs finally reading back the retrieval telemetry the system had been writing since RDR-080.
  • Managed cloud (RDR-166, onboarding guide): scoped service tokens with JIT data-token minting, tenant-locked mint credentials, and a public-edge contract gate so the CDN cannot silently strip the fields clients depend on.

What did not change

The nx CLI, the PyPI package name conexus, the plugin namespace, the MCP server names, your T2 memory, your T3 collections, the catalog, the RDR history, and the plan library. Every migration in this arc was copy-not-move with the source intact.

5.0 was structural: a rename, a Desktop build, pinned releases. The eleven weeks since were the product growing into that structure. 7.6.1 is what it looks like settled: one substrate, one engine identity, one upgrade command, a workflow layer that enforces its own discipline, and a system that would rather stop loudly than succeed falsely.

CHANGELOG | Getting started | Release notes



Leave a Reply