mlx-bun 0.0.8 → 0.0.9

package/src/memory/tools.ts

@@ -3,39 +3,70 @@
 // These are pi custom tools (defineTool), registered alongside the coding +
 // web tools in both front doors (pi-terminal.ts, pi-web.ts). They're read-only,
 // so they auto-allow (not in GATED_TOOLS) — consulting your own memory never
-// needs an approval gate. They read ~/.mlx-bun/wiki via src/memory/vault.ts.
+// needs an approval gate. They read ~/.mlx-bun/wiki via src/memory/vault.ts +
+// the deterministic navigation index in src/memory/query.ts.
 //
-// Mirrors lucien's read surface: search (discovery) → focused read (toc /
-// section / links) → full read / list / status. Knowing *when* to consult is
-// driven by these tool descriptions and the bundled memory skill (pi surfaces
-// its description and loads the body on demand); the system prompt carries only
-// a one-line presence hint (memoryIndexHint), not a title dump.
+// The read surface is a deliberate FIND → READ path, never a vector search and
+// never an infobox-field filter (the infobox is CONTENT the model reads, not a
+// query target — there is NO memory_infobox_query):
+//
+//   memory_resolve  (name/alias → the article)        ─┐ FIND the article
+//   memory_category (category/type/series → members)  ─┘ deterministically
+//   memory_read     (TOC + lead by default)            ─┐ READ it small:
+//   memory_section  (one section's body — THE DEFAULT) ─┘ TOC → one section
+//   memory_links / memory_infobox (follow the graph / read the infobox)
+//   memory_search   (LAST resort: substring fallback when FIND failed)
+//
+// Silent-colleague contract (ported from lucien's LUCIEN_INSTRUCTIONS): look the
+// article up BEFORE answering; each article is the consolidated current position,
+// so read it rather than reconstructing from raw history; then speak as a
+// continuation, never "per the wiki…". Knowing *when* to consult is driven by
+// these tool descriptions + the bundled memory skill (pi surfaces its description
+// and loads the body on demand); the system prompt carries only a one-line
+// presence hint (memoryIndexHint), not a title dump.
 
 import { defineTool, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import {
+  infoboxFieldValues,
+  parseInfobox,
+  parseSeriesBanner,
+  type Infobox,
+} from "./article";
+import {
+  articlesInCategory,
+  buildMemoryIndex,
+  resolveName,
+  type MemoryIndex,
+} from "./query";
 import { scheduleStatus } from "./schedule";
 import {
   extractSection,
-  getArticleLinks,
+  extractWikilinkTargets,
   listArticles,
   listReferenceDocs,
   parseToc,
   readArticle,
+  resolveWikilinkToStem,
   searchArticles,
   vaultRoot,
   vaultStatus,
   type SearchHit,
 } from "./vault";
 
-/** Tool names, exported so the front doors can add them to the allowlist. */
+/** Tool names, exported so the front doors can add them to the allowlist. The
+ *  order is the recommended call order: FIND (resolve/category) → READ (read/
+ *  section) → follow (links/infobox) → reference utilities → search LAST. */
 export const MEMORY_TOOL_NAMES = [
-  "memory_search",
+  "memory_resolve",
+  "memory_category",
   "memory_read",
-  "memory_toc",
   "memory_section",
   "memory_links",
+  "memory_infobox",
   "memory_list",
   "memory_status",
+  "memory_search",
 ] as const;
 
 export const REFERENCE_TOOL_NAMES = [
@@ -45,6 +76,15 @@ export const REFERENCE_TOOL_NAMES = [
 ] as const;
 
 const MAX_SEARCH_HITS = 30;
+/** memory_search is the demoted fallback: only the strongest few summaries. */
+const MAX_MEMORY_SUMMARIES = 8;
+/** A whole-article read above this many bytes degrades to TOC+lead+steer. */
+const MAX_FULL_READ_BYTES = 8 * 1024;
+/** memory_category page size (rows) and per-row lead budget. */
+const MAX_CATEGORY_ROWS = 40;
+const CATEGORY_LEAD_CHARS = 140;
+/** memory_links: cap per origin group before "+N more". */
+const MAX_LINKS_PER_GROUP = 25;
 
 function textResult(text: string): { content: [{ type: "text"; text: string }]; details: Record<string, never> } {
   return { content: [{ type: "text", text }], details: {} };
@@ -68,17 +108,34 @@ async function memoryUnavailableMessage(): Promise<string | null> {
   return `Memory is not set up yet at ${st.root}. Run \`mlx-bun memory init\` to create the local Markdown wiki, or ask the user before setting it up.`;
 }
 
+/** Title form of a stem (underscores → spaces). */
+function titleOf(stem: string): string {
+  return stem.replace(/_/g, " ");
+}
+
+/** Casefold + collapse whitespace/underscores (mirrors query.ts/reindex.ts). */
+function normalizeAlias(s: string): string {
+  return s.trim().toLowerCase().replace(/_/g, " ").replace(/\s+/g, " ").trim();
+}
+
+/** Truncate to a budget, marking the cut so callers never silently lose text. */
+function clip(text: string, max: number): string {
+  const t = text.trim();
+  return t.length <= max ? t : `${t.slice(0, max - 1).trimEnd()}…`;
+}
+
 /** Compact, model-friendly rendering of search hits grouped by relevance. */
 function formatSearch(
   query: string,
   summaries: { article: string; occurrences: number; matched_terms?: string[] }[],
   hits: SearchHit[],
-  opts: { corpusLabel?: string; readTool?: string } = {},
+  opts: { corpusLabel?: string; readTool?: string; maxSummaries?: number } = {},
 ): string {
   const corpus = opts.corpusLabel ?? "personal-memory articles";
   const readTool = opts.readTool ?? "memory_read";
+  const maxSummaries = opts.maxSummaries ?? 12;
   if (summaries.length === 0) return `No ${corpus} match "${query}".`;
-  const top = summaries.slice(0, 12);
+  const top = summaries.slice(0, maxSummaries);
   const lines = [`${corpus[0]!.toUpperCase()}${corpus.slice(1)} matching "${query}" (most relevant first):`, ""];
   for (const s of top) {
     const terms = s.matched_terms && s.matched_terms.length ? ` [${s.matched_terms.join(", ")}]` : "";
@@ -92,85 +149,182 @@ function formatSearch(
       lines.push(`- ${where}:${h.line}  ${h.excerpt}`);
     }
   }
-  lines.push("", `Read a full result with ${readTool} (e.g. ${readTool} article="${top[0]!.article}").`);
+  lines.push("", `Read a result with ${readTool} (e.g. ${readTool} stem="${top[0]!.article}").`);
   return lines.join("\n");
 }
 
-const memorySearchTool = defineTool({
-  name: "memory_search",
-  label: "Search Memory",
+// ---- index access -----------------------------------------------------
+
+/** Build the (mtime-cached) navigation index over the live vault. */
+function index(): MemoryIndex {
+  return buildMemoryIndex(vaultRoot());
+}
+
+function kindOf(idx: MemoryIndex, stem: string): string {
+  return idx.infoboxByStem.get(stem)?.entityKind ?? "thing";
+}
+
+function leadOf(idx: MemoryIndex, stem: string): string | null {
+  return idx.leadByStem.get(stem) ?? null;
+}
+
+// ---- FIND: resolve by name/alias --------------------------------------
+
+const memoryResolveTool = defineTool({
+  name: "memory_resolve",
+  label: "Resolve Memory Article",
   description:
-    "Search the user's local personal-memory articles for user-specific continuity: prior conversations, named personal projects, people, preferences, decisions, or history. " +
-    "Use when the answer depends on missing personal context; do not use for weather, current public facts, generic web research, or ordinary coding/file tasks when current files are sufficient. " +
-    "Returns ranked article matches and sample lines; follow up with memory_read to read a relevant article in full.",
+    "FIND the user's article for a name or alias — the first move when the user names a specific thing, person, project, or topic. " +
+    "Deterministic alias lookup (no model, no substring search): returns the matched article's stem, title, kind, and lead so you can then read it. " +
+    "On a miss it offers up to 3 near candidates. Look the article up before answering rather than guessing from raw history.",
   parameters: Type.Object({
-    query: Type.String({ description: "Word or phrase to search for across the user's memory articles." }),
-    limit: Type.Optional(Type.Number({ description: `Max sample line-hits to return (default ${MAX_SEARCH_HITS}).` })),
+    surface: Type.String({ description: "The name or alias as the user said it (a short form or the way they referred to the thing)." }),
   }),
   execute: async (_id, params) => {
-    const query = params.query.trim();
-    if (!query) return textResult("memory_search needs a non-empty query.");
-    const limit = Math.max(1, Math.min(MAX_SEARCH_HITS, Math.round(params.limit ?? MAX_SEARCH_HITS)));
+    const surface = params.surface.trim();
+    if (!surface) return textResult("memory_resolve needs a name or alias.");
     try {
       const unavailable = await memoryUnavailableMessage();
       if (unavailable) return textResult(unavailable);
-      const { summaries, hits } = await searchArticles(vaultRoot(), query, { limit, scope: "articles" });
-      return textResult(formatSearch(query, summaries, hits));
+      const idx = index();
+      const stem = resolveName(idx, surface);
+      if (stem) {
+        const lead = leadOf(idx, stem);
+        return textResult(
+          [
+            `${titleOf(stem)}  (stem: ${stem}, kind: ${kindOf(idx, stem)})`,
+            lead ? `\n${clip(lead, 360)}` : "",
+            `\n\nRead it with memory_read stem="${stem}" (TOC + lead), then memory_section for the part you need.`,
+          ].join(""),
+        );
+      }
+      // Miss: deterministic token-overlap candidates (no substring, no model).
+      const qTokens = new Set(normalizeAlias(surface).split(" ").filter(Boolean));
+      const scored = new Map<string, number>();
+      for (const [alias, st] of idx.aliasToStem) {
+        let shared = 0;
+        for (const tok of alias.split(" ")) if (qTokens.has(tok)) shared++;
+        if (shared > 0) scored.set(st, Math.max(scored.get(st) ?? 0, shared));
+      }
+      const candidates = [...scored.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, 3)
+        .map(([st]) => st);
+      if (candidates.length === 0) {
+        return textResult(`No article resolves "${surface}". Try memory_category to find articles about a topic, or memory_search as a last resort.`);
+      }
+      return textResult(
+        `No exact match for "${surface}". Did you mean one of:\n` +
+          candidates.map((st) => `- ${titleOf(st)} (stem: ${st})`).join("\n") +
+          `\n\nResolve one with memory_read, or use memory_category for a topic.`,
+      );
     } catch (err) {
-      return textResult(`memory_search failed: ${err instanceof Error ? err.message : String(err)}`);
+      return textResult(`memory_resolve failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   },
 });
 
-const memoryReadTool = defineTool({
-  name: "memory_read",
-  label: "Read Memory",
+// ---- FIND: articles about a category / type / series ------------------
+
+const memoryCategoryTool = defineTool({
+  name: "memory_category",
+  label: "Articles in Category",
   description:
-    "Read one full Markdown article from the user's personal memory. " +
-    "Use after memory_search when user-specific prior context is needed. " +
-    "Pass the article stem exactly as returned by memory_search or memory_list (underscored, e.g. \"Archie_Project\").",
+    "FIND the articles ABOUT a topic by membership — the \"articles about X\" finder. " +
+    "Pass exactly one of category, type, or series; returns the member articles as \"stem · lead\" rows. " +
+    "This is deterministic set membership (declared [[Category:…]] / infobox type / series banner), NOT a search and NOT an infobox-field filter. " +
+    "Use it to land on the right article, then memory_read its TOC and memory_section the one part you need.",
   parameters: Type.Object({
-    article: Type.String({ description: "Article stem to read (underscored filename, no .md, e.g. \"Archie_Project\")." }),
+    category: Type.Optional(Type.String({ description: "Category name — the grouping declared as [[Category:<Name>]] near the top of member articles." })),
+    type: Type.Optional(Type.String({ description: "Infobox type label (the article's `type:` field value)." })),
+    series: Type.Optional(Type.String({ description: "Series name from a *Part of a series on [[X]]* banner." })),
   }),
   execute: async (_id, params) => {
-    const article = params.article.trim();
-    if (!article) return textResult("memory_read needs an article name.");
+    const category = params.category?.trim();
+    const type = params.type?.trim();
+    const series = params.series?.trim();
+    const picked = [category, type, series].filter((v) => v && v.length > 0);
+    if (picked.length !== 1) {
+      return textResult("memory_category needs exactly one of: category, type, or series.");
+    }
     try {
       const unavailable = await memoryUnavailableMessage();
       if (unavailable) return textResult(unavailable);
-      if (isReferenceId(article)) return textResult("memory_read is for personal-memory articles. Use reference_read for Reference/ documents.");
-      const { content } = await readArticle(vaultRoot(), article);
-      return textResult(content);
+      const idx = index();
+      let stems: string[];
+      let label: string;
+      if (category) {
+        stems = articlesInCategory(idx, category);
+        label = `Category:${category}`;
+      } else if (type) {
+        stems = [...(idx.typeToStems.get(type) ?? [])];
+        label = `type:${type}`;
+      } else {
+        stems = [...(idx.seriesToStems.get(series!) ?? [])];
+        label = `series:${series}`;
+      }
+      if (stems.length === 0) return textResult(`No articles in ${label}.`);
+      const page = stems.slice(0, MAX_CATEGORY_ROWS);
+      const lines = [`Articles in ${label} (${stems.length}):`, ""];
+      for (const stem of page) {
+        const lead = leadOf(idx, stem);
+        lines.push(lead ? `- ${stem} · ${clip(lead, CATEGORY_LEAD_CHARS)}` : `- ${stem}`);
+      }
+      if (stems.length > page.length) lines.push(`  …and ${stems.length - page.length} more.`);
+      lines.push("", "Open one with memory_read, then memory_section for the relevant part.");
+      return textResult(lines.join("\n"));
     } catch (err) {
-      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_search to find the right article name.`);
+      return textResult(`memory_category failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   },
 });
 
-const memoryTocTool = defineTool({
-  name: "memory_toc",
-  label: "Memory TOC",
+// ---- READ: TOC + lead by default; full only on force -------------------
+
+function tocAndLead(content: string, stem: string, idx: MemoryIndex, note?: string): string {
+  const lead = leadOf(idx, stem);
+  const toc = parseToc(content);
+  const lines = [`${titleOf(stem)}  (stem: ${stem})`];
+  if (lead) lines.push("", clip(lead, 480));
+  if (note) lines.push("", note);
+  lines.push("", "Sections:");
+  if (toc.length === 0) lines.push("- (no headings)");
+  else for (const h of toc) lines.push(`${"  ".repeat(Math.max(0, h.depth - 1))}- ${h.title}  (#${h.anchor})`);
+  lines.push("", `Read the one relevant section with memory_section stem="${stem}" anchor="…". Whole article: memory_read stem="${stem}" force=true.`);
+  return lines.join("\n");
+}
+
+const memoryReadTool = defineTool({
+  name: "memory_read",
+  label: "Read Memory Article",
   description:
-    "List the Markdown headings in one memory article, with anchors. Use before memory_section when the article is long or you need a specific part.",
+    "Open one article. BY DEFAULT returns its TOC + lead so you can pick the one section you need — small focused reads are the norm, never a whole-article dump. " +
+    "Pass force=true for the full prose+infobox, but only when you genuinely need the whole article (large articles still degrade to TOC+lead). " +
+    "The article is the user's consolidated current position on its topic; read it before answering rather than reconstructing from history. " +
+    "Pass the article stem (underscored, e.g. an \"<Article_Stem>\" filename without .md).",
   parameters: Type.Object({
-    article: Type.String({ description: "Article stem (underscored filename, no .md, e.g. \"Archie_Project\")." }),
+    stem: Type.String({ description: "Article stem (underscored filename, no .md — e.g. \"<Article_Stem>\")." }),
+    force: Type.Optional(Type.Boolean({ description: "Return the FULL article instead of TOC+lead. Use sparingly." })),
   }),
   execute: async (_id, params) => {
-    const article = params.article.trim();
-    if (!article) return textResult("memory_toc needs an article name.");
+    const stem = params.stem.trim();
+    if (!stem) return textResult("memory_read needs an article stem.");
     try {
       const unavailable = await memoryUnavailableMessage();
       if (unavailable) return textResult(unavailable);
-      if (isReferenceId(article)) return textResult("memory_toc is for personal-memory articles. Use reference_read for Reference/ documents.");
-      const { content } = await readArticle(vaultRoot(), article);
-      const toc = parseToc(content);
-      if (toc.length === 0) return textResult(`${article} has no Markdown headings.`);
-      return textResult(
-        `Headings in ${article}:\n\n` +
-          toc.map((h) => `${"  ".repeat(Math.max(0, h.depth - 1))}- ${h.title}  (#${h.anchor})`).join("\n"),
-      );
+      if (isReferenceId(stem)) return textResult("memory_read is for personal-memory articles. Use reference_read for Reference/ documents.");
+      const { content } = await readArticle(vaultRoot(), stem);
+      const idx = index();
+      if (!params.force) return textResult(tocAndLead(content, stem, idx));
+      const bytes = Buffer.byteLength(content, "utf8");
+      if (bytes > MAX_FULL_READ_BYTES) {
+        return textResult(
+          tocAndLead(content, stem, idx, `(This article is large — ${(bytes / 1024).toFixed(1)} KB. Read just the section you need.)`),
+        );
+      }
+      return textResult(content);
     } catch (err) {
-      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_search to find the right article name.`);
+      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_resolve or memory_category to find the right article.`);
     }
   },
 });
@@ -179,62 +333,205 @@ const memorySectionTool = defineTool({
   name: "memory_section",
   label: "Read Memory Section",
   description:
-    "Read one section from a memory article by heading anchor. Use memory_toc or memory_search first to find anchors; this is cheaper than reading a long article in full.",
+    "Read ONE section of an article by its heading anchor. This is the DEFAULT read: find the article, scan its TOC with memory_read, then read just the relevant section here — much cheaper than the whole article. " +
+    "Get anchors from memory_read's TOC.",
   parameters: Type.Object({
-    article: Type.String({ description: "Article stem (underscored filename, no .md, e.g. \"Archie_Project\")." }),
-    anchor: Type.String({ description: "Heading anchor, e.g. \"origin\" or \"current-design\"." }),
+    stem: Type.String({ description: "Article stem (underscored, e.g. \"<Article_Stem>\")." }),
+    anchor: Type.String({ description: "Heading anchor (the slug of a section heading from memory_read's TOC, e.g. \"<section-anchor>\")." }),
   }),
   execute: async (_id, params) => {
-    const article = params.article.trim();
+    const stem = params.stem.trim();
     const anchor = params.anchor.trim().replace(/^#/, "");
-    if (!article) return textResult("memory_section needs an article name.");
+    if (!stem) return textResult("memory_section needs an article stem.");
     if (!anchor) return textResult("memory_section needs a heading anchor.");
     try {
       const unavailable = await memoryUnavailableMessage();
       if (unavailable) return textResult(unavailable);
-      if (isReferenceId(article)) return textResult("memory_section is for personal-memory articles. Use reference_read for Reference/ documents.");
-      const { content } = await readArticle(vaultRoot(), article);
+      if (isReferenceId(stem)) return textResult("memory_section is for personal-memory articles. Use reference_read for Reference/ documents.");
+      const { content } = await readArticle(vaultRoot(), stem);
       const section = extractSection(content, anchor);
-      if (!section) return textResult(`No section #${anchor} found in ${article}. Try memory_toc article=\"${article}\".`);
+      if (!section) return textResult(`No section #${anchor} in ${stem}. Use memory_read stem="${stem}" to see the TOC.`);
       return textResult(section);
     } catch (err) {
-      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_search to find the right article name.`);
+      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_resolve or memory_category to find the right article.`);
     }
   },
 });
 
+// ---- FOLLOW: links grouped by origin ----------------------------------
+
+const WIKILINK_RE = /\[\[([^\]]+)\]\]/g;
+
+/** Resolved outbound links grouped by where they appear in the article. Mirrors
+ *  the reindex `via` taxonomy (infobox/series/seealso/prose); red links (no
+ *  existing article) are dropped, matching getArticleLinks. */
+function groupedOutbound(content: string, stem: string, stemSet: Set<string>, box: Infobox | null): {
+  infobox: string[];
+  series: string[];
+  seealso: string[];
+  prose: string[];
+} {
+  const dedupe = (arr: string[]): string[] => [...new Set(arr)].sort((a, b) => a.localeCompare(b));
+  const resolve = (raw: string): string | null => {
+    const base = raw.split("|")[0]!.split("#")[0]!.trim();
+    const r = resolveWikilinkToStem(base, stemSet);
+    return r && r !== stem ? r : null;
+  };
+
+  const infobox: string[] = [];
+  if (box) {
+    for (const field of box.fields) {
+      for (const value of infoboxFieldValues(field)) {
+        WIKILINK_RE.lastIndex = 0;
+        const m = WIKILINK_RE.exec(value);
+        if (m) {
+          const r = resolve(m[1]!);
+          if (r) infobox.push(r);
+        }
+      }
+    }
+  }
+
+  const series: string[] = [];
+  const banner = parseSeriesBanner(content);
+  if (banner) {
+    const r = resolve(banner);
+    if (r) series.push(r);
+  }
+
+  const seealso: string[] = [];
+  const prose: string[] = [];
+  const lines = content.split(/\r?\n/);
+  let inFence = false;
+  let section: string | null = null;
+  for (const line of lines) {
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) continue;
+    const hm = /^(#{1,6})\s+(.+)$/.exec(line);
+    if (hm) {
+      if (hm[1]!.length >= 2) section = hm[2]!.trim().toLowerCase();
+      continue;
+    }
+    const t = line.trim();
+    if (/^\*part of a series on \[\[/i.test(t)) continue;
+    if (/^categories:/i.test(t)) continue;
+    if (/^\*?\s*main article:/i.test(t)) continue;
+    WIKILINK_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = WIKILINK_RE.exec(line)) !== null) {
+      const base = m[1]!.split("|")[0]!.split("#")[0]!.trim();
+      if (!base || /^conv:/i.test(base) || /^Category:/i.test(base)) continue;
+      const r = resolve(base);
+      if (!r) continue;
+      if (section === "see also") seealso.push(r);
+      else prose.push(r);
+    }
+  }
+
+  return { infobox: dedupe(infobox), series: dedupe(series), seealso: dedupe(seealso), prose: dedupe(prose) };
+}
+
 const memoryLinksTool = defineTool({
   name: "memory_links",
   label: "Memory Links",
   description:
-    "Show resolved outgoing and incoming wikilinks for one memory article. Use when nearby concepts/backlinks might matter to the answer.",
+    "Follow the wiki graph: the article's outgoing [[links]] grouped by where they come from (infobox / series / see also / prose), plus inbound backlinks. " +
+    "Use to hop to a neighbouring article (e.g. from one entity's infobox [[wikilink]] to the linked entity's article) when a topic genuinely spans articles.",
   parameters: Type.Object({
-    article: Type.String({ description: "Article stem (underscored filename, no .md, e.g. \"Archie_Project\")." }),
+    stem: Type.String({ description: "Article stem (underscored, e.g. \"<Article_Stem>\")." }),
   }),
   execute: async (_id, params) => {
-    const article = params.article.trim();
-    if (!article) return textResult("memory_links needs an article name.");
+    const stem = params.stem.trim();
+    if (!stem) return textResult("memory_links needs an article stem.");
     try {
       const unavailable = await memoryUnavailableMessage();
       if (unavailable) return textResult(unavailable);
-      if (isReferenceId(article)) return textResult("memory_links is for personal-memory articles; Reference/ documents do not participate in the personal-memory link graph.");
-      const { outbound, inbound } = await getArticleLinks(vaultRoot(), article);
-      const lines = [`Links for ${article}:`, "", "Outbound:"];
-      lines.push(outbound.length ? outbound.map((s) => `- ${s}`).join("\n") : "- (none)");
-      lines.push("", "Inbound:");
-      lines.push(inbound.length ? inbound.map((s) => `- ${s}`).join("\n") : "- (none)");
-      return textResult(lines.join("\n"));
+      if (isReferenceId(stem)) return textResult("memory_links is for personal-memory articles; Reference/ documents are not in the link graph.");
+      const { content } = await readArticle(vaultRoot(), stem);
+      const stems = await listArticles(vaultRoot());
+      const stemSet = new Set(stems);
+      if (!stemSet.has(stem)) return textResult(`Article not found: ${stem}.`);
+      const box = parseInfobox(content);
+      const groups = groupedOutbound(content, stem, stemSet, box);
+
+      // Inbound: who points here (any origin).
+      const inbound: string[] = [];
+      for (const other of stems) {
+        if (other === stem) continue;
+        try {
+          const oc = (await readArticle(vaultRoot(), other)).content;
+          const og = groupedOutbound(oc, other, stemSet, parseInfobox(oc));
+          if ([...og.infobox, ...og.series, ...og.seealso, ...og.prose].includes(stem)) inbound.push(other);
+        } catch {
+          // best-effort
+        }
+      }
+
+      const renderGroup = (title: string, arr: string[]): string => {
+        if (arr.length === 0) return `${title}: (none)`;
+        const shown = arr.slice(0, MAX_LINKS_PER_GROUP);
+        const extra = arr.length > shown.length ? ` +${arr.length - shown.length} more` : "";
+        return `${title}: ${shown.join(", ")}${extra}`;
+      };
+      return textResult(
+        [
+          `Links for ${stem}:`,
+          "",
+          renderGroup("infobox", groups.infobox),
+          renderGroup("series", groups.series),
+          renderGroup("see also", groups.seealso),
+          renderGroup("prose", groups.prose),
+          renderGroup("inbound", inbound.sort((a, b) => a.localeCompare(b))),
+        ].join("\n"),
+      );
+    } catch (err) {
+      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_resolve or memory_category to find the right article.`);
+    }
+  },
+});
+
+// ---- READ the infobox as content (NOT a query target) -----------------
+
+const memoryInfoboxTool = defineTool({
+  name: "memory_infobox",
+  label: "Read Memory Infobox",
+  description:
+    "Read an article's infobox as key:value CONTENT — the structured facts (the `type:`, `kind:`, relationship, and world-fact fields). " +
+    "This surfaces facts to READ, not a filter: there is no way to query/sort articles by an infobox field; to find articles use memory_category or memory_resolve.",
+  parameters: Type.Object({
+    stem: Type.String({ description: "Article stem (underscored, e.g. \"<Article_Stem>\")." }),
+  }),
+  execute: async (_id, params) => {
+    const stem = params.stem.trim();
+    if (!stem) return textResult("memory_infobox needs an article stem.");
+    try {
+      const unavailable = await memoryUnavailableMessage();
+      if (unavailable) return textResult(unavailable);
+      if (isReferenceId(stem)) return textResult("memory_infobox is for personal-memory articles.");
+      const idx = index();
+      if (!idx.infoboxByStem.has(stem)) return textResult(`Article not found: ${stem}.`);
+      const box = idx.infoboxByStem.get(stem) ?? null;
+      if (!box || box.fields.length === 0) return textResult(`${stem} has no infobox.`);
+      return textResult(
+        `Infobox for ${stem} (facts to read, not a filter):\n\n` +
+          box.fields.map((f) => `${f.key}: ${f.value}`).join("\n"),
+      );
     } catch (err) {
-      return textResult(`${err instanceof Error ? err.message : String(err)} — try memory_search to find the right article name.`);
+      return textResult(`memory_infobox failed: ${err instanceof Error ? err.message : String(err)}`);
     }
   },
 });
 
+// ---- overview + status ------------------------------------------------
+
 const memoryListTool = defineTool({
   name: "memory_list",
   label: "List Memory",
   description:
-    "List the titles of the user's personal-memory articles. Use as an overview, or as a fallback when memory_search doesn't surface what you expected.",
+    "List the stems of the user's personal-memory articles. An overview/fallback when memory_resolve and memory_category don't surface what you expected — not a first move.",
   parameters: Type.Object({}),
   execute: async () => {
     try {
@@ -243,8 +540,7 @@ const memoryListTool = defineTool({
       const articles = await listArticles(vaultRoot());
       if (articles.length === 0) return textResult("The user's memory has no personal articles yet.");
       return textResult(
-        `${articles.length} personal-memory article(s):\n\n` +
-          articles.map((s) => `- ${s}`).join("\n"),
+        `${articles.length} personal-memory article(s):\n\n` + articles.map((s) => `- ${s}`).join("\n"),
       );
     } catch (err) {
       return textResult(`memory_list failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -252,16 +548,37 @@ const memoryListTool = defineTool({
   },
 });
 
+/** Last synthesis-pipeline write to the vault, from its git log (every
+ *  pipeline write commits with a "memory: …" message — synthesize.ts,
+ *  reconcile.ts, wikify.ts, stages.ts). null when the vault has no git repo
+ *  or no synthesis commit yet. */
+async function lastSynthesisCommit(root: string): Promise<{ date: string; subject: string } | null> {
+  try {
+    const proc = Bun.spawn(
+      ["git", "log", "-1", "--grep=^memory: ", "--format=%cI\t%s"],
+      { cwd: root, stdout: "pipe", stderr: "ignore" },
+    );
+    const out = (await new Response(proc.stdout).text()).trim();
+    if ((await proc.exited) !== 0 || !out) return null;
+    const tab = out.indexOf("\t");
+    if (tab === -1) return null;
+    return { date: out.slice(0, tab), subject: out.slice(tab + 1) };
+  } catch {
+    return null;
+  }
+}
+
 const memoryStatusTool = defineTool({
   name: "memory_status",
   label: "Memory Status",
   description:
-    "Show read-only status for the user's memory: vault path, setup state, article count, git state, and nightly schedule state. Use when the user asks whether memory is on or where it lives.",
+    "Show read-only status for the user's memory: vault path, setup state, article count, git state, last synthesis run, and nightly schedule state. Use when the user asks whether memory is on or where it lives.",
   parameters: Type.Object({}),
   execute: async () => {
     try {
       const st = await vaultStatus();
       const sched = await scheduleStatus();
+      const last = st.isGitRepo ? await lastSynthesisCommit(st.root) : null;
       const recent = st.recentArticles.length
         ? st.recentArticles.slice(0, 5).map((r) => `  - ${r.article} (${new Date(r.mtimeMs).toISOString()})`).join("\n")
         : "  - (none)";
@@ -272,8 +589,8 @@ const memoryStatusTool = defineTool({
         `- articles: ${st.articleCount}`,
         `- read-only references: ${st.referenceCount}`,
         `- git: ${st.isGitRepo ? "tracked" : "not tracked"}`,
-        `- last synthesis: not available yet (M1 synthesis is stubbed)`,
-        `- synthesis: M1 stub (manual/nightly writes are not implemented yet)`,
+        `- last synthesis: ${last ? `${last.date} (${last.subject})` : "no synthesis run recorded yet"}`,
+        "- synthesis: available — `mlx-bun memory synthesize` runs the full local pipeline (conversations → articles); the nightly job runs it automatically when scheduled",
         `- nightly: ${sched.installed ? (sched.loaded ? "scheduled" : "installed but not loaded") : "not scheduled"}`,
         sched.installed ? `- launchd plist: ${sched.plistPath}` : "- setup command: mlx-bun memory init",
         "- recent changed articles:",
@@ -285,6 +602,33 @@ const memoryStatusTool = defineTool({
   },
 });
 
+// ---- search: the demoted last-resort fallback -------------------------
+
+const memorySearchTool = defineTool({
+  name: "memory_search",
+  label: "Search Memory (fallback)",
+  description:
+    "LAST-RESORT substring search across memory articles — use ONLY when name/category lookup (memory_resolve, memory_category) has failed across a couple of phrasings. " +
+    "It does not understand meaning; prefer the deterministic finders first. Returns the top few article matches; follow up with memory_read.",
+  parameters: Type.Object({
+    query: Type.String({ description: "Word or phrase to substring-match across memory articles." }),
+    limit: Type.Optional(Type.Number({ description: `Max sample line-hits to return (default ${MAX_SEARCH_HITS}).` })),
+  }),
+  execute: async (_id, params) => {
+    const query = params.query.trim();
+    if (!query) return textResult("memory_search needs a non-empty query.");
+    const limit = Math.max(1, Math.min(MAX_SEARCH_HITS, Math.round(params.limit ?? MAX_SEARCH_HITS)));
+    try {
+      const unavailable = await memoryUnavailableMessage();
+      if (unavailable) return textResult(unavailable);
+      const { summaries, hits } = await searchArticles(vaultRoot(), query, { limit, scope: "articles" });
+      return textResult(formatSearch(query, summaries, hits, { maxSummaries: MAX_MEMORY_SUMMARIES }));
+    } catch (err) {
+      return textResult(`memory_search failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  },
+});
+
 // ---- reference docs (separate from personal memory) -------------------
 
 const referenceSearchTool = defineTool({
@@ -356,13 +700,15 @@ const referenceListTool = defineTool({
 
 export function createMemoryTools(): ToolDefinition[] {
   return [
-    memorySearchTool,
+    memoryResolveTool,
+    memoryCategoryTool,
     memoryReadTool,
-    memoryTocTool,
     memorySectionTool,
     memoryLinksTool,
+    memoryInfoboxTool,
     memoryListTool,
     memoryStatusTool,
+    memorySearchTool,
   ];
 }
 
@@ -372,14 +718,14 @@ export function createReferenceTools(): ToolDefinition[] {
 
 /**
  * One gated line for the system prompt: states that memory is ON for this user
- * and points at the `memory` skill. NOT a title dump and NOT a how-to. pi
- * already auto-injects every skill's name+description+location
- * (formatSkillsForPrompt) and loads the SKILL.md body on demand, so the skill
- * owns the detailed workflow. This hint is intentionally soft: memory is a
- * scoped retrieval capability for user-specific continuity, not a default first
- * step for every prompt. Returns "" when memory is not turned on (vault absent)
- * so we never advertise memory the user hasn't enabled. Runs once at session
- * construction.
+ * and points at the `memory` skill, plus the FIND→READ order and the
+ * silent-colleague contract. NOT a title dump and NOT a how-to. pi already
+ * auto-injects every skill's name+description+location (formatSkillsForPrompt)
+ * and loads the SKILL.md body on demand, so the skill owns the detailed
+ * workflow. This hint is intentionally soft: memory is a scoped retrieval
+ * capability for user-specific continuity, not a default first step for every
+ * prompt. Returns "" when memory is not turned on (vault absent) so we never
+ * advertise memory the user hasn't enabled. Runs once at session construction.
  */
 export async function memoryIndexHint(): Promise<string> {
   let st: Awaited<ReturnType<typeof vaultStatus>>;
@@ -392,8 +738,12 @@ export async function memoryIndexHint(): Promise<string> {
   const articleCount = st.articleCount > 0 ? `${st.articleCount} article${st.articleCount === 1 ? "" : "s"}` : "no user articles yet";
   const refCount = st.referenceCount > 0 ? ` plus ${st.referenceCount} read-only mlx-bun reference doc${st.referenceCount === 1 ? "" : "s"}` : "";
   return (
-    `\n\nThe user's personal memory is on (${articleCount}${refCount}). Use it only when the answer depends on ` +
-    `user-specific continuity or missing personal context; do not use it for weather, current public facts, ` +
-    `generic web research, or ordinary coding/file tasks when the current files are enough. See the \`memory\` skill for the memory_* workflow.`
+    `\n\nThe user's personal memory is on (${articleCount}${refCount}). When the answer depends on user-specific ` +
+    `continuity or missing personal context, look it up BEFORE answering: FIND the article (memory_resolve a name, ` +
+    `or memory_category for a topic), open its TOC with memory_read, then memory_section the one relevant part — ` +
+    `each article is the user's consolidated current position, so read it rather than reconstructing from history. ` +
+    `Whole-article reads and memory_search are last resorts. Use what you find silently, as a continuation — never ` +
+    `"per the wiki…". Do not use memory for weather, current public facts, generic web research, or ordinary ` +
+    `coding/file tasks when the current files are enough. See the \`memory\` skill for the workflow.`
   );
 }