@coreyuan/vector-mind 1.0.30 → 1.0.32

package/dist/index.js

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import * as readline from "node:readline";
 import crypto from "node:crypto";
 import os from "node:os";
+import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import chokidar from "chokidar";
 import Database from "better-sqlite3";
@@ -13,9 +14,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { toJsonSchemaCompat } from "@modelcontextprotocol/sdk/server/zod-json-schema-compat.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { BUILTIN_CONVENTIONS } from "./builtin-conventions.js";
-import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
+import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.30";
+const SERVER_VERSION = "1.0.32";
 const rootFromEnv = process.env.VECTORMIND_ROOT?.trim() ?? "";
 const prettyJsonOutput = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_PRETTY_JSON ?? "").trim().toLowerCase());
 const debugLogEnabled = ["1", "true", "on", "yes"].includes((process.env.VECTORMIND_DEBUG_LOG ?? "").trim().toLowerCase());
@@ -64,6 +65,11 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+const RIPGREP_RESOLVE_TIMEOUT_MS = 5_000;
+const RIPGREP_SEARCH_TIMEOUT_MS = 30_000;
+const RIPGREP_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+let cachedRipgrepCommand;
+let cachedRipgrepResolveError = null;
 function getCodexHomeDir() {
     const raw = process.env.CODEX_HOME?.trim();
     if (raw)
@@ -253,7 +259,7 @@ function summarizeActivityEvent(e) {
         case "semantic_search":
             return `semantic_search mode=${String(d.mode ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
         case "grep":
-            return `grep q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
+            return `grep backend=${String(d.backend ?? "")} q=${String(d.query ?? "")} matches=${String(d.matches ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "query_codebase":
             return `query_codebase q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
         case "read_file_lines":
@@ -505,6 +511,22 @@ const IGNORED_PATH_SEGMENTS = new Set([
     "x64",
     "x86",
 ].map((s) => s.toLowerCase()));
+const NOISE_FILE_SUFFIXES = [
+    ".min.js",
+    ".min.css",
+    ".bundle.js",
+    ".bundle.css",
+    ".chunk.js",
+    ".chunk.css",
+];
+const NOISE_FILE_BASENAMES = [
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "cargo.lock",
+    "composer.lock",
+];
 const IGNORED_LIKE_PATTERNS = (() => {
     const patterns = [];
     for (const seg of IGNORED_PATH_SEGMENTS) {
@@ -608,27 +630,11 @@ function pruneIgnoredIndexesByPathPatterns() {
 function pruneFilenameNoiseIndexes() {
     if (!db)
         return { chunks_deleted: 0, symbols_deleted: 0 };
-    const suffixes = [
-        ".min.js",
-        ".min.css",
-        ".bundle.js",
-        ".bundle.css",
-        ".chunk.js",
-        ".chunk.css",
-    ];
-    const baseNames = [
-        "package-lock.json",
-        "pnpm-lock.yaml",
-        "yarn.lock",
-        "bun.lockb",
-        "cargo.lock",
-        "composer.lock",
-    ];
     try {
-        const suffixWhere = suffixes.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
-        const baseWhere = baseNames.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
-        const suffixArgs = suffixes.map((s) => `%${s}`);
-        const baseArgs = baseNames.map((n) => `%/${n}`);
+        const suffixWhere = NOISE_FILE_SUFFIXES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const baseWhere = NOISE_FILE_BASENAMES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const suffixArgs = NOISE_FILE_SUFFIXES.map((s) => `%${s}`);
+        const baseArgs = NOISE_FILE_BASENAMES.map((n) => `%/${n}`);
         const whereParts = [];
         const args = [];
         if (suffixWhere) {
@@ -710,21 +716,9 @@ function isSymbolIndexableFile(filePath) {
 }
 function shouldIgnoreContentFile(filePath) {
     const base = path.basename(filePath).toLowerCase();
-    const ignoreNames = new Set([
-        "package-lock.json",
-        "pnpm-lock.yaml",
-        "yarn.lock",
-        "bun.lockb",
-        "cargo.lock",
-        "composer.lock",
-    ]);
-    if (ignoreNames.has(base))
-        return true;
-    if (base.endsWith(".min.js") || base.endsWith(".min.css"))
-        return true;
-    if (base.endsWith(".bundle.js") || base.endsWith(".bundle.css"))
+    if (NOISE_FILE_BASENAMES.includes(base))
         return true;
-    if (base.endsWith(".chunk.js") || base.endsWith(".chunk.css"))
+    if (NOISE_FILE_SUFFIXES.some((suffix) => base.endsWith(suffix)))
         return true;
     return false;
 }
@@ -1175,13 +1169,14 @@ const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
     // If case_sensitive is omitted and smart_case=true, uppercase => case-sensitive, otherwise case-insensitive.
     smart_case: z.boolean().optional().default(true),
     case_sensitive: z.boolean().optional(),
-    // Optional hint used to narrow candidates quickly when mode=regex and the pattern has few literals.
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     literal_hint: z.string().optional().default(""),
-    // Defaults to code/doc chunks; can be widened if needed.
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     kinds: z.array(z.string().min(1)).optional(),
     include_paths: z.array(z.string().min(1)).optional(),
     exclude_paths: z.array(z.string().min(1)).optional(),
     max_results: z.number().int().min(1).max(5000).optional().default(200),
+    // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     max_candidates: z.number().int().min(1).max(50_000).optional(),
 }));
 const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
@@ -1922,6 +1917,385 @@ function compileGrepRegex(opts) {
     const source = opts.mode === "literal" ? escapeRegExp(opts.query) : opts.query;
     return new RegExp(source, flags);
 }
+function trimGrepText(input, maxChars) {
+    if (input.length <= maxChars)
+        return input;
+    return `${input.slice(0, maxChars)}…`;
+}
+function buildGrepPreviewSnippet(lineText, col, maxChars = 500) {
+    const clean = lineText.replace(/\r$/, "");
+    if (clean.length <= maxChars)
+        return clean;
+    const matchIndex = Math.max(0, col - 1);
+    let start = Math.max(0, matchIndex - Math.floor(maxChars * 0.35));
+    if (start + maxChars > clean.length)
+        start = Math.max(0, clean.length - maxChars);
+    const end = Math.min(clean.length, start + maxChars);
+    let snippet = clean.slice(start, end);
+    if (start > 0)
+        snippet = `…${snippet}`;
+    if (end < clean.length)
+        snippet = `${snippet}…`;
+    return snippet;
+}
+function extractGrepMatchText(opts) {
+    const clean = opts.lineText.replace(/\r$/, "");
+    const startIndex = Math.max(0, opts.col - 1);
+    if (opts.mode === "literal") {
+        const slice = clean.slice(startIndex, startIndex + opts.query.length) || opts.query;
+        return trimGrepText(slice, 200);
+    }
+    try {
+        const flags = opts.caseSensitive ? "m" : "im";
+        const anchored = new RegExp(opts.query, flags);
+        const tail = clean.slice(startIndex);
+        const found = anchored.exec(tail);
+        if (found?.index === 0 && found[0])
+            return trimGrepText(found[0], 200);
+    }
+    catch { }
+    const fallback = clean.slice(startIndex, Math.min(clean.length, startIndex + 200));
+    return trimGrepText(fallback || opts.query, 200);
+}
+function toProcessText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value == null)
+        return "";
+    return value.toString("utf8");
+}
+function formatProcessFailure(result) {
+    if (result.error)
+        return `${result.error.name}: ${result.error.message}`;
+    const stderr = toProcessText(result.stderr).trim();
+    if (stderr)
+        return stderr;
+    const stdout = toProcessText(result.stdout).trim();
+    if (stdout)
+        return stdout;
+    if (typeof result.status === "number")
+        return `exit ${result.status}`;
+    if (result.signal)
+        return `signal ${result.signal}`;
+    return "unknown failure";
+}
+function buildRipgrepEnv() {
+    const env = { ...process.env };
+    delete env.RIPGREP_CONFIG_PATH;
+    return env;
+}
+function pushUniqueCandidate(candidates, seen, raw) {
+    const value = raw?.trim();
+    if (!value || seen.has(value))
+        return;
+    seen.add(value);
+    candidates.push(value);
+}
+function listChildDirsSafe(dirPath) {
+    try {
+        return fs
+            .readdirSync(dirPath, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(dirPath, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+function collectRipgrepCandidates() {
+    const candidates = [];
+    const seen = new Set();
+    const override = process.env.VECTORMIND_RG_PATH?.trim();
+    if (override)
+        pushUniqueCandidate(candidates, seen, path.resolve(override));
+    if (process.platform === "win32") {
+        pushUniqueCandidate(candidates, seen, "rg.exe");
+        pushUniqueCandidate(candidates, seen, "rg");
+    }
+    else {
+        pushUniqueCandidate(candidates, seen, "rg");
+    }
+    for (const rawDir of (process.env.PATH ?? "").split(path.delimiter)) {
+        const dir = rawDir.trim().replace(/^"+|"+$/g, "");
+        if (!dir)
+            continue;
+        if (process.platform === "win32") {
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg.exe"));
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg"));
+        }
+        else {
+            pushUniqueCandidate(candidates, seen, path.join(dir, "rg"));
+        }
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA?.trim();
+        const programsDir = localAppData ? path.join(localAppData, "Programs") : "";
+        if (programsDir && fs.existsSync(programsDir)) {
+            for (const appDir of listChildDirsSafe(programsDir)) {
+                pushUniqueCandidate(candidates, seen, path.join(appDir, "resources", "app", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                pushUniqueCandidate(candidates, seen, path.join(appDir, "resources", "app", "extensions", "kiro.kiro-agent", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                for (const childDir of listChildDirsSafe(appDir)) {
+                    pushUniqueCandidate(candidates, seen, path.join(childDir, "resources", "app", "node_modules", "@vscode", "ripgrep", "bin", "rg.exe"));
+                }
+            }
+        }
+    }
+    return candidates;
+}
+function resolveRipgrepCommand() {
+    if (typeof cachedRipgrepCommand !== "undefined") {
+        if (cachedRipgrepCommand)
+            return { ok: true, command: cachedRipgrepCommand };
+        return { ok: false, error: cachedRipgrepResolveError ?? "ripgrep unavailable", attempts: [] };
+    }
+    const env = buildRipgrepEnv();
+    const attempts = [];
+    for (const candidate of collectRipgrepCandidates()) {
+        const probe = spawnSync(candidate, ["--version"], {
+            cwd: projectRoot || undefined,
+            env,
+            encoding: "utf8",
+            windowsHide: true,
+            timeout: RIPGREP_RESOLVE_TIMEOUT_MS,
+            maxBuffer: 256 * 1024,
+        });
+        if (probe.status === 0) {
+            cachedRipgrepCommand = candidate;
+            cachedRipgrepResolveError = null;
+            return { ok: true, command: candidate };
+        }
+        attempts.push(`${candidate}: ${formatProcessFailure(probe)}`);
+    }
+    cachedRipgrepCommand = null;
+    cachedRipgrepResolveError = attempts.slice(0, 8).join(" | ") || "ripgrep unavailable";
+    return { ok: false, error: cachedRipgrepResolveError, attempts };
+}
+function appendBuiltInRipgrepExcludes(args) {
+    for (const segment of IGNORED_PATH_SEGMENTS) {
+        args.push("-g", `!${segment}/**`);
+        args.push("-g", `!**/${segment}/**`);
+    }
+    for (const baseName of NOISE_FILE_BASENAMES) {
+        args.push("-g", `!**/${baseName}`);
+    }
+    for (const suffix of NOISE_FILE_SUFFIXES) {
+        args.push("-g", `!**/*${suffix}`);
+    }
+}
+function runRipgrepSearch(opts) {
+    const resolved = resolveRipgrepCommand();
+    if (!resolved.ok) {
+        return { ok: false, unavailable: true, error: resolved.error, attempts: resolved.attempts };
+    }
+    const args = ["--vimgrep", "--no-heading", "--color", "never", "-m", String(opts.maxResults)];
+    args.push(opts.caseSensitive ? "-s" : "-i");
+    if (opts.mode === "literal")
+        args.push("-F");
+    appendBuiltInRipgrepExcludes(args);
+    args.push("--", opts.query, ".");
+    const result = spawnSync(resolved.command, args, {
+        cwd: projectRoot,
+        env: buildRipgrepEnv(),
+        encoding: "utf8",
+        windowsHide: true,
+        timeout: RIPGREP_SEARCH_TIMEOUT_MS,
+        maxBuffer: RIPGREP_MAX_BUFFER_BYTES,
+    });
+    if (result.error) {
+        return {
+            ok: false,
+            unavailable: false,
+            error: formatProcessFailure(result),
+            attempts: [],
+            rg_command: resolved.command,
+            exit_status: result.status,
+        };
+    }
+    const status = result.status ?? 0;
+    if (status !== 0 && status !== 1) {
+        return {
+            ok: false,
+            unavailable: false,
+            error: formatProcessFailure(result),
+            attempts: [],
+            rg_command: resolved.command,
+            exit_status: status,
+        };
+    }
+    const matches = [];
+    let totalMatches = 0;
+    let truncated = false;
+    for (const rawLine of toProcessText(result.stdout).split(/\r?\n/)) {
+        if (!rawLine)
+            continue;
+        const parsed = /^(.*?):(\d+):(\d+):(.*)$/.exec(rawLine);
+        if (!parsed)
+            continue;
+        const filePath = path.posix
+            .normalize(parsed[1].replace(/\\/g, "/"))
+            .replace(/^\.\/+/, "");
+        const lineNumber = Number.parseInt(parsed[2] ?? "0", 10);
+        const colNumber = Number.parseInt(parsed[3] ?? "0", 10);
+        const lineText = (parsed[4] ?? "").replace(/\r$/, "");
+        if (!filePath || !Number.isFinite(lineNumber) || !Number.isFinite(colNumber))
+            continue;
+        if (shouldIgnoreDbFilePath(filePath))
+            continue;
+        if (shouldIgnoreContentFile(filePath))
+            continue;
+        if (!passesPathFilters(filePath, opts.includePaths, opts.excludePaths))
+            continue;
+        totalMatches += 1;
+        if (matches.length >= opts.maxResults) {
+            truncated = true;
+            continue;
+        }
+        matches.push({
+            file_path: filePath,
+            kind: "file_match",
+            line: lineNumber,
+            col: colNumber,
+            preview: buildGrepPreviewSnippet(lineText, colNumber),
+            match: extractGrepMatchText({
+                lineText,
+                query: opts.query,
+                mode: opts.mode,
+                caseSensitive: opts.caseSensitive,
+                col: colNumber,
+            }),
+        });
+    }
+    return {
+        ok: true,
+        backend: "ripgrep",
+        rg_command: resolved.command,
+        matches,
+        truncated,
+        total_matches: totalMatches,
+    };
+}
+function runIndexedGrepSearch(opts) {
+    const hint = (() => {
+        if (opts.mode === "literal")
+            return opts.query;
+        const explicit = opts.literalHint.trim();
+        if (explicit)
+            return explicit;
+        return extractLongestLiteralFromRegex(opts.query);
+    })();
+    if (opts.mode === "regex" && hint.trim().length < 3) {
+        throw new Error("Regex has no sufficiently long literal anchor for indexed narrowing. Provide literal_hint (>= 3 chars) or narrow with include_paths.");
+    }
+    let re;
+    try {
+        re = compileGrepRegex({
+            query: opts.query,
+            mode: opts.mode,
+            caseSensitive: opts.caseSensitive,
+        });
+    }
+    catch (err) {
+        throw new Error(`Invalid pattern: ${String(err)}`);
+    }
+    const maxCandidates = opts.maxCandidates ?? Math.min(50_000, Math.max(1000, opts.maxResults * 200));
+    const candidates = (() => {
+        if (ftsAvailable) {
+            const matchQuery = buildFtsMatchQuery(hint);
+            const placeholders = opts.kinds.map(() => "?").join(", ");
+            const stmt = db.prepare(`
+        SELECT
+          m.id as id,
+          m.kind as kind,
+          m.content as content,
+          m.file_path as file_path,
+          m.start_line as start_line,
+          m.end_line as end_line
+        FROM ${FTS_TABLE_NAME}
+        JOIN memory_items m ON m.id = ${FTS_TABLE_NAME}.rowid
+        WHERE ${FTS_TABLE_NAME} MATCH ?
+          AND m.kind IN (${placeholders})
+        ORDER BY m.file_path ASC, m.start_line ASC, m.id ASC
+        LIMIT ?
+      `);
+            return stmt.all(matchQuery, ...opts.kinds, maxCandidates);
+        }
+        const needle = opts.mode === "literal" ? opts.query : hint;
+        const escaped = escapeLike(needle);
+        const like = `%${escaped}%`;
+        const placeholders = opts.kinds.map(() => "?").join(", ");
+        const stmt = db.prepare(`
+      SELECT
+        id,
+        kind,
+        content,
+        file_path,
+        start_line,
+        end_line
+      FROM memory_items
+      WHERE content LIKE ? ESCAPE '\\'
+        AND kind IN (${placeholders})
+      ORDER BY file_path ASC, start_line ASC, id ASC
+      LIMIT ?
+    `);
+        return stmt.all(like, ...opts.kinds, maxCandidates);
+    })();
+    const matches = [];
+    let candidatesScanned = 0;
+    let truncated = false;
+    for (const c of candidates) {
+        candidatesScanned += 1;
+        if (!c.file_path || c.start_line == null)
+            continue;
+        if (shouldIgnoreDbFilePath(c.file_path))
+            continue;
+        if (!passesPathFilters(c.file_path, opts.includePaths, opts.excludePaths))
+            continue;
+        const content = c.content ?? "";
+        const lineStarts = buildLineStarts(content);
+        re.lastIndex = 0;
+        let m;
+        while ((m = re.exec(content)) !== null) {
+            const idx = m.index ?? 0;
+            const matched = m[0] ?? "";
+            if (!matched) {
+                if (re.lastIndex >= content.length)
+                    break;
+                re.lastIndex += 1;
+                continue;
+            }
+            const lineIdx = lineIndexForOffset(lineStarts, idx);
+            const lineStart = lineStarts[lineIdx] ?? 0;
+            const lineEnd = lineIdx + 1 < lineStarts.length
+                ? (lineStarts[lineIdx + 1] ?? content.length) - 1
+                : content.length;
+            const previewRaw = content.slice(lineStart, Math.max(lineStart, lineEnd));
+            matches.push({
+                file_path: c.file_path,
+                kind: c.kind,
+                line: c.start_line + lineIdx,
+                col: idx - lineStart + 1,
+                preview: trimGrepText(previewRaw, 500),
+                match: trimGrepText(matched, 200),
+            });
+            if (matches.length >= opts.maxResults) {
+                truncated = true;
+                break;
+            }
+        }
+        if (truncated)
+            break;
+    }
+    return {
+        backend: "indexed_fallback",
+        hint,
+        kinds: opts.kinds,
+        include_paths: opts.includePaths ?? [],
+        exclude_paths: opts.excludePaths ?? [],
+        candidates: { total: candidates.length, scanned: candidatesScanned },
+        matches,
+        truncated,
+    };
+}
 function resolveProjectPathUnderRoot(inputPath, opts = {}) {
     const normalizedInput = inputPath.trim() || ".";
     const abs = path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput);
@@ -2150,15 +2524,19 @@ function buildServerInstructions() {
         "Built-in architecture and code-organization policy:",
         BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
         "",
+        "Built-in low-overhead execution and heavy-thread policy:",
+        BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS,
+        "",
         "Required workflow:",
-        "- On every new conversation/session: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
+        "- On every new conversation/session for analysis/design/development work: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
         "  - Output is compact by default. Use include_content=true only when you truly need full text (it increases tokens).",
         "  - Tune output size with: requirements_limit/changes_limit/notes_limit, preview_chars, pending_limit/pending_offset.",
         "  - Prefer read_memory_item(id, offset, limit) to fetch full text on demand instead of returning large content in other tool outputs.",
+        "- For pure execution-first tasks with explicit targets (for example compile/build/run/launch/package/publish/test rerun), you may skip retrieval and go straight to the minimum necessary shell or host tools unless code/context lookup is actually needed to unblock execution.",
         "- To read local Codex skill/prompt/rule files (for example SKILL.md under CODEX_HOME or AGENTS_HOME), prefer read_codex_text_file({ path }) instead of assuming a filesystem MCP resource server exists.",
         "- For project file/directory browsing, prefer list_project_files({ path, recursive?, max_depth? }) over shelling out to Get-ChildItem/ls. It respects ignore rules and keeps output bounded.",
         "- For small/medium raw file reads, prefer read_file_text({ path, offset?, max_chars? }) over Get-Content -Raw. Use read_file_lines(...) when you need deterministic line ranges or the file may be large.",
-        "- For an rg/Select-String-style search with exact file+line+col matches, prefer grep({ query: <pattern> }) over shelling out (uses the indexed code/doc chunks).",
+        "- For raw repo text search with exact file+line+col matches, prefer grep({ query: <pattern> }). It uses ripgrep against real project files when available, applies built-in noise filters, and only falls back to indexed search if ripgrep is unavailable.",
         "- To read a bounded segment of a file, prefer read_file_lines({ path: <file>, from_line/to_line or total_count }) over unbounded file reads.",
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
@@ -2167,6 +2545,7 @@ function buildServerInstructions() {
         "- When you need full text for a specific note/summary/match: call read_memory_item(id, offset, limit) and page through it.",
         "- When asked to locate code (class/function/type): call query_codebase(query) instead of guessing.",
         "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing.",
+        "- If the current thread is already heavy or the user reports it has become slow, switch to a lighter workflow: avoid redundant retrieval, keep outputs compact, and recommend continuing substantial new analysis in a fresh thread after a short handoff summary.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
     ].join("\n");
@@ -2732,7 +3111,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "grep",
-                description: "Fast indexed grep across code/doc chunks with precise file/line/col matches. Prefer this over shelling out to rg/Select-String when possible.",
+                description: "Repo text search with precise file/line/col matches, powered by ripgrep against real project files plus built-in noise filters. Falls back to indexed search only when ripgrep is unavailable.",
                 inputSchema: toJsonSchemaCompat(GrepArgsSchema),
             },
             {
@@ -3434,15 +3813,53 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const includePaths = args.include_paths?.length ? args.include_paths : null;
             const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
             const maxResults = args.max_results;
-            const hint = (() => {
-                if (mode === "literal")
-                    return q;
-                const explicit = args.literal_hint.trim();
-                if (explicit)
-                    return explicit;
-                return extractLongestLiteralFromRegex(q);
-            })();
-            if (mode === "regex" && hint.trim().length < 3) {
+            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
+            const ripgrepResult = runRipgrepSearch({
+                query: q,
+                mode,
+                smartCase,
+                caseSensitive,
+                includePaths,
+                excludePaths,
+                maxResults,
+            });
+            if (ripgrepResult.ok) {
+                logActivity("grep", {
+                    backend: ripgrepResult.backend,
+                    rg_command: ripgrepResult.rg_command,
+                    query: q,
+                    mode,
+                    case_sensitive: caseSensitive,
+                    smart_case: smartCase,
+                    include_paths: includePaths ?? [],
+                    exclude_paths: excludePaths ?? [],
+                    matches: ripgrepResult.matches.length,
+                    total_matches: ripgrepResult.total_matches,
+                    truncated: ripgrepResult.truncated,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: true,
+                                backend: ripgrepResult.backend,
+                                rg_command: ripgrepResult.rg_command,
+                                query: q,
+                                mode,
+                                case_sensitive: caseSensitive,
+                                smart_case: smartCase,
+                                include_paths: includePaths ?? [],
+                                exclude_paths: excludePaths ?? [],
+                                matches: ripgrepResult.matches,
+                                total_matches: ripgrepResult.total_matches,
+                                truncated: ripgrepResult.truncated,
+                            }),
+                        },
+                    ],
+                };
+            }
+            if (!ripgrepResult.unavailable) {
                 return {
                     isError: true,
                     content: [
@@ -3450,19 +3867,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             type: "text",
                             text: toolJson({
                                 ok: false,
-                                error: "Regex has no sufficiently long literal anchor for indexed narrowing. Provide literal_hint (>= 3 chars) or narrow with include_paths.",
+                                backend: "ripgrep",
+                                error: ripgrepResult.error,
+                                rg_command: ripgrepResult.rg_command,
+                                exit_status: ripgrepResult.exit_status,
                                 query: q,
                                 mode,
-                                literal_hint: args.literal_hint,
                             }),
                         },
                     ],
                 };
             }
-            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
-            let re;
+            let indexedResult;
             try {
-                re = compileGrepRegex({ query: q, mode, caseSensitive });
+                indexedResult = runIndexedGrepSearch({
+                    query: q,
+                    mode,
+                    smartCase,
+                    caseSensitive,
+                    literalHint: args.literal_hint,
+                    kinds,
+                    includePaths,
+                    excludePaths,
+                    maxResults,
+                    maxCandidates: args.max_candidates,
+                });
             }
             catch (err) {
                 return {
@@ -3470,114 +3899,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     content: [
                         {
                             type: "text",
-                            text: toolJson({ ok: false, error: `Invalid pattern: ${String(err)}`, query: q, mode }),
+                            text: toolJson({
+                                ok: false,
+                                backend: "indexed_fallback",
+                                fallback_reason: "ripgrep_unavailable",
+                                ripgrep_error: ripgrepResult.error,
+                                ripgrep_attempts: ripgrepResult.attempts,
+                                error: String(err),
+                                query: q,
+                                mode,
+                                literal_hint: args.literal_hint,
+                            }),
                         },
                     ],
                 };
             }
-            const maxCandidates = args.max_candidates ?? Math.min(50_000, Math.max(1000, maxResults * 200));
-            const candidates = (() => {
-                if (ftsAvailable) {
-                    const matchQuery = buildFtsMatchQuery(hint);
-                    const placeholders = kinds.map(() => "?").join(", ");
-                    const stmt = db.prepare(`
-            SELECT
-              m.id as id,
-              m.kind as kind,
-              m.content as content,
-              m.file_path as file_path,
-              m.start_line as start_line,
-              m.end_line as end_line
-            FROM ${FTS_TABLE_NAME}
-            JOIN memory_items m ON m.id = ${FTS_TABLE_NAME}.rowid
-            WHERE ${FTS_TABLE_NAME} MATCH ?
-              AND m.kind IN (${placeholders})
-            ORDER BY m.file_path ASC, m.start_line ASC, m.id ASC
-            LIMIT ?
-          `);
-                    return stmt.all(matchQuery, ...kinds, maxCandidates);
-                }
-                const needle = mode === "literal" ? q : hint;
-                const escaped = escapeLike(needle);
-                const like = `%${escaped}%`;
-                const placeholders = kinds.map(() => "?").join(", ");
-                const stmt = db.prepare(`
-          SELECT
-            id,
-            kind,
-            content,
-            file_path,
-            start_line,
-            end_line
-          FROM memory_items
-          WHERE content LIKE ? ESCAPE '\\'
-            AND kind IN (${placeholders})
-          ORDER BY file_path ASC, start_line ASC, id ASC
-          LIMIT ?
-        `);
-                return stmt.all(like, ...kinds, maxCandidates);
-            })();
-            const matches = [];
-            let candidatesScanned = 0;
-            let truncated = false;
-            for (const c of candidates) {
-                candidatesScanned += 1;
-                if (!c.file_path || c.start_line == null)
-                    continue;
-                if (shouldIgnoreDbFilePath(c.file_path))
-                    continue;
-                if (!passesPathFilters(c.file_path, includePaths, excludePaths))
-                    continue;
-                const content = c.content ?? "";
-                const lineStarts = buildLineStarts(content);
-                re.lastIndex = 0;
-                let m;
-                while ((m = re.exec(content)) !== null) {
-                    const idx = m.index ?? 0;
-                    const matched = m[0] ?? "";
-                    if (!matched) {
-                        if (re.lastIndex >= content.length)
-                            break;
-                        re.lastIndex += 1;
-                        continue;
-                    }
-                    const lineIdx = lineIndexForOffset(lineStarts, idx);
-                    const lineStart = lineStarts[lineIdx] ?? 0;
-                    const lineEnd = lineIdx + 1 < lineStarts.length
-                        ? (lineStarts[lineIdx + 1] ?? content.length) - 1
-                        : content.length;
-                    const previewRaw = content.slice(lineStart, Math.max(lineStart, lineEnd));
-                    const preview = previewRaw.length > 500 ? `${previewRaw.slice(0, 500)}…` : previewRaw;
-                    const matchText = matched.length > 200 ? `${matched.slice(0, 200)}…` : matched;
-                    matches.push({
-                        file_path: c.file_path,
-                        kind: c.kind,
-                        line: c.start_line + lineIdx,
-                        col: idx - lineStart + 1,
-                        preview,
-                        match: matchText,
-                    });
-                    if (matches.length >= maxResults) {
-                        truncated = true;
-                        break;
-                    }
-                }
-                if (truncated)
-                    break;
-            }
             logActivity("grep", {
+                backend: indexedResult.backend,
+                fallback_reason: "ripgrep_unavailable",
+                ripgrep_error: ripgrepResult.error,
                 query: q,
                 mode,
                 case_sensitive: caseSensitive,
                 smart_case: smartCase,
-                hint,
+                hint: indexedResult.hint,
                 kinds,
                 include_paths: includePaths ?? [],
                 exclude_paths: excludePaths ?? [],
-                candidates: candidates.length,
-                candidates_scanned: candidatesScanned,
-                matches: matches.length,
-                truncated,
+                candidates: indexedResult.candidates.total,
+                candidates_scanned: indexedResult.candidates.scanned,
+                matches: indexedResult.matches.length,
+                truncated: indexedResult.truncated,
             });
             return {
                 content: [
@@ -3585,17 +3937,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         type: "text",
                         text: toolJson({
                             ok: true,
+                            backend: indexedResult.backend,
+                            fallback_reason: "ripgrep_unavailable",
+                            ripgrep_error: ripgrepResult.error,
+                            ripgrep_attempts: ripgrepResult.attempts,
                             query: q,
                             mode,
                             case_sensitive: caseSensitive,
                             smart_case: smartCase,
-                            hint,
+                            hint: indexedResult.hint,
                             kinds,
                             include_paths: includePaths ?? [],
                             exclude_paths: excludePaths ?? [],
-                            candidates: { total: candidates.length, scanned: candidatesScanned },
-                            matches,
-                            truncated,
+                            candidates: indexedResult.candidates,
+                            matches: indexedResult.matches,
+                            truncated: indexedResult.truncated,
                         }),
                     },
                 ],