@sdsrs/llm-wiki 0.8.1 → 0.8.3

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.8.3 (2026-07-12)
+
+Performance and test-hardening cleanup; no shipped behavior change. Suite 261 → 263.
+
+**Changed:**
+
+- **Retrieval parses the wiki page set once per query, not up to three times.** The
+  BM25 build, the vector-hit valid set, and the index-listing fallback's id set now
+  share one page cache keyed by the same mtime + size freshness token as the BM25
+  index (added in 0.8.2), so any add / edit / removal / invalidation still busts it
+  and retired knowledge can never resurface. On a long-lived MCP server a vector
+  (`auto`/`hybrid`) query drops its second full page parse; `locatePages` also reads
+  `wiki.config.json` once instead of twice.
+- **The `mcp` command loads the MCP SDK + zod lazily.** They were imported at CLI
+  startup for every command; only `mcp` needs them. `scan` / `convert` / `ask` /
+  `init` and friends now skip ~200–250 ms of import cost.
+
+**Internal (not shipped in the npm package):**
+
+- Atomic-write regression guards: `saveManifest`, `saveVectorStore`, and the `scan`
+  plan write now assert the temp + rename path via a `fs.renameSync` spy — the old
+  `.tmp`-absence check alone also passed for a direct truncating write (mem #10097).
+- The full eval report (`scripts/eval/run-all.mjs`) judges the shipped default
+  retrieval mode: answer-level head-to-head now defaults to `bm25,auto` (was the
+  hardcoded `bm25,hybrid`) and takes an `--answer-arms` flag.
+
+## 0.8.2 (2026-07-12)
+
+Performance, no behavior change. Suite 260 → 261.
+
+**Changed:**
+
+- **Retrieval no longer rebuilds the BM25 index from disk on every query.** The
+  index is cached per KB and reused while the wiki pages and `bm25TitleWeight` are
+  unchanged; a cheap freshness token (each live page's mtime + size) rebuilds it on
+  any page add / edit / removal / invalidation or config change, so results are
+  never stale. A one-shot CLI call is unaffected (it built the index once anyway);
+  a long-lived MCP server drops per-`wiki_search` cost (~9× on the dogfood KB:
+  9.4 ms → 1.0 ms/query). Cache is bounded (last 8 KBs).
+
 ## 0.8.1 (2026-07-12)
 
 Audit-driven remediation batch (see the v0.8.0 audit report): test-gate

package/bin/llm-wiki.mjs

@@ -14,7 +14,6 @@ import { statusKb } from '../src/status.mjs'
 import { connectProject, installSkills } from '../src/connect.mjs'
 import { exportGraph, loadGraph, exportMarkdownPages } from '../src/export.mjs'
 import { shortestPath, neighborhood, hubs } from '../src/graph.mjs'
-import { runMcpServer } from '../src/mcp.mjs'
 
 const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 
@@ -203,6 +202,9 @@ program.command('mcp')
   .description('run a read-only MCP server (stdio) over the knowledge base')
   .option('--kb <dir>', 'knowledge base root', '.')
   .action(async (opts) => {
+    // Lazy import: mcp.mjs pulls in the MCP SDK + zod, which no other command needs.
+    // Static-importing it would load them on every scan/convert/ask invocation.
+    const { runMcpServer } = await import('../src/mcp.mjs')
     // stdout belongs to the MCP transport from here on — no console.log.
     await runMcpServer(opts.kb)
   })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdsrs/llm-wiki",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Compile messy document directories into Karpathy-style llm_wiki knowledge bases — standalone Q&A CLI + Claude Code/Codex skills",
   "directories": {
     "test": "test"

package/src/ask.mjs

@@ -2,7 +2,7 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { kbPaths } from './paths.mjs'
 import { loadKbConfig } from './templates.mjs'
-import { listWikiPages, isInvalidated, asList } from './pages.mjs'
+import { listWikiPages, isInvalidated, asList, PAGE_DIRS } from './pages.mjs'
 import { buildBm25Index, searchBm25 } from './bm25.mjs'
 import { worstCaseTokens } from './scanner.mjs'
 import { loadLlmConfig, makeTransport } from './llm-config.mjs'
@@ -10,6 +10,52 @@ import { loadVectorStore, normalize, cosineTopK } from './vector.mjs'
 import { embedTexts } from './embed.mjs'
 import { fetchWithRetry } from './retry.mjs'
 
+// Two per-KB caches, both keyed by a cheap page-set freshness token so neither can
+// serve a stale view. The token is each live page file's mtime+size: any page
+// add / remove / in-place edit / invalidation (a frontmatter status change IS a
+// content change) flips it and forces a rebuild. Statting the page set is far cheaper
+// than reading + parsing it; MCP is read-only and never mutates pages while serving, so
+// within one server's lifetime pages change only via a separate build process (which
+// rewrites files with new mtimes). Both caches are bounded so a process serving many
+// KBs can't grow them without limit.
+const bm25Cache = new Map()   // kbRoot -> { token: `${pagesToken}|w=${w}`, idx }
+const pagesCache = new Map()  // kbRoot -> { token: pagesToken, pages }
+const CACHE_MAX = 8
+
+function pagesToken(kbRoot) {
+  const wiki = kbPaths(kbRoot).wiki
+  const parts = []
+  for (const dir of PAGE_DIRS) {
+    let entries
+    try { entries = fs.readdirSync(path.join(wiki, dir)) } catch { continue }
+    for (const f of entries.sort()) {
+      if (!f.endsWith('.md')) continue
+      try {
+        const st = fs.statSync(path.join(wiki, dir, f))
+        parts.push(`${dir}/${f}:${st.mtimeMs}:${st.size}`)
+      } catch { /* vanished mid-scan: next call rebuilds */ }
+    }
+  }
+  return parts.join('|')
+}
+
+// The parsed, filtered live-page list — the dominant per-query cost (listWikiPages
+// reads + frontmatter-parses every page), shared by the BM25 build, the vector-hit
+// valid set, and the listing fallback's validIds. Excluding invalidated pages here is
+// the query-time exclusion every consumer needs, done once. Callers on the same query
+// pass the token already computed for the BM25 cache; standalone callers let it default.
+function livePages(kbRoot, token = pagesToken(kbRoot)) {
+  let entry = pagesCache.get(kbRoot)
+  if (!entry || entry.token !== token) {
+    const pages = listWikiPages(kbRoot).filter(p => !p.error && !isInvalidated(p))
+    pagesCache.delete(kbRoot) // re-insert so this KB becomes most-recent for LRU eviction
+    pagesCache.set(kbRoot, { token, pages })
+    while (pagesCache.size > CACHE_MAX) pagesCache.delete(pagesCache.keys().next().value)
+    entry = pagesCache.get(kbRoot)
+  }
+  return entry.pages
+}
+
 export function retrievePages(kbRoot, question, k = 6) {
   // Title is a field: repeat it bm25TitleWeight times in the indexed text so a
   // title term outweighs the same term buried in the body (measured +0.04 Recall@5
@@ -18,12 +64,20 @@ export function retrievePages(kbRoot, question, k = 6) {
   // loadKbConfig guarantees a finite integer >= 1; cap the upper bound so a large
   // value can't materialize a giant per-page array (Array(w).fill) and OOM retrieval.
   const w = Math.min(25, loadKbConfig(kbRoot).bm25TitleWeight)
-  const pages = listWikiPages(kbRoot).filter(p => !p.error && !isInvalidated(p))
-  const idx = buildBm25Index(pages.map(p => ({
-    id: p.relPath,
-    text: [Array(w).fill(p.data.title ?? '').join('\n'), p.data.description, asList(p.data.tags).join(' '), p.body].join('\n'),
-  })))
-  return searchBm25(idx, question, k).map(h => ({ relPath: h.id, score: h.score }))
+  const token = pagesToken(kbRoot)
+  const bmKey = `${token}|w=${w}` // title weight changes the indexed text but not the page list
+  let entry = bm25Cache.get(kbRoot)
+  if (!entry || entry.token !== bmKey) {
+    const idx = buildBm25Index(livePages(kbRoot, token).map(p => ({
+      id: p.relPath,
+      text: [Array(w).fill(p.data.title ?? '').join('\n'), p.data.description, asList(p.data.tags).join(' '), p.body].join('\n'),
+    })))
+    bm25Cache.delete(kbRoot) // re-insert so this KB becomes most-recent for LRU eviction
+    bm25Cache.set(kbRoot, { token: bmKey, idx })
+    while (bm25Cache.size > CACHE_MAX) bm25Cache.delete(bm25Cache.keys().next().value)
+    entry = bm25Cache.get(kbRoot)
+  }
+  return searchBm25(entry.idx, question, k).map(h => ({ relPath: h.id, score: h.score }))
 }
 
 const RRF_K = 60
@@ -81,7 +135,9 @@ export async function locatePages(kbRoot, question, { k = 6, fetchImpl, retrieva
     if (retrieval === 'hybrid') throw new Error(`retrieval 'hybrid' unavailable: ${what}`)
     return asBm25()
   }
-  if (retrieval === 'auto' && !loadKbConfig(kbRoot).vectorEnabled) return asBm25()
+  // One config read for both the vectorEnabled gate and the lexicalGuard flag below.
+  const kbCfg = loadKbConfig(kbRoot)
+  if (retrieval === 'auto' && !kbCfg.vectorEnabled) return asBm25()
   const store = loadVectorStore(kbRoot)
   if (!store) return unavailable('no wiki/.vectors.json — run `llm-wiki embed` first')
   const cfg = loadLlmConfig(kbRoot)
@@ -98,10 +154,10 @@ export async function locatePages(kbRoot, question, { k = 6, fetchImpl, retrieva
     // renamed since then still have vectors. Keep only hits that map to a live,
     // non-invalidated page so retired knowledge cannot resurface (and askKb never
     // ENOENTs reading a vanished file).
-    const valid = new Set(listWikiPages(kbRoot).filter(pg => !pg.error && !isInvalidated(pg)).map(pg => pg.relPath))
+    const valid = new Set(livePages(kbRoot).map(pg => pg.relPath))
     const vecHitsValid = vecHits.filter(h => valid.has(h.relPath))
     const { hits, guardApplied } = fuseChannels({ bm25, vector: vecHitsValid }, k,
-      { lexicalGuard: retrieval === 'auto' && loadKbConfig(kbRoot).lexicalGuard })
+      { lexicalGuard: retrieval === 'auto' && kbCfg.lexicalGuard })
     return { hits, usedVector: true, guardApplied }
   } catch (err) {
     if (retrieval === 'hybrid') throw err
@@ -176,9 +232,7 @@ export async function askKb(kbRoot, question, { k = 6, retrieveOnly = false, fet
   if (retrieveOnly) return { pages: hits, answer: null }
   let validIds
   if (hits.length === 0) {
-    validIds = new Set(listWikiPages(kbRoot)
-      .filter(pg => !pg.error && !isInvalidated(pg))
-      .map(pg => pg.relPath.replace(/\.md$/, '')))
+    validIds = new Set(livePages(kbRoot).map(pg => pg.relPath.replace(/\.md$/, '')))
     if (validIds.size === 0) throw new Error('No relevant pages found — the knowledge base has no valid pages.')
   }
   const cfg = loadLlmConfig(kbRoot)

package/src/pages.mjs

@@ -3,7 +3,7 @@ import path from 'node:path'
 import { kbPaths } from './paths.mjs'
 import { parseFrontmatter } from './frontmatter.mjs'
 
-const PAGE_DIRS = ['sources', 'entities', 'concepts', 'comparisons']
+export const PAGE_DIRS = ['sources', 'entities', 'concepts', 'comparisons']
 const REQUIRED = ['type', 'title', 'description', 'tags', 'created', 'updated']
 
 export const PAGE_STATUSES = ['active', 'invalidated']