@zosmaai/pi-llm-wiki 0.5.0 → 0.6.1

package/extensions/llm-wiki/lib/recall.ts

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import type { Registry } from "./metadata.js";
+import { type VaultPaths, readJson, resolveVaultPaths } from "./utils.js";
+
+// ─── Public API ────────────────────────────────────────
+
+export interface RecallResult {
+  /** Page identifier (folder-qualified, e.g. "concepts/rag") */
+  id: string;
+  /** Page title */
+  title: string;
+  /** Page type: source, entity, concept, synthesis, analysis */
+  type: string;
+  /** First N chars of page content for context */
+  preview: string;
+  /** Relative path from wiki root */
+  path: string;
+}
+
+/**
+ * Search the wiki registry for pages matching a query.
+ * Returns up to `maxResults` matches, each with a content preview.
+ */
+export function searchWiki(paths: VaultPaths, query: string, maxResults = 5): RecallResult[] {
+  const registry = readJson<Registry>(join(paths.meta, "registry.json"), {
+    version: "1.0",
+    last_updated: "",
+    pages: {},
+  });
+
+  const q = query.toLowerCase();
+  const terms = q
+    .split(/\s+/)
+    .filter((t) => t.length > 2)
+    .slice(0, 10);
+
+  if (terms.length === 0) return [];
+
+  type Scored = { id: string; entry: Registry["pages"][string]; score: number };
+  const scored: Scored[] = [];
+
+  for (const [id, entry] of Object.entries(registry.pages)) {
+    let score = 0;
+    const title = String(entry.title || "").toLowerCase();
+    const type = String(entry.type || "").toLowerCase();
+
+    for (const term of terms) {
+      if (id.toLowerCase().includes(term)) score += 3;
+      if (title.includes(term)) score += 4;
+      if (type.includes(term)) score += 1;
+    }
+
+    // Boost if query terms appear in tags/categories
+    const tags = String(entry.tags || entry.category || entry.domain || "");
+    for (const term of terms) {
+      if (tags.toLowerCase().includes(term)) score += 2;
+    }
+
+    if (score > 0) {
+      scored.push({ id, entry, score });
+    }
+  }
+
+  scored.sort((a, b) => b.score - a.score);
+  const top = scored.slice(0, maxResults);
+
+  return top.map(({ id, entry }) => {
+    // Try to read page content for preview
+    let preview = "";
+    const pagePath = join(paths.wiki, `${id}.md`);
+    if (existsSync(pagePath)) {
+      const content = readFileSync(pagePath, "utf-8");
+      // Strip frontmatter
+      const body = content.replace(/^---[\s\S]*?---\n/, "").trim();
+      preview = body.slice(0, 200).replace(/\n/g, " ");
+    }
+
+    return {
+      id,
+      title: String(entry.title || id),
+      type: String(entry.type || "page"),
+      preview,
+      path: pagePath,
+    };
+  });
+}
+
+/**
+ * Format recall results as a compact system-prompt section.
+ */
+export function formatRecallContext(results: RecallResult[]): string {
+  if (results.length === 0) return "";
+
+  const lines: string[] = [
+    "## Relevant Wiki Knowledge",
+    "",
+    `_${results.length} page(s) matched your query — reviewed automatically by LLM Wiki._`,
+    "",
+  ];
+
+  for (const r of results) {
+    lines.push(`- **[[${r.id}]]** — *${r.type}* — ${r.title}`);
+    if (r.preview) {
+      // Truncate preview to one line
+      const preview = r.preview.length > 120 ? `${r.preview.slice(0, 120)}…` : r.preview;
+      lines.push(`  ${preview}`);
+    }
+    lines.push("");
+  }
+
+  lines.push(
+    "Use `read` to view full pages. Add new findings via wiki_ensure_page or wiki_retro.",
+    "",
+  );
+
+  return lines.join("\n");
+}
+
+// ─── Tool Registration ──────────────────────────────────
+
+/**
+ * Register the `wiki_recall` tool.
+ * The model can call this explicitly to search the wiki.
+ * It is also called automatically via before_agent_start hook.
+ */
+export function registerWikiRecall(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "wiki_recall",
+    label: "Wiki Recall",
+    description:
+      "Search the wiki for pages relevant to a query. " +
+      "Returns matching page IDs, titles, types, and content previews. " +
+      "Called automatically at session start — use explicitly to dig deeper.",
+    promptSnippet: "Recall wiki knowledge relevant to the current task",
+    promptGuidelines: [
+      "Use wiki_recall at the START of every task to find relevant wiki knowledge.",
+      "The extension auto-calls wiki_recall — but calling it explicitly with specific terms gets better results.",
+    ],
+    parameters: Type.Object({
+      query: Type.String({
+        description: "Search query — use the user's full request or key terms",
+      }),
+      max_results: Type.Optional(
+        Type.Number({ description: "Max results (default: 5, max: 10)", default: 5 }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const paths = resolveVaultPaths(process.cwd());
+
+      if (!existsSync(join(paths.dotWiki, "config.json"))) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No wiki vault found at this location. Initialize one with wiki_bootstrap first.",
+            },
+          ],
+          details: { error: "no_vault" } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      const maxResults = Math.min(params.max_results ?? 5, 10);
+      const results = searchWiki(paths, params.query, maxResults);
+
+      if (results.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No wiki pages found matching "${params.query}". Use wiki_search for broader results.`,
+            },
+          ],
+          details: { query: params.query, matches: [] } as Record<string, unknown>,
+        };
+      }
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `🧠 **${results.length} wiki page(s) relevant** to "${params.query}":`,
+              "",
+              ...results.map(
+                (r) =>
+                  `- [[${r.id}]] — *${r.type}* — ${r.title}${
+                    r.preview ? `\n  > ${r.preview.slice(0, 150)}` : ""
+                  }`,
+              ),
+              "",
+              "Use `read` on any page for full content.",
+              "Use `wiki_retro` to save new insights from this task.",
+            ].join("\n"),
+          },
+        ],
+        details: { query: params.query, matches: results.map((r) => r.id) } as Record<
+          string,
+          unknown
+        >,
+      };
+    },
+  });
+}

package/extensions/llm-wiki/lib/retro.ts

@@ -0,0 +1,196 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "typebox";
+import { appendEvent, rebuildMetadataLight } from "./metadata.js";
+import { type VaultPaths, fmtDate, nextSourceId, resolveVaultPaths } from "./utils.js";
+
+// ─── Public API ────────────────────────────────────────
+
+export interface RetroResult {
+  sourceId: string;
+  packetPath: string;
+  sourcePagePath: string;
+}
+
+/**
+ * Save an atomic insight into the wiki as a source packet + source page.
+ * Returns the source ID, packet path, and source page path.
+ */
+export function saveInsight(
+  paths: VaultPaths,
+  slug: string,
+  title: string,
+  body: string,
+  category?: string,
+): RetroResult {
+  const sourceId = nextSourceId(paths);
+  const packetPath = join(paths.rawSources, sourceId);
+  mkdirSync(packetPath, { recursive: true });
+  mkdirSync(join(packetPath, "attachments"), { recursive: true });
+
+  const today = fmtDate();
+
+  // Write manifest
+  const manifest = {
+    id: sourceId,
+    title,
+    slug,
+    category: category || "uncategorized",
+    captured: today,
+    format: "insight",
+    packet_version: "1.0",
+  };
+  writeFileSync(
+    join(packetPath, "manifest.json"),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    "utf-8",
+  );
+
+  // Write extracted text (the insight body in markdown)
+  const extracted = [
+    `# ${title}`,
+    "",
+    body,
+    "",
+    "---",
+    `*Captured: ${today}*`,
+    category ? `*Category: ${category}*` : "",
+  ]
+    .filter(Boolean)
+    .join("\n");
+  writeFileSync(join(packetPath, "extracted.md"), extracted, "utf-8");
+
+  // Create source page
+  const sourcePageDir = join(paths.wiki, "sources");
+  mkdirSync(sourcePageDir, { recursive: true });
+  const sourcePagePath = join(sourcePageDir, `${sourceId}.md`);
+
+  const tagLine = category ? `category: ${category}` : "";
+  const sourcePageContent = [
+    "---",
+    "type: source",
+    `title: "${title}"`,
+    `source_id: ${sourceId}`,
+    "status: insight",
+    `created: ${today}`,
+    `updated: ${today}`,
+    tagLine,
+    "---",
+    "",
+    `# ${title}`,
+    "",
+    body,
+    "",
+    "## Source",
+    "",
+    `- **Packet:** \`${packetPath}\``,
+    `- **Captured:** ${today}`,
+    category ? `- **Category:** ${category}` : "",
+    "",
+    "## Related",
+    "",
+    "_(Add [[wikilinks]] to related pages)_",
+    "",
+  ]
+    .filter((l) => l !== "")
+    .join("\n");
+  writeFileSync(sourcePagePath, sourcePageContent, "utf-8");
+
+  // Log event
+  appendEvent(paths, {
+    kind: "retro",
+    source_id: sourceId,
+    title,
+    slug,
+    category: category || "uncategorized",
+  });
+
+  // Rebuild metadata
+  rebuildMetadataLight(paths);
+
+  return { sourceId, packetPath, sourcePagePath };
+}
+
+// ─── Tool Registration ──────────────────────────────────
+
+/**
+ * Register the `wiki_retro` tool.
+ * The model calls this to save an atomic insight from a completed task.
+ * Inspired by the memex_retro pattern.
+ */
+export function registerWikiRetro(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "wiki_retro",
+    label: "Wiki Retro",
+    description:
+      "Save an atomic insight from a completed task into the wiki. " +
+      "Creates a source packet and source page. The insight will be " +
+      "surfaced automatically by wiki_recall in future sessions.",
+    promptSnippet: "Save atomic insights from completed tasks into the wiki",
+    promptGuidelines: [
+      "Use wiki_retro at the END of every meaningful task to save what you learned.",
+      "Write atomic insights — one insight per call. Use multiple calls for multiple insights.",
+      "The insight will be auto-surfaced by wiki_recall in future sessions.",
+    ],
+    parameters: Type.Object({
+      slug: Type.String({
+        description:
+          "Unique kebab-case identifier (e.g. 'jwt-revocation-pattern'). Used for lookups.",
+      }),
+      title: Type.String({
+        description: "Short descriptive title (60 chars max). Noun phrase, not a sentence.",
+      }),
+      body: Type.String({
+        description:
+          "Markdown body with [[wikilinks]] to related wiki pages. Explain what was learned.",
+      }),
+      category: Type.Optional(
+        Type.String({
+          description: "Optional category (e.g. frontend, architecture, devops, bugfix, design)",
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const paths = resolveVaultPaths(process.cwd());
+
+      if (!existsSync(join(paths.dotWiki, "config.json"))) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: "No wiki vault found at this location. Initialize one with wiki_bootstrap first.",
+            },
+          ],
+          details: { error: "no_vault" } as Record<string, unknown>,
+          isError: true,
+        };
+      }
+
+      const result = saveInsight(paths, params.slug, params.title, params.body, params.category);
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              `🧠 **Insight saved**: ${params.title}`,
+              "",
+              `- Source: \`${result.sourceId}\``,
+              `- Packet: \`${result.packetPath}\``,
+              `- Page: \`${result.sourcePagePath}\``,
+              "",
+              "This insight will be auto-surfaced by wiki_recall in future sessions.",
+            ].join("\n"),
+          },
+        ],
+        details: {
+          sourceId: result.sourceId,
+          slug: params.slug,
+          title: params.title,
+          category: params.category || null,
+        } as Record<string, unknown>,
+      };
+    },
+  });
+}

