0.6.0 stops hybrid search from silently dropping its keyword arm, takes archived thoughts out of
default retrieval, raises a typed error on a wrong-dimension query vector, and adds three opt-in
extension points. It migrates the database schema (user_version 18 → 20), and if you wrote your
own embedding provider there is one thing to check: dimension has to be public. Details below.
What changed for you
Hybrid search keeps its keyword arm on hard queries. A quoted phrase, a wildcard, or a bare
boolean operator used to produce an FTS5 MATCH expression that failed, and the BM25 arm was
dropped without a signal — the query still returned vector results, so the loss was invisible. Those
expressions are now quoted or normalized, a failed first attempt is retried through bare-query
normalization before the arm is dropped at all, and every first-attempt failure increments
fts_match_failure_count. This is a correctness fix to which arms run, not a change to how results
are ranked.
Archived thoughts leave default retrieval. search_similar, search_fts, search_hybrid and
recall now exclude LifecycleStatus.ARCHIVED rows unless you pass include_archived=True.
list_thoughts and count_thoughts are unchanged. If your application relied on archived rows
coming back from recall, account for that before you deploy.
Wrong-dimension query vectors fail loudly. search_similar and the vector arm raise
VectorDimensionMismatchError instead of raising an incidental ValueError or returning an empty
list. Empty, all-zero and non-finite vectors still return an empty result rather than raising, and
increment vector_arm_degradation_count.
Edges carry metadata. link_thoughts accepts an arbitrary metadata mapping and the edge reads
return it. Schema step 18 → 19; existing edges read back metadata == {}.
A second recency axis. Recency can now score on transaction time with a caller-supplied now,
alongside the existing cycle-based mode. Existing behaviour is the default; the new axis is opt-in.
Inverted validity intervals are rejected. A valid_from later than valid_until is refused at
write time rather than stored, where it would quietly skew the as-of queries that read it.
Memory hygiene archives less eagerly. A thought must now be inactive for a minimum age before
it is eligible at all, and a run archives nothing unless the candidate pool carries actual evidence
of use — a read, a confirmation, or an action outcome. Cycle-recency and confidence do not count,
because they exist on every store: on a bulk import with no usage history they would let ingest
order alone decide what gets evicted. Permanently collecting a hygiene-archived thought also waits
out a wall-clock restore window (schema step 19 → 20 adds thought.archived_at). If you enabled
hygiene on 0.5, omitted fields resolve to a seven-day minimum age and a 30-day
restore window — review them before the first 0.6 run. Rows archived before the upgrade have no
wall-clock stamp and fail closed: they are not auto-collected while the window is active.
Extension points. Three, all opt-in. A derived-records seam, where an extension produces
records from the thoughts you write, plus a derive_existing() backfill so a store that already
holds data can be brought up to date rather than only deriving from here on. A structural split
producer with two dependency-free modes — split on a configurable blank-line boundary (the default,
and the previous behaviour byte for byte), or fixed windows measured in characters or words with
optional overlap. And a cycle-provider seam: you supply the cognitive-cycle counter the store
stamps records with, and the new max_cycle() accessor reports the store's high-water mark across
thoughts and edges, so a consumer can resume its own counter after a restart. Migrating a store does
not enable any of them.
Upgrading from 0.5
This is a schema-changing minor upgrade. Back up the database, stop the 0.5 workers, let one 0.6
process run ensure_schema() (or engrava migrate) to completion, then start the 0.6 workers. Do
not run 0.5 and 0.6 workers against one file across the migration. Both steps only add columns — no
table is dropped, and no value you wrote is rewritten.
An edge you set to decay_multiplier = 0.0 may already read 1.0. On 0.5 the column stored the
value you wrote, but the decode tested it for truthiness and handed back the 1.0 default — and
because update_edge rebuilds the record from that read, any later change to such an edge, including
an invalidate_edge closing its valid-time interval, persisted 1.0 over the stored 0.0. 0.6
decodes on presence, so 0.0 round-trips as written. The migration does not undo what 0.5 already
overwrote — it only adds columns, as above; where a 0.5 update replaced a stored 0.0, the database
holds 1.0 and 0.6 reads that back faithfully. If you set 0.0 deliberately, re-check those edges
after upgrading. Full note:
Upgrade to 0.6.
If you wrote your own embedding provider, read this one. EmbeddingProviderProtocol has always
required a public dimension, but 0.5 read it at exactly one site off the query path — so a
provider that kept the value privately (self._dimension, no public property) worked for as long as
nothing called verify_embedding_model(). 0.6 reads it before every vector search that has to ask
the provider — a sqlite-vec backend is consulted first and takes the dimension from its own vec0
table, so that configuration never reaches the provider read. Everywhere else, such a provider now
raises EmbeddingProviderContractError naming the class and the missing member. The fix is a
property:
@property
def dimension(self) -> int:
return self._dimension
The check is lazy — construction still succeeds, and a store that never searches by vector is
unaffected — so call verify_embedding_model() after construction if you would rather fail at
startup. We hit this in one of our own integrations.
Full notes, including both migration steps and the behaviour changes above:
Upgrade guide, 0.5 → 0.6
· Known limitations
engrava-mcp
engrava-mcp 0.6.0 ships alongside this release and moves its engrava range to
>=0.6,<0.7 — 0.5 is dropped, so upgrade both together. The server surface becomes 13 tools, 3
resources and 3 prompts: get_edges and list_edges close the write-but-can't-read asymmetry on
edges, link_thoughts accepts edge metadata, search_memory accepts recency_now, and
metadata_equals / metadata_in filters are available on the wire.
pip install --upgrade engrava