@polycode-projects/the-mechanical-code-talker 0.5.0 → 0.7.0

package/src/corpus/conceptnet.mjs

@@ -4,7 +4,7 @@
 //   loadSlice(path?)        stream corpus/conceptnet/slice.jsonl → assertions
 //   loadMap(path?)          src/corpus/conceptnet-map.toml → Map(rel → row)
 //   toFacts(assertions,map) assertions → appendFact-shaped triples
-//   seedMemory(dir, opts)   write them into <dir>/.tmct/memory via appendFact
+//   seedMemory(dir, opts)   write them into <dir>/.tmct/memory via appendFacts (one batched write)
 //
 // The slice is committed data (one JSON object per line: {start, rel, end,
 // surfaceText?, weight}; en→en only; CC-BY-SA 4.0 for ConceptNet-derived rows
@@ -13,11 +13,12 @@
 // ace = "none" are deliberate non-emissions. A slice relation MISSING from
 // the table is a drift error — loud, never guessed around.
 //
-// Seeding goes through src/memory/core.mjs appendFact() ONLY (memory is
-// import-only here): fact ids are content-hashed from (s,p,o), so re-seeding
-// is idempotent by construction. seedMemory additionally pre-loads the store
-// once and skips triples already present, so a re-seed is read-mostly instead
-// of N rewrites.
+// Seeding goes through src/memory/core.mjs appendFacts() (memory is import-only
+// here): fact ids are content-hashed from (s,p,o), so re-seeding is idempotent by
+// construction. seedMemory pre-loads the store once and skips triples already
+// present, then hands the survivors to appendFacts as ONE batched read-modify-
+// write — so seeding the whole slice is O(N), not the O(N²) a per-fact appendFact
+// loop would incur (the 6 k-fact slice: ~7 min → a couple of seconds).
 
 import { createReadStream } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -25,12 +26,23 @@ import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { parse as parseToml } from "smol-toml";
-import { appendFact, loadMemory, normFactTerm } from "../memory/core.mjs";
+import { appendFacts, loadMemory, normFactTerm } from "../memory/core.mjs";
 
 const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 export const SLICE_FILE = join(PKG_ROOT, "corpus", "conceptnet", "slice.jsonl");
 export const MAP_FILE = join(PKG_ROOT, "src", "corpus", "conceptnet-map.toml");
 
