@coreyuan/vector-mind 1.0.19 → 1.0.30

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import path from "node:path";
 import fs from "node:fs";
+import * as readline from "node:readline";
 import crypto from "node:crypto";
 import os from "node:os";
 import { fileURLToPath } from "node:url";
@@ -11,8 +12,10 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 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";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.19";
+const SERVER_VERSION = "1.0.30";
 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());
@@ -61,6 +64,58 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+function getCodexHomeDir() {
+    const raw = process.env.CODEX_HOME?.trim();
+    if (raw)
+        return path.resolve(raw);
+    return path.join(os.homedir(), ".codex");
+}
+function getAgentsHomeDir() {
+    const raw = process.env.AGENTS_HOME?.trim();
+    if (raw)
+        return path.resolve(raw);
+    return path.join(os.homedir(), ".agents");
+}
+function getAllowedCodexTextRoots() {
+    const codexHome = getCodexHomeDir();
+    const agentsHome = getAgentsHomeDir();
+    return Array.from(new Set([
+        path.join(codexHome, "skills"),
+        path.join(codexHome, "prompts"),
+        path.join(codexHome, "rules"),
+        path.join(agentsHome, "skills"),
+    ].map((p) => path.resolve(p))));
+}
+const INDEX_MAX_CODE_BYTES = (() => {
+    const raw = process.env.VECTORMIND_INDEX_MAX_CODE_BYTES?.trim();
+    if (!raw)
+        return 400_000;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return 400_000;
+    return n;
+})();
+const INDEX_MAX_DOC_BYTES = (() => {
+    const raw = process.env.VECTORMIND_INDEX_MAX_DOC_BYTES?.trim();
+    if (!raw)
+        return 600_000;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return 600_000;
+    return n;
+})();
+const INDEX_SKIP_MINIFIED = (() => {
+    const raw = (process.env.VECTORMIND_INDEX_SKIP_MINIFIED ?? "").trim().toLowerCase();
+    if (!raw)
+        return true;
+    return ["1", "true", "on", "yes"].includes(raw);
+})();
+const INDEX_AUTO_PRUNE_IGNORED = (() => {
+    const raw = (process.env.VECTORMIND_INDEX_AUTO_PRUNE_IGNORED ?? "").trim().toLowerCase();
+    if (!raw)
+        return true;
+    return ["1", "true", "on", "yes"].includes(raw);
+})();
 const ROOTS_LIST_TIMEOUT_MS = (() => {
     const raw = process.env.VECTORMIND_ROOTS_TIMEOUT_MS?.trim();
     if (!raw)
@@ -197,8 +252,18 @@ function summarizeActivityEvent(e) {
             return `pending_list returned=${String(d.returned ?? "")} total=${String(d.total ?? "")}`;
         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 ?? "")}`;
         case "query_codebase":
             return `query_codebase q=${String(d.query ?? "")} matches=${String(d.matches ?? "")}`;
+        case "read_file_lines":
+            return `read_file_lines file=${String(d.file_path ?? "")} returned=${String(d.returned ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "read_file_text":
+            return `read_file_text file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "list_project_files":
+            return `list_project_files path=${String(d.path ?? "")} returned=${String(d.returned ?? "")} scanned=${String(d.scanned ?? "")} truncated=${String(d.truncated ?? "")}`;
+        case "read_codex_text_file":
+            return `read_codex_text_file file=${String(d.file_path ?? "")} returned=${String(d.returned_chars ?? "")}/${String(d.total_chars ?? "")} truncated=${String(d.truncated ?? "")}`;
         case "start_requirement":
             return `start_requirement #${String(d.req_id ?? "")} ${String(d.title ?? "")}`;
         case "sync_change_intent":
@@ -406,6 +471,10 @@ const IGNORED_PATH_SEGMENTS = new Set([
     ".next",
     ".nuxt",
     ".svelte-kit",
+    ".turbo",
+    ".nx",
+    ".cache",
+    ".parcel-cache",
     // .NET / VS build artifacts
     "bin",
     "obj",
@@ -414,9 +483,11 @@ const IGNORED_PATH_SEGMENTS = new Set([
     // General build outputs
     "dist",
     "build",
+    "buildfiles",
     "out",
     "target",
     "coverage",
+    "artifacts",
     // Python caches/venvs
     "__pycache__",
     ".pytest_cache",
@@ -465,7 +536,9 @@ function pruneIgnoredPendingChanges() {
     try {
         if (!IGNORED_LIKE_PATTERNS.length)
             return;
-        const where = IGNORED_LIKE_PATTERNS.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+        const where = IGNORED_LIKE_PATTERNS
+            .map(() => "LOWER(REPLACE(file_path, '\\\\', '/')) LIKE ?")
+            .join(" OR ");
         db.prepare(`DELETE FROM pending_changes WHERE ${where}`).run(...IGNORED_LIKE_PATTERNS);
     }
     catch (err) {
@@ -498,6 +571,102 @@ function prunePendingChanges() {
         console.error("[vectormind] prune pending_changes failed:", err);
     }
 }
+function pruneIgnoredIndexesByPathPatterns() {
+    if (!db)
+        return { chunks_deleted: 0, symbols_deleted: 0 };
+    try {
+        if (!IGNORED_LIKE_PATTERNS.length)
+            return { chunks_deleted: 0, symbols_deleted: 0 };
+        const where = IGNORED_LIKE_PATTERNS
+            .map(() => "LOWER(REPLACE(file_path, '\\\\', '/')) LIKE ?")
+            .join(" OR ");
+        const chunksDeleted = db
+            .prepare(`DELETE FROM memory_items
+         WHERE file_path IS NOT NULL
+           AND (kind = 'code_chunk' OR kind = 'doc_chunk')
+           AND (${where})`)
+            .run(...IGNORED_LIKE_PATTERNS).changes;
+        const symbolsDeleted = db
+            .prepare(`DELETE FROM symbols
+         WHERE file_path IS NOT NULL
+           AND (${where})`)
+            .run(...IGNORED_LIKE_PATTERNS).changes;
+        if (chunksDeleted || symbolsDeleted) {
+            logActivity("index_prune", {
+                reason: "ignored_paths",
+                chunks_deleted: chunksDeleted,
+                symbols_deleted: symbolsDeleted,
+            });
+        }
+        return { chunks_deleted: chunksDeleted, symbols_deleted: symbolsDeleted };
+    }
+    catch (err) {
+        console.error("[vectormind] prune indexes failed:", err);
+        return { chunks_deleted: 0, symbols_deleted: 0 };
+    }
+}
+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 whereParts = [];
+        const args = [];
+        if (suffixWhere) {
+            whereParts.push(`(${suffixWhere})`);
+            args.push(...suffixArgs);
+        }
+        if (baseWhere) {
+            whereParts.push(`(${baseWhere})`);
+            args.push(...baseArgs);
+        }
+        if (!whereParts.length)
+            return { chunks_deleted: 0, symbols_deleted: 0 };
+        const where = whereParts.join(" OR ");
+        const chunksDeleted = db
+            .prepare(`DELETE FROM memory_items
+         WHERE file_path IS NOT NULL
+           AND (kind = 'code_chunk' OR kind = 'doc_chunk')
+           AND (${where})`)
+            .run(...args).changes;
+        const symbolsDeleted = db
+            .prepare(`DELETE FROM symbols
+         WHERE file_path IS NOT NULL
+           AND (${where})`)
+            .run(...args).changes;
+        if (chunksDeleted || symbolsDeleted) {
+            logActivity("index_prune", {
+                reason: "filename_noise",
+                chunks_deleted: chunksDeleted,
+                symbols_deleted: symbolsDeleted,
+            });
+        }
+        return { chunks_deleted: chunksDeleted, symbols_deleted: symbolsDeleted };
+    }
+    catch (err) {
+        console.error("[vectormind] prune filename noise failed:", err);
+        return { chunks_deleted: 0, symbols_deleted: 0 };
+    }
+}
 function shouldIgnorePath(inputPath) {
     const normalizedAbs = path.resolve(inputPath);
     const rel = path.relative(projectRoot, normalizedAbs);
@@ -515,6 +684,8 @@ function shouldIgnorePath(inputPath) {
     return false;
 }
 function isSymbolIndexableFile(filePath) {
+    if (shouldIgnoreContentFile(filePath))
+        return false;
     const ext = path.extname(filePath).toLowerCase();
     const allowed = new Set([
         ".ts",
@@ -551,6 +722,56 @@ function shouldIgnoreContentFile(filePath) {
         return true;
     if (base.endsWith(".min.js") || base.endsWith(".min.css"))
         return true;
+    if (base.endsWith(".bundle.js") || base.endsWith(".bundle.css"))
+        return true;
+    if (base.endsWith(".chunk.js") || base.endsWith(".chunk.css"))
+        return true;
+    return false;
+}
+function looksLikeGeneratedFile(content) {
+    const head = content.slice(0, 4000).toLowerCase();
+    if (head.includes("@generated"))
+        return true;
+    if (head.includes("do not edit") && (head.includes("generated") || head.includes("auto-generated"))) {
+        return true;
+    }
+    if (head.includes("this file was generated") && head.includes("do not edit"))
+        return true;
+    return false;
+}
+function looksLikeMinifiedBundle(content) {
+    if (content.length < 30_000)
+        return false;
+    let lines = 1;
+    let currentLen = 0;
+    let maxLineLen = 0;
+    let longLines = 0;
+    for (let i = 0; i < content.length; i++) {
+        const code = content.charCodeAt(i);
+        if (code === 10 /* \\n */) {
+            if (currentLen > maxLineLen)
+                maxLineLen = currentLen;
+            if (currentLen >= 800)
+                longLines += 1;
+            currentLen = 0;
+            lines += 1;
+            continue;
+        }
+        currentLen += 1;
+    }
+    if (currentLen > maxLineLen)
+        maxLineLen = currentLen;
+    if (currentLen >= 800)
+        longLines += 1;
+    const avgLineLen = content.length / Math.max(1, lines);
+    if (lines <= 2 && maxLineLen >= 2000)
+        return true;
+    if (maxLineLen >= 6000)
+        return true;
+    if (avgLineLen >= 900)
+        return true;
+    if (lines <= 10 && longLines >= Math.ceil(lines * 0.6))
+        return true;
     return false;
 }
 function getContentChunkKind(filePath) {
@@ -853,6 +1074,9 @@ function indexFile(absPath, reason) {
     const indexContent = isContentIndexableFile(absPath);
     if (!indexSymbols && !indexContent)
         return;
+    const kind = getContentChunkKind(absPath);
+    if (!kind)
+        return;
     let stat;
     try {
         stat = fs.statSync(absPath);
@@ -862,7 +1086,8 @@ function indexFile(absPath, reason) {
     }
     if (!stat.isFile())
         return;
-    if (stat.size > 1_000_000)
+    const maxBytes = kind === "code_chunk" ? INDEX_MAX_CODE_BYTES : INDEX_MAX_DOC_BYTES;
+    if (maxBytes > 0 && stat.size > maxBytes)
         return;
     let content;
     try {
@@ -873,7 +1098,19 @@ function indexFile(absPath, reason) {
     }
     if (content.includes("\u0000"))
         return;
+    const ext = path.extname(absPath).toLowerCase();
     const filePath = normalizeToDbPath(absPath);
+    if (INDEX_SKIP_MINIFIED &&
+        kind === "code_chunk" &&
+        (ext === ".js" || ext === ".mjs" || ext === ".cjs" || ext === ".css") &&
+        looksLikeMinifiedBundle(content)) {
+        logActivity("index_skip", { file_path: filePath, reason: "minified_bundle", bytes: stat.size });
+        return;
+    }
+    if (kind === "code_chunk" && stat.size >= 20_000 && looksLikeGeneratedFile(content)) {
+        logActivity("index_skip", { file_path: filePath, reason: "generated_file", bytes: stat.size });
+        return;
+    }
     let symbolCount = 0;
     let chunkCount = 0;
     if (indexSymbols) {
@@ -931,6 +1168,65 @@ const SyncChangeIntentArgsSchema = ProjectRootArgSchema.merge(z.object({
 const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(z.object({
     query: z.string().min(1),
 }));
+const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Pattern to search for. Defaults to regex mode for parity with tools like ripgrep.
+    query: z.string().min(1),
+    mode: z.enum(["regex", "literal"]).optional().default("regex"),
+    // 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.
+    literal_hint: z.string().optional().default(""),
+    // Defaults to code/doc chunks; can be widened if needed.
+    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),
+    max_candidates: z.number().int().min(1).max(50_000).optional(),
+}));
+const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative to project_root, or an absolute path under project_root.
+    path: z.string().min(1),
+    from_line: z.number().int().min(1).optional().default(1),
+    to_line: z.number().int().min(1).optional(),
+    // Convenience for "head": if set, reads from_line..(from_line+total_count-1) unless to_line is provided.
+    total_count: z.number().int().min(1).optional(),
+    // Hard limits to avoid huge token blow-ups.
+    max_lines: z.number().int().min(1).max(2000).optional().default(400),
+    max_chars: z.number().int().min(200).max(200_000).optional().default(20_000),
+}));
+const ReadFileTextArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative to project_root, or an absolute path under project_root.
+    path: z.string().min(1),
+    // Character offset in the decoded UTF-8 text.
+    offset: z.number().int().min(0).optional().default(0),
+    // Hard limit on returned text to avoid huge outputs.
+    max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
+    // Safety guard for raw reads; use read_file_lines on larger files.
+    max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
+}));
+const ReadCodexTextFileArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Absolute path, file:// URI, or a path under CODEX_HOME / AGENTS_HOME allowed roots.
+    path: z.string().min(1),
+    offset: z.number().int().min(0).optional().default(0),
+    max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
+    max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
+}));
+const ListProjectFilesArgsSchema = ProjectRootArgSchema.merge(z.object({
+    // Relative directory/file path under project_root. "." means the project root.
+    path: z.string().optional().default("."),
+    recursive: z.boolean().optional().default(false),
+    max_depth: z.number().int().min(1).max(20).optional().default(4),
+    include_files: z.boolean().optional().default(true),
+    include_dirs: z.boolean().optional().default(true),
+    include_hidden: z.boolean().optional().default(false),
+    respect_ignore: z.boolean().optional().default(true),
+    include_paths: z.array(z.string().min(1)).optional(),
+    exclude_paths: z.array(z.string().min(1)).optional(),
+    extensions: z.array(z.string().min(1)).optional(),
+    max_results: z.number().int().min(1).max(5000).optional().default(200),
+    include_stats: z.boolean().optional().default(false),
+}));
 const UpsertProjectSummaryArgsSchema = ProjectRootArgSchema.merge(z.object({
     summary: z.string().min(1),
 }));
@@ -939,6 +1235,13 @@ const AddNoteArgsSchema = ProjectRootArgSchema.merge(z.object({
     content: z.string().min(1),
     tags: z.array(z.string().min(1)).optional(),
 }));
+const PruneIndexArgsSchema = ProjectRootArgSchema.merge(z.object({
+    dry_run: z.boolean().optional().default(true),
+    prune_ignored_paths: z.boolean().optional().default(true),
+    prune_minified_bundles: z.boolean().optional().default(false),
+    max_files: z.number().int().min(1).max(50_000).optional().default(2000),
+    vacuum: z.boolean().optional().default(false),
+}));
 const UpsertConventionArgsSchema = ProjectRootArgSchema.merge(z.object({
     key: z.string().min(1),
     content: z.string().min(1),
@@ -1220,6 +1523,34 @@ function toMemoryItemPreview(row, includeContent, previewChars, contentMaxChars)
         updated_at: row.updated_at,
     };
 }
+function getBuiltinConventionRows() {
+    return BUILTIN_CONVENTIONS.map((spec, idx) => ({
+        id: -1000 - idx,
+        kind: "convention",
+        title: spec.key,
+        content: spec.content,
+        file_path: null,
+        start_line: null,
+        end_line: null,
+        req_id: null,
+        metadata_json: safeJson({ source: "builtin", key: spec.key, tags: spec.tags ?? [] }),
+        content_hash: sha256Hex(spec.content),
+        created_at: "builtin",
+        updated_at: "builtin",
+    }));
+}
+function getConventionPreviews(conventionsLimit, previewChars, contentMaxChars) {
+    if (conventionsLimit <= 0)
+        return [];
+    const builtin = getBuiltinConventionRows()
+        .map((row) => toMemoryItemPreview(row, false, previewChars, contentMaxChars))
+        .slice(0, conventionsLimit);
+    if (builtin.length >= conventionsLimit)
+        return builtin;
+    const remaining = conventionsLimit - builtin.length;
+    const stored = listConventionsStmt.all(remaining).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+    return [...builtin, ...stored];
+}
 function toRequirementPreview(req, includeContent, previewChars, contentMaxChars) {
     const context = req.context_data ?? null;
     const contextPreview = context ? makePreviewText(context, previewChars) : null;
@@ -1478,18 +1809,357 @@ async function semanticSearchHybridInternal(opts) {
     }
     return likeSearchInternal(opts);
 }
-const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
-    capabilities: { tools: {} },
-    instructions: [
+function escapeRegExp(literal) {
+    return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasUppercaseAscii(s) {
+    return /[A-Z]/.test(s);
+}
+function extractLongestLiteralFromRegex(pattern) {
+    // Best-effort extraction: pull the longest literal run to use as an indexed candidate hint.
+    // This is intentionally conservative; if we can't find a reasonable literal anchor, callers
+    // should pass `literal_hint` or narrow with include_paths.
+    let best = "";
+    let cur = "";
+    let inClass = false;
+    const flush = () => {
+        if (cur.length > best.length)
+            best = cur;
+        cur = "";
+    };
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i] ?? "";
+        if (!ch)
+            break;
+        if (inClass) {
+            // Skip until the closing bracket.
+            if (ch === "]")
+                inClass = false;
+            flush();
+            continue;
+        }
+        if (ch === "[") {
+            inClass = true;
+            flush();
+            continue;
+        }
+        if (ch === "\\") {
+            const next = pattern[i + 1] ?? "";
+            if (!next) {
+                flush();
+                continue;
+            }
+            // Common regex escapes that are NOT literal characters.
+            if (/[dDsSwWbB0-9]/.test(next)) {
+                flush();
+                i += 1;
+                continue;
+            }
+            // Treat \x as literal x (e.g. \( \) \. \\).
+            cur += next;
+            i += 1;
+            continue;
+        }
+        // Regex metacharacters.
+        if (".*+?^$|(){}".includes(ch)) {
+            flush();
+            continue;
+        }
+        cur += ch;
+    }
+    flush();
+    return best;
+}
+function normalizePathNeedle(s) {
+    return s.replace(/\\/g, "/").toLowerCase();
+}
+function passesPathFilters(filePath, includePaths, excludePaths) {
+    const fp = filePath.toLowerCase();
+    if (excludePaths?.length) {
+        for (const raw of excludePaths) {
+            const n = normalizePathNeedle(raw);
+            if (!n)
+                continue;
+            if (fp.includes(n))
+                return false;
+        }
+    }
+    if (includePaths?.length) {
+        for (const raw of includePaths) {
+            const n = normalizePathNeedle(raw);
+            if (!n)
+                continue;
+            if (fp.includes(n))
+                return true;
+        }
+        return false;
+    }
+    return true;
+}
+function buildLineStarts(text) {
+    const starts = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10)
+            starts.push(i + 1); // '\n'
+    }
+    return starts;
+}
+function lineIndexForOffset(lineStarts, offset) {
+    let lo = 0;
+    let hi = lineStarts.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >> 1;
+        const v = lineStarts[mid] ?? 0;
+        if (v <= offset)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return Math.max(0, lo - 1);
+}
+function compileGrepRegex(opts) {
+    const flags = `${opts.caseSensitive ? "" : "i"}gm`;
+    const source = opts.mode === "literal" ? escapeRegExp(opts.query) : opts.query;
+    return new RegExp(source, flags);
+}
+function resolveProjectPathUnderRoot(inputPath, opts = {}) {
+    const normalizedInput = inputPath.trim() || ".";
+    const abs = path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput);
+    const absPath = path.resolve(abs);
+    const root = path.resolve(projectRoot);
+    const rel = path.relative(root, absPath);
+    const insideRoot = rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    if (!insideRoot) {
+        throw new Error(`[VectorMind] Path must be under project_root: ${inputPath}`);
+    }
+    if (rel === "" && !opts.allowRoot) {
+        throw new Error(`[VectorMind] Path must not be the project_root itself: ${inputPath}`);
+    }
+    return {
+        absPath,
+        dbFilePath: rel === "" ? "." : normalizeToDbPath(absPath),
+    };
+}
+function resolveReadPathUnderProjectRoot(inputPath) {
+    return resolveProjectPathUnderRoot(inputPath, { allowRoot: false });
+}
+function resolveCodexTextPath(inputPath) {
+    const trimmed = inputPath.trim();
+    if (!trimmed)
+        throw new Error("[VectorMind] path is required");
+    const uriPath = trimmed.startsWith("file:") ? parseFileUriToPath(trimmed) : null;
+    const absPath = path.resolve(uriPath ?? trimmed);
+    const allowedRoot = getAllowedCodexTextRoots().find((root) => {
+        const rel = path.relative(root, absPath);
+        return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+    });
+    if (!allowedRoot) {
+        throw new Error(`[VectorMind] Path must be under one of the allowed local text roots: ${getAllowedCodexTextRoots().join(", ")}`);
+    }
+    return { absPath, displayPath: absPath, allowedRoot };
+}
+function isHiddenBaseName(name) {
+    return name.startsWith(".") && name !== "." && name !== "..";
+}
+function normalizeExtensionsFilter(values) {
+    if (!values?.length)
+        return null;
+    const normalized = values
+        .map((v) => v.trim().toLowerCase())
+        .filter(Boolean)
+        .map((v) => (v.startsWith(".") ? v : `.${v}`));
+    return normalized.length ? Array.from(new Set(normalized)) : null;
+}
+async function readTextFileLines(opts) {
+    let lineNo = 0;
+    const lines = [];
+    let totalChars = 0;
+    let truncated = false;
+    const stream = fs.createReadStream(opts.absPath, { encoding: "utf8" });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+        for await (const line of rl) {
+            lineNo += 1;
+            if (lineNo < opts.fromLine)
+                continue;
+            if (lineNo > opts.toLine)
+                break;
+            const rendered = `${lineNo}:${line}`;
+            totalChars += rendered.length + 1;
+            if (lines.length >= opts.maxLines || totalChars > opts.maxChars) {
+                truncated = true;
+                break;
+            }
+            lines.push(rendered);
+        }
+    }
+    finally {
+        try {
+            rl.close();
+        }
+        catch { }
+        try {
+            stream.destroy();
+        }
+        catch { }
+    }
+    return { text: lines.join("\n"), returned: lines.length, truncated };
+}
+function readTextFileSlice(opts) {
+    const st = fs.statSync(opts.absPath);
+    if (!st.isFile())
+        throw new Error("Not a file");
+    if (st.size > opts.maxFileBytes) {
+        throw new Error(`File is too large for raw text read (${st.size} bytes > limit ${opts.maxFileBytes}). Use read_file_lines instead.`);
+    }
+    const text = fs.readFileSync(opts.absPath, "utf8");
+    const totalChars = text.length;
+    const safeOffset = Math.min(opts.offset, totalChars);
+    const slice = text.slice(safeOffset, safeOffset + opts.maxChars);
+    const returnedChars = slice.length;
+    const truncated = safeOffset + returnedChars < totalChars;
+    return { text: slice, totalChars, returnedChars, truncated };
+}
+function listProjectFilesInternal(opts) {
+    const entries = [];
+    let scanned = 0;
+    let truncated = false;
+    const pushEntry = (entry) => {
+        if (entries.length >= opts.maxResults) {
+            truncated = true;
+            return;
+        }
+        entries.push(entry);
+    };
+    const startStat = fs.statSync(opts.startAbsPath);
+    if (startStat.isFile()) {
+        const relPath = opts.startDbPath;
+        if ((!opts.respectIgnore || !shouldIgnoreDbFilePath(relPath)) && passesPathFilters(relPath, opts.includePaths, opts.excludePaths)) {
+            const ext = path.extname(relPath).toLowerCase();
+            if (!opts.extensions || opts.extensions.includes(ext)) {
+                pushEntry({
+                    path: relPath,
+                    kind: "file",
+                    depth: 0,
+                    ...(opts.includeStats ? { size: startStat.size, mtime: startStat.mtime.toISOString() } : {}),
+                });
+            }
+        }
+        return { entries, returned: entries.length, scanned: 1, truncated };
+    }
+    const effectiveMaxDepth = opts.recursive ? opts.maxDepth : 1;
+    const stack = [{ absPath: opts.startAbsPath, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            break;
+        let dirEntries;
+        try {
+            dirEntries = fs.readdirSync(current.absPath, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        dirEntries.sort((a, b) => a.name.localeCompare(b.name));
+        for (let idx = dirEntries.length - 1; idx >= 0; idx -= 1) {
+            const child = dirEntries[idx];
+            if (!child)
+                continue;
+            if (!opts.includeHidden && isHiddenBaseName(child.name))
+                continue;
+            const childAbs = path.join(current.absPath, child.name);
+            const childRel = normalizeToDbPath(childAbs);
+            if (opts.respectIgnore && shouldIgnoreDbFilePath(childRel))
+                continue;
+            scanned += 1;
+            const childDepth = current.depth + 1;
+            const matchesPath = passesPathFilters(childRel, opts.includePaths, opts.excludePaths);
+            if (child.isDirectory()) {
+                if (opts.includeDirs && matchesPath) {
+                    let stats = null;
+                    if (opts.includeStats) {
+                        try {
+                            stats = fs.statSync(childAbs);
+                        }
+                        catch {
+                            stats = null;
+                        }
+                    }
+                    pushEntry({
+                        path: childRel,
+                        kind: "dir",
+                        depth: childDepth,
+                        ...(stats ? { size: stats.size, mtime: stats.mtime.toISOString() } : {}),
+                    });
+                    if (truncated)
+                        break;
+                }
+                if (childDepth < effectiveMaxDepth) {
+                    stack.push({ absPath: childAbs, depth: childDepth });
+                }
+                continue;
+            }
+            if (!child.isFile())
+                continue;
+            if (!opts.includeFiles || !matchesPath)
+                continue;
+            const ext = path.extname(childRel).toLowerCase();
+            if (opts.extensions && !opts.extensions.includes(ext))
+                continue;
+            let stats = null;
+            if (opts.includeStats) {
+                try {
+                    stats = fs.statSync(childAbs);
+                }
+                catch {
+                    stats = null;
+                }
+            }
+            pushEntry({
+                path: childRel,
+                kind: "file",
+                depth: childDepth,
+                ...(stats ? { size: stats.size, mtime: stats.mtime.toISOString() } : {}),
+            });
+            if (truncated)
+                break;
+        }
+        if (truncated)
+            break;
+    }
+    entries.sort((a, b) => a.path.localeCompare(b.path));
+    return { entries, returned: entries.length, scanned, truncated };
+}
+function buildServerInstructions() {
+    return [
         "VectorMind MCP is available in this session. Use it to avoid guessing project context.",
+        "This package ships built-in baseline policy. If a client supports MCP instructions, these rules auto-apply as soon as the MCP is installed and connected; no user-side config file is required.",
+        "The write-operation rules below are strict workflow constraints. Do not claim that the environment has real git branch locks, checkout APIs, or file-lock tools unless such tools are actually available in the current client/runtime. If such tools are absent, you must still enforce the same exclusivity semantics through explicit coordination and serialized same-file edits.",
         "Project root resolution order: tool argument project_root (recommended for clients without roots/list), then VECTORMIND_ROOT (avoid hardcoding in global config), then MCP roots/list (best-effort; falls back quickly if unsupported), then process.cwd() (so start your MCP client in the project directory for per-project isolation).",
         "If root_source is fallback, file watching/indexing is disabled (pass project_root to enable per-project tracking).",
         "",
+        "Built-in write-operation policy:",
+        BUILTIN_WRITE_POLICY_INSTRUCTIONS,
+        "",
+        "Built-in task-list / Plan-Lite policy:",
+        BUILTIN_PLAN_LITE_INSTRUCTIONS,
+        "",
+        "Built-in destructive-operation guard policy:",
+        BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS,
+        "",
+        "Built-in architecture and code-organization policy:",
+        BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_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).",
         "  - 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.",
+        "- 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).",
+        "- 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.)",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
@@ -1499,7 +2169,11 @@ const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
         "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
-    ].join("\n"),
+    ].join("\n");
+}
+const server = new Server({ name: SERVER_NAME, version: SERVER_VERSION }, {
+    capabilities: { tools: {} },
+    instructions: buildServerInstructions(),
 });
 async function resolveProjectRootFromMcpRoots() {
     const caps = server.getClientCapabilities();
@@ -1870,6 +2544,13 @@ function initDatabase() {
     });
     // Clean up noisy pending changes recorded by older versions (build artifacts, node_modules, etc).
     prunePendingChanges();
+    // Clean up noisy indexes recorded by older versions (build artifacts, etc).
+    if (INDEX_AUTO_PRUNE_IGNORED) {
+        pruneIgnoredIndexesByPathPatterns();
+    }
+    // Clean up common "file name noise" recorded by older versions.
+    // (These files are ignored by current index rules; keep the DB consistent automatically.)
+    pruneFilenameNoiseIndexes();
 }
 function initWatcher() {
     watcherReady = false;
@@ -2049,6 +2730,31 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Clear the in-memory debug activity log. Enable logging with VECTORMIND_DEBUG_LOG=1.",
                 inputSchema: toJsonSchemaCompat(ClearActivityLogArgsSchema),
             },
+            {
+                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.",
+                inputSchema: toJsonSchemaCompat(GrepArgsSchema),
+            },
+            {
+                name: "list_project_files",
+                description: "AI-friendly, ignore-aware file/directory listing under project_root with bounded output. Prefer this over Get-ChildItem/ls for local repository browsing.",
+                inputSchema: toJsonSchemaCompat(ListProjectFilesArgsSchema),
+            },
+            {
+                name: "read_codex_text_file",
+                description: "Read bounded text from local Codex/agents files such as SKILL.md, prompt files, and rules under CODEX_HOME/AGENTS_HOME. Prefer this over assuming a filesystem MCP resource server exists.",
+                inputSchema: toJsonSchemaCompat(ReadCodexTextFileArgsSchema),
+            },
+            {
+                name: "read_file_lines",
+                description: "Read a specific line range from a file under project_root (with strict size limits). Prefer this over Get-Content for deterministic reads.",
+                inputSchema: toJsonSchemaCompat(ReadFileLinesArgsSchema),
+            },
+            {
+                name: "read_file_text",
+                description: "Read bounded raw UTF-8 text from a file under project_root. Prefer this over Get-Content -Raw for small/medium text files; use read_file_lines for large files or line-specific reads.",
+                inputSchema: toJsonSchemaCompat(ReadFileTextArgsSchema),
+            },
             {
                 name: "query_codebase",
                 description: "Search the symbol index for class/function/type names (or substrings) to locate definitions by file path and signature. Use this when you need to find code—do not guess locations.",
@@ -2074,6 +2780,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Semantic search across the local memory store (requirements, change intents, notes, project summary, and indexed code/doc chunks). Use this to retrieve relevant context instead of guessing.",
                 inputSchema: toJsonSchemaCompat(SemanticSearchArgsSchema),
             },
+            {
+                name: "prune_index",
+                description: "Prune noisy auto-indexed items (code_chunk/doc_chunk + symbols). Useful after tightening ignore rules to shrink the index and improve search relevance.",
+                inputSchema: toJsonSchemaCompat(PruneIndexArgsSchema),
+            },
         ],
     };
 });
