Repository navigation
fix: cache the embedding index on disk so a cold process start costs bytes, not megabytes (GIT-98) - #31
Merged
1 commit merged intoSep 21, 2026
Merged
fix: cache the embedding index on disk so a cold process start costs bytes, not megabytes (GIT-98)#311 commit merged into
1 commit merged into
Conversation
…bytes, not megabytes (GIT-98) In local search mode every server process downloaded every learning with its 1536-dim embedding at startup and discarded it at exit. Short-lived processes (sub-agents, fan-outs, CI) paid full price each time; a customer exhausted a Supabase egress allowance this way. - getLearningsFingerprint(): one request, one row (Prefer: count=exact) gives row count + newest updated_at for ~60 bytes. - vector-disk-cache: rows persisted under that fingerprint, keyed by a hash of (store URL, table). Any mismatch, corruption or unknown fingerprint is a miss and falls back to the download. Atomic temp+rename writes, mode 0600. - Misses are single-flighted across processes with an O_EXCL lock: one leader downloads, followers wait (async, bounded) and read its cache. - cache-flush bypasses the disk cache and rewrites it. - Opt out with GITMEM_VECTOR_DISK_CACHE=0.
This was referenced Sep 21, 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
2 participants
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.
Linear: https://linear.app/nteg-labs/issue/GIT-98
Read the Linear comments first; they contain corrections and known gaps.
What
Caches the embedding index on disk so a cold process start transfers a few bytes instead of megabytes.
getLearningsFingerprint()makes one request for one row (Prefer: count=exact) and gets the row count plus the newestupdated_at, about 60 bytes.vector-disk-cachestores the rows under that fingerprint, keyed by a hash of (store URL, table). Any mismatch, corruption or unknown fingerprint counts as a miss and falls back to the full download. Writes are atomic (temp file + rename) with mode 0600.O_EXCLlock picks a leader, and the others wait (async, bounded) and then read its cache.cache-flushskips the disk cache and rewrites it.GITMEM_VECTOR_DISK_CACHE=0.Why
In local search mode, every server process downloaded every learning with its 1536-dim embedding at startup and threw it away at exit. Short-lived processes (sub-agents, fan-outs, CI) paid that cost every time, and one customer used up a Supabase egress allowance this way.
Provenance
Written and unit-tested by Brain (Claude chat) in a container that could neither push nor reach a real Supabase. Applied here with
git amontoorigin/main@d47a625, with commit authorship left unchanged. File blob hashes after apply match the expected values:src/services/startup.ts6a127ed✅src/services/supabase-client.ts1e52576✅src/services/vector-disk-cache.ts91853b9✅tests/unit/services/vector-disk-cache.test.tsb87d965✅Verified locally (unit level only)
npx tsc --noEmit -p .passes with no errors.npm run test:unit(run withHOMEset to a temp dir, see GIT-92): 75 files / 1228 tests passed.tscclean.Required before merge (NOT yet run)
Known caveat:
refreshBehavioralScores()bumpsupdated_aton everysession_start. That changes the fingerprint, so expect roughly one full download per session, not a true warm start. Per-row delta sync is the follow-up.Checklist
npm run test:unitpassestests/unit/services/vector-disk-cache.test.ts)GITMEM_VECTOR_DISK_CACHEopt-out is new and user-facingNo version bump and no publish in this PR.
🤖 Generated with Claude Code