@polycode-projects/the-mechanical-code-talker 2.10.3 → 2.11.0

package/src/surfaces/web/memory-stats.mjs

@@ -0,0 +1,53 @@
+// memory-stats.mjs — the "what does this session's memory hold" reader,
+// shared by chat-browser-entry.mjs and ingest-browser-entry.mjs so both
+// bundles' stats panels read the exact same breakdown for the exact same
+// store shape.
+import { loadMemory, readFactRows } from "../../adapters/memory/core.mjs";
+import { provenanceTagToSource } from "../../domain/memory/trust.mjs";
+
+/**
+ * The memory a running session holds, broken down by where each fact came
+ * from: the seed corpus bands it booted with (keyed by the SAME band name
+ * build-chat-seed.mjs/extensions.mjs seed under — "human", "seon",
+ * "conceptnet" today, whichever bands a future seed adds tomorrow) plus
+ * whatever has been taught THIS session. Reuses memory/trust.mjs's own
+ * `provenanceTagToSource` against each fact's already-stored provenance
+ * tag(s) (readFactRows' `provenance`, the ' | '-joined compat string) rather
+ * than inventing a second provenance parse — the same tag chat.mjs's own
+ * "(source: ...)" citation already carries, so this panel and a turn's
+ * citation always agree on where a fact came from.
+ *
+ * Returns { total, bandCounts, taught }: `bandCounts` maps a band label to
+ * its fact count ("taught this session" for a teach/operator-sourced fact
+ * with no corpus band, "other" for anything provenance can't place);
+ * `taught` lists every session-taught fact (subject/predicate/object + its
+ * own provenance tag), most-recently-taught last — a stats panel's
+ * provenance column reads straight off this, no further lookup needed.
+ */
+export async function memoryStats(memoryDir) {
+  const memory = await loadMemory(memoryDir);
+  const rows = readFactRows(memory);
+  const bandCounts = {};
+  const taught = [];
+  for (const row of rows) {
+    const tags = String(row.provenance || "").split(" | ").filter(Boolean);
+    let band = null;
+    let isTaught = false;
+    let taughtTag = "";
+    for (const tag of tags) {
+      const src = provenanceTagToSource(tag);
+      if (!src) continue;
+      // corpusWeak (a /r/RelatedTo-strength triple, e.g. ConceptNet's or
+      // SEON's own weaker associations) names the SAME band as corpus (a
+      // /r/IsA-strength one) — both carry `src.name`, and a band count that
+      // dropped the weak tier would undercount a corpus by exactly its
+      // weak-relation facts (SEON: 19 of them, all `corpus-weak:seon`).
+      if ((src.kind === "corpus" || src.kind === "corpusWeak") && src.name) band = src.name;
+      if (src.kind === "teach" || src.kind === "operator") { isTaught = true; taughtTag = tag; }
+    }
+    const label = band || (isTaught ? "taught this session" : "other");
+    bandCounts[label] = (bandCounts[label] || 0) + 1;
+    if (isTaught) taught.push({ subject: row.subject, predicate: row.predicate, object: row.object, tag: taughtTag });
+  }
+  return { total: rows.length, bandCounts, taught };
+}

package/src/tools/definitions.mjs

@@ -297,6 +297,20 @@ export const TOOL_DEFINITIONS = Object.freeze([
     inputSchema: { type: "object", required: [], properties: {} },
     example: {},
   },
+  {
+    name: "tmct_ingest",
+    tier: "cold",
+    summary: "Ground plain text into memory facts with the same deterministic recognizer the chat teach lane uses — the strict tier, plus an optional lower-trust fuzzy tier — and report the canonical triples.",
+    inputSchema: {
+      type: "object",
+      required: ["text"],
+      properties: {
+        text: { type: "string", description: "The plain text to ground into facts." },
+        optimistic: { type: "boolean", description: "Also run the lower-trust fuzzy tier over sentences the strict recognizer skips." },
+      },
+    },
+    example: { text: "A kettle is a container. An otter is a mammal.", optimistic: true },
+  },
 ]);
 
 export const HOT_TOOLS = TOOL_DEFINITIONS.filter((t) => t.tier === "hot");

package/src/tools/handlers/index.mjs

