kongbrain 0.1.0

package/src/tools/core-memory.ts

@@ -0,0 +1,120 @@
+/**
+ * Core memory management tool — CRUD on always-loaded directives.
+ * Ported from kongbrain with SurrealStore injection.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { GlobalPluginState, SessionState } from "../state.js";
+
+const coreMemorySchema = Type.Object({
+  action: Type.Union([
+    Type.Literal("list"),
+    Type.Literal("add"),
+    Type.Literal("update"),
+    Type.Literal("deactivate"),
+  ], { description: "Action to perform on core memory." }),
+  tier: Type.Optional(Type.Number({ description: "Filter by tier (0=always loaded, 1=session-pinned). Default: list all." })),
+  category: Type.Optional(Type.String({ description: "Category (identity/rules/tools/operations/general)." })),
+  text: Type.Optional(Type.String({ description: "Text content for add/update actions." })),
+  priority: Type.Optional(Type.Number({ description: "Priority for add/update (higher=loaded first). Default: 50." })),
+  id: Type.Optional(Type.String({ description: "Record ID for update/deactivate (e.g. core_memory:abc123)." })),
+  session_id: Type.Optional(Type.String({ description: "Session ID for Tier 1 entries." })),
+});
+
+export function createCoreMemoryToolDef(state: GlobalPluginState, session: SessionState) {
+  return {
+    name: "core_memory",
+    label: "Core Memory",
+    description: "Manage always-loaded core directives (Tier 0) and session-pinned context (Tier 1). Tier 0 entries are present in EVERY turn — use for identity, rules, tool patterns. Tier 1 entries are pinned for the current session.",
+    parameters: coreMemorySchema,
+    execute: async (_toolCallId: string, params: {
+      action: "list" | "add" | "update" | "deactivate";
+      tier?: number; category?: string; text?: string;
+      priority?: number; id?: string; session_id?: string;
+    }) => {
+      const { store } = state;
+      if (!store.isAvailable()) {
+        return { content: [{ type: "text" as const, text: "Database unavailable." }], details: null };
+      }
+
+      try {
+        switch (params.action) {
+          case "list": {
+            const entries = await store.getAllCoreMemory(params.tier);
+            if (entries.length === 0) {
+              return { content: [{ type: "text" as const, text: "No core memory entries found." }], details: null };
+            }
+            const formatted = entries.map((e, i) => {
+              const sid = e.session_id ? ` session:${e.session_id}` : "";
+              return `${i + 1}. [T${e.tier}/${e.category}/p${e.priority}${sid}] ${e.id}\n   ${e.text.slice(0, 200)}`;
+            }).join("\n\n");
+            return {
+              content: [{ type: "text" as const, text: `${entries.length} core memory entries:\n\n${formatted}` }],
+              details: { count: entries.length },
+            };
+          }
+
+          case "add": {
+            if (!params.text) {
+              return { content: [{ type: "text" as const, text: "Error: 'text' is required for add action." }], details: null };
+            }
+            const tier = params.tier ?? 0;
+            const sid = tier === 1 ? (params.session_id ?? session.sessionId) : undefined;
+            const id = await store.createCoreMemory(
+              params.text,
+              params.category ?? "general",
+              params.priority ?? 50,
+              tier,
+              sid,
+            );
+            if (!id) {
+              return {
+                content: [{ type: "text" as const, text: "FAILED: Core memory entry was not created." }],
+                details: { error: true },
+              };
+            }
+            return {
+              content: [{ type: "text" as const, text: `Created core memory: ${id} (tier ${tier}, ${params.category ?? "general"}, p${params.priority ?? 50})` }],
+              details: { id },
+            };
+          }
+
+          case "update": {
+            if (!params.id) {
+              return { content: [{ type: "text" as const, text: "Error: 'id' is required for update action." }], details: null };
+            }
+            const fields: Record<string, unknown> = {};
+            if (params.text !== undefined) fields.text = params.text;
+            if (params.category !== undefined) fields.category = params.category;
+            if (params.priority !== undefined) fields.priority = params.priority;
+            if (params.tier !== undefined) fields.tier = params.tier;
+            const updated = await store.updateCoreMemory(params.id, fields);
+            if (!updated) {
+              return {
+                content: [{ type: "text" as const, text: `FAILED: Could not update ${params.id}.` }],
+                details: { error: true },
+              };
+            }
+            return {
+              content: [{ type: "text" as const, text: `Updated core memory: ${params.id}` }],
+              details: { id: params.id },
+            };
+          }
+
+          case "deactivate": {
+            if (!params.id) {
+              return { content: [{ type: "text" as const, text: "Error: 'id' is required for deactivate action." }], details: null };
+            }
+            await store.deleteCoreMemory(params.id);
+            return {
+              content: [{ type: "text" as const, text: `Deactivated core memory: ${params.id}` }],
+              details: { id: params.id },
+            };
+          }
+        }
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Core memory operation failed: ${err}` }], details: null };
+      }
+    },
+  };
+}

package/src/tools/introspect.ts

@@ -0,0 +1,329 @@
+/**
+ * Introspect tool — inspect the memory database.
+ * Ported from kongbrain with SurrealStore injection.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { GlobalPluginState, SessionState } from "../state.js";
+import { assertRecordId } from "../surreal.js";
+import { migrateWorkspace } from "../workspace-migrate.js";
+import { checkGraduation, formatGraduationReport, hasSoul } from "../soul.js";
+
+const ALLOWED_TABLES = new Set([
+  "agent", "project", "task", "artifact", "concept",
+  "turn", "identity_chunk", "session", "memory",
+  "core_memory", "monologue", "skill", "reflection",
+  "retrieval_outcome", "orchestrator_metrics",
+  "causal_chain", "compaction_checkpoint", "subagent",
+  "memory_utility_cache", "soul", "graduation_event", "maturity_stage",
+]);
+
+const VECTOR_TABLES = new Set([
+  "concept", "memory", "artifact", "identity_chunk", "turn", "monologue", "skill", "reflection",
+]);
+
+const COUNT_FILTERS: Record<string, string> = {
+  active: "WHERE active = true",
+  inactive: "WHERE active = false",
+  recent_24h: "WHERE created_at > time::now() - 24h",
+  with_embedding: "WHERE embedding != NONE AND array::len(embedding) > 0",
+  unresolved: "WHERE status != 'resolved' OR status IS NONE",
+};
+
+const QUERY_TEMPLATES: Record<string, { sql: string; description: string; needsTable?: boolean }> = {
+  recent: {
+    sql: "SELECT id, text, content, description, created_at FROM type::table($t) ORDER BY created_at DESC LIMIT 5",
+    description: "Last 5 records by creation time",
+    needsTable: true,
+  },
+  sessions: {
+    sql: "SELECT id, started_at, turn_count, total_input_tokens, total_output_tokens, last_active FROM session ORDER BY started_at DESC LIMIT 10",
+    description: "Last 10 sessions with stats",
+  },
+  core_by_category: {
+    sql: "SELECT category, count() AS count FROM core_memory WHERE active = true GROUP BY category",
+    description: "Core memory entries grouped by category",
+  },
+  memory_status: {
+    sql: "SELECT status, count() AS count FROM memory GROUP BY status",
+    description: "Memory counts grouped by status",
+  },
+  embedding_coverage: {
+    sql: "",
+    description: "Per-table embedding vs total counts",
+  },
+};
+
+const introspectSchema = Type.Object({
+  action: Type.Union([
+    Type.Literal("status"),
+    Type.Literal("count"),
+    Type.Literal("verify"),
+    Type.Literal("query"),
+    Type.Literal("migrate"),
+  ], { description: "Action: status (health overview), count (row counts), verify (confirm record), query (predefined reports), migrate (ingest workspace .md files into DB — ask user first)." }),
+  table: Type.Optional(Type.String({ description: "Table name for count/query actions." })),
+  filter: Type.Optional(Type.String({ description: "For count: active, inactive, recent_24h, with_embedding, unresolved. For query: template name." })),
+  record_id: Type.Optional(Type.String({ description: "Record ID for verify action (e.g. memory:abc123)." })),
+});
+
+export function createIntrospectToolDef(state: GlobalPluginState, session: SessionState) {
+  return {
+    name: "introspect",
+    label: "Memory Introspect",
+    description: "Inspect your memory database. Use for ALL database queries — NEVER use curl or bash to access SurrealDB directly. Actions: status (health + table counts), count (filtered row counts), verify (confirm record exists), query (predefined reports).",
+    parameters: introspectSchema,
+    execute: async (_toolCallId: string, params: {
+      action: "status" | "count" | "verify" | "query" | "migrate";
+      table?: string; filter?: string; record_id?: string;
+    }) => {
+      const { store } = state;
+      if (!store.isAvailable()) {
+        return { content: [{ type: "text" as const, text: "Database unavailable." }], details: null };
+      }
+
+      try {
+        switch (params.action) {
+          case "status": return await statusAction(store, session.sessionId);
+          case "count": return await countAction(store, params.table, params.filter);
+          case "verify": return await verifyAction(store, params.record_id);
+          case "query": return await queryAction(store, params.table, params.filter);
+          case "migrate": return await migrateAction(state);
+        }
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Introspect failed: ${err}` }], details: null };
+      }
+    },
+  };
+}
+
+// ── Actions ──────────────────────────────────────────────────────────────
+
+async function statusAction(store: any, sessionId: string) {
+  const info = store.getInfo();
+  const alive = await store.ping();
+
+  const lines: string[] = [];
+  lines.push("MEMORY DATABASE STATUS");
+  lines.push("═══════════════════════════════════");
+  lines.push(`Connection:  ${info?.url ?? "unknown"}`);
+  lines.push(`Namespace:   ${info?.ns ?? "unknown"}`);
+  lines.push(`Database:    ${info?.db ?? "unknown"}`);
+  lines.push(`Ping:        ${alive ? "OK" : "FAILED"}`);
+  lines.push(`Session:     ${sessionId}`);
+  lines.push("");
+
+  const counts: Record<string, number> = {};
+  const embCounts: Record<string, number> = {};
+
+  for (const t of ALLOWED_TABLES) {
+    try {
+      const rows = await store.queryFirst(
+        `SELECT count() AS count FROM type::table($t) GROUP ALL`, { t },
+      );
+      counts[t] = rows[0]?.count ?? 0;
+    } catch { counts[t] = -1; }
+  }
+
+  for (const t of VECTOR_TABLES) {
+    try {
+      const rows = await store.queryFirst(
+        `SELECT count() AS count FROM type::table($t) WHERE embedding != NONE AND array::len(embedding) > 0 GROUP ALL`, { t },
+      );
+      embCounts[t] = rows[0]?.count ?? 0;
+    } catch { embCounts[t] = 0; }
+  }
+
+  for (const t of ALLOWED_TABLES) {
+    const c = counts[t];
+    const label = (t + ":").padEnd(28);
+    const countStr = c === -1 ? "error" : String(c).padStart(5);
+    const embStr = VECTOR_TABLES.has(t) ? `  (${embCounts[t] ?? 0} embedded)` : "";
+    lines.push(`  ${label}${countStr}${embStr}`);
+  }
+
+  const totalNodes = Object.values(counts).filter(c => c >= 0).reduce((a, b) => a + b, 0);
+  const totalEmb = Object.values(embCounts).reduce((a, b) => a + b, 0);
+  lines.push("");
+  lines.push(`Total records:     ${totalNodes}`);
+  lines.push(`Total embeddings:  ${totalEmb}`);
+
+  // Graduation status
+  lines.push("");
+  lines.push("SOUL GRADUATION");
+  lines.push("═══════════════════════════════════");
+  try {
+    const soulExists = await hasSoul(store);
+    if (soulExists) {
+      lines.push("Status: GRADUATED (soul document exists)");
+    } else {
+      const report = await checkGraduation(store);
+      lines.push(formatGraduationReport(report));
+    }
+  } catch {
+    lines.push("Status: Unable to check graduation");
+  }
+
+  return {
+    content: [{ type: "text" as const, text: lines.join("\n") }],
+    details: { counts, embCounts, alive, totalNodes, totalEmb },
+  };
+}
+
+async function countAction(store: any, table?: string, filter?: string) {
+  if (!table || !ALLOWED_TABLES.has(table)) {
+    return {
+      content: [{ type: "text" as const, text: `Error: valid 'table' required. Available: ${[...ALLOWED_TABLES].sort().join(", ")}` }],
+      details: null,
+    };
+  }
+
+  let whereClause = "";
+  if (filter) {
+    if (!COUNT_FILTERS[filter]) {
+      return {
+        content: [{ type: "text" as const, text: `Error: unknown filter "${filter}". Available: ${Object.keys(COUNT_FILTERS).join(", ")}` }],
+        details: null,
+      };
+    }
+    whereClause = " " + COUNT_FILTERS[filter];
+  }
+
+  const rows = await store.queryFirst(
+    `SELECT count() AS count FROM type::table($t)${whereClause} GROUP ALL`, { t: table },
+  );
+  const count = rows[0]?.count ?? 0;
+  return {
+    content: [{ type: "text" as const, text: `${table}: ${count} rows${filter ? ` (filter: ${filter})` : ""}` }],
+    details: { table, count, filter },
+  };
+}
+
+async function verifyAction(store: any, recordId?: string) {
+  if (!recordId) {
+    return { content: [{ type: "text" as const, text: "Error: 'record_id' is required." }], details: null };
+  }
+  try { assertRecordId(recordId); } catch {
+    return { content: [{ type: "text" as const, text: `Error: invalid record ID "${recordId}".` }], details: null };
+  }
+
+  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 } };
+  }
+
+  const record = rows[0];
+  const cleaned: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(record as any)) {
+    if (Array.isArray(val) && val.length > 100 && typeof val[0] === "number") {
+      cleaned[key] = `[${val.length} dims]`;
+    } else {
+      cleaned[key] = val;
+    }
+  }
+
+  const lines = Object.entries(cleaned)
+    .map(([k, v]) => `  ${k}: ${typeof v === "string" ? v.slice(0, 300) : JSON.stringify(v)}`)
+    .join("\n");
+
+  return {
+    content: [{ type: "text" as const, text: `Record ${recordId}:\n${lines}` }],
+    details: { exists: true, id: recordId, record: cleaned },
+  };
+}
+
+async function migrateAction(state: GlobalPluginState) {
+  const { store, embeddings, workspaceDir } = state;
+  if (!workspaceDir) {
+    return {
+      content: [{ type: "text" as const, text: "No workspace directory configured — cannot migrate." }],
+      details: null,
+    };
+  }
+
+  const result = await migrateWorkspace(workspaceDir, store, embeddings);
+
+  const lines: string[] = [];
+  lines.push("WORKSPACE MIGRATION REPORT");
+  lines.push("═══════════════════════════════════");
+  lines.push(`Files ingested:  ${result.ingested}`);
+  lines.push(`Files skipped:   ${result.skipped}`);
+  lines.push(`Archived:        ${result.archived ? "Yes" : "No"}`);
+  if (result.archivePath) lines.push(`Archive path:    ${result.archivePath}`);
+  lines.push("");
+  lines.push("Details:");
+  for (const detail of result.details) {
+    lines.push(`  ${detail}`);
+  }
+  if (result.ingested > 0) {
+    lines.push("");
+    lines.push("SOUL.md was left in place — it will be read as a nudge during soul graduation.");
+  }
+
+  return {
+    content: [{ type: "text" as const, text: lines.join("\n") }],
+    details: result,
+  };
+}
+
+async function queryAction(store: any, table?: string, template?: string) {
+  const tmpl = template ?? "";
+  if (!QUERY_TEMPLATES[tmpl]) {
+    const available = Object.entries(QUERY_TEMPLATES)
+      .map(([k, v]) => `  ${k}${v.needsTable ? " (requires table)" : ""}: ${v.description}`)
+      .join("\n");
+    return {
+      content: [{ type: "text" as const, text: `Available query templates:\n${available}` }],
+      details: { templates: Object.keys(QUERY_TEMPLATES) },
+    };
+  }
+
+  const spec = QUERY_TEMPLATES[tmpl];
+  if (spec.needsTable && (!table || !ALLOWED_TABLES.has(table))) {
+    return {
+      content: [{ type: "text" as const, text: `Error: "${tmpl}" requires a valid table.` }],
+      details: null,
+    };
+  }
+
+  // Embedding coverage special case
+  if (tmpl === "embedding_coverage") {
+    const lines: string[] = [];
+    for (const t of VECTOR_TABLES) {
+      try {
+        const totalRows = await store.queryFirst(
+          `SELECT count() AS count FROM type::table($t) GROUP ALL`, { t },
+        );
+        const embRows = await store.queryFirst(
+          `SELECT count() AS count FROM type::table($t) WHERE embedding != NONE AND array::len(embedding) > 0 GROUP ALL`, { t },
+        );
+        const total = totalRows[0]?.count ?? 0;
+        const emb = embRows[0]?.count ?? 0;
+        const pct = total > 0 ? Math.round((emb / total) * 100) : 0;
+        lines.push(`  ${(t + ":").padEnd(20)} ${emb}/${total} (${pct}%)`);
+      } catch { /* skip */ }
+    }
+    return { content: [{ type: "text" as const, text: `Embedding coverage:\n${lines.join("\n")}` }], details: null };
+  }
+
+  const rows = await store.queryFirst(spec.sql, table ? { t: table } : undefined);
+  if (rows.length === 0) {
+    return { content: [{ type: "text" as const, text: `No results for "${tmpl}".` }], details: null };
+  }
+
+  const formatted = rows.map((r: any, i: number) => {
+    const fields = Object.entries(r)
+      .filter(([k]) => k !== "embedding")
+      .map(([k, v]) => {
+        if (typeof v === "string" && v.length > 200) return `${k}: ${v.slice(0, 200)}...`;
+        return `${k}: ${JSON.stringify(v)}`;
+      })
+      .join(", ");
+    return `${i + 1}. ${fields}`;
+  }).join("\n");
+
+  return {
+    content: [{ type: "text" as const, text: `${tmpl}${table ? ` (${table})` : ""}:\n${formatted}` }],
+    details: { count: rows.length },
+  };
+}

