Vector Index

Collections are named memorysync-user-{user_id}. There is exactly one per user, no per-project sub-collections. A query against another user's collection cannot happen through the API surface — the collection name is derived from the authenticated user_id, never from the body.

Every collection is created with cosine similarity. The index returns a distance; the platform converts to similarity with similarity = 1 - clamp(distance, 0, 1). No other metric is configured.

• vector_id — stable handle, unique inside the collection.
• vector — the embedding floats themselves.
• metadata payload: memory_id, user_id, project_id, environment, source, tags, importance, created_at (ISO string), tier.

• Memory text — encrypted in the durable store only.
• Memory summary — same.
• Quality, confidence, and freshness scores — those live on the row and are joined in at rank time.
• The relationship graph — separate table, accessed only when traversal is needed.
• Extraction metadata — irrelevant to similarity search.

1. When a memory is created, a vector row is inserted under a freshly generated vector_id.
2. When a memory's content is updated, a new vector_id is generated. The old vector is deleted by the previous handle; the new one is upserted.
3. When a memory's tier changes, the vector is re-upserted so the metadata payload's tier field stays consistent.
4. Deleting a non-existent vector is a no-op — deletion is idempotent so retry-on-failure is safe.

Where-clauses on metadata fields run during the similarity search, not after. That is what makes a tightly filtered query as fast as an unfiltered one — the index never returns 10,000 rows that the platform then throws away.

• Every call wraps in a retry loop: 50 ms → 100 ms → 200 ms exponential backoff.
• After three consecutive failures, the call surfaces an HTTP 503; recall does not silently degrade to "empty index".
• Per-user collections are cached locally so steady-state queries skip the collection-listing path on every call.

When a memory is archived or moved to cold tier, its vector can be exported to a cold object-storage bucket and removed from the active collection. The platform tracks archived vectors so cold-tier recall (a slow path with a multi-second SLA) can pull them back in on demand. Cold archive purge is governed by the same retention timeline as the row.