negotium 0.2.17 → 0.2.19

package/dist/runtime/src/mcp/wiki-server.ts

@@ -4,6 +4,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import {
   closeSync,
+  type Dirent,
   existsSync,
   mkdirSync,
   openSync,
@@ -14,7 +15,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { basename, dirname, join, resolve } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { argv, exit } from "node:process";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -25,6 +26,13 @@ import {
   type ListToolsResult,
   type Tool,
 } from "@modelcontextprotocol/sdk/types.js";
+import {
+  type IndexedWikiKind,
+  type PreparedWikiSearchDocument,
+  resetCorruptWikiSearchIndex,
+  WikiSearchIndex,
+  type WikiSearchIndexSource,
+} from "#mcp/wiki-search-index";
 import { SHARED_WIKI_DIR } from "#platform/config";
 import {
   wikiBriefStorageKey,
@@ -45,6 +53,7 @@ export interface WikiTopicBrief {
 
 export interface WikiMcpHost {
   wikiRoot: string;
+  canReadTopicMemory?(selection: string, userId: string): boolean;
   getTopicBrief?(topicId: string): WikiTopicBrief | null;
   resolveTopicBrief?(selection: string, userId: string): WikiTopicBrief | null;
   setTopicBrief?(
@@ -55,10 +64,13 @@ export interface WikiMcpHost {
       summaryDate?: string;
     },
   ): void;
+  adoptTopicMemory?(topicId: string, userId: string, memoryKey: string): boolean;
 }
 
 export interface WikiMcpContext {
   userId: string;
+  /** The room executing the tool, even when topicId points at inherited memory. */
+  currentTopicId?: string;
   topicId?: string;
   surface?: WikiSurface;
 }
@@ -91,6 +103,7 @@ export function resolveAccessibleWikiTopicBrief(
 }
 
 interface WikiRuntime extends Required<Pick<WikiMcpContext, "userId" | "surface">> {
+  currentTopicId?: string;
   topicId?: string;
   host: WikiMcpHost;
   wikiDir: string;
@@ -111,22 +124,26 @@ function runtime(): WikiRuntime {
 
 function parseArgv(): {
   userId: string;
+  currentTopicId?: string;
   topicId?: string;
   surface: WikiSurface;
 } {
   let userId = "local";
+  let currentTopicId: string | undefined;
   let topicId: string | undefined;
   let surface: WikiSurface = "all";
 
   for (let i = 2; i < argv.length; i++) {
     const a = argv[i];
     if (a.startsWith("--user-id=")) userId = a.slice("--user-id=".length);
-    else if (a.startsWith("--topic-id=")) topicId = a.slice("--topic-id=".length);
+    else if (a.startsWith("--current-topic-id=")) {
+      currentTopicId = a.slice("--current-topic-id=".length);
+    } else if (a.startsWith("--topic-id=")) topicId = a.slice("--topic-id=".length);
     else if (a === "--surface=wiki") surface = "wiki";
     else if (a === "--surface=skills") surface = "skills";
   }
 
-  return { userId, topicId, surface };
+  return { userId, currentTopicId, topicId, surface };
 }
 
 // --- Helpers ---------------------------------------------------------------
@@ -270,12 +287,521 @@ function slugify(topic: string): string {
 
 // --- Tool handlers (file-based) -------------------------------------------
 
+type WikiQueryKind = "all" | "topic" | "article" | "summary";
+
+interface WikiIndexCandidate {
+  kind: Exclude<WikiQueryKind, "all">;
+  key: string;
+  description: string;
+  date?: string;
+}
+
+type WikiSearchResultKind = Exclude<WikiQueryKind, "all"> | "skill";
+
+interface WikiSearchResult {
+  kind: WikiSearchResultKind;
+  key: string;
+  score: number;
+  keyScore: number;
+  description?: string;
+  date?: string;
+  path?: string;
+  text?: string;
+  title?: string;
+}
+
+function normalizeSearchText(value: string): string {
+  return value
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9가-힣]+/g, " ")
+    .trim()
+    .replaceAll(/\s+/g, " ");
+}
+
+function compactSearchText(value: string): string {
+  return normalizeSearchText(value).replaceAll(" ", "");
+}
+
+function trigrams(value: string): Set<string> {
+  const compact = compactSearchText(value);
+  if (compact.length < 3) return new Set(compact ? [compact] : []);
+  const result = new Set<string>();
+  for (let i = 0; i <= compact.length - 3; i += 1) result.add(compact.slice(i, i + 3));
+  return result;
+}
+
+function fuzzySearchScore(query: string, candidate: string, maximum: number): number {
+  const compactQuery = compactSearchText(query);
+  const compactCandidate = compactSearchText(candidate);
+  if (compactQuery.length < 3 || compactCandidate.length < 3) return 0;
+  const similarity = trigramSimilarity(compactQuery, compactCandidate);
+  const minimumSimilarity = compactQuery.length <= 4 ? 0.6 : 0.45;
+  return similarity >= minimumSimilarity ? similarity * maximum : 0;
+}
+
+const SEARCH_STOP_WORDS = new Set([
+  "a",
+  "an",
+  "and",
+  "are",
+  "as",
+  "at",
+  "be",
+  "by",
+  "for",
+  "from",
+  "in",
+  "is",
+  "it",
+  "of",
+  "on",
+  "or",
+  "that",
+  "the",
+  "to",
+  "with",
+]);
+
+const SEARCH_MONTHS = new Map([
+  ["january", "01"],
+  ["jan", "01"],
+  ["1월", "01"],
+  ["february", "02"],
+  ["feb", "02"],
+  ["2월", "02"],
+  ["march", "03"],
+  ["mar", "03"],
+  ["3월", "03"],
+  ["april", "04"],
+  ["apr", "04"],
+  ["4월", "04"],
+  ["may", "05"],
+  ["5월", "05"],
+  ["june", "06"],
+  ["jun", "06"],
+  ["6월", "06"],
+  ["july", "07"],
+  ["jul", "07"],
+  ["7월", "07"],
+  ["august", "08"],
+  ["aug", "08"],
+  ["8월", "08"],
+  ["september", "09"],
+  ["sep", "09"],
+  ["sept", "09"],
+  ["9월", "09"],
+  ["october", "10"],
+  ["oct", "10"],
+  ["10월", "10"],
+  ["november", "11"],
+  ["nov", "11"],
+  ["11월", "11"],
+  ["december", "12"],
+  ["dec", "12"],
+  ["12월", "12"],
+]);
+
+const SEARCH_RECENCY_TERMS = new Set([
+  "latest",
+  "newest",
+  "recent",
+  "earliest",
+  "oldest",
+  "최근",
+  "최신",
+  "최초",
+  "오래된",
+]);
+
+function meaningfulSearchTokens(value: string): string[] {
+  return normalizeSearchText(value)
+    .split(" ")
+    .filter((token) => (token.length >= 2 || /^\d+$/.test(token)) && !SEARCH_STOP_WORDS.has(token));
+}
+
+function canonicalSearchToken(token: string): string {
+  return token.length > 4 && token.endsWith("s") ? token.slice(0, -1) : token;
+}
+
+function canonicalSearchTokens(value: string): string[] {
+  return meaningfulSearchTokens(value).map(canonicalSearchToken);
+}
+
+function countToken(tokens: string[], token: string): number {
+  let count = 0;
+  for (const candidate of tokens) if (candidate === token) count += 1;
+  return count;
+}
+
+function countPhrase(text: string, phrase: string): number {
+  if (!phrase) return 0;
+  let count = 0;
+  let offset = 0;
+  let match = text.indexOf(phrase, offset);
+  while (match >= 0) {
+    count += 1;
+    offset = match + phrase.length;
+    match = text.indexOf(phrase, offset);
+  }
+  return count;
+}
+
+function summaryTopicIdentity(key: string): string {
+  return normalizeSearchText(key.replace(/^\d{4}-\d{2}-\d{2}-/, ""));
+}
+
+function scoreSummaryTime(query: string, key: string, title: string): number | null {
+  const date = key.match(/^(\d{4})-(\d{2})-(\d{2})/);
+  if (!date) return 0;
+  const tokens = meaningfulSearchTokens(query);
+  const documentDate = `${date[1]}-${date[2]}-${date[3]}`;
+  const requestedDateMatch = query.match(/\b(\d{4}) (\d{2}) (\d{2})\b/);
+  const requestedDate = requestedDateMatch
+    ? `${requestedDateMatch[1]}-${requestedDateMatch[2]}-${requestedDateMatch[3]}`
+    : undefined;
+  const beforeDate = /\bbefore\b/.test(query);
+  const afterDate = /\bafter\b/.test(query);
+  if (requestedDate && beforeDate && documentDate >= requestedDate) return null;
+  if (requestedDate && afterDate && documentDate <= requestedDate) return null;
+  const queryYear = tokens.find((token) => /^\d{4}(?:년)?$/.test(token))?.replace(/년$/, "");
+  const queryMonth = tokens.map((token) => SEARCH_MONTHS.get(token)).find(Boolean);
+  const hasRecencyTerm = tokens.some((token) => SEARCH_RECENCY_TERMS.has(token));
+  const yearMatches = !queryYear || queryYear === date[1];
+  const monthMatches = !queryMonth || queryMonth === date[2];
+  if ((!queryYear && !queryMonth && !hasRecencyTerm) || !yearMatches || !monthMatches) return 0;
+
+  const normalizedMetadata = `${normalizeSearchText(key)} ${normalizeSearchText(title)}`;
+  const contentTokens = tokens.filter(
+    (token) =>
+      !/^\d{4}(?:년)?$/.test(token) &&
+      !SEARCH_MONTHS.has(token) &&
+      !SEARCH_RECENCY_TERMS.has(token),
+  );
+  const contentMatches = contentTokens.filter((token) => normalizedMetadata.includes(token)).length;
+  const relationScore = requestedDate && (beforeDate || afterDate) ? 60 : 0;
+  const exactDateScore = requestedDate === documentDate ? 90 : 0;
+  return 30 + relationScore + exactDateScore + contentMatches * 15;
+}
+
+function trigramSimilarity(left: string, right: string): number {
+  const a = trigrams(left);
+  const b = trigrams(right);
+  if (a.size === 0 || b.size === 0) return 0;
+  let overlap = 0;
+  for (const gram of a) if (b.has(gram)) overlap += 1;
+  return (2 * overlap) / (a.size + b.size);
+}
+
+const WIKI_SEARCH_INDEX_FILENAME = ".wiki-search-index.sqlite";
+
+/**
+ * Open the derived body-search index.
+ *
+ * The index is a rebuildable cache that is written only by the wiki write path,
+ * so a missing or unreadable file is a normal cold state rather than an error:
+ * catalog retrieval still works, and `wiki_reindex` refills the bodies.
+ */
+function openWikiSearchIndex(): WikiSearchIndex | undefined {
+  const path = resolve(runtime().wikiDir, WIKI_SEARCH_INDEX_FILENAME);
+  try {
+    return new WikiSearchIndex(path);
+  } catch (error) {
+    if (!/malformed|not a database|schema/i.test(String(error))) return undefined;
+    try {
+      resetCorruptWikiSearchIndex(path);
+      return new WikiSearchIndex(path);
+    } catch {
+      return undefined;
+    }
+  }
+}
+
+/** Derive the indexed fields for one document body. */
+function prepareWikiSearchDocument(
+  kind: IndexedWikiKind,
+  key: string,
+  text: string,
+): PreparedWikiSearchDocument {
+  const titleLine = text.split("\n").find((line) => /^#+\s*/.test(line)) ?? "";
+  const title = titleLine ? titleLine.replace(/^#+\s*/, "") : basename(key);
+  return {
+    title,
+    text,
+    tokens: canonicalSearchTokens(`${key} ${title} ${text}`),
+    ...(kind === "summary" && /^\d{4}-\d{2}-\d{2}/.test(key)
+      ? { date: key.slice(0, 10), family: summaryTopicIdentity(key) }
+      : {}),
+  };
+}
+
+/**
+ * Mirror a freshly written document into the derived body index.
+ *
+ * Returns false when the cache could not be updated. The document and its
+ * catalog row are already durable at this point, so a cache miss degrades
+ * retrieval to catalog-only rather than failing the write.
+ */
+function indexWikiSearchDocument(kind: IndexedWikiKind, key: string, text: string): boolean {
+  const root = kind === "article" ? runtime().articlesDir : runtime().summariesDir;
+  const path = resolve(root, `${key}.md`);
+  const index = openWikiSearchIndex();
+  if (!index) return false;
+  try {
+    const stat = statSync(path);
+    index.upsert(
+      { kind, key, path, mtimeMs: stat.mtimeMs, size: stat.size },
+      prepareWikiSearchDocument(kind, key, text),
+    );
+    return true;
+  } catch {
+    return false;
+  } finally {
+    index.close();
+  }
+}
+
+type WikiIndexKind = "article" | "summary" | "topic" | "skill";
+
+const WIKI_INDEX_FILENAMES: Record<WikiIndexKind, string> = {
+  article: "article-index.md",
+  summary: "summary-index.md",
+  topic: "topic-index.md",
+  skill: "skill-index.md",
+};
+
+const WIKI_INDEX_NAMESPACES: Record<WikiIndexKind, string> = {
+  article: "articles",
+  summary: "summaries",
+  topic: "topic",
+  skill: "skills",
+};
+
+/** Resolve the human-readable catalog that owns a given entry kind. */
+function wikiIndexPath(kind: WikiIndexKind): string {
+  return resolve(runtime().wikiDir, WIKI_INDEX_FILENAMES[kind]);
+}
+
+const MAX_INDEX_DESCRIPTION_LENGTH = 400;
+
+/**
+ * Reduce a caller-supplied description to a single catalog line.
+ *
+ * Catalog rows are line-oriented, so an embedded newline would split one entry
+ * into an unparsable fragment. Rejecting empty text here is what keeps index
+ * quality a schema guarantee rather than a prompt convention.
+ */
+function normalizeIndexDescription(raw: string): { description: string } | { error: string } {
+  const description = raw.replaceAll(/\s+/g, " ").trim();
+  if (!description) return { error: "A non-empty one-line description is required." };
+  if (description.length > MAX_INDEX_DESCRIPTION_LENGTH) {
+    return {
+      error: `Description must be at most ${MAX_INDEX_DESCRIPTION_LENGTH} characters (got ${description.length}).`,
+    };
+  }
+  return { description };
+}
+
+/** Reject slugs that would escape their content directory or break a wikilink. */
+function normalizeWikiSlug(raw: string): { slug: string } | { error: string } {
+  const slug = raw.trim().replace(/\.md$/i, "").replace(/^\/+/, "");
+  if (!slug) return { error: "A non-empty slug is required." };
+  if (/[[\]|\\]/.test(slug)) return { error: "Slug must not contain [ ] | or backslashes." };
+  if (slug.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+    return { error: "Slug must not contain empty or relative path segments." };
+  }
+  return { slug };
+}
+
+function parseWikiIndex(path: string): WikiIndexCandidate[] {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch {
+    return [];
+  }
+  const candidates: WikiIndexCandidate[] = [];
+  const entryPattern = /^\s*-\s*\[\[(topic|articles|summaries)\/([^\]]+)\]\]\s*(.*)$/;
+  for (const line of text.split("\n")) {
+    const match = line.match(entryPattern);
+    if (!match) continue;
+    const namespace = match[1]!;
+    const key = match[2]!.replace(/\.md$/i, "");
+    const tail = match[3]!.trim();
+    const dateMatch = tail.match(/\((\d{4}-\d{2}-\d{2})(?:[^)]*)\)\s*$/);
+    const description = dateMatch ? tail.slice(0, dateMatch.index).trim() : tail;
+    candidates.push({
+      kind: namespace === "topic" ? "topic" : namespace === "articles" ? "article" : "summary",
+      key,
+      description,
+      ...(dateMatch ? { date: dateMatch[1] } : {}),
+    });
+  }
+  return candidates;
+}
+
+function indexCandidateExists(candidate: WikiIndexCandidate): boolean {
+  // Topic indexes may point at canonical DB-backed memories rather than local files.
+  if (candidate.kind === "topic") return true;
+  const root = candidate.kind === "article" ? runtime().articlesDir : runtime().summariesDir;
+  const filePath = resolve(root, `${candidate.key}.md`);
+  const relativePath = relative(root, filePath);
+  if (relativePath.startsWith("..") || relativePath.startsWith("/")) return false;
+  try {
+    return statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function scoreIndexKey(query: string, key: string): number {
+  const normalizedQuery = normalizeSearchText(query);
+  const compactQuery = compactSearchText(normalizedQuery);
+  const normalizedKey = normalizeSearchText(key);
+  const compactKey = compactSearchText(normalizedKey);
+  const tokens = meaningfulSearchTokens(normalizedQuery);
+  let score = 0;
+  if (normalizedKey === normalizedQuery) score += 120;
+  else if (compactKey === compactQuery) score += 110;
+  else {
+    if (
+      compactQuery.length >= 2 &&
+      (compactKey.startsWith(compactQuery) || compactQuery.startsWith(compactKey))
+    ) {
+      score += 65;
+    }
+    if (tokens.length > 0 && compactQuery.length >= 3 && compactKey.includes(compactQuery)) {
+      score += 45;
+    }
+    score += fuzzySearchScore(compactQuery, compactKey, 55);
+  }
+  for (const token of tokens) {
+    if (normalizedKey.includes(token)) score += 10;
+  }
+  return score;
+}
+
+function scoreIndexCandidate(query: string, candidate: WikiIndexCandidate): number {
+  const normalizedQuery = normalizeSearchText(query);
+  if (!normalizedQuery) return 0;
+  const normalizedDescription = normalizeSearchText(candidate.description);
+  const tokens = canonicalSearchTokens(normalizedQuery);
+  const descriptionTokens = new Set(canonicalSearchTokens(normalizedDescription));
+  let score = scoreIndexKey(normalizedQuery, candidate.key);
+  if (tokens.length > 0 && normalizedDescription.includes(normalizedQuery)) score += 30;
+  let descriptionMatches = 0;
+  for (const token of tokens) {
+    if (descriptionTokens.has(token)) {
+      score += 5;
+      descriptionMatches += 1;
+    }
+  }
+  if (tokens.length > 1 && descriptionMatches === tokens.length) score += 25;
+  if (candidate.kind === "topic") {
+    const requestsCurrent = /\b(?:current|active|ongoing|open)\b|현재|진행 중/.test(
+      normalizedQuery,
+    );
+    const archivedCandidate = /\b(?:archive|archived|historical|closed)\b|보관|종료/.test(
+      `${normalizeSearchText(candidate.key)} ${normalizedDescription}`,
+    );
+    if (requestsCurrent && archivedCandidate) score -= 40;
+  }
+  return score;
+}
+
 function wikiQuery(args: Record<string, unknown>): CallToolResult {
-  const question = safeExt(args, ["question", "query", "q", "text"], "");
-  const query = question.toLowerCase();
+  const question = String(safeExt(args, ["question", "query", "q", "text"], "")).trim();
+  const requestedKind = String(safeExt(args, ["kind", "type"], "all"));
+  const kind: WikiQueryKind =
+    requestedKind === "topic" || requestedKind === "article" || requestedKind === "summary"
+      ? requestedKind
+      : "all";
+  const requestedLimit = Number(safeExt(args, ["limit", "maxResults"], 8));
+  const limit = Math.min(Math.max(Number.isFinite(requestedLimit) ? requestedLimit : 8, 1), 20);
+  if (!question) {
+    return {
+      content: [{ type: "text", text: "A non-empty wiki query is required." }],
+      isError: true,
+    };
+  }
+  const normalizedQuery = normalizeSearchText(question);
+  if (!normalizedQuery) {
+    return { content: [{ type: "text", text: "No matching wiki articles found." }] };
+  }
+
+  const canReadTopicMemory = runtime().host.canReadTopicMemory;
+  const temporalDirection = /\b(?:latest|newest|recent)\b|최근|최신/.test(normalizedQuery)
+    ? "newest"
+    : /\b(?:earliest|oldest)\b|가장 오래된|최초/.test(normalizedQuery)
+      ? "oldest"
+      : undefined;
+
+  const visibleIndexCandidates = [
+    ...parseWikiIndex(resolve(runtime().wikiDir, "topic-index.md")),
+    ...parseWikiIndex(resolve(runtime().wikiDir, "article-index.md")),
+  ]
+    .filter((candidate) => kind === "all" || candidate.kind === kind)
+    .filter(
+      (candidate) =>
+        candidate.kind !== "topic" ||
+        !canReadTopicMemory ||
+        canReadTopicMemory(candidate.key, runtime().userId),
+    );
+  const hasStaleExactIndexMatch = visibleIndexCandidates.some(
+    (candidate) =>
+      !indexCandidateExists(candidate) && scoreIndexKey(question, candidate.key) >= 100,
+  );
+  const indexCandidates = visibleIndexCandidates
+    .filter(indexCandidateExists)
+    .map((candidate) => ({
+      candidate,
+      keyScore: scoreIndexKey(question, candidate.key),
+      score: scoreIndexCandidate(question, candidate),
+    }))
+    .filter(({ keyScore, score }) => keyScore >= 25 || score >= 40)
+    .sort(
+      (left, right) =>
+        right.score - left.score || left.candidate.key.localeCompare(right.candidate.key),
+    );
+
+  const strongestIndex = indexCandidates[0];
+  if (
+    kind === "topic" &&
+    strongestIndex &&
+    (strongestIndex.keyScore >= 25 || strongestIndex.score >= 40)
+  ) {
+    const runnerUp = indexCandidates[1];
+    const ambiguous =
+      strongestIndex.keyScore < 100 &&
+      runnerUp !== undefined &&
+      runnerUp.score >= strongestIndex.score * 0.9;
+    if (ambiguous) {
+      const lines = ["Found 2 ambiguous wiki candidates:", ""];
+      for (const { candidate, score } of [strongestIndex, runnerUp]) {
+        lines.push(
+          `- kind: ${candidate.kind}`,
+          `  key: ${candidate.key}`,
+          `  score: ${score.toFixed(2)}`,
+          `  description: ${candidate.description || "(none)"}`,
+          ...(candidate.date ? [`  date: ${candidate.date}`] : []),
+        );
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+    const lines = ["Found 1 wiki candidate:", ""];
+    for (const { candidate, score } of [strongestIndex]) {
+      lines.push(
+        `- kind: ${candidate.kind}`,
+        `  key: ${candidate.key}`,
+        `  score: ${score.toFixed(2)}`,
+        `  description: ${candidate.description || "(none)"}`,
+        ...(candidate.date ? [`  date: ${candidate.date}`] : []),
+      );
+    }
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
 
   const results: string[] = [];
-  const scored: { score: number; path: string; text: string }[] = [];
+  const scored: WikiSearchResult[] = [];
 
   function scan(dir: string, label: string): void {
     ensureDir(dir);
@@ -291,10 +817,15 @@ function wikiQuery(args: Record<string, unknown>): CallToolResult {
                 const fp = join(sub, f.name);
                 try {
                   const text = readFileSync(fp, "utf-8");
+                  const key = `${entry.name}/${f.name.replace(/\.md$/i, "")}`;
                   scored.push({
-                    score: scoreMatch(text),
+                    kind: label === "articles" ? "article" : "skill",
+                    key,
+                    keyScore: scoreIndexKey(question, key),
+                    score: scoreMatch(text, key, label === "articles" ? "article" : "skill"),
                     path: `${label}/${entry.name}/${f.name}`,
                     text,
+                    title: titleFromDocument(text, key),
                   });
                 } catch {
                   /* skip unreadable */
@@ -305,13 +836,36 @@ function wikiQuery(args: Record<string, unknown>): CallToolResult {
             }
           }
         } else if (entry.isFile() && entry.name.endsWith(".md")) {
+          if (
+            label === "topic" &&
+            canReadTopicMemory &&
+            !canReadTopicMemory(entry.name.replace(/\.md$/i, ""), runtime().userId)
+          ) {
+            continue;
+          }
           const fp = join(dir, entry.name);
           try {
             const text = readFileSync(fp, "utf-8");
+            const key = entry.name.replace(/\.md$/i, "");
+            const resultKind =
+              label === "articles"
+                ? "article"
+                : label === "topic"
+                  ? "topic"
+                  : label === "summaries"
+                    ? "summary"
+                    : "skill";
             scored.push({
-              score: scoreMatch(text),
+              kind: resultKind,
+              key,
+              keyScore: scoreIndexKey(question, key),
+              score: scoreMatch(text, key, resultKind),
               path: `${label}/${entry.name}`,
               text,
+              title: titleFromDocument(text, key),
+              ...(label === "summaries" && /^\d{4}-\d{2}-\d{2}/.test(key)
+                ? { date: key.slice(0, 10) }
+                : {}),
             });
           } catch {
             /* skip unreadable */
@@ -323,48 +877,275 @@ function wikiQuery(args: Record<string, unknown>): CallToolResult {
     }
   }
 
-  function scoreMatch(text: string): number {
-    const lower = text.toLowerCase();
+  function titleFromDocument(text: string, key: string): string {
+    const titleLine = text.split("\n").find((line) => /^#+\s*/.test(line));
+    return titleLine ? titleLine.replace(/^#+\s*/, "") : basename(key);
+  }
+
+  function scoreMatch(text: string, key: string, resultKind: WikiSearchResultKind): number {
+    const titleLine = text.split("\n").find((line) => /^#+\s*/.test(line)) ?? "";
+    const title = titleLine.replace(/^#+\s*/, "");
+    const normalizedKey = normalizeSearchText(key);
+    const normalizedTitle = normalizeSearchText(title);
+    const normalizedBody = normalizeSearchText(text.replace(titleLine, ""));
+    const compactQuery = compactSearchText(normalizedQuery);
+    const compactKey = compactSearchText(normalizedKey);
+    const compactTitle = compactSearchText(normalizedTitle);
+    const tokens = canonicalSearchTokens(normalizedQuery);
+    const keyTokens = new Set(canonicalSearchTokens(normalizedKey));
+    const titleTokens = new Set(canonicalSearchTokens(normalizedTitle));
+    const bodyTokens = canonicalSearchTokens(normalizedBody);
     let score = 0;
-    const words = query.split(/\s+/).filter(Boolean);
-    for (const w of words) {
-      if (lower.includes(w)) {
-        score += w.length >= 3 ? 3 : 1;
-        // Bonus for title match (first line starts with #)
-        const firstLine = lower.split("\n")[0];
-        if (firstLine.startsWith("#") && firstLine.includes(w)) score += 5;
+    let strongMetadataEvidence = false;
+
+    if (normalizedKey === normalizedQuery) {
+      score += 120;
+      strongMetadataEvidence = true;
+    } else if (compactKey === compactQuery) {
+      score += 110;
+      strongMetadataEvidence = true;
+    } else if (
+      compactQuery.length >= 2 &&
+      (compactKey.startsWith(compactQuery) || compactQuery.startsWith(compactKey))
+    ) {
+      score += 65;
+      strongMetadataEvidence = true;
+    }
+    if (tokens.length > 0 && compactQuery.length >= 3 && compactKey.includes(compactQuery)) {
+      score += 45;
+      strongMetadataEvidence = true;
+    }
+    const fuzzyKeyScore = fuzzySearchScore(compactQuery, compactKey, 55);
+    score += fuzzyKeyScore;
+    if (fuzzyKeyScore > 0) strongMetadataEvidence = true;
+
+    if (normalizedTitle === normalizedQuery) {
+      score += 115;
+      strongMetadataEvidence = true;
+    } else if (compactTitle === compactQuery) {
+      score += 105;
+      strongMetadataEvidence = true;
+    } else if (compactQuery.length >= 2 && compactTitle.startsWith(compactQuery)) {
+      score += 60;
+      strongMetadataEvidence = true;
+    }
+    const fuzzyTitleScore = fuzzySearchScore(compactQuery, compactTitle, 50);
+    score += fuzzyTitleScore;
+    if (fuzzyTitleScore > 0) strongMetadataEvidence = true;
+    if (resultKind === "summary") {
+      const temporalScore = scoreSummaryTime(normalizedQuery, key, title);
+      if (temporalScore === null) return 0;
+      score += temporalScore;
+      if (temporalScore > 0) strongMetadataEvidence = true;
+    }
+
+    const isMultiToken = tokens.length > 1;
+    if (tokens.length > 0 && normalizedTitle.includes(normalizedQuery)) {
+      score += 35;
+      strongMetadataEvidence = true;
+    }
+    const phraseMatches = isMultiToken ? countPhrase(normalizedBody, normalizedQuery) : 0;
+    if (phraseMatches > 0) score += phraseMatches * 12;
+    else if (tokens.length === 1 && tokens[0]!.length >= 5 && normalizedBody.includes(tokens[0]!)) {
+      score += 16;
+    }
+
+    let bodyMatches = 0;
+    let minimumBodyFrequency = Number.POSITIVE_INFINITY;
+    for (const token of tokens) {
+      if (keyTokens.has(token)) score += 10;
+      if (titleTokens.has(token)) score += 12;
+      const bodyFrequency = countToken(bodyTokens, token);
+      if (bodyFrequency > 0) {
+        score += Math.min(bodyFrequency, 3) * 4;
+        bodyMatches += 1;
+        minimumBodyFrequency = Math.min(minimumBodyFrequency, bodyFrequency);
       }
     }
+    if (isMultiToken && bodyMatches === tokens.length) {
+      score += 8 * Math.min(minimumBodyFrequency, 3);
+    }
+    const minimumBodyTokens = hasStaleExactIndexMatch ? 3 : 2;
+    const partialArticleEvidence =
+      resultKind === "article" && bodyMatches >= 3 && bodyMatches / tokens.length >= 0.6;
+    const strongBodyEvidence =
+      tokens.length >= minimumBodyTokens &&
+      ((bodyMatches === tokens.length && (phraseMatches > 0 || minimumBodyFrequency >= 1)) ||
+        partialArticleEvidence);
+    if (!strongMetadataEvidence && !strongBodyEvidence) return 0;
     return score;
   }
 
-  scan(runtime().articlesDir, "articles");
-  // Skills are node-local runtime knowledge, not canonical workspace memory.
-  // Keep the legacy all-in-one server compatible while ensuring the explicit
-  // wiki surface cannot read a node's skill library.
-  if (runtime().surface === "all") scan(runtime().skillsDir, "skills");
-  scan(runtime().topicsDir, "topic");
-  scan(runtime().summariesDir, "summaries");
+  // Article and summary bodies come from the derived index, which the write path
+  // keeps current. Reading every file here is what made retrieval cost grow with
+  // the size of the wiki.
+  const bodyKinds: IndexedWikiKind[] = [
+    ...(kind === "all" || kind === "article" ? (["article"] as const) : []),
+    ...(kind === "all" || kind === "summary" ? (["summary"] as const) : []),
+  ];
+  if (bodyKinds.length > 0) {
+    const searchIndex = openWikiSearchIndex();
+    if (searchIndex) {
+      try {
+        const terms = canonicalSearchTokens(normalizedQuery);
+        const ids = searchIndex.matchingDocumentIds(bodyKinds, terms);
+        // "latest summary" carries no term any document contains, so a purely
+        // temporal question is answered from the indexed dates instead.
+        if (temporalDirection && bodyKinds.includes("summary")) {
+          for (const item of searchIndex.summaryMetadataByDate({
+            direction: temporalDirection === "newest" ? "latest" : "oldest",
+            limit,
+          })) {
+            ids.add(item.id);
+          }
+        }
+        for (const document of searchIndex.documents(ids)) {
+          scored.push({
+            kind: document.kind,
+            key: document.key,
+            keyScore: scoreIndexKey(question, document.key),
+            score: scoreMatch(document.text, document.key, document.kind),
+            path: `${document.kind === "article" ? "articles" : "summaries"}/${document.key}.md`,
+            text: document.text,
+            title: document.title,
+            ...(document.date ? { date: document.date } : {}),
+          });
+        }
+      } catch {
+        // A damaged cache must not make catalog retrieval unavailable.
+      } finally {
+        searchIndex.close();
+      }
+    }
+  }
+  // Topic briefs and skills are small, node-local sets that no derived index
+  // covers, so they are still read directly. Skills stay out of the explicit
+  // wiki surface: they are node runtime knowledge, not canonical memory.
+  if (kind === "all" && runtime().surface === "all") scan(runtime().skillsDir, "skills");
+  if (kind === "all" || kind === "topic") scan(runtime().topicsDir, "topic");
+
+  const merged = new Map<string, WikiSearchResult>();
+  for (const { candidate, keyScore, score } of indexCandidates) {
+    merged.set(`${candidate.kind}:${candidate.key}`, {
+      kind: candidate.kind,
+      key: candidate.key,
+      keyScore,
+      score,
+      description: candidate.description,
+      date: candidate.date,
+    });
+  }
+  const documentThreshold = kind === "topic" ? 24 : 16;
+  for (const document of scored) {
+    if (document.score < documentThreshold) continue;
+    const id = `${document.kind}:${document.key}`;
+    const indexed = merged.get(id);
+    merged.set(
+      id,
+      indexed
+        ? { ...indexed, ...document, score: Math.max(indexed.score, document.score) }
+        : document,
+    );
+  }
 
-  scored.sort((a, b) => b.score - a.score);
-  const top = scored.slice(0, 8);
+  let ranked = [...merged.values()].sort(
+    (left, right) =>
+      right.score - left.score ||
+      (left.kind === "summary" && right.kind === "summary"
+        ? temporalDirection === "oldest"
+          ? (left.date ?? "").localeCompare(right.date ?? "")
+          : (right.date ?? "").localeCompare(left.date ?? "")
+        : 0) ||
+      left.key.localeCompare(right.key),
+  );
 
-  if (top.length === 0) {
+  if (kind === "summary") {
+    const sameTopic = ranked.filter((result) => {
+      const identity = summaryTopicIdentity(result.key);
+      return identity.length >= 3 && normalizedQuery.includes(identity);
+    });
+    if (sameTopic.length > 0) ranked = sameTopic;
+
+    const requestedDateMatch = normalizedQuery.match(/\b(\d{4}) (\d{2}) (\d{2})\b/);
+    const requestedDate = requestedDateMatch
+      ? `${requestedDateMatch[1]}-${requestedDateMatch[2]}-${requestedDateMatch[3]}`
+      : undefined;
+    const beforeDate = /\bbefore\b/.test(normalizedQuery);
+    const afterDate = /\bafter\b/.test(normalizedQuery);
+    if (requestedDate && beforeDate) {
+      ranked = ranked.filter((result) => !result.date || result.date < requestedDate);
+    } else if (requestedDate && afterDate) {
+      ranked = ranked.filter((result) => !result.date || result.date > requestedDate);
+    }
+    ranked.sort((left, right) => {
+      if (beforeDate) {
+        return (right.date ?? "").localeCompare(left.date ?? "") || right.score - left.score;
+      }
+      if (afterDate) {
+        return (left.date ?? "").localeCompare(right.date ?? "") || right.score - left.score;
+      }
+      if (requestedDate) {
+        const dateDifference =
+          Number(right.date === requestedDate) - Number(left.date === requestedDate);
+        if (dateDifference !== 0) return dateDifference;
+      }
+      if (temporalDirection) {
+        const dateDifference =
+          temporalDirection === "oldest"
+            ? (left.date ?? "").localeCompare(right.date ?? "")
+            : (right.date ?? "").localeCompare(left.date ?? "");
+        if (dateDifference !== 0) return dateDifference;
+      }
+      return (
+        right.score - left.score ||
+        (right.date ?? "").localeCompare(left.date ?? "") ||
+        left.key.localeCompare(right.key)
+      );
+    });
+  }
+
+  if (kind === "topic" && ranked[0]) {
+    const runnerUp = ranked[1];
+    const ambiguous =
+      ranked[0].keyScore < 100 && runnerUp !== undefined && runnerUp.score >= ranked[0].score * 0.9;
+    if (ambiguous) {
+      ranked = ranked.slice(0, 2);
+    } else {
+      ranked = ranked.slice(0, 1);
+    }
+  } else {
+    ranked = ranked.slice(0, limit);
+  }
+
+  if (ranked.length === 0) {
     results.push("No matching wiki articles found.");
   } else {
-    results.push(`Found ${top.length} matching result(s):\n`);
-    for (const { path, text } of top) {
-      // Extract title from first heading
-      const titleLine = text.split("\n").find((l) => l.startsWith("#"));
-      const title = titleLine ? titleLine.replace(/^#+\s*/, "") : basename(path, ".md");
-      // Truncate body to 400 chars
-      const body = text
-        .replace(/^---[\s\S]*?---\n?/, "")
-        .replace(/^#.*$/m, "")
-        .trim()
-        .slice(0, 400);
+    results.push(`Found ${ranked.length} matching result(s):\n`);
+    for (const result of ranked) {
+      if (result.kind === "skill") {
+        const body = (result.text ?? "").trim().slice(0, 400);
+        results.push(
+          `## ${result.title ?? result.key}\nPath: ${result.path}\n\n${body}${(result.text?.length ?? 0) > 400 ? "\n...(truncated)" : ""}\n`,
+        );
+        continue;
+      }
       results.push(
-        `## ${title}\nPath: ${path}\n\n${body}${text.length > 400 ? "\n...(truncated)" : ""}\n`,
+        `- kind: ${result.kind}`,
+        `  key: ${result.key}`,
+        `  score: ${result.score.toFixed(2)}`,
+        ...(result.title ? [`  title: ${result.title}`] : []),
+        `  description: ${result.description || "(none)"}`,
+        ...(result.date ? [`  date: ${result.date}`] : []),
+        ...(result.path ? [`  path: ${result.path}`, `  Path: ${result.path}`] : []),
+        ...(result.text
+          ? [
+              `  excerpt: ${result.text
+                .replace(/^---[\s\S]*?---\n?/, "")
+                .replace(/^#.*$/m, "")
+                .trim()
+                .slice(0, 400)}`,
+            ]
+          : []),
       );
     }
   }
@@ -390,40 +1171,109 @@ function wikiTopicBrief(args: Record<string, unknown>): CallToolResult {
   }
 
   const { getTopicBrief, resolveTopicBrief } = runtime().host;
-  if (runtime().topicId && (getTopicBrief || resolveTopicBrief)) {
+  const hasAuthorizedBridge = Boolean(runtime().topicId && (getTopicBrief || resolveTopicBrief));
+  if (hasAuthorizedBridge) {
     try {
       const brief = resolveTopicBrief
         ? resolveTopicBrief(rawTopic, runtime().userId)
         : getTopicBrief!(rawTopic);
-      if (!brief) {
-        return {
-          content: [{ type: "text", text: `No brief found for topic: ${rawTopic}` }],
-        };
-      }
-      const lines = [
-        `# Topic Brief: ${topicNameFrom(rawTopic)}`,
-        "",
-        brief.briefMd || "(empty brief)",
-      ];
-      if (brief.latestSummaryMd) {
-        lines.push("", "## Latest Summary", "", brief.latestSummaryMd);
-      }
-      if (brief.summaryDate) {
-        lines.push("", `Summary date: ${brief.summaryDate}`);
+      if (brief) {
+        const lines = [
+          `# Topic Brief: ${topicNameFrom(rawTopic)}`,
+          "",
+          brief.briefMd || "(empty brief)",
+        ];
+        if (brief.latestSummaryMd) {
+          lines.push("", "## Latest Summary", "", brief.latestSummaryMd);
+        }
+        if (brief.summaryDate) {
+          lines.push("", `Summary date: ${brief.summaryDate}`);
+        }
+        return { content: [{ type: "text", text: lines.join("\n") }] };
       }
-      return { content: [{ type: "text", text: lines.join("\n") }] };
     } catch {
-      return {
-        content: [{ type: "text", text: `Could not read topic brief for: ${rawTopic}` }],
-      };
+      // The SQLite mirror is optional; fall through to the canonical file.
     }
+    return {
+      content: [{ type: "text", text: `No brief found for topic: ${rawTopic}` }],
+    };
   }
 
+  const topicKey = wikiSummarySlug(rawTopic.replace(/^topic\//, "").replace(/\.md$/i, ""));
+  const filePath = resolve(runtime().topicsDir, `${topicKey}.md`);
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return {
+      content: [{ type: "text", text: `# Topic Brief: ${topicKey}\n\n${content}` }],
+    };
+  } catch {
+    // Report the same not-found result for DB- and file-backed lookups.
+  }
   return {
-    content: [{ type: "text", text: `No topic brief found for: ${rawTopic}` }],
+    content: [{ type: "text", text: `No brief found for topic: ${rawTopic}` }],
   };
 }
 
+function wikiRead(args: Record<string, unknown>): CallToolResult {
+  const rawKind = String(safeExt(args, ["kind", "type"], "article"));
+  const kind = rawKind === "topic" || rawKind === "summary" ? rawKind : "article";
+  const rawKey = String(safeExt(args, ["key", "slug", "topic"], "")).trim();
+  if (!rawKey) {
+    return { content: [{ type: "text", text: "A wiki document key is required." }], isError: true };
+  }
+
+  if (kind === "topic") {
+    const result = wikiTopicBrief({ topic: rawKey });
+    const resultText = result.content
+      .map((entry) => (entry.type === "text" ? entry.text : ""))
+      .join("\n");
+    const adopt = safeExt<boolean>(args, ["adopt", "use", "select"], false);
+    if (!adopt || resultText.startsWith("No brief found for topic")) return result;
+
+    const currentTopicId = runtime().currentTopicId;
+    const memoryKey = wikiSummarySlug(rawKey.replace(/^topic\//, "").replace(/\.md$/i, ""));
+    if (
+      !currentTopicId ||
+      !runtime().host.adoptTopicMemory?.(currentTopicId, runtime().userId, memoryKey)
+    ) {
+      return {
+        content: [
+          ...result.content,
+          { type: "text", text: "\nMemory was read but could not be adopted by this topic." },
+        ],
+      };
+    }
+    return {
+      content: [...result.content, { type: "text", text: `\nAdopted topic memory: ${memoryKey}` }],
+    };
+  }
+
+  if (
+    rawKey.includes("\\") ||
+    rawKey.split("/").some((part) => part === "..") ||
+    rawKey.startsWith("/")
+  ) {
+    return { content: [{ type: "text", text: "Invalid wiki document key." }], isError: true };
+  }
+  const root = kind === "summary" ? runtime().summariesDir : runtime().articlesDir;
+  const key = rawKey
+    .replace(new RegExp(`^(?:${kind === "summary" ? "summaries" : "articles"})/`), "")
+    .replace(/\.md$/i, "");
+  const filePath = resolve(root, `${key}.md`);
+  const relativePath = relative(root, filePath);
+  if (relativePath.startsWith("..") || relativePath.startsWith("/")) {
+    return { content: [{ type: "text", text: "Invalid wiki document key." }], isError: true };
+  }
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    return {
+      content: [{ type: "text", text: `# Wiki ${kind}: ${key}\n\n${content}` }],
+    };
+  } catch {
+    return { content: [{ type: "text", text: `No ${kind} found for: ${rawKey}` }] };
+  }
+}
+
 function wikiLastConversation(args: Record<string, unknown>): CallToolResult {
   const rawTopic = safeExt<string | undefined>(
     args,
@@ -651,15 +1501,12 @@ function skillSave(args: Record<string, unknown>): CallToolResult {
   };
 }
 
-function saveWikiEntry(args: Record<string, unknown>): CallToolResult {
-  const rawTopic = safeExt(args, ["topic", "topicName"], "");
-  const content: string = safeExt(args, ["content", "text", "body"], "");
-
-  if (!rawTopic) return { content: [{ type: "text", text: "Missing topic." }] };
-  if (!content) return { content: [{ type: "text", text: "Missing content." }] };
-
-  const now = new Date();
-  const dateStr = now.toISOString().slice(0, 10);
+/** Write a write-once session summary and report the slug the catalog must use. */
+function writeSummaryDocument(
+  rawTopic: string,
+  content: string,
+  dateStr: string,
+): { slug: string; sqliteUpdated: boolean } {
   const topicId = runtime().topicId;
   const fileSlug = wikiBriefStorageKey(rawTopic, topicId);
 
@@ -683,9 +1530,9 @@ function saveWikiEntry(args: Record<string, unknown>): CallToolResult {
   }
 
   // Record the latest summary. The fresh brief is written authoritatively by
-  // save_topic_brief (called after this step). We only backfill brief_md here so
-  // a summary-only write — e.g. the no-substance path, which skips
-  // save_topic_brief — can't create a title-key row with an empty brief_md that
+  // wiki_write(kind="topic") (called after this step). We only backfill brief_md
+  // here so a summary-only write — e.g. the no-substance path, which skips the
+  // brief — can't create a title-key row with an empty brief_md that
   // shadows an existing brief (see resolveTopicBrief precedence). Backfill order:
   // an existing brief file, else a legacy id-keyed row migrated forward. We
   // never overwrite an existing title brief_md with empty.
@@ -713,25 +1560,14 @@ function saveWikiEntry(args: Record<string, unknown>): CallToolResult {
     }
   }
 
-  return {
-    content: [
-      {
-        type: "text",
-        text:
-          `Saved summary: summaries/${summaryName}` +
-          (sqliteUpdated ? "\nSQLite latest-summary also updated." : ""),
-      },
-    ],
-  };
+  return { slug: summaryName.replace(/\.md$/i, ""), sqliteUpdated };
 }
 
-function saveTopicBrief(args: Record<string, unknown>): CallToolResult {
-  const rawTopic = safeExt(args, ["topic", "topicName"], "");
-  const content: string = safeExt(args, ["content", "brief", "text", "body"], "");
-
-  if (!rawTopic) return { content: [{ type: "text", text: "Missing topic." }] };
-  if (!content) return { content: [{ type: "text", text: "Missing content." }] };
-
+/** Write the accumulated persona brief and mirror it for the next session start. */
+function writeTopicDocument(
+  rawTopic: string,
+  content: string,
+): { slug: string; existed: boolean; sqliteUpdated: boolean } {
   const topicId = runtime().topicId;
   const fileSlug = wikiBriefStorageKey(rawTopic, topicId);
 
@@ -743,7 +1579,7 @@ function saveTopicBrief(args: Record<string, unknown>): CallToolResult {
 
   // Mirror the brief into SQLite so it is injected at the next session start.
   // Partial upsert: only brief_md is touched, leaving latest_summary_md and
-  // summary_date (written by save_wiki_entry) intact.
+  // summary_date (written by the summary path) intact.
   const setTopicBrief = runtime().host.setTopicBrief;
   let sqliteUpdated = false;
   if (topicId && setTopicBrief) {
@@ -755,35 +1591,279 @@ function saveTopicBrief(args: Record<string, unknown>): CallToolResult {
     }
   }
 
+  return { slug: fileSlug, existed, sqliteUpdated };
+}
+
+/** Write a curated concept page. Articles are mergeable, so this overwrites. */
+function writeArticleDocument(slug: string, content: string): { existed: boolean } {
+  const articlePath = resolve(runtime().articlesDir, `${slug}.md`);
+  ensureDir(dirname(articlePath));
+  const existed = existsSync(articlePath);
+  atomicWriteFile(articlePath, content);
+  return { existed };
+}
+
+/**
+ * Write a wiki document and its catalog row in one call.
+ *
+ * This is the only way to create a wiki entry. Pairing the two writes here is
+ * what makes an unindexed document impossible to produce through the tool
+ * surface: a document write that cannot be indexed is reported as a failure so
+ * the caller retries, and the row upsert is idempotent.
+ */
+function wikiWrite(args: Record<string, unknown>): CallToolResult {
+  const rawKind: string = safeExt(args, ["kind", "type"], "");
+  const content: string = safeExt(args, ["content", "text", "body", "brief"], "");
+  const rawDescription = safeExt(args, ["description", "desc"], "");
+  const rawTopic = safeExt(args, ["topic", "topicName"], "");
+  const rawSlug = safeExt(args, ["slug", "id"], "");
+  const section = safeExt<string | undefined>(args, ["section", "category"], undefined);
+  const rawDate = safeExt<string | undefined>(args, ["date", "created"], undefined);
+
+  if (rawKind !== "summary" && rawKind !== "article" && rawKind !== "topic") {
+    return {
+      content: [{ type: "text", text: 'kind must be one of "summary", "article", "topic".' }],
+      isError: true,
+    };
+  }
+  if (!content.trim()) {
+    return { content: [{ type: "text", text: "Missing content." }], isError: true };
+  }
+  const descriptionResult = normalizeIndexDescription(rawDescription);
+  if ("error" in descriptionResult) {
+    return { content: [{ type: "text", text: descriptionResult.error }], isError: true };
+  }
+  const { description } = descriptionResult;
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (rawKind === "article") {
+    const slugResult = normalizeWikiSlug(rawSlug);
+    if ("error" in slugResult) {
+      return { content: [{ type: "text", text: slugResult.error }], isError: true };
+    }
+    if (!section?.trim()) {
+      return {
+        content: [
+          { type: "text", text: "An article requires a section so the catalog stays navigable." },
+        ],
+        isError: true,
+      };
+    }
+    const { existed } = writeArticleDocument(slugResult.slug, content);
+    const link = indexRowOrPartialWrite("article", {
+      kind: "article",
+      slug: slugResult.slug,
+      description,
+      date: rawDate ?? today,
+      section: section.trim(),
+    });
+    if (typeof link !== "string") return link;
+    const searched = indexWikiSearchDocument("article", slugResult.slug, content);
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Saved article: articles/${slugResult.slug}.md (${existed ? "updated" : "created"})\nIndexed: ${link}` +
+            (searched ? "" : `\n${SEARCH_CACHE_SKIPPED_NOTE}`),
+        },
+      ],
+    };
+  }
+
+  const topic = rawTopic.trim();
+  if (!topic) {
+    return { content: [{ type: "text", text: "Missing topic." }], isError: true };
+  }
+
+  if (rawKind === "summary") {
+    const dateStr = rawDate ?? today;
+    const written = writeSummaryDocument(topic, content, dateStr);
+    const link = indexRowOrPartialWrite("summary", {
+      kind: "summary",
+      slug: written.slug,
+      description,
+      date: dateStr,
+    });
+    if (typeof link !== "string") return link;
+    const searched = indexWikiSearchDocument("summary", written.slug, content);
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            `Saved summary: summaries/${written.slug}.md\nIndexed: ${link}` +
+            (written.sqliteUpdated ? "\nSQLite latest-summary also updated." : "") +
+            (searched ? "" : `\n${SEARCH_CACHE_SKIPPED_NOTE}`),
+        },
+      ],
+    };
+  }
+
+  const written = writeTopicDocument(topic, content);
+  const link = indexRowOrPartialWrite("topic", {
+    kind: "topic",
+    slug: written.slug,
+    description,
+    date: rawDate ?? today,
+  });
+  if (typeof link !== "string") return link;
   return {
     content: [
       {
         type: "text",
         text:
-          `Saved brief: topic/${fileSlug}.md (${existed ? "updated" : "created"})` +
-          (sqliteUpdated ? "\nSQLite brief also updated." : ""),
+          `Saved brief: topic/${written.slug}.md (${written.existed ? "updated" : "created"})\nIndexed: ${link}` +
+          (written.sqliteUpdated ? "\nSQLite brief also updated." : ""),
       },
     ],
   };
 }
 
-function indexUpsert(args: Record<string, unknown>): CallToolResult {
-  const slug = safeExt(args, ["slug", "id"], "");
-  const desc = safeExt(args, ["description", "desc", "text"], "");
-  const kind: string = safeExt(args, ["kind", "type"], "article");
-  const section = safeExt<string | undefined>(args, ["section", "category"], undefined);
-  const date = safeExt<string | undefined>(args, ["date", "created"], undefined);
+/** Collect the article and summary documents currently on disk. */
+function collectIndexableDocuments(): WikiSearchIndexSource[] {
+  const sources: WikiSearchIndexSource[] = [];
+  function add(kind: IndexedWikiKind, key: string, path: string): void {
+    try {
+      const stat = statSync(path);
+      if (!stat.isFile()) return;
+      sources.push({ kind, key, path, mtimeMs: stat.mtimeMs, size: stat.size });
+    } catch {
+      // A file that vanished mid-walk is simply absent from this pass.
+    }
+  }
+  for (const [root, kind, allowSubdirectories] of [
+    [runtime().articlesDir, "article", true],
+    [runtime().summariesDir, "summary", false],
+  ] as const) {
+    let entries: Dirent<string>[];
+    try {
+      entries = readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith(".md")) {
+        add(kind, entry.name.replace(/\.md$/i, ""), join(root, entry.name));
+        continue;
+      }
+      if (!entry.isDirectory() || !allowSubdirectories) continue;
+      let nested: Dirent<string>[];
+      try {
+        nested = readdirSync(join(root, entry.name), { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const file of nested) {
+        if (!file.isFile() || !file.name.endsWith(".md")) continue;
+        add(
+          kind,
+          `${entry.name}/${file.name.replace(/\.md$/i, "")}`,
+          join(root, entry.name, file.name),
+        );
+      }
+    }
+  }
+  return sources;
+}
 
-  if (!slug) return { content: [{ type: "text", text: "Missing slug." }] };
+/**
+ * Refill the derived body index and report catalog gaps.
+ *
+ * This is the only place that walks the content directories, and it runs only
+ * when asked. Retrieval never scans, and this command deliberately does not
+ * invent catalog rows: it names the documents that need one so a description is
+ * written by whoever knows what the document is for.
+ */
+function wikiReindex(): CallToolResult {
+  const documents = collectIndexableDocuments();
+  const index = openWikiSearchIndex();
+  if (!index) {
+    return {
+      content: [{ type: "text", text: "Could not open the wiki search index." }],
+      isError: true,
+    };
+  }
+  let synced: { added: number; updated: number; removed: number };
+  try {
+    synced = index.sync(documents, (source, text) =>
+      prepareWikiSearchDocument(source.kind, source.key, text),
+    );
+  } catch (error) {
+    return {
+      content: [{ type: "text", text: `Failed to rebuild the search index: ${String(error)}` }],
+      isError: true,
+    };
+  } finally {
+    index.close();
+  }
 
-  const today = new Date().toISOString().slice(0, 10);
-  const dateStr = date ?? today;
+  // Compare the documents on disk against the catalogs. A document with no row
+  // is invisible to retrieval; a row with no document is a harmless tombstone.
+  const lines = [
+    `Search index: ${synced.added} added, ${synced.updated} updated, ${synced.removed} removed (${documents.length} documents).`,
+  ];
+  for (const kind of ["article", "summary"] as const) {
+    const rows = new Set(
+      parseWikiIndex(wikiIndexPath(kind))
+        .filter((candidate) => candidate.kind === kind)
+        .map((candidate) => candidate.key),
+    );
+    const keys = documents.filter((source) => source.kind === kind).map((source) => source.key);
+    const unindexed = keys.filter((key) => !rows.has(key));
+    const tombstones = [...rows].filter((key) => !keys.includes(key));
+    lines.push(
+      `${WIKI_INDEX_FILENAMES[kind]}: ${rows.size} rows for ${keys.length} documents` +
+        (unindexed.length > 0 ? `; missing rows: ${unindexed.join(", ")}` : "") +
+        (tombstones.length > 0 ? `; tombstones: ${tombstones.join(", ")}` : ""),
+    );
+  }
+  return { content: [{ type: "text", text: lines.join("\n") }] };
+}
 
-  const indexPath = (() => {
-    if (kind === "topic") return resolve(runtime().wikiDir, "topic-index.md");
-    if (kind === "skill") return resolve(runtime().wikiDir, "skill-index.md");
-    return resolve(runtime().wikiDir, "article-index.md");
-  })();
+const SEARCH_CACHE_SKIPPED_NOTE =
+  "Body-search cache was not updated; catalog retrieval still works. Run wiki_reindex to refill it.";
+
+/**
+ * Index a freshly written document, turning an index failure into an explicit
+ * partial-write error naming the document that still needs a catalog row.
+ */
+function indexRowOrPartialWrite(
+  label: string,
+  options: Parameters<typeof upsertIndexRow>[0],
+): string | CallToolResult {
+  try {
+    return upsertIndexRow(options);
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Wrote the ${label} document but failed to index it (${String(error)}). Retry the same wiki_write call: both writes are idempotent.`,
+        },
+      ],
+      isError: true,
+    };
+  }
+}
+
+/**
+ * Insert or update one catalog row in the index that owns `kind`.
+ *
+ * Shared by `wiki_write` (which pairs it with the document write) and
+ * `index_upsert` (which only curates an existing entry). Throwing here is what
+ * lets `wiki_write` report a partial write instead of silently leaving a
+ * document unindexed.
+ */
+function upsertIndexRow(options: {
+  kind: WikiIndexKind;
+  slug: string;
+  description: string;
+  date: string;
+  section?: string | undefined;
+}): string {
+  const { kind, slug, description, date, section } = options;
+  const indexPath = wikiIndexPath(kind);
 
   ensureDir(dirname(indexPath));
   const releaseLock = acquireFileLock(indexPath);
@@ -797,34 +1877,11 @@ function indexUpsert(args: Record<string, unknown>): CallToolResult {
     }
 
     const lines = index.split("\n");
-    const link = (() => {
-      switch (kind) {
-        case "summary":
-          return `- [[summaries/${slug}]] ${desc} (${dateStr})`;
-        case "topic":
-          return `- [[topic/${slug}]] ${desc} (${dateStr})`;
-        case "skill":
-          return `- [[skills/${slug}]] ${desc} (${dateStr})`;
-        default:
-          return `- [[articles/${slug}]] ${desc} (${dateStr})`;
-      }
-    })();
-
+    const target = `${WIKI_INDEX_NAMESPACES[kind]}/${slug}`;
+    const link = `- [[${target}]] ${description} (${date})`;
     // Find every existing entry for this canonical target. Historical versions
     // appended duplicates because they searched for [[slug]] while writing
     // [[topic/slug]].
-    const target = (() => {
-      switch (kind) {
-        case "summary":
-          return `summaries/${slug}`;
-        case "topic":
-          return `topic/${slug}`;
-        case "skill":
-          return `skills/${slug}`;
-        default:
-          return `articles/${slug}`;
-      }
-    })();
     const slugPattern = `[[${target}]]`;
     let replaced = false;
     for (let i = lines.length - 1; i >= 0; i--) {
@@ -869,18 +1926,91 @@ function indexUpsert(args: Record<string, unknown>): CallToolResult {
 
     atomicWriteFile(indexPath, lines.join("\n"));
 
-    return { content: [{ type: "text", text: `Index updated: ${link}` }] };
+    return link;
   } finally {
     releaseLock();
   }
 }
 
+/** Does the document backing a catalog row exist on disk? */
+function wikiDocumentExists(kind: WikiIndexKind, slug: string): boolean {
+  const root =
+    kind === "article"
+      ? runtime().articlesDir
+      : kind === "summary"
+        ? runtime().summariesDir
+        : kind === "topic"
+          ? runtime().topicsDir
+          : runtime().skillsDir;
+  const filePath = resolve(root, `${slug}.md`);
+  if (relative(root, filePath).startsWith("..")) return false;
+  try {
+    return statSync(filePath).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Curate an existing catalog row.
+ *
+ * This tool deliberately cannot introduce a row for a document that does not
+ * exist: `wiki_write` is the only way to create an entry, so a description fix
+ * can never be the step that invents an unbacked row.
+ */
+function indexUpsert(args: Record<string, unknown>): CallToolResult {
+  const rawSlug = safeExt(args, ["slug", "id"], "");
+  const rawDescription = safeExt(args, ["description", "desc", "text"], "");
+  const rawKind: string = safeExt(args, ["kind", "type"], "article");
+  const section = safeExt<string | undefined>(args, ["section", "category"], undefined);
+  const date = safeExt<string | undefined>(args, ["date", "created"], undefined);
+
+  if (!(rawKind in WIKI_INDEX_FILENAMES)) {
+    return {
+      content: [{ type: "text", text: `Unsupported kind: ${rawKind}` }],
+      isError: true,
+    };
+  }
+  const kind = rawKind as WikiIndexKind;
+
+  const slugResult = normalizeWikiSlug(rawSlug);
+  if ("error" in slugResult) {
+    return { content: [{ type: "text", text: slugResult.error }], isError: true };
+  }
+  const descriptionResult = normalizeIndexDescription(rawDescription);
+  if ("error" in descriptionResult) {
+    return { content: [{ type: "text", text: descriptionResult.error }], isError: true };
+  }
+
+  // Topic rows may point at a DB-backed brief rather than a local file.
+  if (kind !== "topic" && !wikiDocumentExists(kind, slugResult.slug)) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: `No ${kind} document named ${slugResult.slug}. Use wiki_write to create the document and its catalog row together.`,
+        },
+      ],
+      isError: true,
+    };
+  }
+
+  const link = upsertIndexRow({
+    kind,
+    slug: slugResult.slug,
+    description: descriptionResult.description,
+    date: date ?? new Date().toISOString().slice(0, 10),
+    section,
+  });
+  return { content: [{ type: "text", text: `Index updated: ${link}` }] };
+}
+
 // --- MCP Tool definitions -------------------------------------------------
 
 const WIKI_TOOLS: Tool[] = [
   {
     name: "wiki_query",
-    description: "Search the wiki knowledge base and return relevant articles.",
+    description: "Search topic, article, or summary indexes and return relevant candidates.",
     inputSchema: {
       type: "object",
       properties: {
@@ -892,10 +2022,38 @@ const WIKI_TOOLS: Tool[] = [
           type: "string",
           description: "Optional topic name to narrow the search",
         },
+        kind: {
+          type: "string",
+          enum: ["all", "topic", "article", "summary"],
+          description: "Document kind to search; defaults to all",
+        },
+        limit: {
+          type: "number",
+          minimum: 1,
+          maximum: 20,
+          description: "Maximum number of candidates; defaults to 8",
+        },
       },
       required: ["question"],
     },
   },
+  {
+    name: "wiki_read",
+    description:
+      "Read one topic, article, or summary returned by wiki_query. For a clearly matching continuing persona, set adopt=true when reading a topic.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        kind: { type: "string", enum: ["topic", "article", "summary"] },
+        key: { type: "string", description: "Canonical key returned by wiki_query" },
+        adopt: {
+          type: "boolean",
+          description: "For kind=topic, persist this canonical memory key for the current room",
+        },
+      },
+      required: ["kind", "key"],
+    },
+  },
   {
     name: "wiki_topic_brief",
     description: "Get the lightweight topic brief for a specific topic.",
@@ -931,36 +2089,49 @@ const WIKI_TOOLS: Tool[] = [
     },
   },
   {
-    name: "save_wiki_entry",
-    description: "Save a session summary directly to wiki/summaries/.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        topic: { type: "string", description: "Topic name of the session" },
-        content: { type: "string", description: "Session summary in markdown" },
-      },
-      required: ["topic", "content"],
-    },
-  },
-  {
-    name: "save_topic_brief",
+    name: "wiki_write",
     description:
-      "Write the accumulated persona/topic brief to wiki/topic/<topic>.md and mirror it into SQLite for next-session injection. Call this AFTER save_wiki_entry (archive → summary → brief order).",
+      "Write a wiki document and its catalog row together. The only way to create a summary, article, or topic brief: summaries go to wiki/summaries/ + summary-index.md, articles to wiki/articles/ + article-index.md, briefs to wiki/topic/ + topic-index.md (also mirrored into SQLite for next-session injection). Never write wiki files by any other means.",
     inputSchema: {
       type: "object",
       properties: {
-        topic: { type: "string", description: "Topic name of the session" },
-        content: {
+        kind: {
+          type: "string",
+          enum: ["summary", "article", "topic"],
+          description: "Which document to write",
+        },
+        content: { type: "string", description: "Document body in markdown" },
+        description: {
+          type: "string",
+          description: "Single-line catalog description; required so the index stays useful",
+        },
+        topic: {
+          type: "string",
+          description: "Topic name; required for kind=summary and kind=topic",
+        },
+        slug: {
+          type: "string",
+          description: "Article slug in kebab-case; required for kind=article",
+        },
+        section: {
           type: "string",
-          description: "Full accumulated topic brief in markdown (persona layer + recent work)",
+          description: "H2 catalog section; required for kind=article",
         },
+        date: { type: "string", description: "Override entry date YYYY-MM-DD (default: today)" },
       },
-      required: ["topic", "content"],
+      required: ["kind", "content", "description"],
     },
   },
+  {
+    name: "wiki_reindex",
+    description:
+      "Rebuild the derived body-search cache from the documents on disk and report catalog gaps. Run this once after adding documents outside wiki_write; retrieval itself never scans the wiki.",
+    inputSchema: { type: "object", properties: {} },
+  },
   {
     name: "index_upsert",
-    description: "Upsert an entry in wiki/article-index.md, topic-index.md, or skill-index.md.",
+    description:
+      "Correct the description or section of an entry that already exists. Cannot create an entry — use wiki_write for that.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1033,6 +2204,7 @@ export function createWikiMcpServer(context: WikiMcpContext, host: WikiMcpHost):
   const wikiDir = resolve(host.wikiRoot);
   const current: WikiRuntime = {
     userId: context.userId,
+    currentTopicId: context.currentTopicId ?? context.topicId,
     topicId: context.topicId,
     surface,
     host,
@@ -1074,12 +2246,13 @@ export function createWikiMcpServer(context: WikiMcpContext, host: WikiMcpHost):
       const { name, arguments: args } = request.params;
       const handlers: Record<string, (a: Record<string, unknown>) => CallToolResult> = {
         wiki_query: wikiQuery,
+        wiki_read: wikiRead,
         wiki_topic_brief: wikiTopicBrief,
         wiki_last_conversation: wikiLastConversation,
         skill_query: skillQuery,
         skill_save: skillSave,
-        save_wiki_entry: saveWikiEntry,
-        save_topic_brief: saveTopicBrief,
+        wiki_write: wikiWrite,
+        wiki_reindex: wikiReindex,
         index_upsert: indexUpsert,
       };
       const handler = tools.some((tool) => tool.name === name) ? handlers[name] : undefined;
@@ -1098,12 +2271,31 @@ async function main() {
   let bridge: Partial<WikiMcpHost> = {};
   if (context.topicId) {
     try {
-      const [briefs, topics] = await Promise.all([
+      const [briefs, topics, topicLifecycle] = await Promise.all([
         import("#storage/api-topic-brief"),
         import("#storage/api-topics"),
+        import("#topics/derive"),
       ]);
       bridge = {
         getTopicBrief: briefs.getTopicBrief,
+        canReadTopicMemory: (selection, userId) => {
+          const normalized = selection
+            .trim()
+            .toLowerCase()
+            .replace(/^topic\//, "")
+            .replace(/\.md$/i, "");
+          return topics.listTopics().some((topic) => {
+            if (topic.visibility === "hidden") return false;
+            if (!topic.participants.some((participant) => participant.userId === userId))
+              return false;
+            return (
+              topic.id === selection ||
+              topic.title.trim().toLowerCase() === normalized ||
+              wikiSummarySlug(topic.title).toLowerCase() === normalized ||
+              topic.memoryKey?.toLowerCase() === normalized
+            );
+          });
+        },
         resolveTopicBrief: (selection, userId) =>
           resolveAccessibleWikiTopicBrief(
             selection,
@@ -1112,6 +2304,17 @@ async function main() {
             briefs.resolveTopicBrief,
           ),
         setTopicBrief: briefs.setTopicBrief,
+        adoptTopicMemory: (topicId, userId, memoryKey) => {
+          const topic = topics.getTopic(topicId);
+          if (
+            !topic?.participants.some(
+              (participant) => participant.userId === userId && participant.role === "owner",
+            )
+          ) {
+            return false;
+          }
+          return topicLifecycle.updateTopic(topicId, { memoryKey });
+        },
       };
     } catch {
       // DB not available — degrade gracefully (file-only).