+// The tier-1 curated Software-Engineering ontology (SEON). concepts.jsonl is in
+// the SAME slice shape as ConceptNet ({start, rel, end, weight}), so it loads +
+// maps through the identical loadSlice/loadMap/toFacts path — just with a
+// "corpus:seon" provenance prefix. definitions.jsonl is a separate {term,
+// definition, sense} list the chat answer layer prefers for a lexicon term's
+// "what is a <term>". tier-2 corpuses (aws/python/java) share the slice shape too.
+export const SEON_CONCEPTS_FILE = join(PKG_ROOT, "corpus", "seon", "concepts.jsonl");
+export const SEON_DEFINITIONS_FILE = join(PKG_ROOT, "corpus", "seon", "definitions.jsonl");
+export const TIER2_DIR = join(PKG_ROOT, "corpus", "tier2");
+export const TIER2_MANIFEST_FILE = join(TIER2_DIR, "manifest.json");
+
 const ACE_PATTERNS = new Set(["subClassOf", "type", "ObjectProperty", "someValuesFrom", "disjointWith", "property", "none"]);
 
 /** Load the slice JSONL as a stream (never the whole file as one string) and
@@ -92,8 +104,13 @@ export const termText = (uri) => {
  *  (provenance is a STRING — exactly what src/memory/core.mjs appendFact
  *  takes; it names the corpus and the originating ConceptNet relation).
  *  Rows whose relation maps ace="none" are skipped — deliberate non-emission.
- *  A relation with NO row in the map throws: that is table drift, not data. */
-export function toFacts(assertions, map) {
+ *  A relation with NO row in the map throws: that is table drift, not data.
+ *
+ *  `provenancePrefix` names the corpus half of the provenance string; it defaults
+ *  to "corpus:conceptnet" so the ConceptNet seed stays BYTE-IDENTICAL to before.
+ *  The seon / tier-2 corpuses reuse the same slice shape, tagged "corpus:seon" or
+ *  "corpus:tier2:<id>" so a reader can tell a curated SE fact from ConceptNet noise. */
+export function toFacts(assertions, map, provenancePrefix = "corpus:conceptnet") {
   const facts = [];
   for (const a of assertions) {
     const row = map.get(a.rel);
@@ -108,7 +125,7 @@ export function toFacts(assertions, map) {
       subject,
       predicate: row.predicate,
       object,
-      provenance: `corpus:conceptnet ${a.rel}`,
+      provenance: `${provenancePrefix} ${a.rel}`,
     });
   }
   return facts;
@@ -124,13 +141,16 @@ export function toFacts(assertions, map) {
  *  location trivia the slice happens to open with; without `prefer` the
  *  behavior is byte-identical to before.
  *
- *  Idempotent twice over: appendFact's content-hashed ids make a blind
+ *  Idempotent twice over: appendFacts' content-hashed ids make a blind
  *  re-append an upsert, and we pre-read the store once to skip triples that
- *  are already there (so re-seeding costs one read, not N rewrites).
- *  Returns { appended, skipped, total }. */
-export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath = MAP_FILE, prefer } = {}) {
+ *  are already there (so re-seeding costs one read, not N rewrites). The
+ *  survivors are written in ONE batched appendFacts call, not a per-fact loop.
+ *  Returns { appended, skipped, total }. `provenancePrefix` is threaded through to
+ *  toFacts (default "corpus:conceptnet" → byte-identical seed) so a seon/tier-2
+ *  corpus can tag its facts "corpus:seon" / "corpus:tier2:<id>". */
+export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath = MAP_FILE, prefer, provenancePrefix } = {}) {
   const [assertions, map] = await Promise.all([loadSlice(slicePath), loadMap(mapPath)]);
-  let facts = toFacts(assertions, map);
+  let facts = toFacts(assertions, map, provenancePrefix);
   if (Array.isArray(prefer) && prefer.length) {
     const rank = new Map(prefer.map((p, i) => [p, i]));
     // stable partition: Array.prototype.sort is stable in Node, so equal-rank
@@ -151,17 +171,20 @@ export async function seedMemory(dir, { limit, slicePath = SLICE_FILE, mapPath =
     existing.add(factKey(get("subject"), get("predicate"), get("object")));
   }
 
-  let appended = 0;
   let skipped = 0;
+  const toWrite = [];
   for (const fact of facts) {
     const key = factKey(fact.subject, fact.predicate, fact.object);
     if (existing.has(key)) {
       skipped += 1;
       continue;
     }
-    await appendFact(dir, fact);
     existing.add(key);
-    appended += 1;
+    toWrite.push(fact);
   }
-  return { appended, skipped, total: facts.length };
+  // ONE read-modify-write for the whole seed (was one per fact — O(N²) I/O, ~7 min
+  // for the 6 k-fact slice). appendFacts also skips any malformed row rather than
+  // throwing, so its skipped count folds into the dedup skips here.
+  const res = await appendFacts(dir, toWrite);
+  return { appended: res.appended, skipped: skipped + res.skipped, total: facts.length };
 }

package/src/init.mjs

@@ -35,12 +35,14 @@ export const MEMORY_DIR_REL = join(".tmct", "memory");
 export const SESSIONS_DIR_REL = join(".tmct", "sessions");
 export const SEED_MARKER_REL = join(".tmct", "memory", "corpus-seed.json");
 
-/** How many corpus facts the seed writes — matches chat.mjs SEED_LIMIT so an
- *  init-seeded repo and a bootstrap-seeded repo carry the identical slice. */
-export const SEED_LIMIT = 500;
+/** `undefined` = seed the WHOLE ConceptNet band (no cap) — matches chat.mjs
+ *  SEED_LIMIT so an init-seeded repo and a bootstrap-seeded repo carry the identical
+ *  slice. A number in `tmct.toml`'s `seed.limit` still caps (explicit user override);
+ *  absent ⇒ all. */
+export const SEED_LIMIT = undefined;
 
-/** Predicate preference for the capped seed (definitional band first) — matches
- *  chat.mjs SEED_PREFER so "what is a cache?" answers land in the first 500. */
+/** Predicate order for the seed (definitional band first) — matches chat.mjs
+ *  SEED_PREFER. With the cap lifted this sets ORDER only; every fact seeds. */
 export const SEED_PREFER = ["rdfs:subClassOf", "rdf:type", "mgx:usedFor", "mgx:partOf", "mgx:capableOf"];
 
 /** The shipped default config — the exact shape written into `tmct.toml` and
@@ -49,7 +51,7 @@ export function defaultConfig() {
   return {
     graphFile: join(".tmct", "graph.json"),
     corpus: { tier: "tier1" },
-    seed: { enabled: true, limit: SEED_LIMIT },
+    seed: { enabled: true },
   };
 }
 
@@ -103,8 +105,9 @@ tier = ${JSON.stringify(corpus.tier)}
 # Offline and deterministic. Set false, or export TMCT_NO_SEED=1, to opt out —
 # the repo still initialises, just empty of corpus facts.
 enabled = ${seed.enabled ? "true" : "false"}
-# How many facts the seed writes (definitional band first).
-limit = ${Number(seed.limit)}
+# By default the WHOLE committed slice seeds (no cap — the operator's "seed all").
+# To cap it, uncomment and set a number (definitional band first):
+${seed.limit != null ? `limit = ${Number(seed.limit)}` : "# limit = 500"}
 `;
 }
 
@@ -183,7 +186,7 @@ export async function initRepo(dir, { force = false, seed, env = process.env } =
   } else {
     try {
       const { seedMemory } = await import("./corpus/conceptnet.mjs");
-      const limit = Number(config.seed?.limit) || SEED_LIMIT;
+      const limit = config.seed?.limit != null ? Number(config.seed.limit) : SEED_LIMIT;
       seedResult = await seedMemory(root, { limit, prefer: SEED_PREFER });
       const markerNew = !(await exists(paths.marker));
       await mkdir(dirname(paths.marker), { recursive: true });

package/src/interpret/normalize.mjs

@@ -90,6 +90,48 @@ export function applyNegationFrames(text) {
   return text;
 }
 
+// ---- phrasing frames (SKILL_CHAT_PLAYTEST drill-down loop) — route the natural
+// ways a developer asks a MEMBERS-of-class or a WHERE-DEFINED question onto the
+// canonical shapes the grammar already answers, so a phrasing miss becomes a real
+// answer (or an honest empty with a receipt) instead of the grammar wall. Same
+// closed-pattern, first-match-wins discipline as the negation/commit frames: each
+// frame REWRITES the whole line to a canonical query BOTH parse strategies then
+// handle for free. Run AFTER applyNegationFrames so a sha "what's in <sha>" is
+// already the commit-subject question before the members frame could see it. ----
+export const PHRASING_FRAMES = Object.freeze([
+  // MEMBERS-of-class → "what does X contain".
+  //   "what functions are in Task", "what methods are inside X", "what attributes are in X"
+  { re: /^what\s+(?:functions?|methods?|members?|attributes?|fields?|properties)\s+(?:are|is)\s+(?:in|inside|within)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `what does ${m[1]} contain` },
+  //   "what functions does Task have", "what methods does X have"
+  { re: /^what\s+(?:functions?|methods?|members?|attributes?|fields?|properties)\s+(?:does|do)\s+(.+?)\s+have\??$/i, to: (m) => `what does ${m[1]} contain` },
+  //   "what are the members of X", "what are the methods in X"
+  { re: /^what\s+are\s+(?:the\s+)?(?:functions?|methods?|members?|attributes?|fields?|properties)\s+(?:of|in|inside|within)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `what does ${m[1]} contain` },
+  //   "members of X", "methods of X", "contents of X"
+  { re: /^(?:the\s+)?(?:members?|methods?|attributes?|contents)\s+of\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `what does ${m[1]} contain` },
+  //   "what's in X" / "what is in X" (contraction already expanded; sha handled above)
+  { re: /^what\s+is\s+(?:in|inside)\s+(?:the\s+)?(.+?)\??$/i, to: (m) => `what does ${m[1]} contain` },
+
+  // WHERE-DEFINED → "where is X defined". PAST TENSE ONLY ("what defined X", "what
+  // declared X"): the PRESENT "what defines X" already parses as a reverse-defines
+  // query (the module defining symbol X — test/ask.test.mjs pins that), so rewriting
+  // it would change that receipt. The past-tense form is the one that hit the wall.
+  { re: /^what\s+(?:defined|declared)\s+(?:the\s+)?(?:function\s+|method\s+|class\s+|module\s+|variable\s+|constant\s+)?(.+?)\??$/i, to: (m) => `where is ${m[1]} defined` },
+  //   "where's X defined" (the "where's" contraction is not in the contraction table)
+  { re: /^where'?s\s+(?:the\s+)?(.+?)\s+(defined|declared|located|implemented)\??$/i, to: (m) => `where is ${m[1]} ${m[2]}` },
+]);
+
+/** Apply the phrasing frames (members-of-class + where-defined) — first match wins
+ *  and rewriting stops; unmatched text passes through unchanged. Kept SEPARATE from
+ *  applyNegationFrames so the ordering (negation/commit first, then phrasing) is
+ *  explicit at the call site (normalizeInput). */
+export function applyPhrasingFrames(text) {
+  for (const frame of PHRASING_FRAMES) {
+    const m = text.match(frame.re);
+    if (m) return frame.to(m).replace(/\s+/g, " ").trim();
+  }
+  return text;
+}
+
 // ---- §B1 negation — the SET-COMPLEMENT frame (Cycle 5, PLAN_CYCLE_4.md). Recognizes
 // a BARE set-negation query — "which X do not <verb> Y", "X that don't <verb> Y",
 // "modules not importing Y", "which X are not <qualifier>" — and returns a descriptor

package/src/interpret/pipeline.mjs

@@ -23,7 +23,7 @@
 // normalization changed the input (`normalizationChanged`), so a repaired
 // spelling/contraction is on the record, never silent.
 
-import { normalizeQuery, applyNegationFrames } from "./normalize.mjs";
+import { normalizeQuery, applyNegationFrames, applyPhrasingFrames } from "./normalize.mjs";
 import { grammarStrategy } from "./strategies/grammar.mjs";
 import { keywordSpotStrategy } from "./strategies/keywords.mjs";
 import { noiseStripStrategy } from "./strategies/noise-strip.mjs";
@@ -47,7 +47,7 @@ export const STRATEGIES = [grammarStrategy, keywordSpotStrategy, noiseStripStrat
  *  before any strategy runs. Returns {raw, text, changed}. */
 export function normalizeInput(input) {
   const raw = String(input || "").trim().replace(/\s+/g, " ");
-  const text = raw ? applyNegationFrames(normalizeQuery(raw)) : "";
+  const text = raw ? applyPhrasingFrames(applyNegationFrames(normalizeQuery(raw))) : "";
   return { raw, text, changed: text !== raw };
 }
 

package/src/memory/core.mjs

@@ -425,6 +425,14 @@ export function normFactTerm(t) {
   return s.toLowerCase();
 }
 
+// The fact-id contract: a Fact is content-addressed by its NUL-DELIMITED
+// (s, p, o). NUL never occurs in a normalized term or a predicate URI, so it is
+// a collision-proof separator (a space could be forged by a term that contains
+// one). appendFact hashes the SAME `${s}\0${p}\0${o}` inline; appendFacts routes
+// through here so the batch path can never drift to a space and silently re-key
+// every seeded fact — the golden-equivalence test pins the two paths together.
+const factIdFor = (s, p, o) => `fact:${fnv1aHex(`${s}\0${p}\0${o}`)}`;
+
 /** Append one grammar-derived OWL triple, RDF-reified: a `Fact` individual
  *  carrying rdf:subject / rdf:predicate / rdf:object (+ provenance). The
  *  Phase-2 ACE parser's write point. Same (s,p,o) → same id → upsert, never a
@@ -465,6 +473,82 @@ export async function appendFact(dir, { subject, predicate, object, provenance =
   return { id };
 }
 
+/** Batch append of grammar/corpus-derived triples — ONE read-modify-write for a
+ *  whole seed (the appendUtterances precedent, for facts). The per-fact
+ *  appendFact does a full read → mutate → prose-reindex → atomic-write PER FACT,
+ *  so seeding N facts is O(N²) I/O (6 k facts ≈ 7 min); this collapses it to a
+ *  single mutate.
+ *
+ *  Every fact is normalized + prose-tokenized OUTSIDE the mutate, then a SINGLE
+ *  mutateMemory upserts each Fact through an id→individual Map (O(1) upsert, so
+ *  the growing individuals array is never rescanned per fact), reconciles each
+ *  touched fact's Sources + trust via the SAME syncFactSources appendFact uses,
+ *  and recountClasses ONCE at the end. The result is deep-equal (modulo array
+ *  order) to looping appendFact: same fact ids, same mgx:factProvenance union,
+ *  same statedBy Source edges, same mgx:trustScore, same first-write-wins
+ *  createdAt. Malformed facts (missing subject/predicate/object) are SKIPPED (a
+ *  bad row never aborts a 6 k-fact seed), not thrown as appendFact does.
+ *  Returns { ids, appended, skipped } — ids one per applied fact (in order),
+ *  appended = ids.length, skipped = malformed count. */
+export async function appendFacts(dir, facts) {
+  const prepared = [];
+  let skipped = 0;
+  for (const f of facts || []) {
+    const s = normFactTerm(f?.subject);
+    const p = normText(f?.predicate);
+    const o = normFactTerm(f?.object);
+    if (!s || !p || !o) { skipped += 1; continue; } // batch skips, never throws
+    const text = `${s} ${p} ${o}`;
+    prepared.push({
+      id: factIdFor(s, p, o), // NUL-delimited — byte-identical to appendFact's id
+      s, p, o, text,
+      tokens: proseTokensFor({ doc: text }),
+      provenance: normText(f?.provenance),
+      createdAt: f?.createdAt || "",
+    });
+  }
+  const ids = [];
+  if (!prepared.length) return { ids, appended: 0, skipped };
+  await mutateMemory(dir, (payload) => {
+    // id → individual index for O(1) upsert (the array grows to thousands).
+    const byId = new Map(payload.individuals.map((i) => [i?.id, i]));
+    const touched = [];
+    const seen = new Set();
+    for (const f of prepared) {
+      const prior = byId.get(f.id);
+      const priorProv = prior?.attributes?.find((a) => a?.prop === "mgx:factProvenance")?.value || "";
+      // Same as appendFact: the mgx:factProvenance union stays byte-identical (a
+      // compat shim); the Source edges below are DERIVED from it, purely additive.
+      const provs = [...new Set([...priorProv.split(" | "), f.provenance].filter(Boolean))];
+      const createdAtVal = firstWriteCreatedAt(prior, f.createdAt); // first-write-wins
+      const ind = {
+        id: f.id, label: labelOf(f.text), class: FACT_CLASS,
+        derived_from: [], mentions: [],
+        attributes: [
+          { prop: "rdf:type", key: "type", value: "rdf:Statement" },
+          { prop: "rdf:subject", key: "subject", value: f.s },
+          { prop: "rdf:predicate", key: "predicate", value: f.p },
+          { prop: "rdf:object", key: "object", value: f.o },
+          { prop: CREATED_AT_PROP, key: "createdAt", value: createdAtVal },
+          ...(provs.length ? [{ prop: "mgx:factProvenance", key: "provenance", value: provs.join(" | ") }] : []),
+          ...(f.tokens.length ? [{ prop: "mgx:hasProseTokens", key: "prose_tokens", value: f.tokens.join(" ") }] : []),
+        ],
+      };
+      // Upsert into BOTH the array (replace-in-place keeps order) and the index.
+      if (prior) payload.individuals[payload.individuals.indexOf(prior)] = ind;
+      else payload.individuals.push(ind);
+      byId.set(f.id, ind);
+      ids.push(f.id);
+      if (!seen.has(f.id)) { seen.add(f.id); touched.push(f.id); }
+    }
+    // Reconcile each touched fact's Sources + trust once (add-only, idempotent),
+    // then recount classes a SINGLE time at the end.
+    for (const id of touched) syncFactSources(payload, byId.get(id));
+    recountClasses(payload);
+  });
+  return { ids, appended: ids.length, skipped };
+}
+
 // ---- Chat-facing seams (W4 fact lookup + contradiction) ---------------------
 // The W4 fact-lookup THREADING lives in chat.mjs (NOT here); these pure readers
 // are the seam it calls so the answer layer ranks candidates by relevance ×

package/src/memory/inspect.mjs

@@ -128,6 +128,31 @@ export function renderMemory({ memory, blocks }, { verbose = false } = {}) {
     lines.push("", "blocks — none folded yet (a session folds when it ends).");
   }
 
+  // ---- explore hooks: real, runnable example queries built from what's actually
+  //      stored, so /memory is a springboard for drilling in, not just a dump ----
+  if (individuals.length) {
+    const clean = (t) => typeof t === "string" && /^[a-z][a-z0-9]+(?: [a-z0-9]{2,}){0,2}$/.test(t) && t.length <= 22 && !/^\d+$/.test(t);
+    const facts = readFactRows(memory);
+    // Rank candidate "what is a X" terms by CATEGORY SIZE (how many facts point at
+    // them) so the hooks land on rich, recognisable categories (function, class, …),
+    // not a lone ConceptNet oddity.
+    const freq = new Map();
+    for (const f of facts) if (clean(f.object)) freq.set(f.object, (freq.get(f.object) || 0) + 1);
+    const terms = [...freq.entries()]
+      .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+      .map(([t]) => t)
+      .slice(0, 3);
+    const sample = facts.find((f) => clean(f.subject) && terms.includes(f.object));
+    const ex = terms.map((t) => `  what is a ${t}`);
+    if (sample) ex.push(`  is a ${sample.subject} a ${sample.object}`);
+    if (terms[0]) ex.push(`  what did i tell you about ${terms[0]}`);
+    if (ex.length) {
+      lines.push("", "explore — ask any of these (real terms from the store above):");
+      lines.push(...ex);
+      lines.push("  /memory verbose — the full store   ·   /stats — the code-graph overview");
+    }
+  }
+
   return lines.join("\n");
 }
 

package/src/server.mjs

@@ -49,9 +49,73 @@ import {
 } from "./codegraph.mjs";
 import { ask } from "./ask.mjs";
 import { createGraphService } from "./providers/graph-service.mjs";
+// Read-ONLY consumers of the conversational-memory graph (src/memory/core.mjs) — the 500
+// corpus facts live there, NOT in the code-map graph.json every tool below loads. Used by
+// the FALL-THROUGH bridge (below): when the code-map resolves NOTHING for a concept query
+// (/subclasses /describe /members /find), answer from the reified isa-family facts instead
+// of a flat "no entity". Never written here; memory writes stay owned by memory/*.
+import { loadMemory, readFactRows, normFactTerm } from "./memory/core.mjs";
 
 const SNIPPET_MAX_LINES = 200;
 
+// The reified isa-family predicates a memory Fact carries ("<subject> rdfs:subClassOf
+// <object>" / "rdf:type"): subject IS-A object. Subclasses of X = facts whose OBJECT is X;
+// superclasses of X = facts whose SUBJECT is X. (Matches chat.mjs's ISA_PREDICATES.)
+const ISA_PREDICATES = new Set(["rdfs:subClassOf", "rdf:type"]);
+const MEMORY_LIST_CAP = 40;
+
+/** Load the conversational-memory Facts as trust-bearing rows, failure-tolerant (no memory
+ *  store / unreadable → [], so the tool still returns its honest code-map miss). repoRoot is
+ *  the dir that CONTAINS .tmct/ (graphFile = <repo>/.tmct/graph.json), which is exactly the
+ *  `dir` loadMemory joins MEMORY_GRAPH_REL onto. */
+async function memoryFactRows(config) {
+  try {
+    return readFactRows(await loadMemory(dirname(dirname(config.graphFile))));
+  } catch {
+    return [];
+  }
+}
+
+/** A short provenance receipt for a set of memory rows — distinct source strings, capped. */
+function memoryProvenance(rows) {
+  const provs = [...new Set(rows.map((r) => r.provenance).filter(Boolean))];
+  if (!provs.length) return "provenance: memory/corpus facts";
+  const shown = provs.slice(0, 2).join("; ");
+  return `provenance: ${shown}${provs.length > 2 ? `, +${provs.length - 2} more source(s)` : ""}`;
+}
+
+/** FALL-THROUGH: subclasses of a concept from the reified isa-family facts (subjects of
+ *  "<subj> subClassOf <term>"). Null when the term names no such facts (so the caller can
+ *  keep the honest code-map miss). Provenance is always cited. */
+function renderMemorySubclasses(rows, term) {
+  const t = normFactTerm(term);
+  const hits = rows.filter((r) => ISA_PREDICATES.has(r.predicate) && r.object === t);
+  if (!hits.length) return null;
+  const labels = [...new Set(hits.map((r) => r.subject))].sort();
+  const shown = labels.slice(0, MEMORY_LIST_CAP);
+  const tail = labels.length > MEMORY_LIST_CAP ? `\n  …+${labels.length - MEMORY_LIST_CAP} more` : "";
+  return `"${term}" is not a code-map entity — answering from memory/corpus facts. ` +
+    `${labels.length} known subclass(es):\n  ${shown.join("\n  ")}${tail}\n(${memoryProvenance(hits)})`;
+}
+
+/** FALL-THROUGH: a concept's DEFINITION from the isa-family facts — its superclasses ("is
+ *  a …") plus a count/sample of its known subclasses. Null when the term names no facts. */
+function renderMemoryDefinition(rows, term) {
+  const t = normFactTerm(term);
+  const isa = rows.filter((r) => ISA_PREDICATES.has(r.predicate) && (r.subject === t || r.object === t));
+  if (!isa.length) return null;
+  const supers = [...new Set(isa.filter((r) => r.subject === t).map((r) => r.object))];
+  const subs = [...new Set(isa.filter((r) => r.object === t).map((r) => r.subject))].sort();
+  const lines = [`"${term}" is not a code-map entity — answering from memory/corpus facts.`];
+  if (supers.length) lines.push(`is a: ${supers.slice(0, MEMORY_LIST_CAP).join(", ")}`);
+  if (subs.length) {
+    const tail = subs.length > MEMORY_LIST_CAP ? `, +${subs.length - MEMORY_LIST_CAP} more` : "";
+    lines.push(`known subclasses (${subs.length}): ${subs.slice(0, MEMORY_LIST_CAP).join(", ")}${tail}`);
+  }
+  lines.push(`(${memoryProvenance(isa)})`);
+  return lines.join("\n");
+}
+
 // Tiered tool surface: the hot tools carry full descriptions/schemas in this
 // catalog; every COLD tool (describe/members/impact/history/…) is still served
 // by dispatchTool below and is reachable via the CLI `cli <tool>` route +
@@ -298,8 +362,11 @@ export async function dispatchTool(name, args, { config, source = defaultSource
   if (name === "tmct_describe") {
     const symbol = String(args?.symbol || "").trim();
     if (!symbol) throw new ToolError("symbol is required");
-    const { match, candidates } = resolveOrThrow(svc, symbol, "symbol");
-    return renderDescribe(graph, match, { candidates });
+    const { match, candidates } = resolveSymbol(svc.graph, symbol);
+    if (match) return renderDescribe(graph, match, { candidates }); // code-map wins when present
+    const fb = renderMemoryDefinition(await memoryFactRows(config), symbol);
+    if (fb) return fb;
+    resolveOrThrow(svc, symbol, "symbol"); // no code-map + no memory fact → the honest miss
   }
   if (name === "tmct_snippet") {
     const symbol = String(args?.symbol || "").trim();
@@ -347,23 +414,37 @@ export async function dispatchTool(name, args, { config, source = defaultSource
     const query = String(args?.query || "").trim();
     const kind = String(args?.kind || "").trim();
     if (!query && !kind) throw new ToolError("query is required");
-    return renderSearch(graph, query, {
+    const out = renderSearch(graph, query, {
       kind,
       decorator: String(args?.decorator || "").trim(),
       name: String(args?.name || "").trim(),
     });
+    // FALL-THROUGH: a code-map miss ("no module matches …") on a plain concept query still
+    // answers from the memory/corpus isa-family facts when the concept is known there.
+    if (!kind && /^no module matches/.test(out)) {
+      const fb = renderMemoryDefinition(await memoryFactRows(config), query);
+      if (fb) return fb;
+    }
+    return out;
   }
   if (name === "tmct_members") {
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
-    const { match } = resolveOrThrow(svc, symbol, "class");
-    return renderMembers(graph, match);
+    const { match } = resolveSymbol(svc.graph, symbol);
+    if (match) return renderMembers(graph, match); // code-map wins when present
+    // a concept's "members" in the corpus sense are its subclasses (its instances).
+    const fb = renderMemorySubclasses(await memoryFactRows(config), symbol);
+    if (fb) return fb;
+    resolveOrThrow(svc, symbol, "class"); // the honest miss
   }
   if (name === "tmct_subclasses") {
     const symbol = String(args?.class || "").trim();
     if (!symbol) throw new ToolError("class is required");
-    const { match } = resolveOrThrow(svc, symbol, "class");
-    return renderSubclasses(graph, match);
+    const { match } = resolveSymbol(svc.graph, symbol);
+    if (match) return renderSubclasses(graph, match); // code-map wins when present
+    const fb = renderMemorySubclasses(await memoryFactRows(config), symbol);
+    if (fb) return fb;
+    resolveOrThrow(svc, symbol, "class"); // no code-map subclass + no memory fact → honest miss
   }
   if (name === "tmct_architecture") {
     return renderArchitecture(graph, { pkg: String(args?.package || "").trim() });

package/src/tui/app.mjs

@@ -92,6 +92,10 @@ export function App({ session }) {
   const [input, setInput] = useState("");
   const [prompt, setPrompt] = useState(session.promptFor());
   const [busy, setBusy] = useState(false);
+  // Command history (up/down arrow recall, readline-style). `history` is oldest→newest;
+  // `histCursor` is -1 for the live input, else the offset back from the newest entry.
+  const [history, setHistory] = useState([]);
+  const [histCursor, setHistCursor] = useState(-1);
 
   const submit = async (line) => {
     if (line === "/exit") { exit(); return; }
@@ -111,14 +115,34 @@ export function App({ session }) {
     if (busy) return; // one turn at a time — the engine is deterministic and fast
     const line = String(raw).trim();
     setInput("");
-    if (line) void submit(line);
+    setHistCursor(-1); // any submit resets history navigation to the live input
+    if (line) {
+      // record for up-arrow recall; collapse an immediate duplicate of the last line
+      setHistory((h) => (h[h.length - 1] === line ? h : [...h, line]));
+      void submit(line);
+    }
   };
 
   useInput((ch, key) => {
     if (key.return) { trySubmit(input); return; }
     if (key.backspace || key.delete) { setInput((s) => s.slice(0, -1)); return; }
     if (key.ctrl && ch === "u") { setInput(""); return; }
-    if (key.ctrl || key.meta || key.escape || key.tab || key.upArrow || key.downArrow || key.leftArrow || key.rightArrow) return;
+    // Up/down arrow: recall previous prompts (readline-style), oldest→newest history.
+    if (key.upArrow) {
+      if (!history.length) return;
+      const nc = Math.min(histCursor + 1, history.length - 1);
+      setHistCursor(nc);
+      setInput(history[history.length - 1 - nc]);
+      return;
+    }
+    if (key.downArrow) {
+      if (histCursor <= 0) { setHistCursor(-1); setInput(""); return; } // back to a fresh line
+      const nc = histCursor - 1;
+      setHistCursor(nc);
+      setInput(history[history.length - 1 - nc]);
+      return;
+    }
+    if (key.ctrl || key.meta || key.escape || key.tab || key.leftArrow || key.rightArrow) return;
     if (!ch) return;
     // A PASTED chunk arrives as one multi-char event; a newline inside it means
     // "submit this line" (one line per turn — the readline shell's per-line read).