@@ -29,6 +29,7 @@ import { tmct_callees } from "./tmct-callees.mjs";
 import { tmct_calls } from "./tmct-calls.mjs";
 import { tmct_cochanges } from "./tmct-cochanges.mjs";
 import { tmct_export } from "./tmct-export.mjs";
+import { tmct_ingest } from "./tmct-ingest.mjs";
 
 export const HANDLERS = Object.freeze({
   tmct_context,
@@ -55,4 +56,5 @@ export const HANDLERS = Object.freeze({
   tmct_calls,
   tmct_cochanges,
   tmct_export,
+  tmct_ingest,
 });

package/src/tools/handlers/tmct-ingest.mjs

@@ -0,0 +1,43 @@
+// tmct_ingest — ground plain text into the conversational-memory store with the
+// same deterministic recognizer the chat teach lane uses. The strict tier keeps
+// only sentences the recognizer turns into stored facts; with optimistic:true the
+// lower-trust fuzzy tier also reaches the sentences it skips. Answers with the
+// canonical triples it grounded and an honest recognized/skipped summary — no
+// LLM, no guessing.
+//
+// The recognizer (ingestText, src/services/extract-facts.mjs) lives in the SERVICE
+// layer, above the tool layer, so this handler never imports it: a service-layer
+// caller injects it as `ingest` through dispatchTool's ctx (bin/tmct.mjs's `cli`
+// route and the chat surface both hold it). Called without that seam wired, the
+// tool says so honestly rather than guessing.
+//
+// Reads the conversational-memory store (not the code-map graph), so it owns its
+// own load and writes with or without a code graph present.
+
+import { dirname } from "node:path";
+import { openConfiguredMemoryBackend } from "../../adapters/memory/core.mjs";
+
+export async function tmct_ingest(args, { config, ingest }) {
+  const text = String(args?.text ?? "");
+  if (!text.trim()) return "(nothing to ingest — pass some text)";
+  if (typeof ingest !== "function") {
+    return "(ingest isn't wired into this context — invoke tmct_ingest through the CLI `cli` route or the chat surface)";
+  }
+  const optimistic = args?.optimistic === true;
+  const { dir, close } = await openConfiguredMemoryBackend(dirname(dirname(config.graphFile)));
+  try {
+    const result = await ingest(text, { memoryDir: dir, config, sourceTag: "tool", optimistic, canonical: true });
+    const grounded = result.extracted.length + result.optimistic.length;
+    const header = `${result.sentences} sentence(s), ${result.recognized} recognized`
+      + (optimistic ? `, ${result.optimistic.length} optimistic candidate(s)` : "")
+      + `, ${result.skipped} skipped — ${grounded} fact(s) grounded.`;
+    return grounded ? `${header}\n${result.canonical.join("\n")}` : header;
+  } finally {
+    await close();
+  }
+}
+
+// The memory store is this tool's only source — it writes with or without a
+// code-map graph, so the shared code-graph load (which refuses an empty graph)
+// must not gate it.
+tmct_ingest.ownsGraphLoad = true;

package/src/tools/server.mjs

@@ -44,13 +44,16 @@ export const TOOLS = HOT_TOOLS.map(({ name, agentDescription, inputSchema }) =>
   inputSchema,
 }));
 
-export async function dispatchTool(name, args, { config, source = defaultSource, tel = null } = {}) {
+export async function dispatchTool(name, args, { config, source = defaultSource, tel = null, ingest = null } = {}) {
   // Reject an unknown tool BEFORE touching the graph — an unknown name never
   // triggers a load. hasOwn, so an inherited name ("constructor", "toString")
   // is unknown rather than a callable found on the prototype chain.
   if (!Object.hasOwn(HANDLERS, name)) throw new ToolError(`unknown tool: ${name}`);
   const handle = HANDLERS[name];
-  if (handle.ownsGraphLoad) return handle(args, { config, source, tel });
+  // `ingest` is the recognizer seam a caller in the service layer injects (the
+  // tool layer sits UNDER services and must not import one, so a tool that needs
+  // the chat recognizer receives it here rather than importing it).
+  if (handle.ownsGraphLoad) return handle(args, { config, source, tel, ingest });
   const graph = await loadGraph(config, source);
   // repo root = the dir containing .tmct/ (graphFile = <repo>/.tmct/graph.json). Passed to
   // createGraphService so svc.snippet()/svc.context() are usable directly, and on to the