kongbrain 0.3.3 → 0.3.8

package/.clawhubignore

@@ -0,0 +1,24 @@
+# Binary assets (not text-based, rejected by clawhub)
+*.png
+*.jpg
+*.jpeg
+*.gif
+
+# Dev tooling
+.claude/
+test/
+vitest.config.ts
+*.test.ts
+
+# Build/deps
+node_modules/
+dist/
+package-lock.json
+
+# Secrets/runtime
+.env
+.env.*
+.kongbrain-handoff.json
+
+# Internal docs
+UPSTREAM-PROPOSALS.md

package/README.md

@@ -1,10 +1,7 @@
-<div align="center">
-
 # KongBrain
 
-![KongBrain](KongClaw.png)
-
 [![npm](https://img.shields.io/npm/v/kongbrain?style=for-the-badge&logo=npm&color=cb3837)](https://www.npmjs.com/package/kongbrain)
+[![ClawHub](https://img.shields.io/badge/ClawHub-kongbrain-ff6b35?style=for-the-badge)](https://clawhub.ai/packages/kongbrain)
 [![GitHub Stars](https://img.shields.io/github/stars/42U/kongbrain?style=for-the-badge&logo=github&color=gold)](https://github.com/42U/kongbrain)
 [![License: MIT](https://img.shields.io/github/license/42U/kongbrain?style=for-the-badge&logo=opensourceinitiative&color=blue)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-20+-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://nodejs.org)
@@ -20,8 +17,6 @@ Your assistant stops forgetting. Then it starts getting better.
 
 [Quick Start](#quick-start) | [Architecture](#architecture) | [How It Works](#how-it-works) | [Tools](#tools) | [Development](#development)
 
-</div>
-
 ---
 
 ## What Changes
@@ -47,29 +42,46 @@ npm install -g openclaw
 
 ### 2. Start SurrealDB
 
-Pick one:
+Install SurrealDB via your platform's package manager (see [surrealdb.com/install](https://surrealdb.com/docs/surrealdb/installation)):
 
 ```bash
-# Native install
+# macOS
+brew install surrealdb/tap/surreal
+
+# Linux (Debian/Ubuntu)
 curl -sSf https://install.surrealdb.com | sh
 export PATH="$HOME/.surrealdb:$PATH"
-surreal start --user root --pass root --bind 0.0.0.0:8042 surrealkv:~/.kongbrain/surreal.db
 ```
 
+Then start it locally — **change the credentials before use**:
+
+```bash
+surreal start --user youruser --pass yourpass --bind 127.0.0.1:8042 surrealkv:~/.kongbrain/surreal.db
+```
+
+Or with Docker:
+
 ```bash
-# Docker
-docker run -d --name surrealdb -p 8042:8000 \
+docker run -d --name surrealdb -p 127.0.0.1:8042:8000 \
   -v ~/.kongbrain/surreal-data:/data \
   surrealdb/surrealdb:latest start \
-  --user root --pass root surrealkv:/data/surreal.db
+  --user youruser --pass yourpass surrealkv:/data/surreal.db
 ```
 
+> **Security note:** Always bind to `127.0.0.1` (not `0.0.0.0`) unless you need remote access. Never use default credentials in production.
+
 ### 3. Install KongBrain
 
 ```bash
+# From ClawHub (recommended)
+openclaw plugins install clawhub:kongbrain
+
+# From npm (fallback)
 openclaw plugins install kongbrain
 ```
 
+> **Note:** Bare `openclaw plugins install kongbrain` checks ClawHub first, then falls back to npm. Use the `clawhub:` prefix to install from ClawHub explicitly.
+
 ### 4. Activate
 
 Add to your OpenClaw config (`~/.openclaw/openclaw.json`):
@@ -93,7 +105,7 @@ openclaw tui
 
 That's it. KongBrain uses whatever LLM provider and model you already have configured in OpenClaw (Anthropic, OpenAI, Google, Ollama, whatever). No separate API keys needed for the brain itself.
 
-The BGE-M3 embedding model (~420MB) downloads automatically on first startup. All database tables and indexes are created automatically on first run. No manual setup required.
+The BGE-M3 embedding model (~420MB) downloads automatically on first startup from [Hugging Face](https://huggingface.co/BAAI/bge-m3). All database tables and indexes are created automatically on first run. No manual setup required.
 
 <details>
 <summary><strong>Configuration Options</strong></summary>
@@ -102,9 +114,9 @@ All options have sensible defaults. Override via plugin config or environment va
 
 | Option | Env Var | Default |
 |--------|---------|---------|
-| `surreal.url` | `SURREAL_URL` | `ws://localhost:8042/rpc` |
-| `surreal.user` | `SURREAL_USER` | `root` |
-| `surreal.pass` | `SURREAL_PASS` | `root` |
+| `surreal.url` | `SURREAL_URL` | `ws://127.0.0.1:8042/rpc` |
+| `surreal.user` | `SURREAL_USER` | (required) |
+| `surreal.pass` | `SURREAL_PASS` | (required) |
 | `surreal.ns` | `SURREAL_NS` | `kong` |
 | `surreal.db` | `SURREAL_DB` | `memory` |
 | `embedding.modelPath` | `KONGBRAIN_EMBEDDING_MODEL` | Auto-downloaded BGE-M3 Q4_K_M |
@@ -123,9 +135,9 @@ Full config example:
       "kongbrain": {
         "config": {
           "surreal": {
-            "url": "ws://localhost:8042/rpc",
-            "user": "root",
-            "pass": "root",
+            "url": "ws://127.0.0.1:8042/rpc",
+            "user": "youruser",
+            "pass": "yourpass",
             "ns": "kong",
             "db": "memory"
           }
@@ -379,8 +391,4 @@ The lobster doesn't accept contributions. The ape does.
 
 ---
 
-<div align="center">
-
 MIT License | Built by [42U](https://github.com/42U)
-
-</div>

package/SKILL.md

@@ -0,0 +1,110 @@
+---
+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.8
+homepage: https://github.com/42U/kongbrain
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - surreal
+      env:
+        - SURREAL_URL
+        - SURREAL_USER
+        - SURREAL_PASS
+        - SURREAL_NS
+        - SURREAL_DB
+    primaryEnv: SURREAL_URL
+    install:
+      - kind: node
+        package: kongbrain
+        bins: []
+---
+
+# KongBrain
+
+Graph-backed persistent memory engine for OpenClaw. Replaces the default context window with SurrealDB + vector embeddings that learn across sessions.
+
+## What it does
+
+KongBrain gives your OpenClaw agent persistent, structured memory:
+
+- **Session tracking** - records conversations and extracts knowledge automatically
+- **9 memory categories** - knowledge, goals, reflections, handoffs, corrections, preferences, decisions, skills, and causal chains
+- **Vector search** - BGE-M3 embeddings for semantic recall
+- **Graph relationships** - memories linked via SurrealDB graph edges for traversal
+- **Tiered memory** - core memories always loaded, session memories pinned, rest searched on demand
+- **Mid-session extraction** - extracts knowledge during conversation, not just at exit
+- **Crash resilience** - deferred cleanup processes orphaned sessions on next startup
+
+## Requirements
+
+- **SurrealDB** - running instance (local or remote)
+- **Node.js** >= 18
+
+## Setup
+
+### Install SurrealDB
+
+See the official install guide: https://surrealdb.com/docs/surrealdb/installation
+
+Platform packages:
+
+```bash
+# macOS
+brew install surrealdb/tap/surreal
+
+# Linux (Debian/Ubuntu)
+curl -sSf https://install.surrealdb.com | sh
+
+# Docker
+docker pull surrealdb/surrealdb:latest
+```
+
+### Start SurrealDB
+
+```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
+```
+
+> **Security note:** Always bind to `127.0.0.1` (not `0.0.0.0`) unless you specifically need remote access. Change the default credentials before use.
+
+For Docker:
+
+```bash
+docker run -d --name surrealdb -p 127.0.0.1:8000:8000 \
+  -v ~/.kongbrain/surreal-data:/data \
+  surrealdb/surrealdb:latest start \
+  --user youruser --pass yourpass surrealkv:/data/surreal.db
+```
+
+## Configuration
+
+Set environment variables or provide a `.env` file:
+
+```
+SURREAL_URL=ws://127.0.0.1:8000/rpc
+SURREAL_USER=youruser
+SURREAL_PASS=yourpass
+SURREAL_NS=kongbrain
+SURREAL_DB=kongbrain
+```
+
+## Usage
+
+Install as an OpenClaw plugin:
+
+```bash
+openclaw plugins install clawhub:kongbrain
+```
+
+Or via npm:
+
+```bash
+npm install kongbrain
+```
+
+The BGE-M3 embedding model (~420MB) downloads automatically on first startup from Hugging Face (https://huggingface.co/BAAI/bge-m3). All database tables and indexes are created automatically on first run.
+
+KongBrain hooks into OpenClaw's plugin lifecycle automatically. Memory extraction runs in the background via a daemon worker thread.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kongbrain",
-  "version": "0.3.3",
+  "version": "0.3.8",
   "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",
@@ -30,6 +30,14 @@
     ],
     "install": {
       "minHostVersion": ">=2026.3.23"
+    },
+    "compat": {
+      "pluginApi": ">=2026.3.23",
+      "minGatewayVersion": "2026.3.23"
+    },
+    "build": {
+      "openclawVersion": "2026.3.23",
+      "pluginSdkVersion": "2026.3.23"
     }
   },
   "scripts": {

package/src/acan.ts

@@ -13,6 +13,7 @@ import { join } from "node:path";
 import { homedir } from "node:os";
 import { Worker } from "node:worker_threads";
 import type { SurrealStore } from "./surreal.js";
+import { assertRecordId } from "./surreal.js";
 import { swallow } from "./errors.js";
 
 // ── Types ──
@@ -197,9 +198,10 @@ async function fetchTrainingData(store: SurrealStore): Promise<TrainingSample[]>
   const embeddingMap = new Map<string, number[]>();
   for (const mid of uniqueMemIds) {
     try {
+      assertRecordId(mid);
+      // Direct interpolation safe: assertRecordId validates format above
       const flat = await store.queryFirst<{ id: string; embedding: number[] }>(
-        `SELECT id, embedding FROM type::record($mid) WHERE embedding != NONE`,
-        { mid },
+        `SELECT id, embedding FROM ${mid} WHERE embedding != NONE`,
       );
       if (flat[0]?.embedding) embeddingMap.set(mid, flat[0].embedding);
     } catch (e) { swallow("acan:fetchEmb", e); }

package/src/causal.ts

@@ -12,6 +12,7 @@
 import type { EmbeddingService } from "./embeddings.js";
 import type { SurrealStore, VectorSearchResult } from "./surreal.js";
 import { swallow } from "./errors.js";
+import { assertRecordId } from "./surreal.js";
 
 // --- Types ---
 
@@ -133,27 +134,31 @@ export async function queryCausalContext(
          ELSE 0 END AS score`;
 
   for (let hop = 0; hop < hops && frontier.length > 0; hop++) {
-    const queries = frontier.flatMap((id) =>
-      causalEdges.map((edge) =>
+    const queries = frontier.flatMap((id) => {
+      assertRecordId(id);
+      // Direct interpolation safe: assertRecordId validates format above
+      return causalEdges.map((edge) =>
         store.queryFirst<any>(
           `SELECT id, text, importance, access_count AS accessCount,
                   created_at AS timestamp, category, meta::tb(id) AS table${scoreExpr}
-           FROM type::record($nid)->${edge}->? LIMIT 3`,
-          { ...bindings, nid: id },
+           FROM ${id}->${edge}->? LIMIT 3`,
+          bindings,
         ).catch(e => { swallow.warn("causal:edge-query", e); return [] as any[]; }),
-      ),
-    );
+      );
+    });
 
-    const reverseQueries = frontier.flatMap((id) =>
-      causalEdges.map((edge) =>
+    const reverseQueries = frontier.flatMap((id) => {
+      assertRecordId(id);
+      // Direct interpolation safe: assertRecordId validates format above
+      return causalEdges.map((edge) =>
         store.queryFirst<any>(
           `SELECT id, text, importance, access_count AS accessCount,
                   created_at AS timestamp, category, meta::tb(id) AS table${scoreExpr}
-           FROM type::record($nid)<-${edge}<-? LIMIT 3`,
-          { ...bindings, nid: id },
+           FROM ${id}<-${edge}<-? LIMIT 3`,
+          bindings,
         ).catch(e => { swallow.warn("causal:edge-query", e); return [] as any[]; }),
-      ),
-    );
+      );
+    });
 
     const allQueryResults = await Promise.all([...queries, ...reverseQueries]);
     const nextFrontier: string[] = [];

package/src/cognitive-bootstrap.ts

@@ -0,0 +1,159 @@
+/**
+ * Cognitive Bootstrap — teaches the agent HOW to use its own memory system.
+ *
+ * Seeds two types of knowledge on first run:
+ *   1. Tier 0 core memory entries (always loaded every turn) — imperative
+ *      reflexes the agent follows without thinking.
+ *   2. Identity chunks (vector-searchable) — deeper reference material
+ *      that surfaces via similarity when the agent thinks about memory topics.
+ *
+ * The identity chunks in identity.ts tell the agent WHAT it is.
+ * This module tells the agent HOW to operate effectively.
+ */
+import type { SurrealStore } from "./surreal.js";
+import type { EmbeddingService } from "./embeddings.js";
+import { swallow } from "./errors.js";
+
+const BOOTSTRAP_SOURCE = "cognitive_bootstrap";
+
+// ── Tier 0 Core Memory: imperative reflexes loaded every turn ────────────
+
+const CORE_ENTRIES: { text: string; category: string; priority: number }[] = [
+  {
+    text: `MEMORY REFLEX: After completing a task or learning something new: (1) Save the insight to core_memory if it should persist across ALL sessions, or let the daemon extract it if session-scoped. (2) When saving, write the WHAT, WHY, and WHEN-TO-USE in the text — vague entries are useless on recall. (3) Link to existing knowledge by using concept names the graph already contains. Check with recall first.`,
+    category: "operations",
+    priority: 95,
+  },
+  {
+    text: `RECALL BEFORE GUESSING: When uncertain about past decisions, user preferences, project history, or your own capabilities, use the recall tool BEFORE answering. Effective queries: use specific technical terms, file paths, error messages, or concept names — not vague questions. Scope to "memories" for decisions/preferences, "concepts" for technical knowledge, "skills" for procedures, "artifacts" for files.`,
+    category: "operations",
+    priority: 90,
+  },
+  {
+    text: `GRAPH-AWARE SAVING: When you save knowledge (core_memory add, or concepts the daemon extracts), include terms that create graph connectivity. Mention specific file paths (links to artifacts), technical concept names (links to concepts), and session context (links to tasks). Forward traversal: "X caused Y" lets future searches from X find Y. Backward traversal: "Y was caused by X" lets searches from Y find X. Write both directions in your text.`,
+    category: "operations",
+    priority: 85,
+  },
+  {
+    text: `SELF-TEACHING CYCLE: Your memory improves when you (1) use recall to review what you've learned, (2) notice gaps or stale information, (3) update or add core_memory entries to correct them, (4) use introspect periodically to understand your memory depth. Corrections from the user are the highest-value signal — always save them. The daemon extracts automatically, but YOU control core_memory (Tier 0) directly.`,
+    category: "operations",
+    priority: 80,
+  },
+  {
+    text: `MEMORY TOOLS: recall = search graph (use: uncertain, need history, checking prior work). core_memory = manage always-loaded directives (use: permanent lessons, rules, identity updates; add/update/deactivate; Tier 0 = every turn, Tier 1 = this session). introspect = inspect DB health and counts (use: status checks, debugging memory). The daemon extracts 9 types automatically from conversation — you don't need to manually save everything.`,
+    category: "tools",
+    priority: 75,
+  },
+];
+
+// ── Identity Chunks: vector-searchable reference material ────────────────
+
+const IDENTITY_CHUNKS: { text: string; importance: number }[] = [
+  {
+    text: `KongBrain's memory daemon runs in the background and extracts 9 knowledge types from your conversations every ~4K tokens: causal chains (cause->effect from debugging), monologue traces (internal reasoning moments), resolved memories (marking issues done), concepts (technical facts worth remembering), corrections (user correcting you — highest signal), preferences (user workflow/style signals), artifacts (files created/modified/read), decisions (choices with rationale), and skills (multi-step procedures that worked). Quality over quantity — the daemon skips weak extractions. You don't need to manually save what the daemon catches, but you should use core_memory for things you want loaded EVERY turn.`,
+    importance: 0.85,
+  },
+  {
+    text: `Effective recall queries use specific terms that match how knowledge was stored. Search by: file paths ("/src/auth/login.ts"), error messages ("ECONNREFUSED"), concept names ("rate limiting"), decision descriptions ("chose PostgreSQL over MongoDB"), or skill names ("deploy to staging"). The recall tool does vector similarity search plus graph neighbor expansion — top results pull in related nodes via edges. Scope options: "all" (default), "memories" (decisions, corrections, preferences), "concepts" (extracted technical knowledge), "turns" (past conversation), "artifacts" (files), "skills" (learned procedures). Check what's already in your injected context before calling recall.`,
+    importance: 0.85,
+  },
+  {
+    text: `KongBrain's memory lifecycle: During a session, the daemon extracts knowledge incrementally. At session end (or mid-session every ~25K tokens): a handoff note is written (summarizing what happened), skills are extracted from successful multi-step tasks, metacognitive reflections are generated, and causal chains may graduate to skills. At next session start: the wakeup system synthesizes a first-person briefing from the handoff + identity + monologues + depth signals. This means what you save in one session becomes the foundation for the next. The more precisely you save knowledge, the better your future self performs.`,
+    importance: 0.80,
+  },
+  {
+    text: `Graph connectivity determines recall quality. When saving to core_memory or when the daemon extracts concepts, the text content determines which edges form. To ensure forward AND backward traversal: mention specific artifact paths (creates artifact_mentions edges), reference concept names already in the graph (creates about_concept/related_to edges), describe cause-effect relationships explicitly (creates caused_by/supports edges), and note what task or session context produced the knowledge (creates derived_from/part_of edges). Reuse existing concept names for maximum graph connectivity — use introspect or recall to discover what names already exist.`,
+    importance: 0.80,
+  },
+  {
+    text: `Three persistence mechanisms serve different purposes. Core memory (Tier 0): you control directly via the core_memory tool. Always loaded every turn. Use for: permanent operational rules, learned patterns, identity refinements. Budget-constrained (~8% of context). Core memory (Tier 1): pinned for the current session only. Use for: session-specific context like "working on auth refactor" or "user prefers verbose logging". Identity chunks: hardcoded self-knowledge, vector-searchable but not always loaded — surfaces when relevant. Daemon extraction: automatic, runs on conversation content, writes to memory/concept/skill/artifact tables. You don't control daemon extraction directly, but the quality of your conversation affects what gets extracted.`,
+    importance: 0.75,
+  },
+];
+
+/**
+ * Seed cognitive bootstrap knowledge on first run.
+ * Idempotent — checks for existing entries before seeding.
+ */
+export async function seedCognitiveBootstrap(
+  store: SurrealStore,
+  embeddings: EmbeddingService,
+): Promise<{ identitySeeded: number; coreSeeded: number }> {
+  if (!store.isAvailable()) return { identitySeeded: 0, coreSeeded: 0 };
+
+  let identitySeeded = 0;
+  let coreSeeded = 0;
+
+  // ── Core memory Tier 0 (always loaded, no embeddings needed) ───────────
+
+  try {
+    const rows = await store.queryFirst<{ cnt: number }>(
+      `SELECT count() AS cnt FROM core_memory WHERE text CONTAINS 'MEMORY REFLEX' GROUP ALL`,
+    );
+    const hasBootstrap = (rows[0]?.cnt ?? 0) > 0;
+
+    if (!hasBootstrap) {
+      for (const entry of CORE_ENTRIES) {
+        try {
+          await store.createCoreMemory(
+            entry.text,
+            entry.category,
+            entry.priority,
+            0, // Tier 0
+          );
+          coreSeeded++;
+        } catch (e) {
+          swallow.warn("bootstrap:seedCore", e);
+        }
+      }
+    }
+  } catch (e) {
+    swallow.warn("bootstrap:checkCore", e);
+  }
+
+  // ── Identity chunks (vector-searchable, requires embeddings) ───────────
+
+  if (!embeddings.isAvailable()) return { identitySeeded, coreSeeded };
+
+  try {
+    const rows = await store.queryFirst<{ count: number }>(
+      `SELECT count() AS count FROM identity_chunk WHERE source = $source GROUP ALL`,
+      { source: BOOTSTRAP_SOURCE },
+    );
+    const count = rows[0]?.count ?? 0;
+
+    if (count < IDENTITY_CHUNKS.length) {
+      // Clear and re-seed (idempotent on content changes)
+      if (count > 0) {
+        await store.queryExec(
+          `DELETE identity_chunk WHERE source = $source`,
+          { source: BOOTSTRAP_SOURCE },
+        );
+      }
+
+      for (let i = 0; i < IDENTITY_CHUNKS.length; i++) {
+        const chunk = IDENTITY_CHUNKS[i];
+        try {
+          const vec = await embeddings.embed(chunk.text);
+          await store.queryExec(`CREATE identity_chunk CONTENT $data`, {
+            data: {
+              agent_id: "kongbrain",
+              source: BOOTSTRAP_SOURCE,
+              chunk_index: i,
+              text: chunk.text,
+              embedding: vec,
+              importance: chunk.importance,
+            },
+          });
+          identitySeeded++;
+        } catch (e) {
+          swallow.warn("bootstrap:seedIdentityChunk", e);
+        }
+      }
+    }
+  } catch (e) {
+    swallow.warn("bootstrap:checkIdentity", e);
+  }
+
+  return { identitySeeded, coreSeeded };
+}

package/src/cognitive-check.ts

@@ -11,6 +11,7 @@
 import type { CompleteFn, SessionState } from "./state.js";
 import type { SurrealStore } from "./surreal.js";
 import { swallow } from "./errors.js";
+import { assertRecordId } from "./surreal.js";
 
 // --- Types ---
 
@@ -182,15 +183,17 @@ Return ONLY valid JSON.`,
     for (const g of correctionGrades) {
       if (g.learned) {
         // Agent followed the correction unprompted — decay toward background (floor 3)
+        assertRecordId(g.id);
+        // Direct interpolation safe: assertRecordId validates format above
         await store.queryExec(
-          `UPDATE type::record($gid) SET importance = math::max([3, importance - 2])`,
-          { gid: g.id },
+          `UPDATE ${g.id} SET importance = math::max([3, importance - 2])`,
         ).catch(e => swallow.warn("cognitive-check:correctionDecay", e));
       } else {
         // Correction was relevant but agent ignored it — reinforce (cap 9)
+        assertRecordId(g.id);
+        // Direct interpolation safe: assertRecordId validates format above
         await store.queryExec(
-          `UPDATE type::record($gid) SET importance = math::min([9, importance + 1])`,
-          { gid: g.id },
+          `UPDATE ${g.id} SET importance = math::min([9, importance + 1])`,
         ).catch(e => swallow.warn("cognitive-check:correctionReinforce", e));
       }
     }
@@ -219,9 +222,11 @@ Return ONLY valid JSON.`,
     // Mid-session resolution — mark addressed memories immediately
     const resolvedGrades = result.grades.filter(g => g.resolved && g.id.startsWith("memory:"));
     for (const g of resolvedGrades) {
+      assertRecordId(g.id);
+      // Direct interpolation safe: assertRecordId validates format above
       await store.queryExec(
-        `UPDATE type::record($gid) SET status = 'resolved', resolved_at = time::now(), resolved_by = $sid`,
-        { gid: g.id, sid: params.sessionId },
+        `UPDATE ${g.id} SET status = 'resolved', resolved_at = time::now(), resolved_by = $sid`,
+        { sid: params.sessionId },
       ).catch(e => swallow.warn("cognitive-check:resolve", e));
     }
   } catch (e) {
@@ -317,9 +322,12 @@ async function applyRetrievalGrades(
         { id: grade.id, sid: sessionId },
       );
       if (row?.[0]?.id) {
+        const rid = String(row[0].id);
+        assertRecordId(rid);
+        // Direct interpolation safe: assertRecordId validates format above
         await store.queryExec(
-          `UPDATE type::record($rid) SET llm_relevance = $score, llm_relevant = $relevant, llm_reason = $reason`,
-          { rid: String(row[0].id), score: grade.score, relevant: grade.relevant, reason: grade.reason },
+          `UPDATE ${rid} SET llm_relevance = $score, llm_relevant = $relevant, llm_reason = $reason`,
+          { score: grade.score, relevant: grade.relevant, reason: grade.reason },
         );
       }
       // Feed relevance score into the utility cache — drives WMR provenUtility scoring

package/src/deferred-cleanup.ts

@@ -129,6 +129,11 @@ async function processOrphanedSession(
           result = JSON.parse(jsonMatch[0].replace(/,\s*([}\]])/g, "$1"));
         } catch { result = {}; }
       }
+      // Strip prototype pollution keys from LLM-generated JSON
+      const BANNED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+      for (const key of Object.keys(result)) {
+        if (BANNED_KEYS.has(key)) delete (result as any)[key];
+      }
 
       const keys = Object.keys(result);
       console.warn(`[deferred] parsed ${keys.length} keys: ${keys.join(", ")}`);

package/src/handoff-file.ts

@@ -6,7 +6,7 @@
  * so the next session's wakeup has context even before deferred
  * extraction runs.
  */
-import { readFileSync, writeFileSync, unlinkSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, unlinkSync, existsSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 
 const HANDOFF_FILENAME = ".kongbrain-handoff.json";
@@ -29,7 +29,7 @@ export function writeHandoffFileSync(
 ): void {
   try {
     const path = join(workspaceDir, HANDOFF_FILENAME);
-    writeFileSync(path, JSON.stringify(data, null, 2), "utf-8");
+    writeFileSync(path, JSON.stringify(data, null, 2), { encoding: "utf-8", mode: 0o600 });
   } catch {
     // Best-effort — sync exit handler, can't log async
   }
@@ -46,7 +46,19 @@ export function readAndDeleteHandoffFile(
   try {
     const raw = readFileSync(path, "utf-8");
     unlinkSync(path);
-    return JSON.parse(raw) as HandoffFileData;
+    const parsed = JSON.parse(raw);
+    // Runtime validation — reject prototype pollution and malformed data
+    if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    if ("__proto__" in parsed || "constructor" in parsed) return null;
+    const data: HandoffFileData = {
+      sessionId: typeof parsed.sessionId === "string" ? parsed.sessionId.slice(0, 200) : "",
+      timestamp: typeof parsed.timestamp === "string" ? parsed.timestamp.slice(0, 50) : "",
+      userTurnCount: typeof parsed.userTurnCount === "number" ? parsed.userTurnCount : 0,
+      lastUserText: typeof parsed.lastUserText === "string" ? parsed.lastUserText.slice(0, 500) : "",
+      lastAssistantText: typeof parsed.lastAssistantText === "string" ? parsed.lastAssistantText.slice(0, 500) : "",
+      unextractedTokens: typeof parsed.unextractedTokens === "number" ? parsed.unextractedTokens : 0,
+    };
+    return data;
   } catch {
     // Corrupted or deleted between check and read
     try { unlinkSync(path); } catch { /* ignore */ }

package/src/index.ts

@@ -23,6 +23,7 @@ import { createAfterToolCallHandler } from "./hooks/after-tool-call.js";
 import { createLlmOutputHandler } from "./hooks/llm-output.js";
 import { startMemoryDaemon } from "./daemon-manager.js";
 import { seedIdentity } from "./identity.js";
+import { seedCognitiveBootstrap } from "./cognitive-bootstrap.js";
 import { synthesizeWakeup } from "./wakeup.js";
 import { extractSkill } from "./skills.js";
 import { generateReflection, setReflectionContextWindow } from "./reflection.js";
@@ -418,6 +419,13 @@ export default definePluginEntry({
         .then(n => { if (n > 0) logger.info(`Seeded ${n} identity chunks`); })
         .catch(e => swallow.warn("factory:seedIdentity", e));
 
+      seedCognitiveBootstrap(store, embeddings)
+        .then(r => {
+          if (r.identitySeeded > 0 || r.coreSeeded > 0)
+            logger.info(`Cognitive bootstrap: ${r.identitySeeded} identity + ${r.coreSeeded} core`);
+        })
+        .catch(e => swallow.warn("factory:seedBootstrap", e));
+
       return new KongBrainContextEngine(state);
     });
 

package/src/memory-daemon.ts

@@ -12,6 +12,7 @@ import type { TurnData, PriorExtractions } from "./daemon-types.js";
 import type { SurrealStore } from "./surreal.js";
 import type { EmbeddingService } from "./embeddings.js";
 import { swallow } from "./errors.js";
+import { assertRecordId } from "./surreal.js";
 
 // --- Build the extraction prompt ---
 
@@ -172,10 +173,12 @@ export async function writeExtractionResults(
     writeOps.push((async () => {
       for (const memId of result.resolved!.slice(0, 20)) {
         if (typeof memId !== "string" || !RECORD_ID_RE.test(memId)) continue;
+        assertRecordId(memId);
         counts.resolved++;
+        // Direct interpolation safe: assertRecordId validates format above
         await store.queryExec(
-          `UPDATE type::record($mid) SET status = 'resolved', resolved_at = time::now(), resolved_by = $sid`,
-          { mid: memId, sid: sessionId },
+          `UPDATE ${memId} SET status = 'resolved', resolved_at = time::now(), resolved_by = $sid`,
+          { sid: sessionId },
         ).catch(e => swallow.warn("daemon:resolveMemory", e));
       }
     })());

package/src/skills.ts

@@ -13,6 +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 { assertRecordId } from "./surreal.js";
 
 // --- Types ---
 
@@ -237,12 +238,14 @@ export async function recordSkillOutcome(
 
   try {
     const field = success ? "success_count" : "failure_count";
+    assertRecordId(skillId);
+    // Direct interpolation safe: assertRecordId validates format above
     await store.queryExec(
-      `UPDATE type::record($sid) SET
+      `UPDATE ${skillId} SET
         ${field} += 1,
         avg_duration_ms = (avg_duration_ms * (success_count + failure_count - 1) + $dur) / (success_count + failure_count),
         last_used = time::now()`,
-      { sid: skillId, dur: durationMs },
+      { dur: durationMs },
     );
   } catch (e) { swallow("skills:non-critical", e); }
 }

package/src/surreal.ts

@@ -447,10 +447,8 @@ export class SurrealStore {
     assertRecordId(fromId);
     assertRecordId(toId);
     const safeName = edge.replace(/[^a-zA-Z0-9_]/g, "");
-    await this.queryExec(
-      `RELATE type::record($from)->${safeName}->type::record($to)`,
-      { from: fromId, to: toId },
-    );
+    // Direct interpolation safe: assertRecordId validates format above
+    await this.queryExec(`RELATE ${fromId}->${safeName}->${toId}`);
   }
 
   // ── 5-Pillar entity operations ─────────────────────────────────────────
@@ -504,12 +502,12 @@ export class SurrealStore {
   ): Promise<void> {
     assertRecordId(sessionId);
     await this.queryExec(
-      `UPDATE type::record($sid) SET
+      `UPDATE ${sessionId} SET
         turn_count += 1,
         total_input_tokens += $input,
         total_output_tokens += $output,
         last_active = time::now()`,
-      { sid: sessionId, input: inputTokens, output: outputTokens },
+      { input: inputTokens, output: outputTokens },
     );
   }
 
@@ -517,27 +515,25 @@ export class SurrealStore {
     assertRecordId(sessionId);
     if (summary) {
       await this.queryExec(
-        `UPDATE type::record($sid) SET ended_at = time::now(), summary = $summary`,
-        { sid: sessionId, summary },
+        `UPDATE ${sessionId} SET ended_at = time::now(), summary = $summary`,
+        { summary },
       );
     } else {
-      await this.queryExec(`UPDATE type::record($sid) SET ended_at = time::now()`, { sid: sessionId });
+      await this.queryExec(`UPDATE ${sessionId} SET ended_at = time::now()`);
     }
   }
 
   async markSessionActive(sessionId: string): Promise<void> {
     assertRecordId(sessionId);
     await this.queryExec(
-      `UPDATE type::record($sid) SET cleanup_completed = false, last_active = time::now()`,
-      { sid: sessionId },
+      `UPDATE ${sessionId} SET cleanup_completed = false, last_active = time::now()`,
     );
   }
 
   async markSessionEnded(sessionId: string): Promise<void> {
     assertRecordId(sessionId);
     await this.queryExec(
-      `UPDATE type::record($sid) SET ended_at = time::now(), cleanup_completed = true`,
-      { sid: sessionId },
+      `UPDATE ${sessionId} SET ended_at = time::now(), cleanup_completed = true`,
     );
   }
 
@@ -555,8 +551,7 @@ export class SurrealStore {
     assertRecordId(sessionId);
     assertRecordId(taskId);
     await this.queryExec(
-      `RELATE type::record($from)->session_task->type::record($to)`,
-      { from: sessionId, to: taskId },
+      `RELATE ${sessionId}->session_task->${taskId}`,
     );
   }
 
@@ -564,8 +559,7 @@ export class SurrealStore {
     assertRecordId(taskId);
     assertRecordId(projectId);
     await this.queryExec(
-      `RELATE type::record($from)->task_part_of->type::record($to)`,
-      { from: taskId, to: projectId },
+      `RELATE ${taskId}->task_part_of->${projectId}`,
     );
   }
 
@@ -573,8 +567,7 @@ export class SurrealStore {
     assertRecordId(agentId);
     assertRecordId(taskId);
     await this.queryExec(
-      `RELATE type::record($from)->performed->type::record($to)`,
-      { from: agentId, to: taskId },
+      `RELATE ${agentId}->performed->${taskId}`,
     );
   }
 
@@ -582,8 +575,7 @@ export class SurrealStore {
     assertRecordId(agentId);
     assertRecordId(projectId);
     await this.queryExec(
-      `RELATE type::record($from)->owns->type::record($to)`,
-      { from: agentId, to: projectId },
+      `RELATE ${agentId}->owns->${projectId}`,
     );
   }
 
@@ -625,7 +617,7 @@ export class SurrealStore {
     for (let hop = 0; hop < hops && frontier.length > 0; hop++) {
       const forwardQueries = frontier.flatMap((id) =>
         forwardEdges.map((edge) =>
-          this.queryFirst<any>(`${selectFields} FROM type::record($nid)->${edge}->? LIMIT 3`, { ...bindings, nid: id }).catch(
+          this.queryFirst<any>(`${selectFields} FROM ${id}->${edge}->? LIMIT 3`, bindings).catch(
             (e) => {
               swallow.warn("surreal:graphExpand", e);
               return [] as Record<string, unknown>[];
@@ -636,7 +628,7 @@ export class SurrealStore {
 
       const reverseQueries = frontier.flatMap((id) =>
         reverseEdges.map((edge) =>
-          this.queryFirst<any>(`${selectFields} FROM type::record($nid)<-${edge}<-? LIMIT 3`, { ...bindings, nid: id }).catch(
+          this.queryFirst<any>(`${selectFields} FROM ${id}<-${edge}<-? LIMIT 3`, bindings).catch(
             (e) => {
               swallow.warn("surreal:graphExpand", e);
               return [] as Record<string, unknown>[];
@@ -687,8 +679,7 @@ export class SurrealStore {
       try {
         assertRecordId(id);
         await this.queryExec(
-          `UPDATE type::record($rid) SET access_count += 1, last_accessed = time::now()`,
-          { rid: id },
+          `UPDATE ${id} SET access_count += 1, last_accessed = time::now()`,
         );
       } catch (e) {
         swallow.warn("surreal:bumpAccessCounts", e);
@@ -710,8 +701,7 @@ export class SurrealStore {
     if (rows.length > 0) {
       const id = String(rows[0].id);
       await this.queryExec(
-        `UPDATE type::record($cid) SET access_count += 1, last_accessed = time::now()`,
-        { cid: id },
+        `UPDATE ${id} SET access_count += 1, last_accessed = time::now()`,
       );
       return id;
     }
@@ -768,8 +758,8 @@ export class SurrealStore {
         const existing = dupes[0];
         const newImp = Math.max(existing.importance ?? 0, importance);
         await this.queryExec(
-          `UPDATE type::record($eid) SET access_count += 1, importance = $imp, last_accessed = time::now()`,
-          { eid: String(existing.id), imp: newImp },
+          `UPDATE ${String(existing.id)} SET access_count += 1, importance = $imp, last_accessed = time::now()`,
+          { imp: newImp },
         );
         return String(existing.id);
       }
@@ -844,7 +834,7 @@ export class SurrealStore {
     assertRecordId(id);
     const ALLOWED_FIELDS = new Set(["text", "category", "priority", "tier", "active"]);
     const sets: string[] = [];
-    const bindings: Record<string, unknown> = { _rid: id };
+    const bindings: Record<string, unknown> = {};
     for (const [key, val] of Object.entries(fields)) {
       if (val !== undefined && ALLOWED_FIELDS.has(key)) {
         sets.push(`${key} = $${key}`);
@@ -854,7 +844,7 @@ export class SurrealStore {
     if (sets.length === 0) return false;
     sets.push("updated_at = time::now()");
     const rows = await this.queryFirst<{ id: string }>(
-      `UPDATE type::record($_rid) SET ${sets.join(", ")} RETURN id`,
+      `UPDATE ${id} SET ${sets.join(", ")} RETURN id`,
       bindings,
     );
     return rows.length > 0;
@@ -863,8 +853,7 @@ export class SurrealStore {
   async deleteCoreMemory(id: string): Promise<void> {
     assertRecordId(id);
     await this.queryExec(
-      `UPDATE type::record($rid) SET active = false, updated_at = time::now()`,
-      { rid: id },
+      `UPDATE ${id} SET active = false, updated_at = time::now()`,
     );
   }
 
@@ -1013,9 +1002,9 @@ export class SurrealStore {
 
   async resolveMemory(memoryId: string): Promise<boolean> {
     try {
+      assertRecordId(memoryId);
       await this.queryFirst(
-        `UPDATE type::record($id) SET status = 'resolved', resolved_at = time::now()`,
-        { id: memoryId },
+        `UPDATE ${memoryId} SET status = 'resolved', resolved_at = time::now()`,
       );
       return true;
     } catch (e) {
@@ -1223,10 +1212,10 @@ export class SurrealStore {
           assertRecordId(String(keep));
           assertRecordId(String(drop));
           await this.queryExec(
-            `UPDATE type::record($kid) SET access_count += 1, importance = math::max([importance, $imp])`,
-            { kid: String(keep), imp: dupe.importance },
+            `UPDATE ${String(keep)} SET access_count += 1, importance = math::max([importance, $imp])`,
+            { imp: dupe.importance },
           );
-          await this.queryExec(`DELETE type::record($did)`, { did: String(drop) });
+          await this.queryExec(`DELETE ${String(drop)}`);
           seen.add(String(drop));
           merged++;
         }
@@ -1252,8 +1241,8 @@ export class SurrealStore {
           const emb = await embedFn(mem.text);
           if (!emb) continue;
           await this.queryExec(
-            `UPDATE type::record($mid) SET embedding = $emb`,
-            { mid: String(mem.id), emb },
+            `UPDATE ${String(mem.id)} SET embedding = $emb`,
+            { emb },
           );
 
           const dupes = await this.queryFirst<{
@@ -1283,10 +1272,10 @@ export class SurrealStore {
             assertRecordId(String(keep));
             assertRecordId(String(drop));
             await this.queryExec(
-              `UPDATE type::record($kid) SET access_count += 1, importance = math::max([importance, $imp])`,
-              { kid: String(keep), imp: dupe.importance },
+              `UPDATE ${String(keep)} SET access_count += 1, importance = math::max([importance, $imp])`,
+              { imp: dupe.importance },
             );
-            await this.queryExec(`DELETE type::record($did)`, { did: String(drop) });
+            await this.queryExec(`DELETE ${String(drop)}`);
             seen.add(String(drop));
             merged++;
           }
@@ -1387,8 +1376,8 @@ export class SurrealStore {
   ): Promise<void> {
     assertRecordId(checkpointId);
     await this.queryExec(
-      `UPDATE type::record($cpid) SET status = "complete", memory_id = $mid`,
-      { cpid: checkpointId, mid: memoryId },
+      `UPDATE ${checkpointId} SET status = "complete", memory_id = $mid`,
+      { mid: memoryId },
     );
   }
 

package/src/tools/introspect.ts

@@ -207,7 +207,8 @@ async function verifyAction(store: any, recordId?: string) {
     return { content: [{ type: "text" as const, text: `Error: invalid record ID "${recordId}".` }], details: null };
   }
 
-  const rows = await store.queryFirst(`SELECT * FROM type::record($rid)`, { rid: recordId });
+  // Direct interpolation safe: assertRecordId validates format above
+  const rows = await store.queryFirst(`SELECT * FROM ${recordId}`);
   if (rows.length === 0) {
     return { content: [{ type: "text" as const, text: `Record not found: ${recordId}` }], details: { exists: false } };
   }