My Embedding Cache Remembered the Model Name. That Wasn’t Its Whole Identity.

I went back through my bookmark extension’s vector cache before writing about model migration. I wanted to know exactly what caused a saved embedding to be reused. “The text hasn’t changed” wasn’t the whole answer.

This is a source inspection of my implementation on November 15. I didn’t switch a user’s embedding model or overwrite a bookmark store for this article. I also didn’t measure a migration speedup. Those limits matter because code describing a migration isn’t the same as watching one finish.

The cache had two gates

My refresh function first compares the saved model name with the selected embedding model. Only matching names make the old records eligible for reuse. It then compares each bookmark’s text hash.

The embedded text combines the note, title, folder path, and host. Changing a note therefore changes more than the visible label. It changes the input that my cache considers equivalent.

The implementation creates a fresh output map from the current item list. A deleted item doesn’t get copied into that new map. New or changed items go into the embedding queue, which is processed in chunks of 24.

Condition in the inspected code Refresh behavior What it doesn’t establish
Same model name and same text hash Reuse eligible cached record Same underlying model weights
Different model name Old records aren’t reused A completed migration on a real browser
Changed note, title, folder, or host Queue that item’s text again Better search quality
Item absent from current input Omit it from the rebuilt map Deletion of the underlying bookmark
Vector length differs from query length Ranking skips the record Compatibility when lengths happen to match

That’s the behavior I can point to in the code. I haven’t turned the table into a claim about every embedding system.

The model name wasn’t enough to prove sameness

The reuse decision checks the model name string. It doesn’t include the configured endpoint in that decision. I also didn’t find a model digest in the saved identity.

That leaves a concrete boundary. Two endpoints can expose the same name without my comparison proving they’re the same embedding implementation. A model behind a name can also change without that name changing.

I’m describing what my identity check doesn’t establish. I haven’t demonstrated corrupted results from either case in this article. I won’t invent a migration failure to make the warning more dramatic.

The possible cost is stale retrieval: a cache can look reusable while its vectors no longer belong with the query vectors. That’s a design risk identified by inspection, not a measured incident count.

Ollama’s embedding documentation says to use the same embedding model for indexing and querying. My cache needs enough identity information to honor that condition. A matching label is weaker evidence than a pinned model identity.

Dimensions are a guard, not a migration

My ranking loop skips vectors whose lengths differ from the query vector. That’s useful containment. It doesn’t recompute the skipped records, and it doesn’t explain missing results to the person searching.

It also can’t detect every incompatible pair. Matching vector lengths don’t establish that two models use a compatible representation. I can’t replace the model check with a dimension check and call the migration handled.

I’d keep three questions separate: is the saved record eligible for reuse, can it be scored against this query, and does the result retrieve useful items? My old embedding threshold experiment addressed retrieval behavior. This inspection concerns cache identity before that evaluation even starts.

Don’t clear the user’s collection to test a cache

The vectors and the bookmark collection aren’t interchangeable data. I don’t need to delete saved bookmarks to inspect a derived cache. I haven’t cleared either one here.

Before changing the migration logic, I’d use an isolated fixture with unchanged, edited, new, and removed items. I’d include two model identities with equal dimensions as well as different dimensions. I’d also inspect what happens when embedding fails before the final save.

Those are pending checks, not results I’m claiming today. I wouldn’t publish a time-saved figure until I had actual call counts and a completed run.

The current implementation saves its rebuilt store after processing the queued items. That source-level observation doesn’t prove crash safety or protection from concurrent refreshes. I haven’t tested those paths in this review.

My cache wasn’t just a speed feature. It was a set of claims about when old work still matched new input. Writing those claims down exposed the missing identity boundary without touching anyone’s data.

Similar Posts