kongbrain 0.4.4 → 0.5.1

package/src/migrate-reembed.ts

@@ -0,0 +1,305 @@
+/**
+ * Re-embed migration: take rows tagged with one provider and rewrite their
+ * embeddings using another provider, updating the embedding_provider tag in
+ * the same UPDATE.
+ *
+ * Resumability: each table is processed in batches of `batchSize` rows
+ * matching `embedding_provider = $fromProvider`. After a batch is written,
+ * those rows no longer match the filter, so a subsequent run picks up from
+ * where the previous one stopped.
+ *
+ * The text re-embedded for each row is the canonical text field for that
+ * table (e.g. concept.content, turn.text). For tables where the original
+ * write site embedded a composed string (skill: "name: description"), we
+ * reproduce that composition here so the new vectors live in roughly the
+ * same conceptual neighborhood as the originals.
+ */
+
+import type { EmbeddingService } from "./embeddings.js";
+import type { SurrealStore } from "./surreal.js";
+import { swallow } from "./errors.js";
+
+/** Tables that store embeddings and need to participate in re-embed. */
+export const VECTOR_TABLES = [
+  "turn",
+  "concept",
+  "memory",
+  "artifact",
+  "identity_chunk",
+  "skill",
+  "reflection",
+  "monologue",
+] as const;
+
+export type VectorTable = typeof VECTOR_TABLES[number];
+
+/**
+ * Per-table mapping from the row shape to the text that should be embedded.
+ * Different tables call their text field different things; skill composes
+ * its embedding text from name + description.
+ */
+type RowTextExtractor = (row: Record<string, unknown>) => string;
+
+const TEXT_EXTRACTORS: Record<VectorTable, RowTextExtractor> = {
+  turn: r => String(r.text ?? ""),
+  concept: r => String(r.content ?? ""),
+  memory: r => String(r.text ?? ""),
+  artifact: r => {
+    // Match what workspace-migrate.ts does for content-rich artifacts when
+    // possible. When content is short, embed it; otherwise embed a header
+    // plus a content excerpt.
+    const description = String(r.description ?? "");
+    const content = String(r.content ?? "");
+    if (!content) return description;
+    if (content.length < 2000) return content;
+    return `${description}\n${content.slice(0, 1500)}`;
+  },
+  identity_chunk: r => String(r.text ?? ""),
+  // skills.ts embeds `${name}: ${description}` — preserve that.
+  skill: r => `${String(r.name ?? "")}: ${String(r.description ?? "")}`.trim(),
+  reflection: r => String(r.text ?? ""),
+  monologue: r => String(r.content ?? ""),
+};
+
+/** Fields a row must select for migration (per table). */
+const SELECT_FIELDS: Record<VectorTable, string> = {
+  turn: "id, text",
+  concept: "id, content",
+  memory: "id, text",
+  artifact: "id, description, content",
+  identity_chunk: "id, text",
+  skill: "id, name, description",
+  reflection: "id, text",
+  monologue: "id, content",
+};
+
+export interface ReembedOptions {
+  /** Provider id rows should be migrated FROM. Required. */
+  fromProvider: string;
+  /** Provider id to migrate TO. Defaults to `embeddings.providerId`. */
+  toProvider?: string;
+  /** Tables to migrate. Defaults to all 8 vector tables. */
+  tables?: VectorTable[];
+  /** Rows fetched + embedded per batch. Default 256. */
+  batchSize?: number;
+  /** When true, count rows + estimate cost without writing anything. */
+  dryRun?: boolean;
+  /** Optional progress callback per batch. */
+  onProgress?: (event: ProgressEvent) => void;
+}
+
+export interface ProgressEvent {
+  table: VectorTable;
+  /** Rows processed in this batch. */
+  batchSize: number;
+  /** Cumulative rows processed for this table. */
+  tableProcessed: number;
+  /** Total rows (counted at start) for this table. */
+  tableTotal: number;
+}
+
+export interface ReembedResult {
+  /** Total rows updated (or counted, when dryRun). */
+  total: number;
+  /** Per-table breakdown. */
+  perTable: Record<VectorTable, number>;
+  /** Approximate input character count (sum of text lengths). */
+  approxChars: number;
+  /** Approximate input token count using a chars/4 heuristic. */
+  approxTokens: number;
+  /** True if no writes were performed. */
+  dryRun: boolean;
+  /** Wall clock duration in ms. */
+  durationMs: number;
+}
+
+/**
+ * Approximate token count using the chars/4 heuristic. Real tokenization
+ * varies by model; this estimate is good enough for cost ballparks.
+ */
+function approxTokenCount(chars: number): number {
+  return Math.ceil(chars / 4);
+}
+
+/**
+ * Migrate rows from one provider to another, batching reads + writes.
+ *
+ * The embedding service passed in MUST already be initialized and produce
+ * vectors in the target provider's space. The function does NOT switch
+ * providers itself — that is a config-time decision.
+ */
+export async function reembedAll(
+  store: SurrealStore,
+  embeddings: EmbeddingService,
+  opts: ReembedOptions,
+): Promise<ReembedResult> {
+  const startedAt = Date.now();
+  const tables: VectorTable[] = opts.tables ?? [...VECTOR_TABLES];
+  const batchSize = opts.batchSize ?? 256;
+  const fromProvider = opts.fromProvider;
+  const toProvider = opts.toProvider ?? embeddings.providerId;
+  const dryRun = opts.dryRun ?? false;
+
+  if (fromProvider === toProvider) {
+    throw new Error(
+      `reembedAll: fromProvider (${fromProvider}) and toProvider (${toProvider}) are identical — nothing to do.`,
+    );
+  }
+  if (!dryRun && !embeddings.isAvailable()) {
+    throw new Error("reembedAll: embedding service is not initialized.");
+  }
+  if (!store.isAvailable()) {
+    throw new Error("reembedAll: SurrealStore is not initialized.");
+  }
+
+  const perTable: Record<VectorTable, number> = Object.fromEntries(
+    VECTOR_TABLES.map(t => [t, 0]),
+  ) as Record<VectorTable, number>;
+  let approxChars = 0;
+
+  for (const table of tables) {
+    // Count the rows we'll touch up front so onProgress can report
+    // progress against a total. Cheap with the embedding_provider index.
+    const countRows = await store.queryFirst<{ count: number }>(
+      `SELECT count() AS count FROM ${table}
+       WHERE embedding != NONE AND embedding_provider = $provider
+       GROUP ALL`,
+      { provider: fromProvider },
+    );
+    const tableTotal = Number(countRows[0]?.count ?? 0);
+    if (tableTotal === 0) continue;
+
+    let tableProcessed = 0;
+    while (true) {
+      const rows = await store.queryFirst<Record<string, unknown>>(
+        `SELECT ${SELECT_FIELDS[table]} FROM ${table}
+         WHERE embedding != NONE AND embedding_provider = $provider
+         LIMIT $lim`,
+        { provider: fromProvider, lim: batchSize },
+      );
+      if (rows.length === 0) break;
+
+      const extract = TEXT_EXTRACTORS[table];
+      const texts = rows.map(r => extract(r));
+      // Skip blanks: nothing useful to embed, but we still need to flip
+      // the provider tag so the row stops matching the FROM filter and
+      // the loop terminates. We set embedding to NONE to keep it out of
+      // the index entirely.
+      const blankIndices: number[] = [];
+      const realIndices: number[] = [];
+      const realTexts: string[] = [];
+      for (let i = 0; i < rows.length; i++) {
+        const t = texts[i];
+        if (!t || t.trim().length === 0) blankIndices.push(i);
+        else { realIndices.push(i); realTexts.push(t); }
+      }
+
+      // Sum chars before any embed call so dry-run accumulates the same
+      // way as the real run.
+      for (const t of realTexts) approxChars += t.length;
+
+      if (dryRun) {
+        // Count and continue without writing.
+        tableProcessed += rows.length;
+        perTable[table] = tableProcessed;
+        opts.onProgress?.({
+          table,
+          batchSize: rows.length,
+          tableProcessed,
+          tableTotal,
+        });
+        // In dry-run we cannot move past this batch (we did not flip
+        // provider tags), so break after recording the first batch's
+        // count and rely on the up-front count() instead.
+        perTable[table] = tableTotal;
+        break;
+      }
+
+      // Real run: embed in one batched call (provider implementations
+      // chunk internally if needed).
+      let vecs: number[][] = [];
+      if (realTexts.length > 0) {
+        vecs = await embeddings.embedBatch(realTexts);
+        if (vecs.length !== realTexts.length) {
+          throw new Error(
+            `reembedAll[${table}]: embedBatch returned ${vecs.length} vectors for ${realTexts.length} inputs.`,
+          );
+        }
+      }
+
+      // Write back: one UPDATE per row. Could be batched into a single
+      // queryBatch call for speed, but the simpler form is easier to
+      // reason about for resumability and is bounded by batchSize.
+      for (let j = 0; j < realIndices.length; j++) {
+        const row = rows[realIndices[j]];
+        const id = String(row.id);
+        try {
+          await store.queryExec(
+            `UPDATE ${id} SET embedding = $emb, embedding_provider = $provider`,
+            { emb: vecs[j], provider: toProvider },
+          );
+        } catch (e) {
+          swallow.warn(`reembed:update:${table}`, e);
+        }
+      }
+      // Blank-text rows: drop the embedding and flip the tag so they
+      // exit the FROM filter (otherwise we loop forever).
+      for (const idx of blankIndices) {
+        const row = rows[idx];
+        const id = String(row.id);
+        try {
+          await store.queryExec(
+            `UPDATE ${id} SET embedding = NONE, embedding_provider = NONE`,
+          );
+        } catch (e) {
+          swallow.warn(`reembed:blank:${table}`, e);
+        }
+      }
+
+      tableProcessed += rows.length;
+      perTable[table] = tableProcessed;
+      opts.onProgress?.({
+        table,
+        batchSize: rows.length,
+        tableProcessed,
+        tableTotal,
+      });
+
+      // Loop again unless the batch was undersized (no more to do).
+      if (rows.length < batchSize) break;
+    }
+  }
+
+  const total = Object.values(perTable).reduce((a, b) => a + b, 0);
+  return {
+    total,
+    perTable,
+    approxChars,
+    approxTokens: approxTokenCount(approxChars),
+    dryRun,
+    durationMs: Date.now() - startedAt,
+  };
+}
+
+/**
+ * Format a result for human display. Used by the CLI; exposed so callers
+ * who embed the migrator into their own UIs can reuse the formatting.
+ */
+export function formatResult(result: ReembedResult, toProvider: string): string {
+  const lines: string[] = [];
+  lines.push(result.dryRun ? "DRY RUN — no writes performed." : "Migration complete.");
+  lines.push(`Target provider: ${toProvider}`);
+  lines.push(`Rows ${result.dryRun ? "to be migrated" : "migrated"}: ${result.total}`);
+  for (const t of VECTOR_TABLES) {
+    const n = result.perTable[t];
+    if (n > 0) lines.push(`  ${t}: ${n}`);
+  }
+  lines.push(`Approx input: ${result.approxChars.toLocaleString()} chars (~${result.approxTokens.toLocaleString()} tokens)`);
+  // text-embedding-3-small is $0.02/1M tokens; -3-large is $0.13/1M.
+  // We don't know which model the caller is using, so report both.
+  const small = (result.approxTokens / 1_000_000) * 0.02;
+  const large = (result.approxTokens / 1_000_000) * 0.13;
+  lines.push(`Estimated cost: $${small.toFixed(4)} (text-embedding-3-small) | $${large.toFixed(4)} (text-embedding-3-large)`);
+  lines.push(`Duration: ${(result.durationMs / 1000).toFixed(2)}s`);
+  return lines.join("\n");
+}