package/extensions/llm-wiki/lib/tools.ts

@@ -13,13 +13,14 @@ import {
 import { captureFile, captureText, captureUrl } from "./source-packet.js";
 import {
   type VaultPaths,
+  detectVaultFormat,
   ensureVaultStructure,
   extractWikilinks,
   findWikiPages,
   fmtDate,
   getVaultPaths,
   readJson,
-  resolveVaultRoot,
+  resolveVaultPaths,
   writeJson,
 } from "./utils.js";
 
@@ -28,12 +29,11 @@ import {
  */
 
 function getPaths(cwd = process.cwd()): VaultPaths {
-  const root = resolveVaultRoot(cwd);
-  return getVaultPaths(root);
+  return resolveVaultPaths(cwd);
 }
 
 function requireVault(paths: VaultPaths): { ok: true } | { ok: false; reason: string } {
-  if (!existsSync(join(paths.root, ".wiki", "config.json"))) {
+  if (detectVaultFormat(paths.root) === "none") {
     return { ok: false, reason: `No wiki found at ${paths.root}. Run wiki_bootstrap first.` };
   }
   return { ok: true };
@@ -83,7 +83,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
         "| raw/** | extension | immutable after capture |",
         "| wiki/** | model + user | editable knowledge pages |",
         "| meta/* | extension | auto-generated |",
-        "| .wiki/* | human + explicit request | operating rules |",
+        "| . | human + explicit request | operating rules |",
         "",
         "## Source Packet Format",
         "",
@@ -109,7 +109,7 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
         "- Citation: [[sources/SRC-YYYY-MM-DD-NNN]]",
         "",
       ].join("\n");
-      writeFileSync(join(paths.root, "WIKI_SCHEMA.md"), schema, "utf-8");
+      writeFileSync(join(paths.dotWiki, "WIKI_SCHEMA.md"), schema, "utf-8");
 
       rebuildMetadata(paths);
       appendEvent(paths, { kind: "bootstrap", topic: params.topic, mode });
@@ -122,10 +122,11 @@ export function registerWikiBootstrap(pi: ExtensionAPI): void {
               `✅ Wiki bootstrapped at \`${paths.root}\``,
               "",
               "**Structure:**",
-              "- raw/sources/ — immutable source packets",
-              "- wiki/ — editable knowledge pages",
-              "- meta/ — auto-generated metadata",
-              "- .wiki/ — config and templates",
+              "- .llm-wiki/raw/sources/ — immutable source packets",
+              "- .llm-wiki/wiki/ — editable knowledge pages",
+              "- .llm-wiki/meta/ — auto-generated metadata",
+              "- .llm-wiki/ — config and templates",
+              "- .llm-wiki/WIKI_SCHEMA.md — operating rules",
               "",
               "Next: Use wiki_capture_source to add your first source.",
             ].join("\n"),

package/extensions/llm-wiki/lib/utils.ts

@@ -17,24 +17,53 @@ export interface VaultPaths {
   discoveries: string;
 }
 
+/** Detect whether a vault root uses new (.llm-wiki) or legacy (.wiki) layout. */
+export type VaultFormat = "new" | "legacy" | "none";
+
+/**
+ * Detect the vault format at a given directory.
+ * Returns "new" if .llm-wiki/config.json exists,
+ * "legacy" if .wiki/config.json exists,
+ * "none" otherwise.
+ */
+export function detectVaultFormat(dir: string): VaultFormat {
+  if (existsSync(join(dir, ".llm-wiki", "config.json"))) return "new";
+  if (existsSync(join(dir, ".wiki", "config.json"))) return "legacy";
+  return "none";
+}
+
 /** Resolve vault root from cwd or find nearest wiki root. */
 export function resolveVaultRoot(cwd: string): string {
-  // If cwd has .wiki/config.json, it's the root
-  if (existsSync(join(cwd, ".wiki", "config.json"))) return cwd;
+  // Check for any vault format at cwd
+  if (detectVaultFormat(cwd) !== "none") return cwd;
 
-  // Walk up looking for .wiki/config.json
+  // Walk up looking for a vault sentinel (new or legacy)
   let dir = cwd;
   while (dir !== dirname(dir)) {
-    if (existsSync(join(dir, ".wiki", "config.json"))) return dir;
     dir = dirname(dir);
+    if (detectVaultFormat(dir) !== "none") return dir;
   }
 
   // Fallback: cwd itself
   return cwd;
 }
 
-/** Get all vault paths. */
+/** Get all vault paths for the new (.llm-wiki) layout. */
 export function getVaultPaths(root: string): VaultPaths {
+  return {
+    root,
+    raw: join(root, ".llm-wiki", "raw"),
+    rawSources: join(root, ".llm-wiki", "raw", "sources"),
+    wiki: join(root, ".llm-wiki", "wiki"),
+    meta: join(root, ".llm-wiki", "meta"),
+    dotWiki: join(root, ".llm-wiki"),
+    outputs: join(root, ".llm-wiki", "outputs"),
+    discoveries: join(root, ".llm-wiki", ".discoveries"),
+  };
+}
+
+/** Get all vault paths for the legacy (.wiki) layout. */
+export function getLegacyVaultPaths(root: string): VaultPaths {
   return {
     root,
     raw: join(root, "raw"),
@@ -47,6 +76,17 @@ export function getVaultPaths(root: string): VaultPaths {
   };
 }
 
+/**
+ * Resolve vault paths, auto-detecting new vs legacy layout.
+ * This is the main entry point: use this instead of resolveVaultRoot + getVaultPaths.
+ */
+export function resolveVaultPaths(cwd: string): VaultPaths {
+  const root = resolveVaultRoot(cwd);
+  const format = detectVaultFormat(root);
+  if (format === "legacy") return getLegacyVaultPaths(root);
+  return getVaultPaths(root);
+}
+
 /** Ensure all vault directories exist. */
 export function ensureVaultStructure(paths: VaultPaths): void {
   const dirs = [
@@ -199,10 +239,10 @@ export async function exec(
 /** Check if a path is inside a protected directory. */
 export function isProtectedPath(
   absPath: string,
-  root: string,
+  paths: VaultPaths,
 ): { protected: boolean; reason?: string } {
-  const rawPath = resolve(root, "raw");
-  const metaPath = resolve(root, "meta");
+  const rawPath = resolve(paths.raw);
+  const metaPath = resolve(paths.meta);
   const norm = resolve(absPath);
 
   if (norm.startsWith(`${rawPath}/`) || norm === rawPath) {