@@ -2120,6 +2831,142 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        if (toolName === "prune_index") {
+            const args = PruneIndexArgsSchema.parse(rawArgs);
+            flushPendingChangeBuffer();
+            const result = {
+                ok: true,
+                dry_run: args.dry_run,
+                config: {
+                    index_max_code_bytes: INDEX_MAX_CODE_BYTES,
+                    index_max_doc_bytes: INDEX_MAX_DOC_BYTES,
+                    index_skip_minified: INDEX_SKIP_MINIFIED,
+                    index_auto_prune_ignored: INDEX_AUTO_PRUNE_IGNORED,
+                },
+                pruned: {
+                    ignored_paths: { chunks_deleted: 0, symbols_deleted: 0 },
+                    minified_bundles: { files_matched: 0, chunks_deleted: 0, symbols_deleted: 0 },
+                },
+            };
+            if (args.prune_ignored_paths) {
+                if (!IGNORED_LIKE_PATTERNS.length) {
+                    result.pruned.ignored_paths = { chunks_deleted: 0, symbols_deleted: 0 };
+                }
+                else if (args.dry_run) {
+                    const where = IGNORED_LIKE_PATTERNS
+                        .map(() => "LOWER(REPLACE(file_path, '\\\\', '/')) LIKE ?")
+                        .join(" OR ");
+                    const chunksWould = Number(db
+                        .prepare(`SELECT COUNT(1) AS c
+                   FROM memory_items
+                   WHERE file_path IS NOT NULL
+                     AND (kind = 'code_chunk' OR kind = 'doc_chunk')
+                     AND (${where})`)
+                        .get(...IGNORED_LIKE_PATTERNS)?.c ?? 0);
+                    const symbolsWould = Number(db
+                        .prepare(`SELECT COUNT(1) AS c
+                   FROM symbols
+                   WHERE file_path IS NOT NULL
+                     AND (${where})`)
+                        .get(...IGNORED_LIKE_PATTERNS)?.c ?? 0);
+                    result.pruned.ignored_paths = { chunks_deleted: chunksWould, symbols_deleted: symbolsWould };
+                }
+                else {
+                    result.pruned.ignored_paths = pruneIgnoredIndexesByPathPatterns();
+                }
+            }
+            if (args.prune_minified_bundles) {
+                const maxFiles = args.max_files;
+                const candidates = db
+                    .prepare(`SELECT file_path, content
+             FROM memory_items
+             WHERE kind = 'code_chunk'
+               AND file_path IS NOT NULL
+               AND (
+                 LOWER(file_path) LIKE '%.js'
+                 OR LOWER(file_path) LIKE '%.mjs'
+                 OR LOWER(file_path) LIKE '%.cjs'
+                 OR LOWER(file_path) LIKE '%.css'
+               )
+             ORDER BY updated_at DESC, id DESC
+             LIMIT ?`)
+                    .all(Math.min(50_000, maxFiles * 5));
+                const matched = new Set();
+                for (const row of candidates) {
+                    if (matched.size >= maxFiles)
+                        break;
+                    const fp = row.file_path;
+                    if (!fp || matched.has(fp))
+                        continue;
+                    if (looksLikeMinifiedBundle(row.content))
+                        matched.add(fp);
+                }
+                if (args.dry_run) {
+                    let chunksWould = 0;
+                    let symbolsWould = 0;
+                    const countChunksStmt = db.prepare(`SELECT COUNT(1) AS c
+             FROM memory_items
+             WHERE file_path = ?
+               AND (kind = 'code_chunk' OR kind = 'doc_chunk')`);
+                    const countSymbolsStmt = db.prepare(`SELECT COUNT(1) AS c FROM symbols WHERE file_path = ?`);
+                    for (const fp of matched) {
+                        chunksWould += Number(countChunksStmt.get(fp)?.c ?? 0);
+                        symbolsWould += Number(countSymbolsStmt.get(fp)?.c ?? 0);
+                    }
+                    result.pruned.minified_bundles = {
+                        files_matched: matched.size,
+                        chunks_deleted: chunksWould,
+                        symbols_deleted: symbolsWould,
+                    };
+                }
+                else {
+                    let chunksDeleted = 0;
+                    let symbolsDeleted = 0;
+                    const tx = db.transaction(() => {
+                        for (const fp of matched) {
+                            chunksDeleted += deleteFileChunkItemsStmt.run(fp).changes;
+                            symbolsDeleted += deleteSymbolsForFileStmt.run(fp).changes;
+                        }
+                    });
+                    try {
+                        tx();
+                    }
+                    catch (err) {
+                        console.error("[vectormind] prune minified bundles failed:", err);
+                    }
+                    if (matched.size) {
+                        logActivity("index_prune", {
+                            reason: "minified_bundles",
+                            files_matched: matched.size,
+                            chunks_deleted: chunksDeleted,
+                            symbols_deleted: symbolsDeleted,
+                        });
+                    }
+                    result.pruned.minified_bundles = {
+                        files_matched: matched.size,
+                        chunks_deleted: chunksDeleted,
+                        symbols_deleted: symbolsDeleted,
+                    };
+                }
+            }
+            if (!args.dry_run && args.vacuum) {
+                try {
+                    db.exec("VACUUM");
+                    logActivity("index_prune", { reason: "vacuum" });
+                }
+                catch (err) {
+                    console.error("[vectormind] vacuum failed:", err);
+                }
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson(result),
+                    },
+                ],
+            };
+        }
         if (toolName === "sync_change_intent") {
             const args = SyncChangeIntentArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
@@ -2253,7 +3100,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
-            const conventions = listConventionsStmt.all(conventionsLimit).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+            const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
             const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
@@ -2349,7 +3196,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
-            const conventions = listConventionsStmt.all(conventionsLimit).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
+            const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
             const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
@@ -2578,6 +3425,441 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             clearActivityLog();
             return { content: [{ type: "text", text: toolJson({ ok: true }) }] };
         }
