@jonathangu/openclawbrain 0.3.0

package/src/brain-core/graph.ts

@@ -0,0 +1,321 @@
+/**
+ * In-memory knowledge graph for the brain's learned retrieval layer.
+ *
+ * Loaded from SQLite, provides adjacency queries, seed selection by
+ * embedding similarity, action set computation, and inhibitory veto checks.
+ */
+
+import type {
+  BrainNode,
+  BrainEdge,
+  EdgeKind,
+  NodeKind,
+  TraversalAction,
+} from "./types.js";
+
+/**
+ * Cosine similarity between two Float32Arrays.
+ */
+export function cosineSimilarity(a: Float32Array, b: Float32Array): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  let normA = 0;
+  let normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+export class BrainGraph {
+  private nodes: Map<string, BrainNode> = new Map();
+  private outEdges: Map<string, BrainEdge[]> = new Map();
+  private inEdges: Map<string, BrainEdge[]> = new Map();
+  private seedWeights: Map<string, number> = new Map();
+
+  addNode(node: BrainNode): void {
+    this.nodes.set(node.id, node);
+    if (!this.outEdges.has(node.id)) this.outEdges.set(node.id, []);
+    if (!this.inEdges.has(node.id)) this.inEdges.set(node.id, []);
+  }
+
+  removeNode(nodeId: string): void {
+    this.nodes.delete(nodeId);
+    this.seedWeights.delete(nodeId);
+    // Remove all edges involving this node
+    const out = this.outEdges.get(nodeId) ?? [];
+    for (const edge of out) {
+      const targetIn = this.inEdges.get(edge.target);
+      if (targetIn) {
+        const idx = targetIn.indexOf(edge);
+        if (idx >= 0) targetIn.splice(idx, 1);
+      }
+    }
+    this.outEdges.delete(nodeId);
+
+    const inc = this.inEdges.get(nodeId) ?? [];
+    for (const edge of inc) {
+      const sourceOut = this.outEdges.get(edge.source);
+      if (sourceOut) {
+        const idx = sourceOut.indexOf(edge);
+        if (idx >= 0) sourceOut.splice(idx, 1);
+      }
+    }
+    this.inEdges.delete(nodeId);
+  }
+
+  getNode(nodeId: string): BrainNode | undefined {
+    return this.nodes.get(nodeId);
+  }
+
+  getAllNodes(): BrainNode[] {
+    return [...this.nodes.values()];
+  }
+
+  getAllEdges(): BrainEdge[] {
+    return [...this.outEdges.values()].flatMap((edges) => edges);
+  }
+
+  getNodesByKind(kind: NodeKind): BrainNode[] {
+    return [...this.nodes.values()].filter((n) => n.kind === kind);
+  }
+
+  addEdge(edge: BrainEdge): void {
+    const out = this.outEdges.get(edge.source);
+    if (out) {
+      // Replace if same source/target/kind exists
+      const idx = out.findIndex(
+        (e) => e.target === edge.target && e.kind === edge.kind,
+      );
+      if (idx >= 0) out[idx] = edge;
+      else out.push(edge);
+    } else {
+      this.outEdges.set(edge.source, [edge]);
+    }
+
+    const inc = this.inEdges.get(edge.target);
+    if (inc) {
+      const idx = inc.findIndex(
+        (e) => e.source === edge.source && e.kind === edge.kind,
+      );
+      if (idx >= 0) inc[idx] = edge;
+      else inc.push(edge);
+    } else {
+      this.inEdges.set(edge.target, [edge]);
+    }
+  }
+
+  removeEdge(source: string, target: string, kind: EdgeKind): void {
+    const out = this.outEdges.get(source);
+    if (out) {
+      const idx = out.findIndex((e) => e.target === target && e.kind === kind);
+      if (idx >= 0) out.splice(idx, 1);
+    }
+    const inc = this.inEdges.get(target);
+    if (inc) {
+      const idx = inc.findIndex((e) => e.source === source && e.kind === kind);
+      if (idx >= 0) inc.splice(idx, 1);
+    }
+  }
+
+  getEdge(source: string, target: string): BrainEdge | undefined {
+    const out = this.outEdges.get(source);
+    if (!out) return undefined;
+    return out.find((e) => e.target === target);
+  }
+
+  getOutgoingEdges(nodeId: string): BrainEdge[] {
+    return this.outEdges.get(nodeId) ?? [];
+  }
+
+  getIncomingEdges(nodeId: string): BrainEdge[] {
+    return this.inEdges.get(nodeId) ?? [];
+  }
+
+  getNeighbors(nodeId: string): string[] {
+    const edges = this.outEdges.get(nodeId) ?? [];
+    return [...new Set(edges.map((e) => e.target))];
+  }
+
+  getSeedWeight(nodeId: string): number {
+    return this.seedWeights.get(nodeId) ?? 0;
+  }
+
+  getSeedWeights(nodeIds: string[]): Record<string, number> {
+    const weights: Record<string, number> = {};
+    for (const nodeId of nodeIds) {
+      weights[nodeId] = this.getSeedWeight(nodeId);
+    }
+    return weights;
+  }
+
+  setSeedWeight(nodeId: string, weight: number): void {
+    if (!this.nodes.has(nodeId)) {
+      return;
+    }
+    this.seedWeights.set(nodeId, weight);
+  }
+
+  getAllSeedWeights(): Array<{ nodeId: string; weight: number }> {
+    return [...this.seedWeights.entries()].map(([nodeId, weight]) => ({ nodeId, weight }));
+  }
+
+  hasSeedWeights(): boolean {
+    return this.seedWeights.size > 0;
+  }
+
+  clone(): BrainGraph {
+    const clone = new BrainGraph();
+    for (const node of this.nodes.values()) {
+      clone.addNode({
+        ...node,
+        embedding: node.embedding ? new Float32Array(node.embedding) : null,
+        tags: [...node.tags],
+        metadata: { ...node.metadata },
+      });
+    }
+    for (const edge of this.getAllEdges()) {
+      clone.addEdge({
+        ...edge,
+        metadata: { ...edge.metadata },
+      });
+    }
+    for (const { nodeId, weight } of this.getAllSeedWeights()) {
+      clone.setSeedWeight(nodeId, weight);
+    }
+    return clone;
+  }
+
+  /**
+   * Seed selection: top-k nodes by cosine similarity to query embedding.
+   * Linear scan — fine for <10K nodes.
+   */
+  seedByEmbedding(
+    queryEmbedding: Float32Array,
+    topK: number,
+    threshold: number,
+  ): Array<{ nodeId: string; score: number }> {
+    const scored: Array<{ nodeId: string; score: number }> = [];
+
+    for (const node of this.nodes.values()) {
+      if (!node.embedding) continue;
+      const score = cosineSimilarity(queryEmbedding, node.embedding);
+      if (score >= threshold) {
+        scored.push({ nodeId: node.id, score });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, topK);
+  }
+
+  /**
+   * Compute action set at current state.
+   * A(s) = { traverse(neighbor) for neighbor not in visited } ∪ { STOP }
+   *
+   * At seed phase (currentNodeId === null), uses provided seeds.
+   */
+  getActionSet(
+    currentNodeId: string | null,
+    visited: Set<string>,
+    seeds?: Array<{ nodeId: string; score?: number }>,
+  ): TraversalAction[] {
+    const actions: TraversalAction[] = [];
+
+    if (currentNodeId === null) {
+      // Seed phase: actions are the seed candidates
+      if (seeds) {
+        for (const seed of seeds) {
+          if (!visited.has(seed.nodeId)) {
+            actions.push({ type: "traverse", targetNodeId: seed.nodeId, seedScore: seed.score });
+          }
+        }
+      }
+    } else {
+      // Normal phase: neighbors via outgoing edges
+      const neighbors = this.getNeighbors(currentNodeId);
+      for (const neighborId of neighbors) {
+        if (!visited.has(neighborId)) {
+          actions.push({ type: "traverse", targetNodeId: neighborId });
+        }
+      }
+    }
+
+    // STOP is always available
+    actions.push({ type: "stop" });
+    return actions;
+  }
+
+  /**
+   * Check if traversal from source to target is suppressed by an inhibitory edge.
+   */
+  isVetoed(sourceNodeId: string, targetNodeId: string): boolean {
+    const edges = this.outEdges.get(sourceNodeId) ?? [];
+    return edges.some(
+      (e) => e.target === targetNodeId && (e.kind === "inhibitory" || e.weight < -0.5),
+    );
+  }
+
+  getVetoReason(sourceNodeId: string, targetNodeId: string): string | null {
+    const edges = this.outEdges.get(sourceNodeId) ?? [];
+    const vetoEdge = edges.find(
+      (e) => e.target === targetNodeId && (e.kind === "inhibitory" || e.weight < -0.5),
+    );
+    if (!vetoEdge) return null;
+    if (vetoEdge.kind === "inhibitory") return "inhibitory edge";
+    return `negative weight (${vetoEdge.weight.toFixed(3)})`;
+  }
+
+  /**
+   * Nodes with no edges at all.
+   */
+  getOrphanNodes(): string[] {
+    const orphans: string[] = [];
+    for (const nodeId of this.nodes.keys()) {
+      const outCount = (this.outEdges.get(nodeId) ?? []).length;
+      const inCount = (this.inEdges.get(nodeId) ?? []).length;
+      if (outCount === 0 && inCount === 0) {
+        orphans.push(nodeId);
+      }
+    }
+    return orphans;
+  }
+
+  /**
+   * Nodes not present in any recent episode's fired list.
+   */
+  getDormantNodes(recentFiredNodeIds: Set<string>): string[] {
+    const dormant: string[] = [];
+    for (const nodeId of this.nodes.keys()) {
+      if (!recentFiredNodeIds.has(nodeId)) {
+        dormant.push(nodeId);
+      }
+    }
+    return dormant;
+  }
+
+  nodeCount(): number {
+    return this.nodes.size;
+  }
+
+  edgeCount(): number {
+    let count = 0;
+    for (const edges of this.outEdges.values()) {
+      count += edges.length;
+    }
+    return count;
+  }
+
+  /**
+   * Clear all nodes and edges.
+   */
+  clear(): void {
+    this.nodes.clear();
+    this.outEdges.clear();
+    this.inEdges.clear();
+    this.seedWeights.clear();
+  }
+}

package/src/brain-core/health.ts

@@ -0,0 +1,116 @@
+/**
+ * Graph health metrics for promotion gates and operator visibility.
+ */
+
+import type { HealthMetrics, NodeKind, EdgeKind, Episode } from "./types.js";
+import type { BrainGraph } from "./graph.js";
+
+const NODE_KINDS: NodeKind[] = ["chunk", "workflow", "correction", "toolcard", "episode_anchor", "summary_bridge"];
+const EDGE_KINDS: EdgeKind[] = ["sibling", "semantic", "learned", "seed", "inhibitory", "bridge"];
+
+export function computeFiredPerQuery(episodes: Episode[]): number {
+  if (episodes.length === 0) return 0;
+  const totalFired = episodes.reduce((sum, ep) => sum + ep.firedNodes.length, 0);
+  return totalFired / episodes.length;
+}
+
+export function computeDormantPercent(graph: BrainGraph, episodes: Episode[]): number {
+  const totalNodes = graph.nodeCount();
+  if (totalNodes === 0) return 0;
+
+  const firedSet = new Set<string>();
+  for (const ep of episodes) {
+    for (const id of ep.firedNodes) firedSet.add(id);
+  }
+
+  const dormant = graph.getDormantNodes(firedSet);
+  return dormant.length / totalNodes;
+}
+
+export function computeInhibitoryPercent(graph: BrainGraph): number {
+  const totalEdges = graph.edgeCount();
+  if (totalEdges === 0) return 0;
+
+  let inhibCount = 0;
+  for (const edge of graph.getAllEdges()) {
+    if (edge.kind === "inhibitory" || edge.weight < 0) inhibCount++;
+  }
+  return inhibCount / totalEdges;
+}
+
+export function computeAvgPathLength(episodes: Episode[]): number {
+  if (episodes.length === 0) return 0;
+  const totalHops = episodes.reduce((sum, ep) => sum + ep.trajectory.length, 0);
+  return totalHops / episodes.length;
+}
+
+export function computeAvgReward(episodes: Episode[]): number {
+  const rewarded = episodes.filter((ep) => ep.reward !== null);
+  if (rewarded.length === 0) return 0;
+  const totalReward = rewarded.reduce((sum, ep) => sum + (ep.reward ?? 0), 0);
+  return totalReward / rewarded.length;
+}
+
+export function computeChurn(
+  previous: HealthMetrics | null,
+  current: HealthMetrics,
+): number {
+  if (!previous) return 0;
+  return Math.abs(current.avgReward - previous.avgReward)
+    + Math.abs(current.firedPerQuery - previous.firedPerQuery) * 0.1
+    + Math.abs(current.dormantPercent - previous.dormantPercent) * 0.1;
+}
+
+export function computeHealth(
+  graph: BrainGraph,
+  recentEpisodes: Episode[],
+  packVersion: number,
+  previousHealth?: HealthMetrics | null,
+): HealthMetrics {
+  const nodesByKind = {} as Record<NodeKind, number>;
+  for (const kind of NODE_KINDS) nodesByKind[kind] = 0;
+  for (const node of graph.getAllNodes()) nodesByKind[node.kind]++;
+
+  const edgesByKind = {} as Record<EdgeKind, number>;
+  for (const kind of EDGE_KINDS) edgesByKind[kind] = 0;
+  for (const edge of graph.getAllEdges()) {
+    edgesByKind[edge.kind]++;
+  }
+
+  // Cross-file edge percent: edges connecting nodes from different sourceUris
+  let crossFileCount = 0;
+  let totalEdgeCount = 0;
+  for (const edge of graph.getAllEdges()) {
+    totalEdgeCount++;
+    const sourceNode = graph.getNode(edge.source);
+    const targetNode = graph.getNode(edge.target);
+    if (sourceNode && targetNode && sourceNode.sourceUri !== targetNode.sourceUri) {
+      crossFileCount++;
+    }
+  }
+
+  const health: HealthMetrics = {
+    nodeCount: graph.nodeCount(),
+    edgeCount: graph.edgeCount(),
+    nodesByKind,
+    edgesByKind,
+    firedPerQuery: computeFiredPerQuery(recentEpisodes),
+    dormantPercent: computeDormantPercent(graph, recentEpisodes),
+    inhibitoryPercent: computeInhibitoryPercent(graph),
+    orphanCount: graph.getOrphanNodes().length,
+    avgPathLength: computeAvgPathLength(recentEpisodes),
+    avgReward: computeAvgReward(recentEpisodes),
+    crossFileEdgePercent: totalEdgeCount > 0 ? crossFileCount / totalEdgeCount : 0,
+    churn: computeChurn(previousHealth ?? null, {
+      // Temporary partial health for churn computation
+      avgReward: computeAvgReward(recentEpisodes),
+      firedPerQuery: computeFiredPerQuery(recentEpisodes),
+      dormantPercent: computeDormantPercent(graph, recentEpisodes),
+    } as HealthMetrics),
+    packVersion,
+    lastUpdateAt: Date.now(),
+    totalEpisodes: recentEpisodes.length,
+  };
+
+  return health;
+}

package/src/brain-core/mutator.ts

@@ -0,0 +1,281 @@
+/**
+ * Structural graph mutations: split, merge, prune, connect, inject.
+ *
+ * All mutations are proposals validated via replay gate before promotion.
+ * Mutations happen in the learned retrieval graph ONLY, never the LCM summary DAG.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Episode, MutationProposal, BrainNode } from "./types.js";
+import type { BrainGraph } from "./graph.js";
+import { cosineSimilarity } from "./graph.js";
+
+export interface BrainMutationPersistence {
+  insertNode(node: BrainNode): void;
+  insertEdge(edge: {
+    source: string;
+    target: string;
+    kind: "learned";
+    weight: number;
+    prior: number;
+    metadata: Record<string, unknown>;
+    decayedAt: number;
+    createdAt: number;
+  }): void;
+  deleteNode(id: string): void;
+  deleteEdge(source: string, target: string, kind: string): void;
+  resolveMutation(id: string, status: "promoted" | "rejected"): void;
+}
+
+export class BrainMutator {
+  constructor(
+    private persistence: BrainMutationPersistence,
+    private graph: BrainGraph,
+    private log: { info: (msg: string) => void },
+  ) {}
+
+  /**
+   * Propose mutations based on episode patterns.
+   * Called periodically by the trainer.
+   */
+  proposeMutations(recentEpisodes: Episode[]): MutationProposal[] {
+    const proposals: MutationProposal[] = [];
+
+    proposals.push(...this.proposePrunes());
+    proposals.push(...this.proposeConnections(recentEpisodes));
+    proposals.push(...this.proposeInjects(recentEpisodes));
+
+    return proposals;
+  }
+
+  /**
+   * Prune: edges dormant across many episodes.
+   * Signal: weight has decayed near zero and no recent traversal.
+   */
+  private proposePrunes(): MutationProposal[] {
+    const proposals: MutationProposal[] = [];
+
+    for (const node of this.graph.getAllNodes()) {
+      for (const edge of this.graph.getOutgoingEdges(node.id)) {
+        if (edge.kind === "sibling" || edge.kind === "bridge") continue;
+        if (Math.abs(edge.weight) < 0.05 && Math.abs(edge.weight - edge.prior) < 0.05) {
+          proposals.push({
+            id: `bm_${randomUUID().slice(0, 8)}`,
+            kind: "prune",
+            proposal: { source: edge.source, target: edge.target, edgeKind: edge.kind, weight: edge.weight },
+            evidence: null,
+            expectedGain: 0.01,
+            status: "pending",
+            createdAt: Date.now(),
+            resolvedAt: null,
+          });
+        }
+      }
+    }
+
+    return proposals.slice(0, 5); // Limit per tick
+  }
+
+  /**
+   * Connect: successful episodes repeatedly bridge two regions.
+   * Signal: nodes co-fire frequently but have no direct edge.
+   */
+  private proposeConnections(episodes: Episode[]): MutationProposal[] {
+    const coFiring = new Map<string, number>();
+
+    for (const ep of episodes) {
+      if (ep.reward === null || ep.reward < 0.3) continue;
+      for (let i = 0; i < ep.firedNodes.length; i++) {
+        for (let j = i + 1; j < ep.firedNodes.length; j++) {
+          const key = [ep.firedNodes[i], ep.firedNodes[j]].sort().join("↔");
+          coFiring.set(key, (coFiring.get(key) ?? 0) + 1);
+        }
+      }
+    }
+
+    const proposals: MutationProposal[] = [];
+    for (const [key, count] of coFiring) {
+      if (count < 3) continue;
+      const [a, b] = key.split("↔");
+      if (this.graph.getEdge(a, b) || this.graph.getEdge(b, a)) continue;
+
+      proposals.push({
+        id: `bm_${randomUUID().slice(0, 8)}`,
+        kind: "connect",
+        proposal: { nodeA: a, nodeB: b, coFireCount: count },
+        evidence: { episodeCount: count },
+        expectedGain: count * 0.05,
+        status: "pending",
+        createdAt: Date.now(),
+        resolvedAt: null,
+      });
+    }
+
+    return proposals.slice(0, 3);
+  }
+
+  private proposeInjects(episodes: Episode[]): MutationProposal[] {
+    const proposals: MutationProposal[] = [];
+    const seenQueries = new Set<string>();
+
+    for (const episode of episodes) {
+      if (episode.reward === null || episode.reward < 0.6) {
+        continue;
+      }
+      if (seenQueries.has(episode.queryText)) {
+        continue;
+      }
+      seenQueries.add(episode.queryText);
+      if (episode.firedNodes.length < 2) {
+        continue;
+      }
+
+      proposals.push({
+        id: `bm_${randomUUID().slice(0, 8)}`,
+        kind: "inject",
+        proposal: {
+          nodeKind: "episode_anchor",
+          content: episode.queryText,
+          firedNodes: episode.firedNodes,
+        },
+        evidence: { episodeId: episode.id, reward: episode.reward },
+        expectedGain: 0.05,
+        status: "pending",
+        createdAt: Date.now(),
+        resolvedAt: null,
+      });
+      if (proposals.length >= 3) {
+        break;
+      }
+    }
+
+    return proposals;
+  }
+
+  /**
+   * Apply a validated mutation to the graph and store.
+   */
+  private applyMutationToGraph(targetGraph: BrainGraph, proposal: MutationProposal): {
+    insertedEdges?: Array<{
+      source: string;
+      target: string;
+      kind: "learned";
+      weight: number;
+      prior: number;
+      metadata: Record<string, unknown>;
+      decayedAt: number;
+      createdAt: number;
+    }>;
+    deletedEdges?: Array<{ source: string; target: string; kind: string }>;
+    deletedNodes?: string[];
+    insertedNodes?: BrainNode[];
+  } {
+    const p = proposal.proposal as Record<string, unknown>;
+    const result: {
+      insertedEdges?: Array<{
+        source: string;
+        target: string;
+        kind: "learned";
+        weight: number;
+        prior: number;
+        metadata: Record<string, unknown>;
+        decayedAt: number;
+        createdAt: number;
+      }>;
+      deletedEdges?: Array<{ source: string; target: string; kind: string }>;
+      deletedNodes?: string[];
+      insertedNodes?: BrainNode[];
+    } = {};
+
+    switch (proposal.kind) {
+      case "prune": {
+        targetGraph.removeEdge(p.source as string, p.target as string, p.edgeKind as any);
+        result.deletedEdges = [{
+          source: p.source as string,
+          target: p.target as string,
+          kind: p.edgeKind as string,
+        }];
+        break;
+      }
+      case "connect": {
+        const now = Date.now();
+        const edge = {
+          source: p.nodeA as string,
+          target: p.nodeB as string,
+          kind: "learned" as const,
+          weight: 0.5,
+          prior: 0.5,
+          metadata: { mutationId: proposal.id },
+          decayedAt: now,
+          createdAt: now,
+        };
+        targetGraph.addEdge(edge);
+        result.insertedEdges = [edge];
+        break;
+      }
+      case "inject": {
+        const now = Date.now();
+        const node: BrainNode = {
+          id: `bn_${randomUUID().slice(0, 12)}`,
+          kind: "episode_anchor",
+          content: String(p.content ?? ""),
+          embedding: null,
+          sourceUri: null,
+          trust: "scanner",
+          tags: ["episode-anchor"],
+          tokenCount: Math.ceil(String(p.content ?? "").length / 4),
+          metadata: {
+            mutationId: proposal.id,
+            firedNodes: Array.isArray(p.firedNodes) ? p.firedNodes : [],
+          },
+          createdAt: now,
+          updatedAt: now,
+        };
+        targetGraph.addNode(node);
+        result.insertedNodes = [node];
+
+        const firedNodes = Array.isArray(p.firedNodes) ? p.firedNodes.filter((value): value is string => typeof value === "string") : [];
+        result.insertedEdges = firedNodes.map((firedNodeId) => {
+          const edge = {
+            source: node.id,
+            target: firedNodeId,
+            kind: "learned" as const,
+            weight: 0.4,
+            prior: 0.4,
+            metadata: { mutationId: proposal.id },
+            decayedAt: now,
+            createdAt: now,
+          };
+          targetGraph.addEdge(edge);
+          return edge;
+        });
+        break;
+      }
+    }
+
+    return result;
+  }
+
+  applyToCandidateGraph(targetGraph: BrainGraph, proposal: MutationProposal): void {
+    this.applyMutationToGraph(targetGraph, proposal);
+  }
+
+  applyMutation(proposal: MutationProposal): void {
+    const result = this.applyMutationToGraph(this.graph, proposal);
+    for (const edge of result.insertedEdges ?? []) {
+      this.persistence.insertEdge(edge);
+    }
+    for (const node of result.insertedNodes ?? []) {
+      this.persistence.insertNode(node);
+    }
+    for (const edge of result.deletedEdges ?? []) {
+      this.persistence.deleteEdge(edge.source, edge.target, edge.kind);
+    }
+    for (const nodeId of result.deletedNodes ?? []) {
+      this.persistence.deleteNode(nodeId);
+    }
+
+    this.persistence.resolveMutation(proposal.id, "promoted");
+    this.log.info(`[brain] Applied ${proposal.kind}: ${proposal.id}`);
+  }
+}