@yolk_vat-y/dsh-project-memory 0.1.3

package/src/symbols.js

@@ -0,0 +1,101 @@
+import { readFileSync } from 'node:fs'
+
+const JS_LIKE = new Set(['.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx'])
+const PYTHON = new Set(['.py'])
+const GO = new Set(['.go'])
+const RUST = new Set(['.rs'])
+const C_FAMILY = new Set(['.c', '.cpp', '.cc', '.h', '.hpp', '.cs', '.java'])
+const SHELL = new Set(['.sh', '.zsh'])
+
+const CONTROL = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'foreach', 'using', 'lock', 'var', 'function'])
+
+function matchJsLike(line) {
+  let m = line.match(/^export\s+(?:default\s+)?(?:async\s+)?(?:function\s+([A-Za-z_$][\w$]*)|class\s+([A-Za-z_$][\w$]*))/)
+  if (m) return { name: m[1] || m[2], kind: m[1] ? 'function' : 'class' }
+  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/)
+  if (m) return { name: m[1], kind: 'function' }
+  m = line.match(/^(?:export\s+)?class\s+([A-Za-z_$][\w$]*)/)
+  if (m) return { name: m[1], kind: 'class' }
+  m = line.match(/^(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\(/)
+  if (m) return { name: m[1], kind: 'function' }
+  m = line.match(/^(?:export\s+)?(?:async\s+)?function\s*\(/) // anonymous
+  if (m) return { name: '(anonymous)', kind: 'function' }
+  return null
+}
+
+function matchPython(line) {
+  let m = line.match(/^class\s+(\w+)\s*(?:\(|:)/)
+  if (m) return { name: m[1], kind: 'class' }
+  m = line.match(/^def\s+(\w+)\s*\(/)
+  if (m) return { name: m[1], kind: 'function' }
+  m = line.match(/^async\s+def\s+(\w+)\s*\(/)
+  if (m) return { name: m[1], kind: 'function' }
+  return null
+}
+
+function matchGo(line) {
+  let m = line.match(/^func\s+\([^)]*\)\s+(\w+)\s*\(/)
+  if (m) return { name: m[1], kind: 'method' }
+  m = line.match(/^func\s+(\w+)\s*\(/)
+  if (m) return { name: m[1], kind: 'function' }
+  m = line.match(/^type\s+(\w+)\s+(?:struct|interface)\b/)
+  if (m) return { name: m[1], kind: 'type' }
+  return null
+}
+
+function matchRust(line) {
+  let m = line.match(/^(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+([A-Za-z_]\w*)\s*\(/)
+  if (m) return { name: m[1], kind: 'function' }
+  m = line.match(/^(?:pub\s+)?(?:struct|enum|trait|impl)\s+(\w+)/)
+  if (m) return { name: m[1], kind: line.includes('impl') ? 'impl' : 'type' }
+  return null
+}
+
+function matchCFamily(line) {
+  const type = line.match(/^(?:public|private|protected|internal|static|abstract|sealed|partial|\s)*\b(?:class|interface|struct|enum|record)\s+(\w+)/)
+  if (type) return { name: type[1], kind: 'class' }
+  const fn = line.match(
+    /^(?:public|private|protected|internal|static|abstract|virtual|override|sealed|async|unsafe|extern|readonly|ref|partial|\s)*(\b[A-Za-z_]\w*(?:<[^<>]*>)?(?:\s*\[\s*\])?|\([^(){};]*\))\s+([A-Za-z_]\w*)\s*\([^(){};]*\)\s*(?:where\s+[^{;]*?)?\s*(?:;|\{)?\s*$/,
+  )
+  if (fn && !CONTROL.has(fn[1])) return { name: fn[2], kind: 'function' }
+  return null
+}
+
+function matchShell(line) {
+  const m = line.match(/^([A-Za-z_]\w*)\s*\(\s*\)/)
+  return m ? { name: m[1], kind: 'function' } : null
+}
+
+export function scanSymbols(filePath, content) {
+  const ext = filePath.slice(filePath.lastIndexOf('.'))
+  const symbols = []
+  const lines = content.split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i]
+    const line = raw.replace(/\/\/.*$/, '').replace(/#.*$/, '').trim()
+    if (!line) continue
+    let matched = null
+    if (JS_LIKE.has(ext)) matched = matchJsLike(line)
+    else if (PYTHON.has(ext)) matched = matchPython(line)
+    else if (GO.has(ext)) matched = matchGo(line)
+    else if (RUST.has(ext)) matched = matchRust(line)
+    else if (C_FAMILY.has(ext)) matched = matchCFamily(line)
+    else if (SHELL.has(ext)) matched = matchShell(line)
+    else if (/^(?:def|func|fn|function)\s+(\w+)/.test(line)) {
+      matched = { name: line.match(/^(?:def|func|fn|function)\s+(\w+)/)[1], kind: 'function' }
+    }
+    if (matched) {
+      symbols.push({
+        id: `${String(filePath).replace(/[\\/:\s]/g, '_')}#${i + 1}`,
+        sourcePath: filePath,
+        sourceLine: i + 1,
+        type: 'symbol',
+        title: `${matched.name} (${matched.kind})`,
+        summary: `${matched.kind} "${matched.name}" declared at ${filePath}:${i + 1}`,
+        keywords: [matched.name, matched.kind],
+        text: raw.trim().slice(0, 200),
+      })
+    }
+  }
+  return symbols
+}

package/src/tools/forget.js

@@ -0,0 +1,36 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { ProjectMemoryStore, withStoreLock } from '../store.js'
+
+export function forgetTool(config) {
+  return defineTool({
+    name: 'forget',
+    description:
+      'Delete experience notes from project memory by id or by matching keywords. Use to clean stale/obsolete notes.',
+    parameters: {
+      id_or_query: {
+        type: 'string',
+        required: true,
+        description: 'Experience note id (from remember/search output), or keywords to match.',
+      },
+      root: {
+        type: 'string',
+        description: 'Project root of the memory store. Defaults to the current working directory.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const memoryDir = memoryRootFor(root, config.memoryDir)
+      return withStoreLock(memoryDir, () => {
+        const store = new ProjectMemoryStore(memoryDir).load()
+        const removed = store.removeExperience(args.id_or_query)
+        store.save()
+        return removed > 0 ? `Removed ${removed} experience note(s).` : 'No matching experience note found.'
+      })
+    },
+  })
+}

package/src/tools/index-doc.js

@@ -0,0 +1,70 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { assertReadableFile, memoryRootFor, sha256OfFile, storeKey } from '../util/fs.js'
+import { buildDocEntries } from '../doc-pipeline.js'
+import { linkEntries } from '../link.js'
+import { ProjectMemoryStore, withStoreLock } from '../store.js'
+import { findProjectRoot } from '../lazy.js'
+
+export function indexDocTool(ctx, config) {
+  return defineTool({
+    name: 'index_doc',
+    description:
+      'Index a project document (PDF, Markdown, txt) into persistent project memory: split into sections, ' +
+      'summarize each with the LLM, and store cited summaries (path + line) for later query_memory recall. ' +
+      'Re-indexing the same unchanged file is a no-op (content-hash skip).',
+    parameters: {
+      file_path: {
+        type: 'string',
+        required: true,
+        description: 'Absolute path to the document to index.',
+      },
+      root: {
+        type: 'string',
+        description: 'Project root where the .dsh-project-memory store lives. Defaults to the file\'s directory.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) {
+      const filePath = assertReadableFile(args.file_path, config.maxFileSizeMb)
+      const root = path.resolve(args.root && args.root.trim() ? args.root : findProjectRoot(filePath))
+      const memoryDir = memoryRootFor(root, config.memoryDir)
+
+      return withStoreLock(memoryDir, async () => {
+        const store = new ProjectMemoryStore(memoryDir).load()
+
+        const rel = storeKey(path.relative(root, filePath).split(path.sep).join('/'))
+        const { hash, size } = await sha256OfFile(filePath)
+        const existing = store.fileRecord(rel)
+        if (existing && existing.sha256 === hash) {
+          return `Skipped (unchanged): ${rel}\nAlready indexed with ${(store.entries[rel] || []).length} entry/entries.`
+        }
+
+        const entries = await buildDocEntries(ctx.llm, filePath, {
+          chunkChars: config.chunkChars,
+          maxChunks: config.maxChunksPerFile,
+          maxFileSizeMb: config.maxFileSizeMb,
+          maxPdfPages: config.maxPdfPages,
+        })
+        if (entries === null) {
+          store.removeFile(rel)
+          store.save()
+          return `Skipped: ${rel} looks like a reflection dump, not a document.`
+        }
+        store.setEntries(rel, entries)
+        store.markFile(rel, { sha256: hash, size, type: 'doc', indexedAt: new Date().toISOString() })
+        store.save()
+        const links = linkEntries(store)
+        if (links) store.save()
+
+        const preview = entries
+          .map((e) => `  - ${e.title} @ ${rel}:${e.sourceLine}`)
+          .join('\n')
+        return `Indexed: ${rel}\nEntries: ${entries.length}\n${preview}`
+      })
+    },
+  })
+}

package/src/tools/index-repo.js

@@ -0,0 +1,127 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { readFileSync, statSync } from 'node:fs'
+import { isSupportedCode, isSupportedDoc, looksLikeDump, memoryRootFor, relativePath, sha256OfFile, storeKey, walkDir } from '../util/fs.js'
+import { buildDocEntries } from '../doc-pipeline.js'
+import { scanSymbols } from '../symbols.js'
+import { linkEntries } from '../link.js'
+import { ProjectMemoryStore, withStoreLock } from '../store.js'
+
+export async function indexRepository(ctx, config, root, { reindex = false } = {}) {
+  return withStoreLock(memoryRootFor(root, config.memoryDir), async () => {
+    const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+
+    const files = walkDir(root)
+    const seen = new Set()
+    let indexed = 0
+    let updated = 0
+    let skipped = 0
+    let removed = 0
+    const failures = []
+
+    for (const filePath of files) {
+      const rel = storeKey(relativePath(root, filePath))
+      seen.add(rel)
+      const ext = path.extname(filePath).toLowerCase()
+      if (!isSupportedDoc(ext) && !isSupportedCode(ext)) continue
+
+      try {
+        const size = statSync(filePath).size
+        if (isSupportedCode(ext) && config.maxFileSizeMb && size > config.maxFileSizeMb * 1024 * 1024) {
+          store.removeFile(rel)
+          skipped++
+          continue
+        }
+
+        const existing = store.fileRecord(rel)
+        const { hash } = await sha256OfFile(filePath)
+        if (!reindex && existing && existing.sha256 === hash) {
+          skipped++
+          continue
+        }
+
+        let entries
+        if (isSupportedCode(ext)) {
+          const content = readFileSync(filePath, 'utf8')
+          entries = scanSymbols(filePath, content)
+          store.markFile(rel, { sha256: hash, size, type: 'code', indexedAt: new Date().toISOString() })
+          updated++
+        } else {
+          const content = readFileSync(filePath, 'utf8')
+          if (looksLikeDump(content)) {
+            store.removeFile(rel)
+            skipped++
+            continue
+          }
+          entries = await buildDocEntries(ctx.llm, filePath, {
+            chunkChars: config.chunkChars,
+            maxChunks: config.maxChunksPerFile,
+            maxFileSizeMb: config.maxFileSizeMb,
+            maxPdfPages: config.maxPdfPages,
+          })
+          if (entries === null) {
+            store.removeFile(rel)
+            skipped++
+            continue
+          }
+          store.markFile(rel, { sha256: hash, size, type: 'doc', indexedAt: new Date().toISOString() })
+          indexed++
+        }
+        store.setEntries(rel, entries)
+      } catch (err) {
+        store.removeFile(rel)
+        failures.push(rel)
+      }
+    }
+
+    for (const rel of Object.keys(store.files)) {
+      if (!seen.has(rel)) {
+        store.removeFile(rel)
+        removed++
+      }
+    }
+
+    store.save()
+    const links = linkEntries(store)
+    if (links) store.save()
+    const stats = store.stats()
+    let report =
+      `Indexed project: ${root}\n` +
+      `docs indexed: ${indexed}, code symbols updated: ${updated}, unchanged skipped: ${skipped}, removed: ${removed}\n` +
+      `memory store: ${stats.files} files, ${stats.entries} entries, ${stats.experience} experience notes` +
+      (links ? `, ${links} doc<->symbol links` : '')
+    if (failures.length) {
+      report += `\nfailed to index ${failures.length} file(s): ${failures.join(', ')}`
+    }
+    return report
+  })
+}
+
+export function indexRepoTool(ctx, config) {
+  return defineTool({
+    name: 'index_repo',
+    description:
+      'Index a whole project into persistent memory. Documents (PDF/Markdown/txt) are summarized by the LLM; ' +
+      'code files get a zero-token symbol table (function/class names with line numbers). Incremental: only changed ' +
+      'files are re-extracted (content-hash), deleted files are removed from memory. Call once per project, then query_memory.',
+    parameters: {
+      root: {
+        type: 'string',
+        required: true,
+        description: 'Absolute path to the project root to index.',
+      },
+      reindex: {
+        type: 'boolean',
+        description: 'Force full re-index, ignoring content-hash skips. Default false.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) {
+      const root = path.resolve(args.root)
+      return indexRepository(ctx, config, root, { reindex: Boolean(args.reindex) })
+    },
+  })
+}

package/src/tools/query-memory.js

@@ -0,0 +1,95 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { ProjectMemoryStore } from '../store.js'
+import { expandQuery } from '../llm.js'
+import { rankEntriesMergedScored, rankExperienceScored } from '../util/search.js'
+import { truncate } from '../util/text.js'
+
+export function queryMemoryTool(ctx, config) {
+  return defineTool({
+    name: 'query_memory',
+    description:
+      'Search persistent project memory: doc summaries and code symbol tables (indexed via index_doc/index_repo) ' +
+      'plus experience notes (problem -> solution, saved via remember). Every hit returns its source path and line so ' +
+      'you can verify by reading the real file. Docs are cross-linked to the code symbols they mention. ' +
+      'Use BEFORE grepping when you need orientation, a spec constraint, or a past decision.',
+    parameters: {
+      query: {
+        type: 'string',
+        required: true,
+        description: 'What to look for, e.g. "payment module fees", "who handles refunds", "spec constraint on timeouts".',
+      },
+      root: {
+        type: 'string',
+        description: 'Project root of the memory store to search. Defaults to the current working directory.',
+      },
+      type: {
+        type: 'string',
+        enum: ['all', 'doc', 'symbol', 'experience'],
+        description: 'Which memory layer to search. Default "all".',
+      },
+      limit: {
+        type: 'number',
+        description: 'Max results to return. Default 8.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const store = new ProjectMemoryStore(memoryRootFor(root, config.memoryDir)).load()
+      const type = args.type || 'all'
+      const limit = Math.max(1, Math.min(Number(args.limit) || 8, 20))
+
+      const queries = config.llmQueryExpansion
+        ? await expandQuery(ctx.llm, args.query, config.expansionCount)
+        : [args.query]
+      const symbolById = new Map()
+      for (const e of store.allEntries()) {
+        if (e.type === 'symbol') symbolById.set(e.id, e)
+      }
+
+      const lines = []
+      if (type === 'all' || type === 'doc' || type === 'symbol') {
+        const pool = type === 'all' ? store.allEntries() : store.allEntries().filter((e) => e.type === type)
+        const scored = rankEntriesMergedScored(pool, queries, limit)
+        if (scored.length) {
+          const top = scored[0].score || 1
+          lines.push(`## Memory (${type === 'all' ? 'docs + symbols' : type})`)
+          for (const { entry: e, score } of scored) {
+            const source = e.sourceLine ? `${e.sourcePath}:${e.sourceLine}` : e.sourcePath
+            const rel = Math.round((score / top) * 100)
+            lines.push(`### ${e.title} (score: ${rel})\n- source: ${source}\n- ${e.summary}`)
+            if (e.type === 'doc' && Array.isArray(e.linkedSymbols) && e.linkedSymbols.length) {
+              const refs = e.linkedSymbols.slice(0, 5).map((id) => {
+                const s = symbolById.get(id)
+                return s ? `${s.title} @ ${s.sourcePath}:${s.sourceLine}` : id
+              })
+              lines.push(`- references: ${refs.join('; ')}`)
+            }
+          }
+        }
+      }
+      if (type === 'all' || type === 'experience') {
+        const scoredExp = rankExperienceScored(store.experience, queries, limit)
+        if (scoredExp.length) {
+          const expTop = scoredExp[0].score || 1
+          lines.push(`## Experience (past problems -> solutions)`)
+          for (const { item: e, score } of scoredExp) {
+            const source = e.sourceFile ? ` (source: ${e.sourceFile})` : ''
+            lines.push(
+              `### Problem: ${e.problem} (score: ${Math.round((score / expTop) * 100)}, id: ${e.id})\n- solution: ${e.solution}${source}\n- updated: ${e.updatedAt}`,
+            )
+          }
+        }
+      }
+
+      if (!lines.length) {
+        return `No memory matches for "${args.query}" in ${root}. Index it first with index_repo / index_doc, or note a fix with remember.`
+      }
+      return truncate(lines.join('\n\n'), config.maxOutputChars)
+    },
+  })
+}

package/src/tools/remember.js

@@ -0,0 +1,53 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { memoryRootFor, resolveIndexRoot } from '../util/fs.js'
+import { ProjectMemoryStore, withStoreLock } from '../store.js'
+
+export function rememberTool(config) {
+  return defineTool({
+    name: 'remember',
+    description:
+      'Save an experience note (problem -> solution) into project memory, e.g. a bug you just fixed or a decision made. ' +
+      'Retrieved later only when search_experience / query_memory matches the problem, never auto-injected. ' +
+      'If a note with a similar problem exists, it is superseded instead of duplicated.',
+    parameters: {
+      problem: {
+        type: 'string',
+        required: true,
+        description: 'The problem/situation, e.g. "pdfjs OPS import fails on Node 24".',
+      },
+      solution: {
+        type: 'string',
+        required: true,
+        description: 'The concrete fix or decision, e.g. "import OPS from pdfjs-dist/legacy/build/pdf.mjs".',
+      },
+      root: {
+        type: 'string',
+        description: 'Project root of the memory store. Defaults to the current working directory.',
+      },
+      source_file: {
+        type: 'string',
+        description: 'Optional file the problem is about, for traceability.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args, exec) {
+      const root = resolveIndexRoot(exec, args.root)
+      const memoryDir = memoryRootFor(root, config.memoryDir)
+      return withStoreLock(memoryDir, () => {
+        const store = new ProjectMemoryStore(memoryDir).load()
+        const result = store.addExperience({
+          problem: args.problem,
+          solution: args.solution,
+          sourceFile: args.source_file,
+        })
+        store.save()
+        return result.superseded
+          ? `Updated existing experience note (${result.id}).`
+          : `Saved experience note (${result.id}).`
+      })
+    },
+  })
+}

package/src/tools/watch-repo.js

@@ -0,0 +1,47 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { memoryRootFor } from '../util/fs.js'
+import { ProjectMemoryStore, withStoreLock } from '../store.js'
+
+export function watchRepoTool(watchManager, config) {
+  return defineTool({
+    name: 'watch_repo',
+    description:
+      'Start silent auto-refresh for a project: the plugin polls the root (configurable interval), ' +
+      'detects changed/new docs and code files via mtime+content-hash, and re-indexes only those silently. ' +
+      'No GUI, no manual re-index needed after this. Stop by reloading the plugin or calling with watch=false.',
+    parameters: {
+      root: {
+        type: 'string',
+        required: true,
+        description: 'Absolute path to the project root to watch.',
+      },
+      watch: {
+        type: 'boolean',
+        description: 'Set false to stop watching this root. Default true.',
+      },
+    },
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: value }],
+    },
+    async execute(args) {
+      const root = path.resolve(args.root)
+      const memoryDir = memoryRootFor(root, config.memoryDir)
+      return withStoreLock(memoryDir, () => {
+        const store = new ProjectMemoryStore(memoryDir).load()
+        if (args.watch === false) {
+          watchManager.removeRoot(root)
+          store.watchlist = store.watchlist.filter((r) => r !== root)
+          store.save()
+          return `Stopped watching: ${root}`
+        }
+        store.addWatch(root)
+        store.save()
+        watchManager.addRoot(root)
+        watchManager.start(config.watchInterval * 1000)
+        return `Watching ${root} (interval ${config.watchInterval}s). Docs/code changes will be re-indexed silently.`
+      })
+    },
+  })
+}

package/src/util/fs.js

@@ -0,0 +1,113 @@
+import { accessSync, constants, readdirSync, statSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+
+export function assertReadableFile(filePath, maxFileSizeMb) {
+  if (typeof filePath !== 'string' || !filePath) {
+    throw new Error('file_path must be a non-empty string')
+  }
+  let stats
+  try {
+    accessSync(filePath, constants.R_OK)
+    stats = statSync(filePath)
+  } catch {
+    throw new Error(`File not readable: ${filePath}`)
+  }
+  if (!stats.isFile()) {
+    throw new Error(`Not a regular file: ${filePath}`)
+  }
+  if (maxFileSizeMb && stats.size > maxFileSizeMb * 1024 * 1024) {
+    throw new Error(`File too large (${(stats.size / 1024 / 1024).toFixed(1)} MB), limit is ${maxFileSizeMb} MB`)
+  }
+  return filePath
+}
+
+export function sha256OfBuffer(buf) {
+  return createHash('sha256').update(buf).digest('hex')
+}
+
+export async function sha256OfFile(filePath) {
+  const buf = await readFile(filePath)
+  return { hash: sha256OfBuffer(buf), size: buf.length }
+}
+
+export async function readTextFile(filePath, maxBytes = 2 * 1024 * 1024) {
+  const buf = await readFile(filePath)
+  if (buf.length > maxBytes) {
+    throw new Error(`File too large to index as text (${(buf.length / 1024 / 1024).toFixed(1)} MB)`)
+  }
+  return buf.toString('utf8')
+}
+
+const DEFAULT_IGNORE = new Set([
+  '.git', 'node_modules', 'dist', 'build', '.next', 'venv', '.venv',
+  '__pycache__', '.idea', '.vscode', '.dsh-project-memory', '.cache',
+  'coverage', '.turbo', 'target', 'vendor', 'third_party', 'thirdparty', 'obj',
+])
+
+export function walkDir(root, ignoreNames = DEFAULT_IGNORE) {
+  const out = []
+  const stack = [root]
+  while (stack.length) {
+    const dir = stack.pop()
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      continue
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.') && entry.name !== '.') continue
+      if (entry.isDirectory()) {
+        if (ignoreNames.has(entry.name)) continue
+        stack.push(path.join(dir, entry.name))
+      } else {
+        out.push(path.join(dir, entry.name))
+      }
+    }
+  }
+  return out.sort()
+}
+
+export function isSupportedDoc(ext) {
+  return ['.pdf', '.md', '.markdown', '.txt'].includes(ext)
+}
+
+const DUMP_REFLECTION = /(?:==\s*TYPE\s|\bVersion=\d+\.\d+\.\d+\.\d+|loaded:\s*\S+,\s*Version=)/
+
+export function looksLikeDump(text, maxBytes = 4096) {
+  if (!text) return false
+  const head = String(text).slice(0, maxBytes)
+  if (!/^(\uFEFF)?\s*={3,}/.test(head)) return false
+  return DUMP_REFLECTION.test(head)
+}
+
+export function isSupportedCode(ext) {
+  return [
+    '.js', '.mjs', '.cjs', '.ts', '.jsx', '.tsx', '.py', '.java', '.go',
+    '.rs', '.c', '.cpp', '.cc', '.h', '.hpp', '.cs', '.php', '.rb',
+    '.swift', '.kt', '.kts', '.sh', '.zsh',
+  ].includes(ext)
+}
+
+export function relativePath(root, filePath) {
+  return path.relative(root, filePath).split(path.sep).join('/')
+}
+
+export const CASE_INSENSITIVE_FS = process.platform === 'win32' || process.platform === 'darwin'
+
+export function storeKey(rel, platform = process.platform) {
+  return platform === 'win32' || platform === 'darwin' ? rel.toLowerCase() : rel
+}
+
+export function memoryRootFor(indexRoot, memoryDir) {
+  return path.join(indexRoot, memoryDir)
+}
+
+export function resolveIndexRoot(exec, explicitRoot) {
+  if (explicitRoot && explicitRoot.trim()) return path.resolve(explicitRoot)
+  const sessionCwd = exec?.agent?.session?.header?.cwd
+  if (sessionCwd) return path.resolve(sessionCwd)
+  return path.resolve(process.cwd())
+}