package/src/model-resolution.ts

@@ -0,0 +1,98 @@
+export interface ResolveModelRefInput {
+  explicitProvider?: unknown;
+  explicitModel?: unknown;
+  config?: unknown;
+  runtimeDefaults?: unknown;
+}
+
+export interface ResolvedModelRef {
+  provider: string;
+  modelId: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null
+    ? value as Record<string, unknown>
+    : null;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+}
+
+function unwrapModelRef(value: unknown): string | undefined {
+  const direct = nonEmptyString(value);
+  if (direct) return direct;
+
+  const record = asRecord(value);
+  if (!record) return undefined;
+
+  return unwrapModelRef(record.primary) ?? unwrapModelRef(record.id);
+}
+
+function defaultModelFromConfig(config: unknown): string | undefined {
+  const cfg = asRecord(config);
+  const agents = asRecord(cfg?.agents);
+  const defaults = asRecord(agents?.defaults);
+  return unwrapModelRef(defaults?.model);
+}
+
+function defaultModelFromRuntime(runtimeDefaults: unknown): string | undefined {
+  const defaults = asRecord(runtimeDefaults);
+  return unwrapModelRef(defaults?.model);
+}
+
+function providerFromRuntime(runtimeDefaults: unknown): string | undefined {
+  const defaults = asRecord(runtimeDefaults);
+  return nonEmptyString(defaults?.provider);
+}
+
+function splitQualifiedModelRef(modelRef: string): { provider: string; modelId: string } | null {
+  const slash = modelRef.indexOf("/");
+  if (slash <= 0 || slash === modelRef.length - 1) return null;
+  return {
+    provider: modelRef.slice(0, slash),
+    modelId: modelRef.slice(slash + 1),
+  };
+}
+
+function chooseModelRef(input: ResolveModelRefInput): { modelRef: string; explicit: boolean } | null {
+  const explicit = unwrapModelRef(input.explicitModel);
+  if (explicit) return { modelRef: explicit, explicit: true };
+
+  const configDefault = defaultModelFromConfig(input.config);
+  if (configDefault) return { modelRef: configDefault, explicit: false };
+
+  const runtimeDefault = defaultModelFromRuntime(input.runtimeDefaults);
+  if (runtimeDefault) return { modelRef: runtimeDefault, explicit: false };
+
+  return null;
+}
+
+export function resolveModelRef(input: ResolveModelRefInput): ResolvedModelRef {
+  const chosen = chooseModelRef(input);
+
+  if (!chosen) {
+    throw new Error("No LLM model configured for KongBrain internal completion");
+  }
+
+  const explicitProvider = nonEmptyString(input.explicitProvider);
+  if (chosen.explicit && explicitProvider) {
+    return { provider: explicitProvider, modelId: chosen.modelRef };
+  }
+
+  const qualified = splitQualifiedModelRef(chosen.modelRef);
+  if (qualified) return qualified;
+
+  const provider =
+    explicitProvider ??
+    providerFromRuntime(input.runtimeDefaults);
+
+  if (!provider) {
+    throw new Error(`No LLM provider configured for model "${chosen.modelRef}"`);
+  }
+
+  return { provider, modelId: chosen.modelRef };
+}

