Versioning
Versioning a document, a record and an API are three different problems. A document keeps whole snapshots. A record keeps a current value plus the history of what it replaced. An interface keeps a promise to callers you cannot contact. Applying one of those solutions to another's problem is the usual source of trouble.
Documents: snapshots#
A document version is a complete copy at a moment, kept because someone may need to read the old one exactly as it was. There is no merge problem to solve, only storage and naming, and the useful metadata is who changed it and why rather than which bytes differ.
Connect creates and modifies files as new versions rather than in place, each with provenance and an audit entry. The old version stays readable. That is the right shape here because the alternative — editing the stored file — makes “what did this say when the customer was sent it” unanswerable.
Records: supersession, not snapshots#
A record is read constantly and by many things at once, so keeping whole copies of every state is both expensive and unhelpful — nobody wants to reconstruct a person from forty snapshots. What a record needs is a current value, an origin for that value, and the fact that it replaced something.
Memory works this way in Connect: a corrected memory supersedes the earlier one, which stays as history with its own origin. Lifecycle stages move through move_stage and the movement is the record. Deletions are marks — threads.deleted_at — rather than removals.
- Snapshot versioning a record
- Storage grows with reads, not with meaning, and comparing two states means diffing whole objects
- Supersession
- One current row, one chain of what it replaced, cheap to read and honest about who changed it
- Event sourcing
- The chain is the truth and the current value is derived. Powerful, and a much larger commitment than most record sets need
Interfaces: a promise to callers you cannot reach#
An API version exists because somebody else's code depends on today's shape and you cannot ring them up. Two conventions dominate, and they answer different questions.
| Convention | Reads as | Suits |
|---|---|---|
Semantic versioning (3.1.0) | Major means a break, minor means an addition, patch means a fix | Libraries and specifications, where a caller reasons about compatibility |
Date-based revisions (2026-07-28) | This is the revision published on that date; compatibility is stated in prose | Protocols that revise as a whole, where a “minor” change may still alter behaviour |
The protocol surfaces Connect publishes use both, because their specifications do: the public API description is written to OpenAPI 3.1.0, the agent card follows A2A 1.0.0, and the Model Context Protocol revision is dated 2026-07-28. That revision is a good argument for the date convention — it removed protocol-level sessions and the standalone GET stream, a change no minor-version number would have prepared anyone for.
Does Connect use versioning?#
- Files are versioned as snapshots, with provenance and audit on each new version.
- Records supersede rather than snapshot — memory, lifecycle stage, triage marks.
- Published interface descriptions carry the version of the specification they are written to, not a version of their own invention.
- The product has a version — 6.3.2 — which is what a support conversation refers to.
- Schema changes are not versioned in the migration-file sense at all: migrations run at every boot and are written to be idempotent, so “which migration version is this database on” is not a question that gets asked here.
What Connect does not offer is a versioned public HTTP API with parallel /v1 and /v2 paths. The application's own /openapi.json, /docs and /redoc are closed and stay closed; the published description under /developers is the documented surface.
Questions#
If Connect edits a file, can I still read what it said before?
Yes. A modification creates a new version rather than overwriting the existing one, and each version carries who or what changed it along with an audit entry. The earlier version stays readable, which is what makes it possible to answer what a document said at the time it was used.
Why is the API description written to OpenAPI 3.1.0 rather than the newest?
Because tool support for 3.1 is universal and nothing in the description needs a feature introduced later. A newer specification version is only worth adopting when something in it is being used; adopting it otherwise narrows the set of tools that can read the file for no gain.
How do I know which version of Connect I am using?
Connect is one deployed application rather than something installed per workspace, so both audiences are on the same build at any moment. The product version is 6.3.2; the pages under Product record what that means and how status language is used.