package/src/tools/recall.ts

@@ -0,0 +1,102 @@
+/**
+ * Recall tool — search the persistent memory graph.
+ * Ported from kongbrain with SurrealStore/EmbeddingService injection.
+ */
+
+import { Type } from "@sinclair/typebox";
+import type { GlobalPluginState, SessionState } from "../state.js";
+import { findRelevantSkills, formatSkillContext } from "../skills.js";
+import { swallow } from "../errors.js";
+import type { VectorSearchResult } from "../surreal.js";
+
+const recallSchema = Type.Object({
+  query: Type.String({ description: "What to search for in memory. Can be a concept, topic, decision, file path, or natural language description." }),
+  scope: Type.Optional(Type.Union([
+    Type.Literal("all"),
+    Type.Literal("memories"),
+    Type.Literal("concepts"),
+    Type.Literal("turns"),
+    Type.Literal("artifacts"),
+    Type.Literal("skills"),
+  ], { description: "Limit search to a specific memory type. Default: all." })),
+  limit: Type.Optional(Type.Number({ description: "Max results to return. Default: 5, max: 15." })),
+});
+
+export function createRecallToolDef(state: GlobalPluginState, session: SessionState) {
+  return {
+    name: "recall",
+    label: "Memory Recall",
+    description: "Search your persistent memory graph for past conversations, decisions, concepts, files, and context from previous sessions. Context from past sessions is already auto-injected — check what you have before calling this.",
+    parameters: recallSchema,
+    execute: async (_toolCallId: string, params: { query: string; scope?: string; limit?: number }) => {
+      const { store, embeddings } = state;
+      if (!embeddings.isAvailable() || !store.isAvailable()) {
+        return { content: [{ type: "text" as const, text: "Memory system unavailable." }], details: null };
+      }
+
+      const maxResults = Math.min(params.limit ?? 5, 15);
+
+      try {
+        const queryVec = await embeddings.embed(params.query);
+        const scope = params.scope ?? "all";
+
+        if (scope === "skills") {
+          const skills = await findRelevantSkills(queryVec, maxResults);
+          if (skills.length === 0) {
+            return { content: [{ type: "text" as const, text: `No skills found matching "${params.query}".` }], details: null };
+          }
+          return {
+            content: [{ type: "text" as const, text: `Found ${skills.length} relevant skills:\n${formatSkillContext(skills)}` }],
+            details: { count: skills.length, ids: skills.map((s) => s.id) },
+          };
+        }
+
+        const limits = {
+          turn: scope === "all" || scope === "turns" ? maxResults : 0,
+          identity: 0,
+          concept: scope === "all" || scope === "concepts" ? maxResults : 0,
+          memory: scope === "all" || scope === "memories" ? maxResults : 0,
+          artifact: scope === "all" || scope === "artifacts" ? maxResults : 0,
+        };
+
+        const results = await store.vectorSearch(queryVec, session.sessionId, limits);
+
+        const topIds = results
+          .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+          .slice(0, 5)
+          .map((r) => r.id);
+
+        let neighbors: VectorSearchResult[] = [];
+        if (topIds.length > 0) {
+          try {
+            const expanded = await store.graphExpand(topIds, queryVec);
+            const existingIds = new Set(results.map((r) => r.id));
+            neighbors = expanded.filter((n) => !existingIds.has(n.id));
+          } catch (e) { swallow("recall:graphExpand", e); }
+        }
+
+        const all = [...results, ...neighbors]
+          .sort((a, b) => (b.score ?? 0) - (a.score ?? 0))
+          .slice(0, maxResults);
+
+        if (all.length === 0) {
+          return { content: [{ type: "text" as const, text: `No memories found matching "${params.query}".` }], details: null };
+        }
+
+        const formatted = all.map((r, i) => {
+          const tag = r.table === "turn" ? `[${r.role ?? "turn"}]` : `[${r.table}]`;
+          const time = r.timestamp ? ` (${new Date(r.timestamp).toLocaleDateString()})` : "";
+          const score = r.score ? ` score:${r.score.toFixed(2)}` : "";
+          return `${i + 1}. ${tag}${time}${score}\n   ${(r.text ?? "").slice(0, 500)}`;
+        }).join("\n\n");
+
+        return {
+          content: [{ type: "text" as const, text: `Found ${all.length} results for "${params.query}":\n\n${formatted}` }],
+          details: { count: all.length, ids: all.map((r) => r.id) },
+        };
+      } catch (err) {
+        return { content: [{ type: "text" as const, text: `Memory search failed: ${err}` }], details: null };
+      }
+    },
+  };
+}