package/src/reflection.ts

@@ -179,15 +179,17 @@ export async function generateReflection(
       try { reflEmb = await embeddings.embed(reflectionText); } catch (e) { swallow("reflection:ok", e); }
     }
 
-    // Dedup: skip if a very similar reflection already exists
+    // Dedup: skip if a very similar reflection already exists. Filter by
+    // provider so we don't dedup against vectors in a different space.
     if (reflEmb?.length) {
       const existing = await store.queryFirst<{ id: string; importance: number; score: number }>(
         `SELECT id, importance,
                 vector::similarity::cosine(embedding, $vec) AS score
          FROM reflection
          WHERE embedding != NONE AND array::len(embedding) > 0
+           AND embedding_provider = $provider
          ORDER BY score DESC LIMIT 1`,
-        { vec: reflEmb },
+        { vec: reflEmb, provider: embeddings.providerId },
       );
       const top = existing[0];
       if (top && typeof top.score === "number" && top.score > 0.85) {
@@ -207,7 +209,10 @@ export async function generateReflection(
       severity,
       importance: 7.0,
     };
-    if (reflEmb?.length) record.embedding = reflEmb;
+    if (reflEmb?.length) {
+      record.embedding = reflEmb;
+      record.embedding_provider = embeddings.providerId;
+    }
 
     const rows = await store.queryFirst<{ id: string }>(
       `CREATE reflection CONTENT $record RETURN id`,
@@ -242,8 +247,9 @@ export async function retrieveReflections(
               vector::similarity::cosine(embedding, $vec) AS score
        FROM reflection
        WHERE embedding != NONE AND array::len(embedding) > 0
+         AND embedding_provider = $provider
        ORDER BY score DESC LIMIT $lim`,
-      { vec: queryVec, lim: limit },
+      { vec: queryVec, lim: limit, provider: store.getActiveProvider() },
     );
 
     return rows

package/src/schema-loader.ts

@@ -12,12 +12,30 @@ import { fileURLToPath } from "node:url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export function loadSchema(): string {
+const DEFAULT_EMBEDDING_DIMENSIONS = 1024;
+const DIMENSION_PLACEHOLDER = "__KONGBRAIN_EMBEDDING_DIMENSIONS__";
+
+export interface LoadSchemaOptions {
+  embeddingDimensions?: number;
+}
+
+function normalizeDimensions(value: unknown): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0
+    ? value
+    : DEFAULT_EMBEDDING_DIMENSIONS;
+}
+
+export function loadSchema(options: LoadSchemaOptions = {}): string {
   const primary = join(__dirname, "schema.surql");
+  let schema: string;
   try {
-    return readFileSync(primary, "utf-8");
+    schema = readFileSync(primary, "utf-8");
   } catch {
     // Dev fallback: compiled output lives in dist/, schema source in src/
-    return readFileSync(join(__dirname, "..", "src", "schema.surql"), "utf-8");
+    schema = readFileSync(join(__dirname, "..", "src", "schema.surql"), "utf-8");
   }
+  return schema.replaceAll(
+    DIMENSION_PLACEHOLDER,
+    String(normalizeDimensions(options.embeddingDimensions)),
+  );
 }

package/src/schema.surql

@@ -39,10 +39,12 @@ DEFINE FIELD IF NOT EXISTS type ON artifact TYPE string;
 DEFINE FIELD IF NOT EXISTS description ON artifact TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS content_hash ON artifact TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS embedding ON artifact TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON artifact TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS tags ON artifact TYPE option<array>;
 DEFINE FIELD IF NOT EXISTS created_at ON artifact TYPE datetime DEFAULT time::now();
-DEFINE INDEX IF NOT EXISTS artifact_vec_idx ON artifact FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS artifact_vec_idx ON artifact FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
 DEFINE INDEX IF NOT EXISTS artifact_type_idx ON artifact FIELDS type;
+DEFINE INDEX IF NOT EXISTS artifact_emb_provider_idx ON artifact FIELDS embedding_provider;
 
 -- ============================================================
 -- PILLAR 5: Concept (semantic knowledge nodes)
@@ -52,6 +54,7 @@ DEFINE TABLE IF NOT EXISTS concept SCHEMALESS;
 UPDATE concept SET content = name WHERE content = NONE AND name != NONE;
 DEFINE FIELD IF NOT EXISTS content ON concept TYPE string;
 DEFINE FIELD IF NOT EXISTS embedding ON concept TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON concept TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS stability ON concept TYPE float DEFAULT 1.0;
 DEFINE FIELD IF NOT EXISTS confidence ON concept TYPE float DEFAULT 1.0;
 DEFINE FIELD IF NOT EXISTS access_count ON concept TYPE int DEFAULT 0;
@@ -59,7 +62,8 @@ DEFINE FIELD IF NOT EXISTS tags ON concept TYPE option<array>;
 DEFINE FIELD IF NOT EXISTS source ON concept TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS created_at ON concept TYPE datetime DEFAULT time::now();
 DEFINE FIELD IF NOT EXISTS last_accessed ON concept TYPE option<datetime>;
-DEFINE INDEX IF NOT EXISTS concept_vec_idx ON concept FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS concept_vec_idx ON concept FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
+DEFINE INDEX IF NOT EXISTS concept_emb_provider_idx ON concept FIELDS embedding_provider;
 
 -- ============================================================
 -- Conversation turns (the workhorse table)
@@ -71,15 +75,17 @@ DEFINE FIELD IF NOT EXISTS text ON turn TYPE string;
 -- Migration: ensure embedding is optional (SurrealDB 3.0 HNSW requires this for nullable embeddings)
 REMOVE FIELD IF EXISTS embedding ON turn;
 DEFINE FIELD embedding ON turn TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON turn TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS timestamp ON turn TYPE datetime DEFAULT time::now();
 DEFINE FIELD IF NOT EXISTS created_at ON turn TYPE datetime DEFAULT time::now();
 DEFINE FIELD IF NOT EXISTS token_count ON turn TYPE option<int>;
 DEFINE FIELD IF NOT EXISTS tool_name ON turn TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS model ON turn TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS usage ON turn TYPE option<object>;
-DEFINE INDEX IF NOT EXISTS turn_vec_idx ON turn FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS turn_vec_idx ON turn FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
 DEFINE INDEX IF NOT EXISTS turn_session_idx ON turn FIELDS session_id;
 DEFINE INDEX IF NOT EXISTS turn_tool_name_idx ON turn FIELDS tool_name;
+DEFINE INDEX IF NOT EXISTS turn_emb_provider_idx ON turn FIELDS embedding_provider;
 
 -- Identity chunks (agent persona / identity)
 DEFINE TABLE IF NOT EXISTS identity_chunk SCHEMALESS;
@@ -88,8 +94,10 @@ DEFINE FIELD IF NOT EXISTS source ON identity_chunk TYPE string;
 DEFINE FIELD IF NOT EXISTS chunk_index ON identity_chunk TYPE int;
 DEFINE FIELD IF NOT EXISTS text ON identity_chunk TYPE string;
 DEFINE FIELD IF NOT EXISTS embedding ON identity_chunk TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON identity_chunk TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS importance ON identity_chunk TYPE float DEFAULT 0.5;
-DEFINE INDEX IF NOT EXISTS identity_vec_idx ON identity_chunk FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS identity_vec_idx ON identity_chunk FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
+DEFINE INDEX IF NOT EXISTS identity_emb_provider_idx ON identity_chunk FIELDS embedding_provider;
 
 -- Sessions (lightweight, links to task for 5-pillar integration)
 DEFINE TABLE IF NOT EXISTS session SCHEMALESS;
@@ -106,6 +114,7 @@ DEFINE FIELD IF NOT EXISTS cleanup_completed ON session TYPE bool DEFAULT false;
 DEFINE TABLE IF NOT EXISTS memory SCHEMALESS;
 DEFINE FIELD IF NOT EXISTS text ON memory TYPE string;
 DEFINE FIELD IF NOT EXISTS embedding ON memory TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON memory TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS importance ON memory TYPE float DEFAULT 0.5;
 DEFINE FIELD IF NOT EXISTS confidence ON memory TYPE float DEFAULT 1.0;
 DEFINE FIELD IF NOT EXISTS access_count ON memory TYPE int DEFAULT 0;
@@ -116,8 +125,9 @@ DEFINE FIELD IF NOT EXISTS last_accessed ON memory TYPE option<datetime>;
 DEFINE FIELD IF NOT EXISTS status ON memory TYPE option<string> DEFAULT "active";
 DEFINE FIELD IF NOT EXISTS resolved_at ON memory TYPE option<datetime>;
 DEFINE FIELD IF NOT EXISTS resolved_by ON memory TYPE option<string>;
-DEFINE INDEX IF NOT EXISTS memory_vec_idx ON memory FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS memory_vec_idx ON memory FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
 DEFINE INDEX IF NOT EXISTS memory_category_idx ON memory FIELDS category;
+DEFINE INDEX IF NOT EXISTS memory_emb_provider_idx ON memory FIELDS embedding_provider;
 
 -- ============================================================
 -- GRAPH EDGES: Turn-level
@@ -257,6 +267,7 @@ DEFINE TABLE IF NOT EXISTS skill SCHEMALESS;
 DEFINE FIELD IF NOT EXISTS name ON skill TYPE string;
 DEFINE FIELD IF NOT EXISTS description ON skill TYPE string;
 DEFINE FIELD IF NOT EXISTS embedding ON skill TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON skill TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS preconditions ON skill TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS steps ON skill TYPE option<array>;
 DEFINE FIELD IF NOT EXISTS postconditions ON skill TYPE option<string>;
@@ -265,8 +276,9 @@ DEFINE FIELD IF NOT EXISTS failure_count ON skill TYPE int DEFAULT 0;
 DEFINE FIELD IF NOT EXISTS avg_duration_ms ON skill TYPE float DEFAULT 0.0;
 DEFINE FIELD IF NOT EXISTS last_used ON skill TYPE option<datetime>;
 DEFINE FIELD IF NOT EXISTS created_at ON skill TYPE datetime DEFAULT time::now();
-DEFINE INDEX IF NOT EXISTS skill_vec_idx ON skill FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS skill_vec_idx ON skill FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
 DEFINE INDEX IF NOT EXISTS skill_active_idx ON skill FIELDS active;
+DEFINE INDEX IF NOT EXISTS skill_emb_provider_idx ON skill FIELDS embedding_provider;
 
 DEFINE TABLE IF NOT EXISTS skill_from_task TYPE RELATION IN skill OUT task;
 DEFINE TABLE IF NOT EXISTS skill_uses_concept TYPE RELATION IN skill OUT concept;
@@ -278,12 +290,14 @@ DEFINE TABLE IF NOT EXISTS reflection SCHEMALESS;
 DEFINE FIELD IF NOT EXISTS session_id ON reflection TYPE string;
 DEFINE FIELD IF NOT EXISTS text ON reflection TYPE string;
 DEFINE FIELD IF NOT EXISTS embedding ON reflection TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON reflection TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS category ON reflection TYPE string DEFAULT "efficiency"; -- failure_pattern | efficiency | approach_strategy
 DEFINE FIELD IF NOT EXISTS severity ON reflection TYPE string DEFAULT "minor"; -- minor | moderate | critical
 DEFINE FIELD IF NOT EXISTS importance ON reflection TYPE float DEFAULT 7.0;
 DEFINE FIELD IF NOT EXISTS access_count ON reflection TYPE int DEFAULT 0;
 DEFINE FIELD IF NOT EXISTS created_at ON reflection TYPE datetime DEFAULT time::now();
-DEFINE INDEX IF NOT EXISTS reflection_vec_idx ON reflection FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS reflection_vec_idx ON reflection FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
+DEFINE INDEX IF NOT EXISTS reflection_emb_provider_idx ON reflection FIELDS embedding_provider;
 
 DEFINE TABLE IF NOT EXISTS reflects_on TYPE RELATION IN reflection OUT session;
 
@@ -329,10 +343,12 @@ DEFINE FIELD IF NOT EXISTS session_id ON monologue TYPE string;
 DEFINE FIELD IF NOT EXISTS category ON monologue TYPE string;
 DEFINE FIELD IF NOT EXISTS content ON monologue TYPE string;
 DEFINE FIELD IF NOT EXISTS embedding ON monologue TYPE option<array<float>>;
+DEFINE FIELD IF NOT EXISTS embedding_provider ON monologue TYPE option<string>;
 DEFINE FIELD IF NOT EXISTS timestamp ON monologue TYPE datetime DEFAULT time::now();
 DEFINE INDEX IF NOT EXISTS monologue_session ON monologue FIELDS session_id;
 DEFINE INDEX IF NOT EXISTS monologue_category ON monologue FIELDS category;
-DEFINE INDEX IF NOT EXISTS monologue_vec_idx ON monologue FIELDS embedding HNSW DIMENSION 1024 DIST COSINE;
+DEFINE INDEX IF NOT EXISTS monologue_vec_idx ON monologue FIELDS embedding HNSW DIMENSION __KONGBRAIN_EMBEDDING_DIMENSIONS__ DIST COSINE;
+DEFINE INDEX IF NOT EXISTS monologue_emb_provider_idx ON monologue FIELDS embedding_provider;
 
 -- Fibonacci resurfacing: proactive memory that fades over time
 -- Memories flagged as surfaceable get a next_surface_at timestamp.
@@ -384,3 +400,16 @@ DEFINE FIELD IF NOT EXISTS created_at ON graduation_event TYPE datetime DEFAULT
 -- 768d → 1024d migration completed; REMOVE INDEX / UPDATE stale
 -- embeddings removed to avoid destroying live HNSW indexes on
 -- every startup.
+
+-- embedding_provider backfill: any existing row with an embedding but no
+-- provider tag was written by the original local BGE-M3 model. This is
+-- idempotent (the WHERE clause skips already-tagged rows) so it is safe
+-- to leave running on every startup.
+UPDATE turn           SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE concept        SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE memory         SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE artifact       SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE identity_chunk SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE skill          SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE reflection     SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;
+UPDATE monologue      SET embedding_provider = "local-bge-m3" WHERE embedding != NONE AND embedding_provider = NONE;

package/src/skills.ts

@@ -127,7 +127,10 @@ export async function extractSkill(
       confidence: 1.0,
       active: true,
     };
-    if (skillEmb?.length) record.embedding = skillEmb;
+    if (skillEmb?.length) {
+      record.embedding = skillEmb;
+      record.embedding_provider = embeddings.providerId;
+    }
 
     const rows = await store.queryFirst<{ id: string }>(
       `CREATE skill CONTENT $record RETURN id`,
@@ -170,8 +173,9 @@ export async function supersedeOldSkills(
        WHERE id != $sid
          AND (active = NONE OR active = true)
          AND embedding != NONE AND array::len(embedding) > 0
+         AND embedding_provider = $provider
        ORDER BY score DESC LIMIT 5`,
-      { vec: newEmb, sid: newSkillId },
+      { vec: newEmb, sid: newSkillId, provider: store.getActiveProvider() },
     );
     for (const row of rows) {
       if ((row.score ?? 0) >= 0.82) {
@@ -204,9 +208,11 @@ export async function findRelevantSkills(
               avg_duration_ms AS avgDurationMs,
               vector::similarity::cosine(embedding, $vec) AS score
        FROM skill
-       WHERE embedding != NONE AND array::len(embedding) > 0 AND (active = NONE OR active = true)
+       WHERE embedding != NONE AND array::len(embedding) > 0
+         AND embedding_provider = $provider
+         AND (active = NONE OR active = true)
        ORDER BY score DESC LIMIT $lim`,
-      { vec: queryVec, lim: limit },
+      { vec: queryVec, lim: limit, provider: store.getActiveProvider() },
     );
 
     return rows
@@ -345,7 +351,10 @@ export async function graduateCausalToSkills(
         confidence: 1.0,
         active: true,
       };
-      if (skillEmb?.length) record.embedding = skillEmb;
+      if (skillEmb?.length) {
+        record.embedding = skillEmb;
+        record.embedding_provider = embeddings.providerId;
+      }
 
       const rows = await store.queryFirst<{ id: string }>(
         `CREATE skill CONTENT $record RETURN id`,