vocs 2.4.0 → 2.5.2

package/src/internal/vector-store.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import * as VectorStore from './vector-store.js'
 
 describe('normalize', () => {
@@ -64,3 +64,204 @@ describe('resolveFormat', () => {
     expect(VectorStore.resolveFormat('int8', 'server')).toBe('int8')
   })
 })
+
+describe('cloudflare (remote adapter)', () => {
+  afterEach(() => vi.restoreAllMocks())
+
+  /** In-memory Vectorize API fake backing the `fetch` mock. */
+  function mockVectorize() {
+    const state = {
+      created: false,
+      dimensions: undefined as number | undefined,
+      requests: [] as { body: string | undefined; method: string; path: string }[],
+      vectors: new Map<string, { metadata: Record<string, unknown>; values: number[] }>(),
+    }
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+      const url = new URL(String(input))
+      const method = init?.method ?? 'GET'
+      const body = typeof init?.body === 'string' ? init.body : undefined
+      state.requests.push({ body, method, path: url.pathname + url.search })
+
+      const base = '/client/v4/accounts/acc/vectorize/v2/indexes'
+      if (!url.pathname.startsWith(base)) return new Response('not found', { status: 404 })
+      const rest = url.pathname.slice(base.length)
+
+      // Create index.
+      if (rest === '' && method === 'POST') {
+        state.created = true
+        state.dimensions = JSON.parse(body ?? '{}').config?.dimensions
+        return Response.json({ success: true })
+      }
+      // Get index.
+      if (/^\/[^/]+$/.test(rest) && method === 'GET') {
+        if (!state.created) return new Response('not found', { status: 404 })
+        return Response.json({ result: { config: { dimensions: state.dimensions } } })
+      }
+      if (rest.endsWith('/list'))
+        return Response.json({
+          result: { isTruncated: false, vectors: [...state.vectors.keys()].map((id) => ({ id })) },
+        })
+      if (rest.endsWith('/upsert')) {
+        for (const line of (body ?? '').split('\n')) {
+          const { id, metadata, values } = JSON.parse(line)
+          state.vectors.set(id, { metadata, values })
+        }
+        return Response.json({ success: true })
+      }
+      if (rest.endsWith('/delete_by_ids')) {
+        const ids = JSON.parse(body ?? '{}').ids ?? []
+        // Mirrors Vectorize error 40007.
+        if (ids.length > 100)
+          return Response.json(
+            { success: false, errors: [{ code: 40007, message: 'too many ids in payload' }] },
+            { status: 400 },
+          )
+        for (const id of ids) state.vectors.delete(id)
+        return Response.json({ success: true })
+      }
+      if (rest.endsWith('/query')) {
+        const { topK, vector } = JSON.parse(body ?? '{}')
+        const matches = [...state.vectors.entries()]
+          .map(([id, v]) => ({
+            id,
+            metadata: v.metadata,
+            score: v.values.reduce((sum, x, i) => sum + x * (vector[i] ?? 0), 0),
+          }))
+          .sort((a, b) => b.score - a.score)
+          .slice(0, topK)
+        return Response.json({ result: { matches } })
+      }
+      return new Response('bad request', { status: 400 })
+    })
+    return state
+  }
+
+  function entry(id: string, text: string, vector: number[]): VectorStore.RemoteEntry {
+    return {
+      id,
+      metadata: { href: `/${id}`, text, title: id },
+      vector: VectorStore.normalize(vector),
+    }
+  }
+
+  const credentials = { accountId: 'acc', apiToken: 'tok' }
+
+  it('throws on missing credentials', async () => {
+    const store = VectorStore.cloudflare({ accountId: '', apiToken: '' })
+    await expect(store.query(new Float32Array([1]), { topK: 5 })).rejects.toThrow(/accountId/)
+  })
+
+  it('creates the index on first sync and upserts all entries', async () => {
+    const state = mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+
+    const result = await store.sync([entry('a', 'alpha', [1, 0]), entry('b', 'beta', [0, 1])], {
+      dimensions: 2,
+    })
+
+    expect(state.created).toBe(true)
+    expect(state.dimensions).toBe(2)
+    expect(result).toEqual({ deleted: 0, skipped: 0, upserted: 2 })
+    expect(state.vectors.size).toBe(2)
+    // Content-addressed ids: 64 hex chars (Vectorize's id byte cap).
+    for (const id of state.vectors.keys()) expect(id).toMatch(/^[0-9a-f]{64}$/)
+  })
+
+  it('re-sync skips unchanged entries and prunes stale ones', async () => {
+    const state = mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+
+    await store.sync([entry('a', 'alpha', [1, 0]), entry('b', 'beta', [0, 1])], { dimensions: 2 })
+    const result = await store.sync([entry('a', 'alpha', [1, 0]), entry('c', 'gamma', [1, 1])], {
+      dimensions: 2,
+    })
+
+    expect(result).toEqual({ deleted: 1, skipped: 1, upserted: 1 })
+    expect(state.vectors.size).toBe(2)
+  })
+
+  it('batches deletes within the 100-id Vectorize limit', async () => {
+    const state = mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+
+    const entries = Array.from({ length: 150 }, (_, i) => entry(`e${i}`, `text ${i}`, [1, i]))
+    await store.sync(entries, { dimensions: 2 })
+    const result = await store.sync([entry('keep', 'kept', [1, 0])], { dimensions: 2 })
+
+    expect(result).toEqual({ deleted: 150, skipped: 0, upserted: 1 })
+    expect(state.vectors.size).toBe(1)
+  })
+
+  it('rejects a dimension change against an existing index', async () => {
+    mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+    await store.sync([entry('a', 'alpha', [1, 0])], { dimensions: 2 })
+    await expect(store.sync([entry('a', 'alpha', [1, 0, 0])], { dimensions: 3 })).rejects.toThrow(
+      /dimensions/,
+    )
+  })
+
+  it('bounds oversized metadata under the Vectorize cap', async () => {
+    const state = mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+
+    await store.sync([entry('big', 'x'.repeat(20_000), [1, 0])], { dimensions: 2 })
+
+    const [stored] = [...state.vectors.values()]
+    const size = new TextEncoder().encode(JSON.stringify(stored?.metadata)).length
+    expect(size).toBeLessThanOrEqual(9216)
+    // Trimmed, not dropped.
+    expect(String(stored?.metadata['text']).length).toBeGreaterThan(0)
+  })
+
+  it('sanitizes metadata to Vectorize types (string | number | boolean | string[])', async () => {
+    const state = mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+
+    await store.sync(
+      [
+        {
+          id: 'a',
+          // Sparse `titles` (skipped heading levels) serialize as nulls.
+          metadata: {
+            href: '/a',
+            nested: { drop: true },
+            none: null,
+            title: 'a',
+            titles: ['Guide', null, 'Steps'],
+            weight: 0.8,
+          },
+          vector: VectorStore.normalize([1, 0]),
+        },
+      ],
+      { dimensions: 2 },
+    )
+
+    const [stored] = [...state.vectors.values()]
+    expect(stored?.metadata).toEqual({
+      href: '/a',
+      title: 'a',
+      titles: ['Guide', 'Steps'],
+      weight: 0.8,
+    })
+  })
+
+  it('queries nearest vectors and caps topK at 50', async () => {
+    const state = mockVectorize()
+    const store = VectorStore.cloudflare(credentials)
+    await store.sync([entry('a', 'alpha', [1, 0]), entry('b', 'beta', [0, 1])], { dimensions: 2 })
+
+    const hits = await store.query(VectorStore.normalize([0.9, 0.1]), { topK: 100 })
+
+    expect(hits[0]?.metadata?.['href']).toBe('/a')
+    expect(hits[0]?.score ?? 0).toBeGreaterThan(hits[1]?.score ?? 0)
+    const queryRequest = state.requests.find((r) => r.path.endsWith('/query'))
+    expect(JSON.parse(queryRequest?.body ?? '{}').topK).toBe(50)
+  })
+
+  it('propagates query failures', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('nope', { status: 401 }))
+    const store = VectorStore.cloudflare(credentials)
+    await expect(store.query(new Float32Array([1]), { topK: 5 })).rejects.toThrow(/401/)
+  })
+})