+        if (toolName === "grep") {
+            const args = GrepArgsSchema.parse(rawArgs);
+            const q = args.query;
+            const mode = args.mode;
+            const smartCase = args.smart_case;
+            const kinds = args.kinds?.length ? args.kinds : ["code_chunk", "doc_chunk"];
+            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) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            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.",
+                                query: q,
+                                mode,
+                                literal_hint: args.literal_hint,
+                            }),
+                        },
+                    ],
+                };
+            }
+            const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
+            let re;
+            try {
+                re = compileGrepRegex({ query: q, mode, caseSensitive });
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({ ok: false, error: `Invalid pattern: ${String(err)}`, query: q, mode }),
+                        },
+                    ],
+                };
+            }
+            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", {
+                query: q,
+                mode,
+                case_sensitive: caseSensitive,
+                smart_case: smartCase,
+                hint,
+                kinds,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                candidates: candidates.length,
+                candidates_scanned: candidatesScanned,
+                matches: matches.length,
+                truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            query: q,
+                            mode,
+                            case_sensitive: caseSensitive,
+                            smart_case: smartCase,
+                            hint,
+                            kinds,
+                            include_paths: includePaths ?? [],
+                            exclude_paths: excludePaths ?? [],
+                            candidates: { total: candidates.length, scanned: candidatesScanned },
+                            matches,
+                            truncated,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "list_project_files") {
+            const args = ListProjectFilesArgsSchema.parse(rawArgs);
+            const resolved = resolveProjectPathUnderRoot(args.path, { allowRoot: true });
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `Path not found: ${String(err)}` }) }],
+                };
+            }
+            const includePaths = args.include_paths?.length ? args.include_paths : null;
+            const excludePaths = args.exclude_paths?.length ? args.exclude_paths : null;
+            const extensions = normalizeExtensionsFilter(args.extensions);
+            const result = listProjectFilesInternal({
+                startAbsPath: resolved.absPath,
+                startDbPath: resolved.dbFilePath,
+                recursive: args.recursive,
+                maxDepth: args.max_depth,
+                includeFiles: args.include_files,
+                includeDirs: args.include_dirs,
+                includeHidden: args.include_hidden,
+                respectIgnore: args.respect_ignore,
+                includePaths,
+                excludePaths,
+                extensions,
+                maxResults: args.max_results,
+                includeStats: args.include_stats,
+            });
+            logActivity("list_project_files", {
+                path: resolved.dbFilePath,
+                recursive: args.recursive,
+                max_depth: args.max_depth,
+                include_files: args.include_files,
+                include_dirs: args.include_dirs,
+                include_hidden: args.include_hidden,
+                respect_ignore: args.respect_ignore,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                extensions: extensions ?? [],
+                returned: result.returned,
+                scanned: result.scanned,
+                truncated: result.truncated,
+                path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            path: resolved.dbFilePath,
+                            path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+                            recursive: args.recursive,
+                            max_depth: args.recursive ? args.max_depth : 1,
+                            include_files: args.include_files,
+                            include_dirs: args.include_dirs,
+                            include_hidden: args.include_hidden,
+                            respect_ignore: args.respect_ignore,
+                            include_paths: includePaths ?? [],
+                            exclude_paths: excludePaths ?? [],
+                            extensions: extensions ?? [],
+                            returned: result.returned,
+                            scanned: result.scanned,
+                            truncated: result.truncated,
+                            entries: result.entries,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_file_text") {
+            const args = ReadFileTextArgsSchema.parse(rawArgs);
+            const resolved = resolveReadPathUnderProjectRoot(args.path);
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            let result;
+            try {
+                result = readTextFileSlice({
+                    absPath: resolved.absPath,
+                    offset: args.offset,
+                    maxChars: args.max_chars,
+                    maxFileBytes: args.max_file_bytes,
+                });
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            logActivity("read_file_text", {
+                file_path: resolved.dbFilePath,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.dbFilePath,
+                            offset: args.offset,
+                            returned_chars: result.returnedChars,
+                            total_chars: result.totalChars,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_codex_text_file") {
+            const args = ReadCodexTextFileArgsSchema.parse(rawArgs);
+            let resolved;
+            try {
+                resolved = resolveCodexTextPath(args.path);
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) }],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            let result;
+            try {
+                result = readTextFileSlice({
+                    absPath: resolved.absPath,
+                    offset: args.offset,
+                    maxChars: args.max_chars,
+                    maxFileBytes: args.max_file_bytes,
+                });
+            }
+            catch (err) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: String(err) }) }] };
+            }
+            logActivity("read_codex_text_file", {
+                file_path: resolved.displayPath,
+                allowed_root: resolved.allowedRoot,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.displayPath,
+                            allowed_root: resolved.allowedRoot,
+                            offset: args.offset,
+                            returned_chars: result.returnedChars,
+                            total_chars: result.totalChars,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "read_file_lines") {
+            const args = ReadFileLinesArgsSchema.parse(rawArgs);
+            const resolved = resolveReadPathUnderProjectRoot(args.path);
+            let fromLine = args.from_line;
+            let toLine = args.to_line;
+            if (toLine == null) {
+                const total = args.total_count ?? 200;
+                toLine = fromLine + total - 1;
+            }
+            if (toLine < fromLine) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "to_line must be >= from_line",
+                                path: args.path,
+                                from_line: fromLine,
+                                to_line: toLine,
+                            }),
+                        },
+                    ],
+                };
+            }
+            let st;
+            try {
+                st = fs.statSync(resolved.absPath);
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [
+                        { type: "text", text: toolJson({ ok: false, error: `File not found: ${String(err)}` }) },
+                    ],
+                };
+            }
+            if (!st.isFile()) {
+                return { isError: true, content: [{ type: "text", text: toolJson({ ok: false, error: "Not a file" }) }] };
+            }
+            const maxLines = Math.max(1, Math.min(2000, args.max_lines));
+            const maxChars = Math.max(200, Math.min(200_000, args.max_chars));
+            const result = await readTextFileLines({
+                absPath: resolved.absPath,
+                fromLine,
+                toLine,
+                maxLines,
+                maxChars,
+            });
+            logActivity("read_file_lines", {
+                file_path: resolved.dbFilePath,
+                from_line: fromLine,
+                to_line: toLine,
+                returned: result.returned,
+                truncated: result.truncated,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            file_path: resolved.dbFilePath,
+                            from_line: fromLine,
+                            to_line: toLine,
+                            returned: result.returned,
+                            truncated: result.truncated,
+                            text: result.text,
+                        }),
+                    },
+                ],
+            };
+        }
         if (toolName === "query_codebase") {
             const args = QueryCodebaseArgsSchema.parse(rawArgs);
             const q = args.query.trim();