kongbrain 0.3.11 → 0.3.14

package/README.github.md

@@ -60,15 +60,13 @@ npm install -g openclaw
 
 Install SurrealDB via your platform's package manager (see [surrealdb.com/install](https://surrealdb.com/docs/surrealdb/installation)):
 
+macOS:
 ```bash
-# macOS
 brew install surrealdb/tap/surreal
-
-# Linux (Debian/Ubuntu)
-curl -sSf https://install.surrealdb.com | sh
-export PATH="$HOME/.surrealdb:$PATH"
 ```
 
+Linux — see `https://surrealdb.com/docs/surrealdb/installation` for your distro.
+
 Then start it locally, **change the credentials before use**:
 
 ```bash
@@ -88,11 +86,13 @@ docker run -d --name surrealdb -p 127.0.0.1:8042:8000 \
 
 ### 3. Install KongBrain
 
+From ClawHub (recommended):
 ```bash
-# From ClawHub (recommended)
 openclaw plugins install clawhub:kongbrain
+```
 
-# From npm (fallback)
+From npm:
+```bash
 openclaw plugins install kongbrain
 ```
 

package/README.md

@@ -50,15 +50,13 @@ npm install -g openclaw
 
 Install SurrealDB via your platform's package manager (see [surrealdb.com/install](https://surrealdb.com/docs/surrealdb/installation)):
 
+macOS:
 ```bash
-# macOS
 brew install surrealdb/tap/surreal
-
-# Linux (Debian/Ubuntu)
-curl -sSf https://install.surrealdb.com | sh
-export PATH="$HOME/.surrealdb:$PATH"
 ```
 
+Linux — see `https://surrealdb.com/docs/surrealdb/installation` for your distro.
+
 Then start it locally — **change the credentials before use**:
 
 ```bash
@@ -78,11 +76,13 @@ docker run -d --name surrealdb -p 127.0.0.1:8042:8000 \
 
 ### 3. Install KongBrain
 
+From ClawHub (recommended):
 ```bash
-# From ClawHub (recommended)
 openclaw plugins install clawhub:kongbrain
+```
 
-# From npm (fallback)
+From npm:
+```bash
 openclaw plugins install kongbrain
 ```
 

package/README.npm.md

@@ -50,15 +50,13 @@ npm install -g openclaw
 
 Install SurrealDB via your platform's package manager (see [surrealdb.com/install](https://surrealdb.com/docs/surrealdb/installation)):
 
+macOS:
 ```bash
-# macOS
 brew install surrealdb/tap/surreal
-
-# Linux (Debian/Ubuntu)
-curl -sSf https://install.surrealdb.com | sh
-export PATH="$HOME/.surrealdb:$PATH"
 ```
 
+Linux — see `https://surrealdb.com/docs/surrealdb/installation` for your distro.
+
 Then start it locally — **change the credentials before use**:
 
 ```bash
@@ -78,11 +76,13 @@ docker run -d --name surrealdb -p 127.0.0.1:8042:8000 \
 
 ### 3. Install KongBrain
 
+From ClawHub (recommended):
 ```bash
-# From ClawHub (recommended)
 openclaw plugins install clawhub:kongbrain
+```
 
-# From npm (fallback)
+From npm:
+```bash
 openclaw plugins install kongbrain
 ```
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: kongbrain
 description: Graph-backed persistent memory engine for OpenClaw. Replaces the default context window with SurrealDB + vector embeddings that learn across sessions.
-version: 0.3.11
+version: 0.3.14
 homepage: https://github.com/42U/kongbrain
 metadata:
   openclaw:
@@ -48,23 +48,22 @@ KongBrain gives your OpenClaw agent persistent, structured memory:
 
 See the official install guide: https://surrealdb.com/docs/surrealdb/installation
 
-Platform packages:
-
+macOS:
 ```bash
-# macOS
 brew install surrealdb/tap/surreal
+```
 
-# Linux (Debian/Ubuntu)
-curl -sSf https://install.surrealdb.com | sh
+Linux — see `https://surrealdb.com/docs/surrealdb/installation` for your distro.
 
-# Docker
+Docker:
+```bash
 docker pull surrealdb/surrealdb:latest
 ```
 
 ### Start SurrealDB
 
+Local only (recommended) — use strong credentials in production:
 ```bash
-# Local only (recommended) - use strong credentials in production
 surreal start --user youruser --pass yourpass --bind 127.0.0.1:8000 surrealkv:~/.kongbrain/surreal.db
 ```
 

