Changelog

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