feat(brain): vecq-core 0.3.0 — keyed persistence, residual default, brain.vector_bits knob - #548
Merged
Merged
Conversation
…rain.vector_bits knob Upgrade the opt-in vecq store to vecq-core 0.3.0 and close #547. - Keyed persistence (upstream vecq#32 closed, format v1.3+): symbol-id keys survive reload. load_or_create_vecq now deserializes for real and keeps a healthy keyed index; legacy keyless files, corrupt files, and dim mismatches rebuild dirty so the next re-embeds. A dim guard is mandatory: add_keyed panics on wrong-dim vectors. - brain.vector_bits config (residual|4|5|6, lenient, default residual): residual is best recall@10 at 4-bit scan speed in a recall study on cora's own embeddings (ahead of plain 5-bit at 1k/5k/13k scales). A width change rebuilds the index once so the config takes effect; vecq_file_needs_rebuild is width-aware. - BrainConfig gets a manual Default (derived Default produced empty strings, inconsistent with the serde defaults). - Cross-project heal: the vector index is one shared file; a rebuild (width/dims/legacy/corrupt) now clears embed fingerprints for ALL projects, not just the active one, and the usearch dims-mismatch deletion path joins the same heal (pre-existing fingerprint leak). Tests: keyed roundtrip, legacy keyless rebuild, corrupt rebuild, dim-mismatch rebuild, width-switch rebuild, roundtrip across all four widths, lenient parsing, config merge. 947 pass incl. the fresh-process integration tests from #546. Closes #547
This was referenced Aug 31, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Closes #547:
vecq-core0.2.0 → 0.3.0, and uses what it ships.load_or_create_vecqnow deserializes for real and keeps a healthy keyed index as-is. Legacy keyless files (pre-0.3.0), corrupt files, and dim mismatches rebuild dirty so the nextcora indexre-embeds. A dim guard is mandatory —add_keyedpanics on wrong-dim vectors.brain.vector_bitsknob (residual|4|5|6, lenient, default residual): 4-bit base codes + second-pass residual rescoring. A recall study on cora's own embeddings (real Rust symbol texts through the default hashing provider, ground-truth cosine) put residual at recall@10 0.930/0.917/0.863 at 1k/5k/13k symbols — ahead of plain 5-bit (0.880/0.850/0.840) at every scale, at 4-bit scan speed. A width change rebuilds the index once so the config takes effect;vecq_file_needs_rebuildis width-aware.BrainConfiggets a manualDefault(derived Default produced empty strings, inconsistent with the serde defaults).Why
#546's lazy-load made the search path backend-aware "until upstream lands key serialization" — this is that serialization. Together: the vecq signal is now fully alive in fresh processes, and index rebuilds stop being a per-run cost.
Testing
vector_bitsparsing, config merge/defaults.-D warnings, fmt clean,cora review --stagedpass (pre-commit hook).brain.vector_bits: "6"config → indexed →.vecqheader verified on disk (config → binary → bytes).Closes #547