kongbrain 0.1.0

package/src/cognitive-check.ts

@@ -0,0 +1,330 @@
+/**
+ * Cognitive Check — Periodic reasoning over retrieved context.
+ *
+ * Fires every few turns to evaluate what was retrieved, produce behavioral
+ * directives for the next turn, and grade retrieval quality with LLM-judged
+ * relevance scores that feed back into ACAN training.
+ *
+ * Ported from kongbrain — per-session state via WeakMap, takes SurrealStore param.
+ */
+
+import type { CompleteFn, SessionState } from "./state.js";
+import type { SurrealStore } from "./surreal.js";
+import { swallow } from "./errors.js";
+
+// --- Types ---
+
+export interface CognitiveDirective {
+  type: "repeat" | "continuation" | "contradiction" | "noise" | "insight";
+  target: string;
+  instruction: string;
+  priority: "high" | "medium" | "low";
+}
+
+export interface RetrievalGrade {
+  id: string;
+  relevant: boolean;
+  reason: string;
+  score: number;
+  learned: boolean;
+  resolved: boolean;
+}
+
+export interface UserPreference {
+  observation: string;
+  confidence: "high" | "medium";
+}
+
+export interface CognitiveCheckResult {
+  directives: CognitiveDirective[];
+  grades: RetrievalGrade[];
+  sessionContinuity: "continuation" | "repeat" | "new_topic" | "tangent";
+  preferences: UserPreference[];
+}
+
+export interface CognitiveCheckInput {
+  sessionId: string;
+  userQuery: string;
+  responseText: string;
+  retrievedNodes: { id: string; text: string; score: number; table: string }[];
+  recentTurns: { role: string; text: string }[];
+}
+
+// --- Per-session state ---
+
+interface CognitiveState {
+  pendingDirectives: CognitiveDirective[];
+  sessionContinuity: string;
+  checkInFlight: boolean;
+  suppressedNodeIds: Set<string>;
+}
+
+const sessionState = new WeakMap<SessionState, CognitiveState>();
+
+function getState(session: SessionState): CognitiveState {
+  let state = sessionState.get(session);
+  if (!state) {
+    state = {
+      pendingDirectives: [],
+      sessionContinuity: "new_topic",
+      checkInFlight: false,
+      suppressedNodeIds: new Set(),
+    };
+    sessionState.set(session, state);
+  }
+  return state;
+}
+
+// --- Constants ---
+
+const DIRECTIVE_TYPES = new Set(["repeat", "continuation", "contradiction", "noise", "insight"]);
+const PRIORITIES = new Set(["high", "medium", "low"]);
+const CONTINUITY_TYPES = new Set(["continuation", "repeat", "new_topic", "tangent"]);
+const VALID_RECORD_ID = /^[a-z_]+:[a-zA-Z0-9_]+$/;
+
+// --- Public API ---
+
+/** Returns true on turn 2, then every 3 turns (2, 5, 8, 11...). False if in-flight. */
+export function shouldRunCheck(turnCount: number, session: SessionState): boolean {
+  const state = getState(session);
+  if (state.checkInFlight) return false;
+  if (turnCount < 2) return false;
+  return turnCount === 2 || (turnCount - 2) % 3 === 0;
+}
+
+export function getPendingDirectives(session: SessionState): CognitiveDirective[] {
+  return getState(session).pendingDirectives;
+}
+
+export function clearPendingDirectives(session: SessionState): void {
+  getState(session).pendingDirectives = [];
+}
+
+export function getSessionContinuity(session: SessionState): string {
+  return getState(session).sessionContinuity;
+}
+
+export function getSuppressedNodeIds(session: SessionState): ReadonlySet<string> {
+  return getState(session).suppressedNodeIds;
+}
+
+/** Fire-and-forget LLM call. Stores directives, writes grades to DB. */
+export async function runCognitiveCheck(
+  params: CognitiveCheckInput,
+  session: SessionState,
+  store: SurrealStore,
+  complete: CompleteFn,
+): Promise<void> {
+  const state = getState(session);
+  if (state.checkInFlight) return;
+  if (params.retrievedNodes.length === 0) return;
+
+  state.checkInFlight = true;
+  try {
+    // Build input sections
+    const sections: string[] = [];
+    sections.push(`[QUERY] ${params.userQuery.slice(0, 500)}`);
+    sections.push(`[RESPONSE] ${params.responseText.slice(0, 500)}`);
+
+    const nodeLines = params.retrievedNodes
+      .slice(0, 20)
+      .map(n => `- ${n.id} (score: ${n.score.toFixed(2)}): ${n.text.slice(0, 150)}`);
+    sections.push(`[RETRIEVED]\n${nodeLines.join("\n")}`);
+
+    if (params.recentTurns.length > 0) {
+      const trajectory = params.recentTurns
+        .slice(-6)
+        .map(t => `[${t.role}] ${(t.text ?? "").slice(0, 200)}`)
+        .join("\n");
+      sections.push(`[TRAJECTORY]\n${trajectory}`);
+    }
+
+    const response = await complete({
+      system: `Assess the retrieved context served to an AI assistant. Return JSON:
+
+"directives": [{type, target, instruction, priority}] — max 3. Types:
+  "repeat": same topic discussed in a prior session — instruct to acknowledge and build on it
+  "continuation": user is continuing prior work — instruct to maintain thread
+  "contradiction": retrieved info conflicts with current conversation — flag it
+  "noise": node is irrelevant despite high similarity score — instruct to ignore
+  "insight": useful pattern the model should lean into
+Priority: "high" (must address), "medium" (should note), "low" (nice to know)
+
+"grades": [{id, relevant, reason, score, learned, resolved}] — one per retrieved node. Score 0.0-1.0. "learned": true ONLY if the node is a [CORRECTION] memory AND the assistant's response already follows the correction without being prompted. "resolved": true if this memory's topic has been fully addressed/completed in the current conversation. Both default false.
+
+"sessionContinuity": "repeat" | "continuation" | "new_topic" | "tangent"
+
+"preferences": [{observation, confidence: "high"|"medium"}] — max 2. User communication style, values, or working preferences inferred from the conversation. Only include if clearly observable. Empty [] if nothing notable.
+
+Return ONLY valid JSON.`,
+      messages: [{
+        role: "user",
+        content: sections.join("\n\n"),
+      }],
+    });
+
+    const responseText = response.text;
+
+    const result = parseCheckResponse(responseText);
+    if (!result) return;
+
+    // Store directives for next turn's context formatting
+    state.pendingDirectives = result.directives;
+    state.sessionContinuity = result.sessionContinuity;
+
+    // Write grades to DB
+    if (result.grades.length > 0) {
+      await applyRetrievalGrades(result.grades, params.sessionId, store);
+    }
+
+    // Correction importance adjustment based on behavioral compliance
+    const correctionGrades = result.grades.filter(g => g.id.startsWith("memory:") && g.relevant);
+    for (const g of correctionGrades) {
+      if (g.learned) {
+        // Agent followed the correction unprompted — decay toward background (floor 3)
+        await store.queryExec(
+          `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)
+        await store.queryExec(
+          `UPDATE ${g.id} SET importance = math::min([9, importance + 1])`,
+        ).catch(e => swallow.warn("cognitive-check:correctionReinforce", e));
+      }
+    }
+
+    // Store high-confidence user preferences as session-pinned core memory
+    const highConfPrefs = result.preferences.filter(p => p.confidence === "high");
+    for (const pref of highConfPrefs) {
+      await store.createCoreMemory(
+        `[USER PREFERENCE] ${pref.observation}`,
+        "preference", 7, 1, params.sessionId,
+      ).catch(e => swallow.warn("cognitive-check:preference", e));
+    }
+
+    // Noise suppression — prevent re-retrieval of irrelevant nodes this session
+    for (const g of result.grades) {
+      if (!g.relevant && g.score < 0.3) {
+        state.suppressedNodeIds.add(g.id);
+      }
+    }
+    for (const d of result.directives) {
+      if (d.type === "noise" && VALID_RECORD_ID.test(d.target)) {
+        state.suppressedNodeIds.add(d.target);
+      }
+    }
+
+    // Mid-session resolution — mark addressed memories immediately
+    const resolvedGrades = result.grades.filter(g => g.resolved && g.id.startsWith("memory:"));
+    for (const g of resolvedGrades) {
+      await store.queryExec(
+        `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) {
+    swallow.warn("cognitive-check:run", e);
+  } finally {
+    state.checkInFlight = false;
+  }
+}
+
+// --- Response parsing ---
+
+export function parseCheckResponse(text: string): CognitiveCheckResult | null {
+  // Strip markdown fences if present
+  const stripped = text.replace(/```(?:json)?\s*/g, "").replace(/```\s*$/g, "");
+  const jsonMatch = stripped.match(/\{[\s\S]*\}/);
+  if (!jsonMatch) return null;
+
+  let raw: any;
+  try {
+    raw = JSON.parse(jsonMatch[0]);
+  } catch {
+    try {
+      raw = JSON.parse(jsonMatch[0].replace(/,\s*([}\]])/g, "$1"));
+    } catch { return null; }
+  }
+
+  // Validate directives
+  const directives: CognitiveDirective[] = [];
+  if (Array.isArray(raw.directives)) {
+    for (const d of raw.directives.slice(0, 3)) {
+      if (!d.type || !d.target || !d.instruction) continue;
+      if (!DIRECTIVE_TYPES.has(d.type)) continue;
+      directives.push({
+        type: d.type,
+        target: String(d.target).slice(0, 100),
+        instruction: String(d.instruction).slice(0, 200),
+        priority: PRIORITIES.has(d.priority) ? d.priority : "medium",
+      });
+    }
+  }
+
+  // Validate grades
+  const grades: RetrievalGrade[] = [];
+  if (Array.isArray(raw.grades)) {
+    for (const g of raw.grades.slice(0, 30)) {
+      if (!g.id || typeof g.relevant !== "boolean") continue;
+      if (!VALID_RECORD_ID.test(g.id)) continue;
+      grades.push({
+        id: String(g.id),
+        relevant: Boolean(g.relevant),
+        reason: String(g.reason ?? "").slice(0, 150),
+        score: Math.max(0, Math.min(1, Number(g.score) || 0)),
+        learned: g.learned === true,
+        resolved: g.resolved === true,
+      });
+    }
+  }
+
+  // Validate preferences
+  const preferences: UserPreference[] = [];
+  if (Array.isArray(raw.preferences)) {
+    for (const p of raw.preferences.slice(0, 2)) {
+      if (!p.observation) continue;
+      if (p.confidence !== "high" && p.confidence !== "medium") continue;
+      preferences.push({
+        observation: String(p.observation).slice(0, 200),
+        confidence: p.confidence,
+      });
+    }
+  }
+
+  const sessionContinuity = CONTINUITY_TYPES.has(raw.sessionContinuity)
+    ? raw.sessionContinuity
+    : "new_topic";
+
+  return { directives, grades, sessionContinuity, preferences };
+}
+
+// --- Grade application ---
+
+async function applyRetrievalGrades(
+  grades: RetrievalGrade[],
+  sessionId: string,
+  store: SurrealStore,
+): Promise<void> {
+  for (const grade of grades) {
+    try {
+      // Find the most recent retrieval outcome for this memory+session
+      const row = await store.queryFirst<{ id: string }>(
+        `SELECT id, created_at FROM retrieval_outcome
+          WHERE memory_id = $id AND session_id = $sid
+          ORDER BY created_at DESC LIMIT 1`,
+        { id: grade.id, sid: sessionId },
+      );
+      if (row?.[0]?.id) {
+        await store.queryExec(
+          `UPDATE ${row[0].id} 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
+      await store.updateUtilityCache(grade.id, grade.score).catch(e =>
+        swallow.warn("cognitive-check:utilityCache", e));
+    } catch (e) {
+      swallow.warn("cognitive-check:applyGrade", e);
+    }
+  }
+}

package/src/config.ts

@@ -0,0 +1,64 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface SurrealConfig {
+  url: string;
+  httpUrl: string;
+  user: string;
+  pass: string;
+  ns: string;
+  db: string;
+}
+
+export interface EmbeddingConfig {
+  modelPath: string;
+  dimensions: number;
+}
+
+export interface KongBrainConfig {
+  surreal: SurrealConfig;
+  embedding: EmbeddingConfig;
+}
+
+/**
+ * Parse plugin config from openclaw.plugin.json configSchema values,
+ * with env var overrides and sensible defaults.
+ */
+export function parsePluginConfig(raw?: Record<string, unknown>): KongBrainConfig {
+  const surreal = (raw?.surreal ?? {}) as Record<string, unknown>;
+  const embedding = (raw?.embedding ?? {}) as Record<string, unknown>;
+
+  // Priority: plugin config > env vars > defaults
+  const url =
+    (typeof surreal.url === "string" ? surreal.url : null) ??
+    process.env.SURREAL_URL ??
+    "ws://localhost:8042/rpc";
+
+  return {
+    surreal: {
+      url,
+      get httpUrl() {
+        const override = (typeof surreal.httpUrl === "string" ? surreal.httpUrl : null) ??
+          process.env.SURREAL_HTTP_URL;
+        if (override) return override;
+        return this.url
+          .replace("ws://", "http://")
+          .replace("wss://", "https://")
+          .replace("/rpc", "/sql");
+      },
+      user: (typeof surreal.user === "string" ? surreal.user : null) ?? process.env.SURREAL_USER ?? "root",
+      pass: (typeof surreal.pass === "string" ? surreal.pass : null) ?? process.env.SURREAL_PASS ?? "root",
+      ns: (typeof surreal.ns === "string" ? surreal.ns : null) ?? process.env.SURREAL_NS ?? "kong",
+      db: (typeof surreal.db === "string" ? surreal.db : null) ?? process.env.SURREAL_DB ?? "memory",
+    },
+    embedding: {
+      modelPath:
+        process.env.EMBED_MODEL_PATH ??
+        (typeof embedding.modelPath === "string"
+          ? embedding.modelPath
+          : join(homedir(), ".node-llama-cpp", "models", "bge-m3-q4_k_m.gguf")),
+      dimensions:
+        typeof embedding.dimensions === "number" ? embedding.dimensions : 1024,
+    },
+  };
+}