kongbrain 0.3.12 → 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.12
+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.12",
+  "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/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 ---
 
@@ -170,29 +170,23 @@ export async function writeExtractionResults(
     }
   }
 
-  // ── Phase 2: Create mentions edges (turn → concept) using LLM concepts ─
-  // Links batch turns to extracted concepts, replacing regex-based extraction.
+  // ── 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 (extractedConceptIds.length > 0 && turns && turns.length > 0) {
-    const turnIds = turns.map(t => t.turnId).filter((id): id is string => !!id);
-    for (const turnId of turnIds) {
-      for (const conceptId of extractedConceptIds) {
-        store.relate(turnId, "mentions", conceptId)
-          .catch(e => swallow("daemon:mentions", e));
-      }
+  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 ───────────────────────
 
-  /** Link a source node to all extracted concepts via the given edge. */
-  const linkToConcepts = async (sourceId: string, edgeName: string) => {
-    for (const conceptId of extractedConceptIds) {
-      await store.relate(sourceId, edgeName, conceptId)
-        .catch(e => swallow(`daemon:${edgeName}`, e));
-    }
-  };
-
   const writeOps: Promise<void>[] = [];
 
   // 1. Causal chains
@@ -260,7 +254,7 @@ export async function writeExtractionResults(
         }
         const memId = await store.createMemory(text, emb, 9, "correction", sessionId);
         if (memId) {
-          await linkToConcepts(memId, "about_concept");
+          await linkToRelevantConcepts(memId, "about_concept", text, store, embeddings, "daemon:correction:about_concept");
         }
       })());
     }
@@ -279,7 +273,7 @@ export async function writeExtractionResults(
         }
         const memId = await store.createMemory(text, emb, 7, "preference", sessionId);
         if (memId) {
-          await linkToConcepts(memId, "about_concept");
+          await linkToRelevantConcepts(memId, "about_concept", text, store, embeddings, "daemon:preference:about_concept");
         }
       })());
     }
@@ -300,7 +294,7 @@ export async function writeExtractionResults(
         }
         const artId = await store.createArtifact(a.path, a.action ?? "modified", desc, emb);
         if (artId) {
-          await linkToConcepts(artId, "artifact_mentions");
+          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)
@@ -324,7 +318,7 @@ export async function writeExtractionResults(
         }
         const memId = await store.createMemory(text, emb, 7, "decision", sessionId);
         if (memId) {
-          await linkToConcepts(memId, "about_concept");
+          await linkToRelevantConcepts(memId, "about_concept", text, store, embeddings, "daemon:decision:about_concept");
         }
       })());
     }

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

@@ -692,9 +692,17 @@ export class SurrealStore {
     );
     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;