package/openclaw.plugin.json

@@ -3,6 +3,10 @@
   "name": "KongBrain",
   "description": "Graph-backed cognitive context engine with SurrealDB + BGE-M3",
   "kind": "context-engine",
+  "requires": {
+    "bins": ["surreal"],
+    "env": ["SURREAL_URL", "SURREAL_USER", "SURREAL_PASS", "SURREAL_NS", "SURREAL_DB"]
+  },
   "uiHints": {
     "surreal.url": {
       "label": "SurrealDB URL",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kongbrain",
-  "version": "0.3.11",
+  "version": "0.3.14",
   "description": "Graph-backed persistent memory engine for OpenClaw. Replaces the default context window with SurrealDB + vector embeddings that learn across sessions.",
   "type": "module",
   "license": "MIT",

package/scripts/backfill-embeddings.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env npx tsx
+/**
+ * One-shot backfill: embed all concepts that have `content` but no embedding vector.
+ *
+ * Usage:
+ *   cd /home/zero/voidorigin/kongbrain
+ *   npx tsx scripts/backfill-embeddings.ts
+ *
+ * Env vars (all have defaults matching the plugin config):
+ *   SURREAL_URL       (default: ws://localhost:8042/rpc)
+ *   SURREAL_USER      (default: root)
+ *   SURREAL_PASS      (default: root)
+ *   SURREAL_NS        (default: kong)
+ *   SURREAL_DB        (default: memory)
+ *   EMBED_MODEL_PATH  (default: ~/.node-llama-cpp/models/bge-m3-q4_k_m.gguf)
+ */
+
+import { parsePluginConfig } from "../src/config.js";
+import { SurrealStore } from "../src/surreal.js";
+import { EmbeddingService } from "../src/embeddings.js";
+
+async function main() {
+  const config = parsePluginConfig();
+  const store = new SurrealStore(config.surreal);
+  const embeddings = new EmbeddingService(config.embedding);
+
+  console.log("[backfill] Connecting to SurrealDB...");
+  await store.initialize();
+
+  console.log("[backfill] Loading embedding model...");
+  await embeddings.initialize();
+
+  // Find concepts with content but no embedding
+  const bare = await store.queryFirst<{ id: string; content: string }>(
+    `SELECT id, content FROM concept
+     WHERE content IS NOT NONE AND content != ''
+       AND (embedding IS NONE OR array::len(embedding) = 0)`,
+  );
+
+  console.log(`[backfill] Found ${bare.length} concepts needing embeddings.`);
+  if (bare.length === 0) {
+    console.log("[backfill] Nothing to do.");
+    await embeddings.dispose();
+    return;
+  }
+
+  let ok = 0;
+  let fail = 0;
+
+  for (const concept of bare) {
+    const id = String(concept.id);
+    try {
+      const vec = await embeddings.embed(concept.content);
+      await store.queryExec(
+        `UPDATE ${id} SET embedding = $emb`,
+        { emb: vec },
+      );
+      ok++;
+      if (ok % 10 === 0) console.log(`[backfill] ${ok}/${bare.length} done...`);
+    } catch (e) {
+      fail++;
+      console.error(`[backfill] Failed ${id}: ${e}`);
+    }
+  }
+
+  console.log(`[backfill] Complete. Embedded: ${ok}, Failed: ${fail}`);
+  await embeddings.dispose();
+  process.exit(0);
+}
+
+main().catch((e) => {
+  console.error("[backfill] Fatal:", e);
+  process.exit(1);
+});

package/src/concept-extract.ts

@@ -79,6 +79,48 @@ export async function upsertAndLinkConcepts(
   }
 }
 
+/**
+ * Embedding-based concept linking — replaces batch-local linkToConcepts.
+ *
+ * Given a source node (memory, artifact, turn, skill) and its text content,
+ * embeds the text and finds the top-N most similar concepts in the graph,
+ * then creates edges from source → concept via the specified relation.
+ *
+ * This ensures linking works even when relevant concepts were created in
+ * prior batches or sessions — no batch-timing dependency.
+ */
+export async function linkToRelevantConcepts(
+  sourceId: string,
+  edgeName: string,
+  text: string,
+  store: SurrealStore,
+  embeddings: EmbeddingService,
+  logTag: string,
+  limit = 5,
+  threshold = 0.65,
+): Promise<void> {
+  if (!embeddings.isAvailable() || !text) return;
+  try {
+    const vec = await embeddings.embed(text);
+    if (!vec?.length) return;
+    const matches = await store.queryFirst<{ id: string; score: number }>(
+      `SELECT id, vector::similarity::cosine(embedding, $vec) AS score
+       FROM concept
+       WHERE embedding != NONE AND array::len(embedding) > 0
+       ORDER BY score DESC
+       LIMIT $lim`,
+      { vec, lim: limit },
+    );
+    for (const m of matches) {
+      if (m.score < threshold) break;
+      await store.relate(sourceId, edgeName, String(m.id))
+        .catch(e => swallow(`${logTag}:relate`, e));
+    }
+  } catch (e) {
+    swallow(`${logTag}:embed`, e);
+  }
+}
+
 /**
  * Link a newly-upserted concept to existing concepts via narrower/broader
  * edges when one concept's name is a substring of the other (indicating a

package/src/context-engine.ts

@@ -49,7 +49,6 @@ import { extractSkill } from "./skills.js";
 import { generateReflection } from "./reflection.js";
 import { graduateCausalToSkills } from "./skills.js";
 import { swallow } from "./errors.js";
-import { upsertAndLinkConcepts } from "./concept-extract.js";
 
 export class KongBrainContextEngine implements ContextEngine {
   readonly info: ContextEngineInfo = {
@@ -265,11 +264,7 @@ export class KongBrainContextEngine implements ContextEngine {
               .catch(e => swallow.warn("ingest:responds_to", e));
           }
 
-          // Extract and link concepts for both user and assistant turns
-          if (worthEmbedding) {
-            extractAndLinkConcepts(turnId, text, this.state, session)
-              .catch(e => swallow.warn("ingest:concepts", e));
-          }
+          // Concept extraction (mentions edges) handled by daemon via LLM
         }
 
         if (role === "user") {
@@ -400,7 +395,7 @@ export class KongBrainContextEngine implements ContextEngine {
         const turnData = recentTurns.map(t => ({
           role: t.role as "user" | "assistant",
           text: t.text,
-          turnId: (t as any).id,
+          turnId: String((t as any).id ?? ""),
         }));
 
         // Gather retrieved memory IDs for dedup
@@ -441,7 +436,7 @@ export class KongBrainContextEngine implements ContextEngine {
               const turnData = recentTurns.map(t => ({
                 role: t.role as "user" | "assistant",
                 text: t.text,
-                turnId: (t as any).id,
+                turnId: String((t as any).id ?? ""),
               }));
               session.daemon!.sendTurnBatch(turnData, [...session.pendingThinking], []);
             })
@@ -537,16 +532,3 @@ function hasSemantic(text: string): boolean {
 }
 
 // --- Concept extraction (delegates to shared helper) ---
-
-async function extractAndLinkConcepts(
-  turnId: string,
-  text: string,
-  state: GlobalPluginState,
-  session?: SessionState,
-): Promise<void> {
-  await upsertAndLinkConcepts(
-    turnId, "mentions", text,
-    state.store, state.embeddings, "concepts",
-    session ? { taskId: session.taskId, projectId: session.projectId } : undefined,
-  );
-}

package/src/daemon-manager.ts

@@ -121,7 +121,7 @@ export function startMemoryDaemon(
       }
     }
 
-    const counts = await writeExtractionResults(result, sessionId, store, embeddings, priorState, taskId, projectId);
+    const counts = await writeExtractionResults(result, sessionId, store, embeddings, priorState, taskId, projectId, turns);
     extractedTurnCount = turns.length;
   }
 

package/src/daemon-types.ts

@@ -5,6 +5,7 @@
 export interface TurnData {
   role: string;
   text: string;
+  turnId?: string;
   tool_name?: string;
   tool_result?: string;
   file_paths?: string[];

package/src/hooks/after-tool-call.ts

@@ -5,7 +5,7 @@
 import type { GlobalPluginState } from "../state.js";
 import { recordToolOutcome } from "../retrieval-quality.js";
 import { swallow } from "../errors.js";
-import { upsertAndLinkConcepts } from "../concept-extract.js";
+import { linkToRelevantConcepts } from "../concept-extract.js";
 
 export function createAfterToolCallHandler(state: GlobalPluginState) {
   return async (
@@ -128,8 +128,8 @@ async function trackArtifact(
       await state.store.relate(artifactId, "used_in", projectId)
         .catch(e => swallow.warn("artifact:used_in", e));
     }
-    // Link artifact to concepts it mentions
-    await upsertAndLinkConcepts(
+    // Link artifact to concepts it mentions (embedding-based similarity)
+    await linkToRelevantConcepts(
       artifactId, "artifact_mentions", description,
       state.store, state.embeddings, "artifact:concepts",
     );

package/src/memory-daemon.ts

@@ -13,7 +13,7 @@ import type { SurrealStore } from "./surreal.js";
 import type { EmbeddingService } from "./embeddings.js";
 import { swallow } from "./errors.js";
 import { assertRecordId } from "./surreal.js";
-import { upsertAndLinkConcepts, linkConceptHierarchy } from "./concept-extract.js";
+import { upsertAndLinkConcepts, linkConceptHierarchy, linkToRelevantConcepts } from "./concept-extract.js";
 
 // --- Build the extraction prompt ---
 
@@ -127,12 +127,66 @@ export async function writeExtractionResults(
   priorState: PriorExtractions,
   taskId?: string,
   projectId?: string,
+  turns?: TurnData[],
 ): Promise<ExtractionCounts> {
   const counts: ExtractionCounts = {
     causal: 0, monologue: 0, resolved: 0, concept: 0,
     correction: 0, preference: 0, artifact: 0, decision: 0, skill: 0,
   };
 
+  // ── Phase 1: Upsert concepts first (LLM-extracted) so we have IDs ────
+  // These IDs are used to create mentions/about_concept/artifact_mentions
+  // edges in Phase 2, replacing the old regex-based extraction.
+
+  const extractedConceptIds: string[] = [];
+
+  if (Array.isArray(result.concepts) && result.concepts.length > 0) {
+    for (const c of result.concepts.slice(0, 11)) {
+      if (!c.name || !c.content) continue;
+      if (priorState.conceptNames.includes(c.name)) continue;
+      counts.concept++;
+      priorState.conceptNames.push(c.name);
+      try {
+        let emb: number[] | null = null;
+        if (embeddings.isAvailable()) {
+          try { emb = await embeddings.embed(c.content); } catch (e) { swallow("daemon:embedConcept", e); }
+        }
+        const conceptId = await store.upsertConcept(c.content, emb, `daemon:${sessionId}`);
+        if (conceptId) {
+          extractedConceptIds.push(conceptId);
+          await linkConceptHierarchy(conceptId, c.name, store, embeddings, "daemon:concept");
+          if (taskId) {
+            await store.relate(conceptId, "derived_from", taskId)
+              .catch(e => swallow("daemon:concept:derived_from", e));
+          }
+          if (projectId) {
+            await store.relate(conceptId, "relevant_to", projectId)
+              .catch(e => swallow("daemon:concept:relevant_to", e));
+          }
+        }
+      } catch (e) {
+        swallow.warn("daemon:upsertConcept", e);
+      }
+    }
+  }
+
+  // ── Phase 2: Create mentions edges (turn → concept) via embedding similarity ─
+  // Each turn's text is embedded and matched against existing concepts in the
+  // graph. This replaces the old batch-local linking that only worked when
+  // concepts and turns were extracted in the same batch.
+
+  if (turns && turns.length > 0) {
+    const turnIds = turns.filter(t => t.turnId && t.text).slice(0, 15);
+    for (const t of turnIds) {
+      await linkToRelevantConcepts(
+        t.turnId!, "mentions", t.text!,
+        store, embeddings, "daemon:mentions", 5, 0.65,
+      );
+    }
+  }
+
+  // ── Phase 3: All other extractions in parallel ───────────────────────
+
   const writeOps: Promise<void>[] = [];
 
   // 1. Causal chains
@@ -187,37 +241,7 @@ export async function writeExtractionResults(
     })());
   }
 
-  // 4. Concepts
-  if (Array.isArray(result.concepts) && result.concepts.length > 0) {
-    for (const c of result.concepts.slice(0, 11)) {
-      if (!c.name || !c.content) continue;
-      if (priorState.conceptNames.includes(c.name)) continue;
-      counts.concept++;
-      priorState.conceptNames.push(c.name);
-      writeOps.push((async () => {
-        let emb: number[] | null = null;
-        if (embeddings.isAvailable()) {
-          try { emb = await embeddings.embed(c.content); } catch (e) { swallow("daemon:embedConcept", e); }
-        }
-        const conceptId = await store.upsertConcept(c.content, emb, `daemon:${sessionId}`);
-        if (conceptId) {
-          await linkConceptHierarchy(conceptId, c.name, store, embeddings, "daemon:concept");
-          // derived_from: concept → task
-          if (taskId) {
-            await store.relate(conceptId, "derived_from", taskId)
-              .catch(e => swallow("daemon:concept:derived_from", e));
-          }
-          // relevant_to: concept → project
-          if (projectId) {
-            await store.relate(conceptId, "relevant_to", projectId)
-              .catch(e => swallow("daemon:concept:relevant_to", e));
-          }
-        }
-      })());
-    }
-  }
-
-  // 5. Corrections — high-importance memories
+  // 4. Corrections — high-importance memories, linked to LLM-extracted concepts
   if (Array.isArray(result.corrections) && result.corrections.length > 0) {
     for (const c of result.corrections.slice(0, 5)) {
       if (!c.original || !c.correction) continue;
@@ -230,13 +254,13 @@ export async function writeExtractionResults(
         }
         const memId = await store.createMemory(text, emb, 9, "correction", sessionId);
         if (memId) {
-          await upsertAndLinkConcepts(memId, "about_concept", text, store, embeddings, "daemon:correction", { taskId, projectId });
+          await linkToRelevantConcepts(memId, "about_concept", text, store, embeddings, "daemon:correction:about_concept");
         }
       })());
     }
   }
 
-  // 6. User preferences
+  // 5. User preferences
   if (Array.isArray(result.preferences) && result.preferences.length > 0) {
     for (const p of result.preferences.slice(0, 5)) {
       if (!p.preference) continue;
@@ -249,13 +273,13 @@ export async function writeExtractionResults(
         }
         const memId = await store.createMemory(text, emb, 7, "preference", sessionId);
         if (memId) {
-          await upsertAndLinkConcepts(memId, "about_concept", text, store, embeddings, "daemon:preference", { taskId, projectId });
+          await linkToRelevantConcepts(memId, "about_concept", text, store, embeddings, "daemon:preference:about_concept");
         }
       })());
     }
   }
 
-  // 7. Artifacts
+  // 6. Artifacts
   if (Array.isArray(result.artifacts) && result.artifacts.length > 0) {
     for (const a of result.artifacts.slice(0, 10)) {
       if (!a.path) continue;
@@ -270,7 +294,7 @@ export async function writeExtractionResults(
         }
         const artId = await store.createArtifact(a.path, a.action ?? "modified", desc, emb);
         if (artId) {
-          await upsertAndLinkConcepts(artId, "artifact_mentions", `${a.path} ${desc}`, store, embeddings, "daemon:artifact", { taskId, projectId });
+          await linkToRelevantConcepts(artId, "artifact_mentions", `${a.path} ${desc}`, store, embeddings, "daemon:artifact:artifact_mentions");
           // used_in: artifact → project
           if (projectId) {
             await store.relate(artId, "used_in", projectId)
@@ -281,7 +305,7 @@ export async function writeExtractionResults(
     }
   }
 
-  // 8. Decisions
+  // 7. Decisions
   if (Array.isArray(result.decisions) && result.decisions.length > 0) {
     for (const d of result.decisions.slice(0, 6)) {
       if (!d.decision) continue;
@@ -294,13 +318,13 @@ export async function writeExtractionResults(
         }
         const memId = await store.createMemory(text, emb, 7, "decision", sessionId);
         if (memId) {
-          await upsertAndLinkConcepts(memId, "about_concept", text, store, embeddings, "daemon:decision", { taskId, projectId });
+          await linkToRelevantConcepts(memId, "about_concept", text, store, embeddings, "daemon:decision:about_concept");
         }
       })());
     }
   }
 
-  // 9. Skills
+  // 8. Skills — get ID back to create skill_from_task + skill_uses_concept edges
   if (Array.isArray(result.skills) && result.skills.length > 0) {
     for (const s of result.skills.slice(0, 3)) {
       if (!s.name || !Array.isArray(s.steps) || s.steps.length === 0) continue;
@@ -313,21 +337,35 @@ export async function writeExtractionResults(
         if (embeddings.isAvailable()) {
           try { emb = await embeddings.embed(content); } catch (e) { swallow("daemon:embedSkill", e); }
         }
-        await store.queryExec(
-          `CREATE skill CONTENT $record`,
-          {
-            record: {
-              name: String(s.name).slice(0, 100),
-              description: content,
-              content,
-              steps: s.steps.map((st: string) => String(st).slice(0, 200)),
-              trigger_context: String(s.trigger_context ?? "").slice(0, 200),
-              tags: ["auto-extracted"],
-              session_id: sessionId,
-              ...(emb ? { embedding: emb } : {}),
+        try {
+          const rows = await store.queryFirst<{ id: string }>(
+            `CREATE skill CONTENT $record RETURN id`,
+            {
+              record: {
+                name: String(s.name).slice(0, 100),
+                description: content,
+                content,
+                steps: s.steps.map((st: string) => String(st).slice(0, 200)),
+                trigger_context: String(s.trigger_context ?? "").slice(0, 200),
+                tags: ["auto-extracted"],
+                session_id: sessionId,
+                ...(emb ? { embedding: emb } : {}),
+              },
             },
-          },
-        ).catch(e => swallow.warn("daemon:createSkill", e));
+          );
+          const skillId = rows[0]?.id ? String(rows[0].id) : null;
+          if (skillId) {
+            // skill_from_task: skill → task
+            if (taskId) {
+              await store.relate(skillId, "skill_from_task", taskId)
+                .catch(e => swallow.warn("daemon:skill:skill_from_task", e));
+            }
+            // skill_uses_concept: skill → concept
+            await upsertAndLinkConcepts(skillId, "skill_uses_concept", content, store, embeddings, "daemon:skill:concepts");
+          }
+        } catch (e) {
+          swallow.warn("daemon:createSkill", e);
+        }
       })());
     }
   }

package/src/schema.surql

@@ -47,6 +47,8 @@ DEFINE INDEX IF NOT EXISTS artifact_vec_idx ON artifact FIELDS embedding HNSW DI
 -- PILLAR 5: Concept (semantic knowledge nodes)
 -- ============================================================
 DEFINE TABLE IF NOT EXISTS concept SCHEMALESS;
+-- Recovery: restore content from name if the rename migration ran before revert
+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 stability ON concept TYPE float DEFAULT 1.0;

package/src/skills.ts

@@ -13,7 +13,7 @@ import type { CompleteFn } from "./state.js";
 import type { EmbeddingService } from "./embeddings.js";
 import type { SurrealStore } from "./surreal.js";
 import { swallow } from "./errors.js";
-import { upsertAndLinkConcepts } from "./concept-extract.js";
+import { linkToRelevantConcepts } from "./concept-extract.js";
 import { assertRecordId } from "./surreal.js";
 
 // --- Types ---
@@ -122,7 +122,7 @@ export async function extractSkill(
       await supersedeOldSkills(skillId, skillEmb ?? [], store);
       // skill_uses_concept: skill → concept
       const skillDesc = `${parsed.name} ${parsed.description ?? ""} ${(parsed.preconditions ?? "")}`;
-      await upsertAndLinkConcepts(skillId, "skill_uses_concept", skillDesc, store, embeddings, "skills:concepts");
+      await linkToRelevantConcepts(skillId, "skill_uses_concept", skillDesc, store, embeddings, "skills:concepts");
     }
 
     return skillId || null;
@@ -334,7 +334,7 @@ export async function graduateCausalToSkills(
         await supersedeOldSkills(gradSkillId, skillEmb ?? [], store);
         // skill_uses_concept: skill → concept
         const skillDesc = `${parsed.name} ${parsed.description ?? ""}`;
-        await upsertAndLinkConcepts(gradSkillId, "skill_uses_concept", skillDesc, store, embeddings, "skills:graduate:concepts");
+        await linkToRelevantConcepts(gradSkillId, "skill_uses_concept", skillDesc, store, embeddings, "skills:graduate:concepts");
         created++;
       }
     }

package/src/surreal.ts

@@ -684,15 +684,25 @@ export class SurrealStore {
     embedding: number[] | null,
     source?: string,
   ): Promise<string> {
+    if (!content?.trim()) return "";
+    content = content.trim();
     const rows = await this.queryFirst<{ id: string }>(
       `SELECT id FROM concept WHERE string::lowercase(content) = string::lowercase($content) LIMIT 1`,
       { content },
     );
     if (rows.length > 0) {
       const id = String(rows[0].id);
-      await this.queryExec(
-        `UPDATE ${id} SET access_count += 1, last_accessed = time::now()`,
-      );
+      // Backfill embedding if the existing concept is missing one
+      if (embedding?.length) {
+        await this.queryExec(
+          `UPDATE ${id} SET access_count += 1, last_accessed = time::now(), embedding = IF embedding IS NONE OR array::len(embedding) = 0 THEN $emb ELSE embedding END`,
+          { emb: embedding },
+        );
+      } else {
+        await this.queryExec(
+          `UPDATE ${id} SET access_count += 1, last_accessed = time::now()`,
+        );
+      }
       return id;
     }
     const emb = embedding?.length ? embedding : undefined;