package/src/internal/vector-store.ts

@@ -1,16 +1,24 @@
 /**
- * Built-in static vector store for AI search — the default, open-source
- * alternative to a hosted vector DB (Pinecone, etc).
+ * Vector stores for AI search.
  *
- * Vectors are packed into a single typed-array matrix and base64-encoded, so the
- * whole index is one compact artifact that works server-side (Node) and, with
- * `int8` quantization, in the browser. Cosine similarity reduces to a dot
- * product because all vectors are normalized before packing.
+ * Two storage targets:
+ *
+ * - `static` (default) — the built-in, open-source alternative to a hosted
+ *   vector DB. Vectors are packed into a single typed-array matrix and
+ *   base64-encoded, so the whole index is one compact artifact that works
+ *   server-side (Node) and, with `int8` quantization, in the browser. Cosine
+ *   similarity reduces to a dot product because all vectors are normalized
+ *   before packing.
+ * - `remote` — vectors live in a hosted vector database (e.g. Cloudflare
+ *   Vectorize). The build syncs vectors up; the server queries the database at
+ *   runtime, so no index artifact ships with the server bundle.
  */
 
 export type Format = 'float32' | 'int8'
 
-export type Adapter = {
+export type Adapter = StaticAdapter | RemoteAdapter
+
+export type StaticAdapter = {
   /** Also emit a public/browser artifact (for `runtime: 'server'` deploys). */
   expose: boolean
   /** Storage format. `'auto'` resolves to `float32` (server) / `int8` (client). */
@@ -23,6 +31,55 @@ export type Adapter = {
   type: string
 }
 
+/** Chunk vector + metadata synced into a remote store at build time. */
+export type RemoteEntry = {
+  /** Stable chunk identifier (adapters may derive their own storage id). */
+  id: string
+  /** Chunk metadata returned verbatim by `query` at runtime. */
+  metadata: Record<string, unknown>
+  /** L2-normalized embedding vector. */
+  vector: Float32Array
+}
+
+/** Nearest-neighbor match returned by a remote store. */
+export type RemoteHit = {
+  /** Storage identifier of the matched vector. */
+  id: string
+  /** Chunk metadata attached at sync time (if any). */
+  metadata: Record<string, unknown> | undefined
+  /** Similarity score (higher is more relevant). */
+  score: number
+}
+
+export type RemoteSyncResult = {
+  /** Stale vectors removed from the store. */
+  deleted: number
+  /** Vectors already up to date (not re-uploaded). */
+  skipped: number
+  /** New or changed vectors uploaded. */
+  upserted: number
+}
+
+export type RemoteAdapter = {
+  /** Returns the `topK` nearest vectors to a normalized query vector. */
+  query: (
+    vector: Float32Array,
+    options: { signal?: AbortSignal | undefined; topK: number },
+  ) => Promise<RemoteHit[]>
+  /** Syncs the full chunk set into the store (upserts new, prunes stale). */
+  sync: (
+    entries: readonly RemoteEntry[],
+    options: {
+      dimensions: number
+      onProgress?: ((done: number, total: number) => void) | undefined
+    },
+  ) => Promise<RemoteSyncResult>
+  /** Storage target backing the adapter. */
+  target: 'remote'
+  /** Adapter type identifier. */
+  type: string
+}
+
 /**
  * The built-in static vector store.
  *
@@ -38,7 +95,7 @@ export type Adapter = {
  * ```
  */
 // biome-ignore lint/correctness/noUnusedVariables: re-exported below as `static`
-function staticStore(options: staticStore.Options = {}): Adapter {
+function staticStore(options: staticStore.Options = {}): StaticAdapter {
   return {
     type: 'static',
     target: 'static',
@@ -61,11 +118,311 @@ export declare namespace staticStore {
 
 export { staticStore as static }
 
+/**
+ * Cloudflare Vectorize vector store (remote). Vocs still chunks and embeds
+ * locally (with the configured `embedding` adapter); vectors are synced into a
+ * Vectorize index at build time and queried over REST at runtime, so no vector
+ * artifact ships with the server bundle.
+ *
+ * The index is created on first sync (cosine metric, dimensions inferred from
+ * the embedding). Sync is incremental: vector ids are content-addressed, so
+ * unchanged chunks are skipped and stale vectors are pruned. The API token
+ * needs the `Vectorize:Edit` permission.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig, Embedding, Retriever, VectorStore } from 'vocs/config'
+ *
+ * export default defineConfig({
+ *   ai: {
+ *     retriever: Retriever.local({
+ *       embedding: Embedding.openai(),
+ *       vectorStore: VectorStore.cloudflare({ index: 'my-docs' }),
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function cloudflare(options: cloudflare.Options = {}): RemoteAdapter {
+  const {
+    accountId = process.env['CLOUDFLARE_ACCOUNT_ID'],
+    apiToken = process.env['CLOUDFLARE_API_TOKEN'],
+    baseUrl = 'https://api.cloudflare.com/client/v4',
+    headers,
+    index = 'vocs-ai-search',
+  } = options
+
+  async function request(
+    path: string,
+    init: {
+      body?: string | undefined
+      contentType?: string | undefined
+      method?: string | undefined
+      signal?: AbortSignal | undefined
+    } = {},
+  ): Promise<Response> {
+    if (!accountId)
+      throw new Error(
+        '[vocs] VectorStore.cloudflare: missing `accountId` (or CLOUDFLARE_ACCOUNT_ID).',
+      )
+    if (!apiToken)
+      throw new Error(
+        '[vocs] VectorStore.cloudflare: missing `apiToken` (or CLOUDFLARE_API_TOKEN).',
+      )
+    const url = `${baseUrl.replace(/\/$/, '')}/accounts/${accountId}/vectorize/v2/indexes${path}`
+    return await fetch(url, {
+      method: init.method ?? 'GET',
+      headers: {
+        Authorization: `Bearer ${apiToken}`,
+        ...(init.contentType ? { 'Content-Type': init.contentType } : {}),
+        ...headers,
+      },
+      ...(init.body !== undefined ? { body: init.body } : {}),
+      signal: init.signal ?? null,
+    })
+  }
+
+  /** Creates the index when missing; validates dimensions when present. */
+  async function ensureIndex(dimensions: number): Promise<void> {
+    const existing = await request(`/${index}`)
+    if (existing.ok) {
+      const json = (await existing.json()) as {
+        result?: { config?: { dimensions?: number | undefined } | undefined } | undefined
+      }
+      const remote = json.result?.config?.dimensions
+      if (remote !== undefined && remote !== dimensions)
+        throw new Error(
+          `[vocs] Vectorize index "${index}" has ${remote} dimensions, embedding produces ${dimensions}. Delete the index or configure a different \`index\` name.`,
+        )
+      return
+    }
+    if (existing.status !== 404)
+      throw new Error(
+        `[vocs] Vectorize get index failed (${existing.status}): ${await safeText(existing)}`,
+      )
+    const created = await request('', {
+      method: 'POST',
+      contentType: 'application/json',
+      body: JSON.stringify({ config: { dimensions, metric: 'cosine' }, name: index }),
+    })
+    if (!created.ok)
+      throw new Error(
+        `[vocs] Vectorize create index failed (${created.status}): ${await safeText(created)}`,
+      )
+  }
+
+  /** Enumerates all vector ids in the index, or `undefined` when unsupported. */
+  async function listIds(): Promise<Set<string> | undefined> {
+    const ids = new Set<string>()
+    let cursor: string | undefined
+    do {
+      const params = new URLSearchParams({ count: '1000' })
+      if (cursor) params.set('cursor', cursor)
+      const response = await request(`/${index}/list?${params}`)
+      if (!response.ok) {
+        console.warn(
+          `[vocs] Vectorize list vectors failed (${response.status}); skipping incremental sync (re-upserting all, no pruning).`,
+        )
+        return undefined
+      }
+      const json = (await response.json()) as {
+        result?:
+          | {
+              isTruncated?: boolean | undefined
+              nextCursor?: string | undefined
+              vectors?: { id?: string | undefined }[] | undefined
+            }
+          | undefined
+      }
+      for (const vector of json.result?.vectors ?? []) if (vector.id) ids.add(vector.id)
+      cursor = json.result?.isTruncated ? json.result?.nextCursor : undefined
+    } while (cursor)
+    return ids
+  }
+
+  return {
+    type: 'cloudflare',
+    target: 'remote',
+    async query(vector, { signal, topK }) {
+      const response = await request(`/${index}/query`, {
+        method: 'POST',
+        contentType: 'application/json',
+        body: JSON.stringify({
+          vector: Array.from(vector),
+          // Vectorize caps topK at 50 when returning metadata.
+          topK: Math.min(topK, 50),
+          returnValues: false,
+          returnMetadata: 'all',
+        }),
+        signal,
+      })
+      if (!response.ok)
+        throw new Error(
+          `[vocs] Vectorize query failed (${response.status}): ${await safeText(response)}`,
+        )
+      const json = (await response.json()) as {
+        result?:
+          | {
+              matches?:
+                | { id?: string | undefined; metadata?: unknown; score?: number | undefined }[]
+                | undefined
+            }
+          | undefined
+      }
+      return (json.result?.matches ?? []).map((match) => ({
+        id: match.id ?? '',
+        metadata:
+          typeof match.metadata === 'object' && match.metadata !== null
+            ? (match.metadata as Record<string, unknown>)
+            : undefined,
+        score: match.score ?? 0,
+      }))
+    },
+    async sync(entries, { dimensions, onProgress }) {
+      await ensureIndex(dimensions)
+
+      // Content-addressed ids: unchanged chunks keep their id across builds,
+      // so sync reduces to "upsert what's new, delete what's gone". Ids hash
+      // the bounded metadata so truncation stays stable across builds.
+      const local = new Map<string, RemoteEntry>()
+      for (const entry of entries) {
+        const bounded = {
+          ...entry,
+          metadata: boundMetadata(sanitizeMetadata(entry.metadata)),
+        }
+        local.set(await contentId(bounded), bounded)
+      }
+
+      const remote = await listIds()
+      const toUpsert = remote
+        ? [...local.keys()].filter((id) => !remote.has(id))
+        : [...local.keys()]
+      const toDelete = remote ? [...remote].filter((id) => !local.has(id)) : []
+
+      let upserted = 0
+      const batchSize = 500
+      for (let i = 0; i < toUpsert.length; i += batchSize) {
+        const batch = toUpsert.slice(i, i + batchSize)
+        const ndjson = batch
+          .map((id) => {
+            const entry = local.get(id)
+            if (!entry) return undefined
+            return JSON.stringify({
+              id,
+              metadata: entry.metadata,
+              values: Array.from(entry.vector),
+            })
+          })
+          .filter((line): line is string => line !== undefined)
+          .join('\n')
+        const response = await request(`/${index}/upsert`, {
+          method: 'POST',
+          contentType: 'application/x-ndjson',
+          body: ndjson,
+        })
+        if (!response.ok)
+          throw new Error(
+            `[vocs] Vectorize upsert failed (${response.status}): ${await safeText(response)}`,
+          )
+        upserted += batch.length
+        onProgress?.(upserted, toUpsert.length)
+      }
+
+      // Vectorize caps delete_by_ids at 100 ids per request (error 40007).
+      for (let i = 0; i < toDelete.length; i += 100) {
+        const batch = toDelete.slice(i, i + 100)
+        const response = await request(`/${index}/delete_by_ids`, {
+          method: 'POST',
+          contentType: 'application/json',
+          body: JSON.stringify({ ids: batch }),
+        })
+        if (!response.ok)
+          throw new Error(
+            `[vocs] Vectorize delete failed (${response.status}): ${await safeText(response)}`,
+          )
+      }
+
+      return {
+        deleted: toDelete.length,
+        skipped: local.size - toUpsert.length,
+        upserted: toUpsert.length,
+      }
+    },
+  }
+}
+
+export declare namespace cloudflare {
+  type Options = {
+    /** Cloudflare account id. @default process.env.CLOUDFLARE_ACCOUNT_ID */
+    accountId?: string | undefined
+    /** API token with the `Vectorize:Edit` permission. @default process.env.CLOUDFLARE_API_TOKEN */
+    apiToken?: string | undefined
+    /** API base URL. @default 'https://api.cloudflare.com/client/v4' */
+    baseUrl?: string | undefined
+    /** Extra request headers. */
+    headers?: Record<string, string> | undefined
+    /** Vectorize index name (created on first sync). @default 'vocs-ai-search' */
+    index?: string | undefined
+  }
+}
+
 /** Creates a vector-store adapter from a custom definition. */
 export function from(adapter: Adapter): Adapter {
   return adapter
 }
 
+/** Vectorize metadata values must be string | number | boolean | string[]; drops the rest. */
+function sanitizeMetadata(metadata: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(metadata)) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+      out[key] = value
+    else if (Array.isArray(value))
+      out[key] = value.filter((item): item is string => typeof item === 'string')
+  }
+  return out
+}
+
+/** Vectorize caps metadata at 10KiB/vector; trims the unbounded `text` field to fit. */
+function boundMetadata(metadata: Record<string, unknown>): Record<string, unknown> {
+  const limit = 9216
+  let text = typeof metadata['text'] === 'string' ? metadata['text'] : undefined
+  for (;;) {
+    const out = text !== undefined ? { ...metadata, text } : metadata
+    const size = new TextEncoder().encode(JSON.stringify(out)).length
+    if (size <= limit || !text) return out
+    text = text.slice(0, Math.max(0, text.length - (size - limit)))
+  }
+}
+
+/**
+ * Content-addressed vector id: SHA-256 over chunk id, metadata, and vector
+ * bytes. 64 hex chars — exactly Vectorize's 64-byte id cap.
+ */
+async function contentId(entry: RemoteEntry): Promise<string> {
+  const prefix = new TextEncoder().encode(`${entry.id}\0${JSON.stringify(entry.metadata)}\0`)
+  const vector = new Uint8Array(
+    entry.vector.buffer,
+    entry.vector.byteOffset,
+    entry.vector.byteLength,
+  )
+  const bytes = new Uint8Array(prefix.length + vector.length)
+  bytes.set(prefix, 0)
+  bytes.set(vector, prefix.length)
+  const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', bytes))
+  let hex = ''
+  for (const byte of digest) hex += byte.toString(16).padStart(2, '0')
+  return hex
+}
+
+async function safeText(response: Response): Promise<string> {
+  try {
+    return (await response.text()).slice(0, 200)
+  } catch {
+    return ''
+  }
+}
+
 /**
  * Serialized vector matrix. `data` is base64 of the packed typed array; for
  * `int8`, `scales` is base64 of one Float32 dequantization scale per vector.
@@ -194,7 +551,10 @@ export function search(store: Store, query: Float32Array, topK: number): SearchR
 }
 
 /** Resolves `'auto'` to a concrete format for the given runtime. */
-export function resolveFormat(format: Adapter['format'], runtime: 'server' | 'client'): Format {
+export function resolveFormat(
+  format: StaticAdapter['format'],
+  runtime: 'server' | 'client',
+): Format {
   if (format !== 'auto') return format
   return runtime === 'client' ? 'int8' : 'float32'
 }

package/src/internal/vite-plugins.ts

@@ -822,8 +822,12 @@ export function aiSearch(config: Config.Config): PluginOption {
 
   const { rootDir, basePath } = config
   const localEnabled = Boolean(config._localRetriever)
+  const vectorStore = config._localRetriever?.vectorStore
+  // Remote store: build-time work is syncing vectors into the database; no
+  // index artifact (server manifest or public browser file) is emitted.
+  const remoteStore = vectorStore?.target === 'remote'
   const exposePublic =
-    ai?.runtime === 'client' || config._localRetriever?.vectorStore.expose === true
+    ai?.runtime === 'client' || (vectorStore?.target === 'static' && vectorStore.expose === true)
 
   let mode: 'development' | 'production' = 'development'
   let manifestPromise: Promise<Retriever.IndexManifest> | undefined
@@ -848,7 +852,9 @@ export function aiSearch(config: Config.Config): PluginOption {
           }
           await Retriever.saveIndex(config, manifest)
           logger.info(
-            `AI search index built (${manifest.vectorStore.count} chunks, ${manifest.vectorStore.format}).`,
+            remoteStore
+              ? `AI search index synced (${manifest.vectorStore.count} chunks, remote vector store).`
+              : `AI search index built (${manifest.vectorStore.count} chunks, ${manifest.vectorStore.format}).`,
             { timestamp: true },
           )
           return manifest
@@ -909,8 +915,10 @@ export function aiSearch(config: Config.Config): PluginOption {
     async load(id) {
       if (id === resolvedServerManifestId) {
         // Dev never builds; the server loads the manifest written by
-        // `vocs embeddings generate` from disk instead.
-        if (!localEnabled || mode === 'development' || skipSeeding()) return emptyManifestModule
+        // `vocs embeddings generate` from disk instead. A remote store needs
+        // no baked manifest either — the server queries the database directly.
+        if (!localEnabled || remoteStore || mode === 'development' || skipSeeding())
+          return emptyManifestModule
         const manifest = await buildManifest()
         // Emit as a gzipped asset. Inlining the JSON into the chunk bloats
         // server bundles (manifests can be tens of MB).
@@ -952,7 +960,7 @@ export const getAiSearchManifest = async () =>
       await fs.writeFile(path.join(dir, `ai-search-index-${publicHash}.json`), json, 'utf-8')
 
       const bytes = Buffer.byteLength(json)
-      const max = config._localRetriever?.vectorStore.maxClientBytes
+      const max = vectorStore?.target === 'static' ? vectorStore.maxClientBytes : undefined
       if (max && bytes > max)
         logger.warn(
           `AI search client index is ${(bytes / 1e6).toFixed(1)}MB, exceeds maxClientBytes (${(max / 1e6).toFixed(1)}MB). Consider int8 format or fewer chunks.`,