@coreyuan/vector-mind 1.0.42 → 1.0.48

package/dist/index.js

@@ -14,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_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS, BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
+import { BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS, BUILTIN_DESTRUCTIVE_OPERATION_GUARD_INSTRUCTIONS, BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS, BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS, BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS, BUILTIN_PAYLOAD_GUARD_INSTRUCTIONS, BUILTIN_PLAN_LITE_INSTRUCTIONS, BUILTIN_REQUIREMENT_BOUNDARY_AND_MODULARITY_INSTRUCTIONS, BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.42";
+const SERVER_VERSION = "1.0.48";
 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());
@@ -65,6 +65,42 @@ const PENDING_PRUNE_EVERY = (() => {
         return 500;
     return n;
 })();
+const DEVELOPMENT_WARN_FILE_LINES = (() => {
+    const raw = process.env.VECTORMIND_WARN_FILE_LINES?.trim();
+    if (!raw)
+        return 800;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 100)
+        return 800;
+    return Math.min(50_000, n);
+})();
+const DEVELOPMENT_BLOCK_FILE_LINES = (() => {
+    const raw = process.env.VECTORMIND_BLOCK_FILE_LINES?.trim();
+    if (!raw)
+        return 1200;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < DEVELOPMENT_WARN_FILE_LINES)
+        return Math.max(1200, DEVELOPMENT_WARN_FILE_LINES);
+    return Math.min(100_000, n);
+})();
+const DEVELOPMENT_WARN_FILE_BYTES = (() => {
+    const raw = process.env.VECTORMIND_WARN_FILE_BYTES?.trim();
+    if (!raw)
+        return 120_000;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 10_000)
+        return 120_000;
+    return Math.min(20_000_000, n);
+})();
+const DEVELOPMENT_WARN_PENDING_FILES = (() => {
+    const raw = process.env.VECTORMIND_WARN_PENDING_FILES?.trim();
+    if (!raw)
+        return 12;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 12;
+    return Math.min(500, n);
+})();
 const RIPGREP_RESOLVE_TIMEOUT_MS = 5_000;
 const RIPGREP_SEARCH_TIMEOUT_MS = 30_000;
 const RIPGREP_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
@@ -122,6 +158,48 @@ const INDEX_AUTO_PRUNE_IGNORED = (() => {
         return true;
     return ["1", "true", "on", "yes"].includes(raw);
 })();
+const MAINTENANCE_AUTO_ENABLED = (() => {
+    const raw = (process.env.VECTORMIND_MAINTENANCE_AUTO ?? "").trim().toLowerCase();
+    if (!raw)
+        return true;
+    return ["1", "true", "on", "yes"].includes(raw);
+})();
+const MAINTENANCE_INTERVAL_HOURS = (() => {
+    const raw = process.env.VECTORMIND_MAINTENANCE_INTERVAL_HOURS?.trim();
+    if (!raw)
+        return 24;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 24;
+    return Math.min(24 * 30, n);
+})();
+const MAINTENANCE_COMPACT_AFTER_DAYS = (() => {
+    const raw = process.env.VECTORMIND_COMPACT_AFTER_DAYS?.trim();
+    if (!raw)
+        return 45;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 45;
+    return Math.min(3650, n);
+})();
+const MAINTENANCE_MAX_MEMORY_ITEMS = (() => {
+    const raw = process.env.VECTORMIND_MAINTENANCE_MAX_MEMORY_ITEMS?.trim();
+    if (!raw)
+        return 250;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 250;
+    return Math.min(5000, n);
+})();
+const MAINTENANCE_MAX_INDEX_FILES = (() => {
+    const raw = process.env.VECTORMIND_MAINTENANCE_MAX_INDEX_FILES?.trim();
+    if (!raw)
+        return 1500;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+        return 1500;
+    return Math.min(50_000, n);
+})();
 const ROOTS_LIST_TIMEOUT_MS = (() => {
     const raw = process.env.VECTORMIND_ROOTS_TIMEOUT_MS?.trim();
     if (!raw)
@@ -140,6 +218,15 @@ const BOOTSTRAP_SEMANTIC_TIMEOUT_MS = (() => {
         return 2500;
     return n;
 })();
+const SEMANTIC_EMBEDDINGS_TIMEOUT_MS = (() => {
+    const raw = process.env.VECTORMIND_EMBEDDINGS_TIMEOUT_MS?.trim();
+    if (!raw)
+        return 1500;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return 1500;
+    return n;
+})();
 let initialized = false;
 let rootSource = "cwd";
 let projectRoot = "";
@@ -150,6 +237,7 @@ let watcherReady = false;
 let initializationPromise = null;
 let insertRequirementStmt;
 let getActiveRequirementStmt;
+let listActiveRequirementsStmt;
 let listRecentRequirementsStmt;
 let completeAllActiveRequirementsStmt;
 let completeRequirementByIdStmt;
@@ -170,6 +258,7 @@ let listCurrentDecisionsStmt;
 let upsertProjectSummaryStmt;
 let getProjectSummaryStmt;
 let listRecentNotesStmt;
+let listRecentContextItemsStmt;
 let getLatestChangeIntentForFileStmt;
 let deleteFileChunkItemsStmt;
 let getEmbeddingMetaStmt;
@@ -189,6 +278,8 @@ let insertTokenSavingsStmt;
 let summarizeTokenSavingsStmt;
 let summarizeTokenSavingsByToolStmt;
 let listRecentTokenSavingsStmt;
+let getKvStmt;
+let setKvStmt;
 let indexFileSymbolsTx = null;
 let activitySeq = 0;
 const activityLog = [];
@@ -284,6 +375,8 @@ function summarizeActivityEvent(e) {
             return `sync_change_intent #${String(d.req_id ?? "")} files=${String(d.files_total ?? "")}`;
         case "complete_requirement":
             return `complete_requirement ${String(d.all_active ? "all_active" : d.req_id ?? "")}`;
+        case "memory_maintenance":
+            return `memory_maintenance trigger=${String(d.trigger ?? "")} compacted=${String(d.compacted ?? "")} stale=${String(d.stale_files ?? "")} chunks_deleted=${String(d.chunks_deleted ?? "")}`;
         default:
             return e.type;
     }
@@ -723,9 +816,9 @@ function pruneFilenameNoiseIndexes() {
         return { chunks_deleted: 0, symbols_deleted: 0 };
     try {
         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 baseWhere = NOISE_FILE_BASENAMES.map(() => "(LOWER(file_path) = ? OR LOWER(file_path) LIKE ?)").join(" OR ");
         const suffixArgs = NOISE_FILE_SUFFIXES.map((s) => `%${s}`);
-        const baseArgs = NOISE_FILE_BASENAMES.map((n) => `%/${n}`);
+        const baseArgs = NOISE_FILE_BASENAMES.flatMap((n) => [n, `%/${n}`]);
         const whereParts = [];
         const args = [];
         if (suffixWhere) {
@@ -764,6 +857,446 @@ function pruneFilenameNoiseIndexes() {
         return { chunks_deleted: 0, symbols_deleted: 0 };
     }
 }
+function kvGet(key) {
+    try {
+        const row = getKvStmt?.get(key);
+        return row?.value ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function kvSet(key, value) {
+    try {
+        setKvStmt?.run(key, value);
+    }
+    catch (err) {
+        console.error("[vectormind] kv set failed:", err);
+    }
+}
+function distinctChunkAndSymbolFilePaths(limit) {
+    const rows = db
+        .prepare(`SELECT file_path
+       FROM (
+         SELECT file_path, MAX(updated_at) AS updated_at
+         FROM memory_items
+         WHERE file_path IS NOT NULL
+           AND (kind = 'code_chunk' OR kind = 'doc_chunk')
+         GROUP BY file_path
+         UNION
+         SELECT file_path, CURRENT_TIMESTAMP AS updated_at
+         FROM symbols
+         WHERE file_path IS NOT NULL
+         GROUP BY file_path
+       )
+       WHERE file_path IS NOT NULL
+       ORDER BY updated_at ASC
+       LIMIT ?`)
+        .all(limit);
+    return Array.from(new Set(rows.map((r) => r.file_path).filter(Boolean)));
+}
+function classifyStaleIndexFile(filePath) {
+    if (!filePath)
+        return "empty_path";
+    if (shouldIgnoreDbFilePath(filePath))
+        return "ignored_path";
+    if (shouldIgnoreContentFile(filePath))
+        return "filename_noise";
+    const absPath = path.isAbsolute(filePath) ? filePath : path.join(projectRoot, filePath);
+    const rel = path.relative(projectRoot, absPath);
+    if (rel.startsWith("..") || path.isAbsolute(rel))
+        return "outside_project";
+    let stat;
+    try {
+        stat = fs.statSync(absPath);
+    }
+    catch {
+        return "missing_file";
+    }
+    if (!stat.isFile())
+        return "not_file";
+    if (!isContentIndexableFile(absPath) && !isSymbolIndexableFile(absPath))
+        return "not_indexable";
+    return null;
+}
+function pruneStaleFileIndexes(opts) {
+    const filePaths = distinctChunkAndSymbolFilePaths(Math.min(50_000, opts.maxIndexFiles * 3));
+    const matched = [];
+    for (const fp of filePaths) {
+        if (matched.length >= opts.maxIndexFiles)
+            break;
+        const reason = classifyStaleIndexFile(fp);
+        if (reason)
+            matched.push({ file_path: fp, reason });
+    }
+    let chunksDeleted = 0;
+    let symbolsDeleted = 0;
+    const samples = matched.slice(0, 20).map((m) => `${m.file_path} (${m.reason})`);
+    if (!opts.dryRun && matched.length) {
+        const tx = db.transaction(() => {
+            for (const m of matched) {
+                chunksDeleted += deleteFileChunkItemsStmt.run(m.file_path).changes;
+                symbolsDeleted += deleteSymbolsForFileStmt.run(m.file_path).changes;
+            }
+        });
+        try {
+            tx();
+        }
+        catch (err) {
+            console.error("[vectormind] prune stale indexes failed:", err);
+        }
+    }
+    else if (opts.dryRun && matched.length) {
+        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 m of matched) {
+            chunksDeleted += Number(countChunksStmt.get(m.file_path)?.c ?? 0);
+            symbolsDeleted += Number(countSymbolsStmt.get(m.file_path)?.c ?? 0);
+        }
+    }
+    if (!opts.dryRun && (chunksDeleted || symbolsDeleted)) {
+        logActivity("index_prune", {
+            reason: "stale_files",
+            files_matched: matched.length,
+            chunks_deleted: chunksDeleted,
+            symbols_deleted: symbolsDeleted,
+            samples,
+        });
+    }
+    return {
+        files_checked: filePaths.length,
+        files_matched: matched.length,
+        chunks_deleted: chunksDeleted,
+        symbols_deleted: symbolsDeleted,
+        samples,
+    };
+}
+function countIgnoredIndexDeletes() {
+    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 = 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 symbolsDeleted = Number(db
+        .prepare(`SELECT COUNT(1) AS c
+           FROM symbols
+           WHERE file_path IS NOT NULL
+             AND (${where})`)
+        .get(...IGNORED_LIKE_PATTERNS)?.c ?? 0);
+    return { chunks_deleted: chunksDeleted, symbols_deleted: symbolsDeleted };
+}
+function countFilenameNoiseIndexDeletes() {
+    const suffixWhere = NOISE_FILE_SUFFIXES.map(() => "LOWER(file_path) LIKE ?").join(" OR ");
+    const baseWhere = NOISE_FILE_BASENAMES.map(() => "(LOWER(file_path) = ? OR LOWER(file_path) LIKE ?)").join(" OR ");
+    const suffixArgs = NOISE_FILE_SUFFIXES.map((s) => `%${s}`);
+    const baseArgs = NOISE_FILE_BASENAMES.flatMap((n) => [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 = 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(...args)?.c ?? 0);
+    const symbolsDeleted = Number(db
+        .prepare(`SELECT COUNT(1) AS c
+           FROM symbols
+           WHERE file_path IS NOT NULL
+             AND (${where})`)
+        .get(...args)?.c ?? 0);
+    return { chunks_deleted: chunksDeleted, symbols_deleted: symbolsDeleted };
+}
+function hiddenEmbeddingIds(limit = 10_000) {
+    const rows = db
+        .prepare(`SELECT e.memory_id AS memory_id, m.metadata_json AS metadata_json
+       FROM embeddings e
+       JOIN memory_items m ON m.id = e.memory_id
+       WHERE m.metadata_json LIKE '%compacted%'
+          OR m.metadata_json LIKE '%superseded%'
+       LIMIT ?`)
+        .all(limit);
+    return rows
+        .filter((r) => isHiddenFromDefaultRecall({ metadata_json: r.metadata_json }))
+        .map((r) => r.memory_id);
+}
+function pruneHiddenEmbeddings(dryRun) {
+    const ids = hiddenEmbeddingIds();
+    if (!ids.length)
+        return { embeddings_deleted: 0 };
+    if (!dryRun) {
+        const deleteStmt = db.prepare(`DELETE FROM embeddings WHERE memory_id = ?`);
+        const tx = db.transaction(() => {
+            for (const id of ids)
+                deleteStmt.run(id);
+        });
+        try {
+            tx();
+        }
+        catch (err) {
+            console.error("[vectormind] prune hidden embeddings failed:", err);
+        }
+    }
+    return { embeddings_deleted: ids.length };
+}
+function selectCompactionCandidates(opts) {
+    const kinds = opts.compactNotes
+        ? ["requirement", "change_intent", "note"]
+        : ["requirement", "change_intent"];
+    const placeholders = kinds.map(() => "?").join(", ");
+    const rows = db
+        .prepare(`SELECT
+         m.id, m.kind, m.title, m.content, m.file_path, m.start_line, m.end_line,
+         m.req_id, m.metadata_json, m.content_hash, m.created_at, m.updated_at,
+         r.status AS req_status
+       FROM memory_items m
+       LEFT JOIN requirements r ON r.id = m.req_id
+       WHERE m.kind IN (${placeholders})
+         AND m.updated_at < datetime('now', ?)
+       ORDER BY m.updated_at ASC, m.id ASC
+       LIMIT ?`)
+        .all(...kinds, `-${opts.compactAfterDays} days`, Math.min(20_000, opts.maxMemoryItems * 5));
+    return rows
+        .filter((row) => !isHiddenFromDefaultRecall(row))
+        .filter((row) => metadataStatus(row) !== "current" && metadataStatus(row) !== "active")
+        .filter((row) => row.req_status !== "active")
+        .filter((row) => row.kind !== "note" || opts.compactNotes)
+        .slice(0, opts.maxMemoryItems);
+}
+function compactionLine(row) {
+    const date = oneLine(row.updated_at || row.created_at, 19);
+    const title = row.title ? ` ${oneLine(row.title, 80)}` : "";
+    const file = row.file_path ? ` file=${row.file_path}${row.start_line != null ? `:${row.start_line}` : ""}` : "";
+    const req = row.req_id != null ? ` req#${row.req_id}` : "";
+    return `- ${date} #${row.id} ${row.kind}${req}${file}${title}: ${oneLine(row.content, 220)}`;
+}
+function compactOldMemoryItems(opts) {
+    const candidates = selectCompactionCandidates(opts);
+    const cutoff = new Date(Date.now() - opts.compactAfterDays * 86_400_000).toISOString();
+    const samples = candidates.slice(0, 20).map((row) => ({
+        id: row.id,
+        kind: row.kind,
+        title: row.title,
+        file_path: row.file_path,
+        updated_at: row.updated_at,
+    }));
+    if (opts.dryRun || !candidates.length) {
+        return {
+            cutoff,
+            candidates: candidates.length,
+            compacted: 0,
+            summary_memory_id: null,
+            archived: 0,
+            samples,
+        };
+    }
+    const now = new Date().toISOString();
+    const lines = [
+        `Auto-compacted ${candidates.length} old VectorMind memory items.`,
+        `Cutoff: items updated before ${cutoff} (${opts.compactAfterDays} days).`,
+        "",
+        "This compact summary keeps old history searchable while detailed stale items are hidden from default recall.",
+        "Durable decisions, conventions, and project summaries are never compacted by this automatic pass.",
+        "",
+        ...candidates.map(compactionLine),
+    ];
+    const content = lines.join("\n");
+    const title = `Memory compaction ${now.slice(0, 10)}`;
+    const metadata = {
+        source: "maintenance",
+        status: "current",
+        compacted_item_ids: candidates.map((c) => c.id),
+        compact_after_days: opts.compactAfterDays,
+        compact_notes: opts.compactNotes,
+        generated_at: now,
+    };
+    let summaryMemoryId = 0;
+    let archived = 0;
+    const archiveStmt = db.prepare(`INSERT OR IGNORE INTO memory_item_archive
+       (memory_id, original_kind, original_title, original_content, original_file_path,
+        original_start_line, original_end_line, original_req_id, original_metadata_json,
+        original_content_hash, original_created_at, original_updated_at, archive_reason, compacted_into_id)
+     VALUES
+       (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    const updateMemoryStmt = db.prepare(`UPDATE memory_items
+     SET content = ?, metadata_json = ?, content_hash = ?, updated_at = CURRENT_TIMESTAMP
+     WHERE id = ?`);
+    const deleteEmbeddingStmt = db.prepare(`DELETE FROM embeddings WHERE memory_id = ?`);
+    const tx = db.transaction(() => {
+        const info = insertMemoryItemStmt.run("memory_compaction", title, content, null, null, null, null, safeJson(metadata), sha256Hex(content));
+        summaryMemoryId = Number(info.lastInsertRowid);
+        for (const row of candidates) {
+            const archiveInfo = archiveStmt.run(row.id, row.kind, row.title, row.content, row.file_path, row.start_line, row.end_line, row.req_id, row.metadata_json, row.content_hash, row.created_at, row.updated_at, "auto_compaction", summaryMemoryId);
+            if (archiveInfo.changes > 0)
+                archived += 1;
+            const patchedMeta = {
+                ...parseMetadataJson(row.metadata_json),
+                status: "compacted",
+                compacted: true,
+                compacted_at: now,
+                compacted_into_memory_id: summaryMemoryId,
+            };
+            const stub = [
+                `[compacted into memory item #${summaryMemoryId}]`,
+                `Original ${row.kind} #${row.id} was older than ${opts.compactAfterDays} days and is excluded from default recall.`,
+                `Summary: ${oneLine(row.title || row.content, 260)}`,
+            ].join("\n");
+            updateMemoryStmt.run(stub, safeJson(patchedMeta), sha256Hex(stub), row.id);
+            deleteEmbeddingStmt.run(row.id);
+        }
+    });
+    try {
+        tx();
+        if (summaryMemoryId)
+            enqueueEmbedding(summaryMemoryId);
+    }
+    catch (err) {
+        console.error("[vectormind] compact old memory failed:", err);
+        summaryMemoryId = 0;
+    }
+    if (summaryMemoryId) {
+        logActivity("memory_maintenance", {
+            reason: "compact_old_memories",
+            compacted: candidates.length,
+            summary_memory_id: summaryMemoryId,
+            archived,
+        });
+    }
+    return {
+        cutoff,
+        candidates: candidates.length,
+        compacted: summaryMemoryId ? candidates.length : 0,
+        summary_memory_id: summaryMemoryId || null,
+        archived,
+        samples,
+    };
+}
+function runMemoryMaintenance(args, trigger = "manual") {
+    const compactedMemory = args.compact_old_memories
+        ? compactOldMemoryItems({
+            dryRun: args.dry_run,
+            compactAfterDays: args.compact_after_days,
+            maxMemoryItems: args.max_memory_items,
+            compactNotes: args.compact_notes,
+        })
+        : {
+            cutoff: new Date(Date.now() - args.compact_after_days * 86_400_000).toISOString(),
+            candidates: 0,
+            compacted: 0,
+            summary_memory_id: null,
+            archived: 0,
+            samples: [],
+        };
+    const ignoredPaths = args.prune_ignored_paths
+        ? args.dry_run
+            ? countIgnoredIndexDeletes()
+            : pruneIgnoredIndexesByPathPatterns()
+        : { chunks_deleted: 0, symbols_deleted: 0 };
+    const filenameNoise = args.prune_filename_noise
+        ? args.dry_run
+            ? countFilenameNoiseIndexDeletes()
+            : pruneFilenameNoiseIndexes()
+        : { chunks_deleted: 0, symbols_deleted: 0 };
+    const staleFiles = args.prune_stale_indexes
+        ? pruneStaleFileIndexes({ dryRun: args.dry_run, maxIndexFiles: args.max_index_files })
+        : { files_checked: 0, files_matched: 0, chunks_deleted: 0, symbols_deleted: 0, samples: [] };
+    const hiddenEmbeddings = args.prune_hidden_embeddings
+        ? pruneHiddenEmbeddings(args.dry_run)
+        : { embeddings_deleted: 0 };
+    let vacuumed = false;
+    if (!args.dry_run && args.vacuum) {
+        try {
+            db.exec("VACUUM");
+            vacuumed = true;
+        }
+        catch (err) {
+            console.error("[vectormind] maintenance vacuum failed:", err);
+        }
+    }
+    const result = {
+        ok: true,
+        dry_run: args.dry_run,
+        trigger,
+        generated_at: new Date().toISOString(),
+        project_root: projectRoot,
+        db_path: dbPath,
+        config: {
+            compact_after_days: args.compact_after_days,
+            max_memory_items: args.max_memory_items,
+            max_index_files: args.max_index_files,
+            compact_notes: args.compact_notes,
+        },
+        compacted_memory: compactedMemory,
+        pruned: {
+            ignored_paths: ignoredPaths,
+            filename_noise: filenameNoise,
+            stale_files: staleFiles,
+            hidden_embeddings: hiddenEmbeddings,
+        },
+        vacuumed,
+    };
+    logActivity("memory_maintenance", {
+        trigger,
+        dry_run: args.dry_run,
+        compacted: result.compacted_memory.compacted,
+        stale_files: result.pruned.stale_files.files_matched,
+        chunks_deleted: result.pruned.ignored_paths.chunks_deleted +
+            result.pruned.filename_noise.chunks_deleted +
+            result.pruned.stale_files.chunks_deleted,
+    });
+    return result;
+}
+function runAutoMaintenanceIfDue() {
+    if (!MAINTENANCE_AUTO_ENABLED || !db)
+        return;
+    const lastRaw = kvGet("maintenance.last_auto_at");
+    const last = lastRaw ? Date.parse(lastRaw) : 0;
+    const dueMs = MAINTENANCE_INTERVAL_HOURS * 3_600_000;
+    if (Number.isFinite(last) && last > 0 && Date.now() - last < dueMs)
+        return;
+    try {
+        runMemoryMaintenance({
+            project_root: projectRoot,
+            dry_run: false,
+            format: "compact",
+            compact_old_memories: true,
+            compact_notes: false,
+            prune_stale_indexes: true,
+            prune_ignored_paths: true,
+            prune_filename_noise: true,
+            prune_hidden_embeddings: true,
+            compact_after_days: MAINTENANCE_COMPACT_AFTER_DAYS,
+            max_memory_items: MAINTENANCE_MAX_MEMORY_ITEMS,
+            max_index_files: MAINTENANCE_MAX_INDEX_FILES,
+            vacuum: false,
+        }, "auto");
+        kvSet("maintenance.last_auto_at", new Date().toISOString());
+    }
+    catch (err) {
+        console.error("[vectormind] auto maintenance failed:", err);
+    }
+}
 function shouldIgnorePath(inputPath) {
     const normalizedAbs = path.resolve(inputPath);
     const rel = path.relative(projectRoot, normalizedAbs);
@@ -887,6 +1420,416 @@ function isContentIndexableFile(filePath) {
         return false;
     return getContentChunkKind(filePath) !== null;
 }
+function isLikelySourceImplementationFile(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    return new Set([
+        ".ts",
+        ".tsx",
+        ".js",
+        ".jsx",
+        ".mjs",
+        ".cjs",
+        ".py",
+        ".go",
+        ".rs",
+        ".java",
+        ".kt",
+        ".cs",
+        ".c",
+        ".cc",
+        ".cpp",
+        ".h",
+        ".hpp",
+        ".vue",
+        ".svelte",
+    ]).has(ext);
+}
+function countFileLinesBounded(absPath, maxBytes) {
+    let stat;
+    try {
+        stat = fs.statSync(absPath);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    const bytesToRead = Math.min(stat.size, maxBytes);
+    const fd = fs.openSync(absPath, "r");
+    try {
+        const buffer = Buffer.alloc(bytesToRead);
+        const read = fs.readSync(fd, buffer, 0, bytesToRead, 0);
+        let lines = read > 0 ? 1 : 0;
+        for (let i = 0; i < read; i++) {
+            if (buffer[i] === 10)
+                lines += 1;
+        }
+        return { lines, truncated: stat.size > bytesToRead };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function isPathInsideProjectRoot(absPath) {
+    const root = path.resolve(projectRoot);
+    const rel = path.relative(root, path.resolve(absPath));
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function checkPathScope(inputPath) {
+    const normalizedInput = inputPath.trim() || ".";
+    const absPath = path.resolve(path.isAbsolute(normalizedInput) ? normalizedInput : path.join(projectRoot, normalizedInput));
+    return {
+        input_path: inputPath,
+        abs_path: absPath,
+        in_project: isPathInsideProjectRoot(absPath),
+        project_root: path.resolve(projectRoot),
+    };
+}
+function buildCrossProjectPathWarnings(paths) {
+    const checks = (paths ?? []).map((p) => checkPathScope(p)).filter((c) => !c.in_project);
+    if (!checks.length)
+        return [];
+    return [
+        {
+            code: "cross_project_path",
+            severity: "warning",
+            message: "A path points outside the current project_root. Switch project_root intentionally before reading/searching another repo; do not mix unrelated project context into the current requirement.",
+            files: checks.slice(0, 10).map((c) => c.input_path),
+            details: {
+                project_root: path.resolve(projectRoot),
+                paths: checks.slice(0, 10),
+                total_paths: checks.length,
+            },
+        },
+    ];
+}
+function buildFileReadDevelopmentWarnings(filePath, absPath, stat) {
+    const warnings = [];
+    if (!isPathInsideProjectRoot(absPath)) {
+        warnings.push(...buildCrossProjectPathWarnings([filePath]));
+        return warnings;
+    }
+    if (!isLikelySourceImplementationFile(filePath))
+        return warnings;
+    let st = stat;
+    try {
+        st ??= fs.statSync(absPath);
+    }
+    catch {
+        return warnings;
+    }
+    if (!st.isFile())
+        return warnings;
+    const lineInfo = countFileLinesBounded(absPath, 2_000_000);
+    const lineCount = lineInfo?.lines ?? 0;
+    const tooManyLines = lineCount >= DEVELOPMENT_BLOCK_FILE_LINES;
+    const warnLines = lineCount >= DEVELOPMENT_WARN_FILE_LINES;
+    const warnBytes = st.size >= DEVELOPMENT_WARN_FILE_BYTES;
+    if (!tooManyLines && !warnLines && !warnBytes)
+        return warnings;
+    warnings.push({
+        code: "large_file_read",
+        severity: tooManyLines ? "blocker" : "warning",
+        message: tooManyLines
+            ? "You are reading a very large implementation file. Do not keep patching new feature code into it; identify a narrow function and split new behavior into focused modules unless this task is explicitly a planned extraction."
+            : "You are reading a large implementation file. Keep the target narrow and prefer extracting focused modules before adding responsibilities.",
+        files: [filePath],
+        details: {
+            lines: lineInfo?.truncated ? `${lineCount}+` : lineCount,
+            bytes: st.size,
+            warn_lines: DEVELOPMENT_WARN_FILE_LINES,
+            block_lines: DEVELOPMENT_BLOCK_FILE_LINES,
+            warn_bytes: DEVELOPMENT_WARN_FILE_BYTES,
+        },
+    });
+    return warnings;
+}
+function buildMatchedFileDevelopmentWarnings(filePaths) {
+    const seen = new Set();
+    const warnings = [];
+    for (const fp of filePaths) {
+        if (!fp || seen.has(fp))
+            continue;
+        seen.add(fp);
+        const abs = path.isAbsolute(fp) ? path.resolve(fp) : path.join(projectRoot, fp);
+        warnings.push(...buildFileReadDevelopmentWarnings(normalizeToDbPath(fp), abs));
+        if (warnings.length >= 8)
+            break;
+    }
+    return warnings;
+}
+function buildRequirementStartWarnings(args) {
+    const warnings = [];
+    const activeReqs = listActiveRequirementsStmt.all(10);
+    if (!args.close_previous && activeReqs.length > 0) {
+        warnings.push({
+            code: "multiple_active_requirements",
+            severity: "warning",
+            message: "Starting a requirement without closing previous active requirements can mix unrelated context. Only keep multiple active requirements when the user explicitly asked for parallel work.",
+            details: {
+                active_requirements: activeReqs.slice(0, 5).map((r) => ({ id: r.id, title: r.title, status: r.status })),
+            },
+        });
+    }
+    const text = `${args.title}\n${args.background}`.toLowerCase();
+    const broadTerms = [
+        "顺便",
+        "一起",
+        "所有",
+        "全部",
+        "整体",
+        "重构",
+        "统一",
+        "优化一下",
+        "顺手",
+        "相关的",
+        "all ",
+        "everything",
+        "refactor",
+        "cleanup",
+        "clean up",
+    ];
+    const matched = broadTerms.filter((term) => text.includes(term));
+    if (matched.length >= 2 || text.length > 1800) {
+        warnings.push({
+            code: "broad_requirement_scope",
+            severity: "warning",
+            message: "The requirement wording looks broad. Treat the current user request as the only boundary; do not add extra workflows, fields, pages, interfaces, or touch completed related features unless explicitly required.",
+            details: { matched_terms: matched.slice(0, 10), text_length: text.length },
+        });
+    }
+    return warnings;
+}
+function normalizeScopeTerms(values) {
+    return Array.from(new Set((values ?? []).map((v) => v.trim()).filter(Boolean)));
+}
+function buildRequirementScopeContract(args) {
+    const allowTerms = normalizeScopeTerms(args.scope_allow);
+    const denyTerms = normalizeScopeTerms(args.scope_deny);
+    const allowedPaths = normalizeScopeTerms(args.allowed_paths).map(normalizeToDbPath);
+    const deniedPaths = normalizeScopeTerms(args.denied_paths).map((p) => p.replace(/\\/g, "/"));
+    return {
+        allow_terms: allowTerms,
+        deny_terms: Array.from(new Set(denyTerms)),
+        allowed_paths: Array.from(new Set(allowedPaths)),
+        denied_paths: Array.from(new Set(deniedPaths)),
+        inferred_from: [],
+    };
+}
+function getRequirementScopeContract(reqId) {
+    const memId = getRequirementMemoryItemIdStmt.get(reqId)?.id;
+    if (memId == null)
+        return null;
+    const row = getMemoryItemByIdStmt.get(memId);
+    const meta = parseMetadataJson(row?.metadata_json);
+    const raw = meta.scope_contract;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const obj = raw;
+    return {
+        allow_terms: Array.isArray(obj.allow_terms) ? obj.allow_terms.filter((v) => typeof v === "string") : [],
+        deny_terms: Array.isArray(obj.deny_terms) ? obj.deny_terms.filter((v) => typeof v === "string") : [],
+        allowed_paths: Array.isArray(obj.allowed_paths) ? obj.allowed_paths.filter((v) => typeof v === "string") : [],
+        denied_paths: Array.isArray(obj.denied_paths) ? obj.denied_paths.filter((v) => typeof v === "string") : [],
+        inferred_from: Array.isArray(obj.inferred_from) ? obj.inferred_from.filter((v) => typeof v === "string") : [],
+    };
+}
+function wildcardToRegex(pattern) {
+    const source = escapeRegExp(pattern).replace(/\\\*/g, ".*");
+    return new RegExp(source, "i");
+}
+function pathMatchesAnyPattern(filePath, patterns) {
+    const normalized = filePath.replace(/\\/g, "/");
+    return patterns.filter((p) => wildcardToRegex(p.replace(/\\/g, "/")).test(normalized));
+}
+function fileContentHasDeniedTerms(filePath, terms) {
+    if (!terms.length || filePath === "(unspecified)")
+        return [];
+    const abs = path.isAbsolute(filePath) ? path.resolve(filePath) : path.join(projectRoot, filePath);
+    let st;
+    try {
+        st = fs.statSync(abs);
+    }
+    catch {
+        return [];
+    }
+    if (!st.isFile() || st.size > 2_000_000)
+        return [];
+    let content = "";
+    try {
+        content = fs.readFileSync(abs, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const lower = `${filePath}\n${content.slice(0, 250_000)}`.toLowerCase();
+    return terms.filter((term) => lower.includes(term.toLowerCase()));
+}
+function mergeScopeContracts(base, extra) {
+    if (!base && !extra)
+        return null;
+    return {
+        allow_terms: Array.from(new Set([...(base?.allow_terms ?? []), ...(extra?.allow_terms ?? [])])),
+        deny_terms: Array.from(new Set([...(base?.deny_terms ?? []), ...(extra?.deny_terms ?? [])])),
+        allowed_paths: Array.from(new Set([...(base?.allowed_paths ?? []), ...(extra?.allowed_paths ?? [])])),
+        denied_paths: Array.from(new Set([...(base?.denied_paths ?? []), ...(extra?.denied_paths ?? [])])),
+        inferred_from: Array.from(new Set([...(base?.inferred_from ?? []), ...(extra?.inferred_from ?? [])])),
+    };
+}
+function buildScopeDriftWarnings(args) {
+    const requirementContract = args.requirement ? getRequirementScopeContract(args.requirement.id) : null;
+    const contract = mergeScopeContracts(requirementContract, args.contract);
+    const hasScopeRules = !!contract && (contract.allow_terms.length > 0 ||
+        contract.deny_terms.length > 0 ||
+        contract.allowed_paths.length > 0 ||
+        contract.denied_paths.length > 0);
+    const warnings = [];
+    if (!contract || !hasScopeRules) {
+        if (args.includeMissingContractHint && args.files.length > 0) {
+            warnings.push({
+                code: "scope_contract_missing",
+                severity: "warning",
+                message: "No explicit scope allow/deny contract is set for this requirement, so the planned files cannot be proven in-scope before editing. Define scope_allow/scope_deny or allowed_paths/denied_paths before editing.",
+                files: args.files.map((f) => normalizeToDbPath(f.file_path)).slice(0, 12),
+                details: {
+                    requirement_id: args.requirement?.id ?? null,
+                    requirement_title: args.requirement?.title ?? null,
+                },
+            });
+        }
+        return warnings;
+    }
+    const allowTerms = contract.allow_terms;
+    const denyTerms = contract.deny_terms;
+    const allowedPaths = contract.allowed_paths;
+    const deniedPaths = contract.denied_paths;
+    const intentText = args.intent ?? "";
+    const intentDenied = denyTerms.filter((term) => intentText.toLowerCase().includes(term.toLowerCase()));
+    const suspicious = [];
+    for (const f of args.files) {
+        const fp = normalizeToDbPath(f.file_path);
+        if (fp === "(unspecified)")
+            continue;
+        const matchedDeniedPaths = pathMatchesAnyPattern(fp, deniedPaths);
+        const matchedDeniedTerms = [
+            ...denyTerms.filter((term) => fp.toLowerCase().includes(term.toLowerCase())),
+            ...fileContentHasDeniedTerms(fp, denyTerms),
+        ];
+        const isExplicitlyAllowed = pathMatchesAnyPattern(fp, allowedPaths).length > 0 ||
+            allowTerms.some((term) => fp.toLowerCase().includes(term.toLowerCase()));
+        const violatesAllowedPaths = allowedPaths.length > 0 && pathMatchesAnyPattern(fp, allowedPaths).length === 0;
+        if ((matchedDeniedPaths.length || matchedDeniedTerms.length || intentDenied.length || violatesAllowedPaths) &&
+            !isExplicitlyAllowed) {
+            suspicious.push({
+                file_path: fp,
+                matched_terms: Array.from(new Set([...matchedDeniedTerms, ...intentDenied])).slice(0, 12),
+                matched_paths: [
+                    ...matchedDeniedPaths.slice(0, 12),
+                    ...(violatesAllowedPaths ? [`outside allowed_paths: ${allowedPaths.slice(0, 5).join(", ")}`] : []),
+                ],
+            });
+        }
+    }
+    if (suspicious.length) {
+        warnings.push({
+            code: "scope_drift",
+            severity: "blocker",
+            message: "The current requirement appears to be touching a denied or out-of-scope domain. Stop and narrow the change unless the user explicitly expanded this requirement.",
+            files: suspicious.slice(0, 12).map((s) => s.file_path),
+            details: {
+                requirement_id: args.requirement?.id ?? null,
+                requirement_title: args.requirement?.title ?? null,
+                inferred_from: contract.inferred_from,
+                deny_terms: denyTerms.slice(0, 30),
+                denied_paths: deniedPaths.slice(0, 30),
+                suspicious: suspicious.slice(0, 12),
+            },
+        });
+    }
+    return warnings;
+}
+function buildDevelopmentWarnings(files, opts = {}) {
+    const warnings = [];
+    const uniqueFiles = Array.from(new Set(files
+        .map((f) => f.file_path)
+        .filter((f) => !!f && f !== "(unspecified)")
+        .map((f) => normalizeToDbPath(f))));
+    if (opts.includeUnspecified || files.some((f) => f.file_path === "(unspecified)")) {
+        warnings.push({
+            code: "unspecified_change_target",
+            severity: "warning",
+            message: "No changed file target was captured. For development work, sync concrete files so the current requirement owns only its real changes.",
+        });
+    }
+    if (uniqueFiles.length >= DEVELOPMENT_WARN_PENDING_FILES) {
+        warnings.push({
+            code: "many_pending_files",
+            severity: "warning",
+            message: "This requirement touches many files. Re-check the user request and keep only files required by the current requirement.",
+            files: uniqueFiles.slice(0, 20),
+            details: { total_files: uniqueFiles.length, threshold: DEVELOPMENT_WARN_PENDING_FILES },
+        });
+    }
+    const topDirs = new Set(uniqueFiles
+        .map((f) => f.replace(/\\/g, "/").split("/").filter(Boolean)[0] ?? "")
+        .filter(Boolean));
+    if (uniqueFiles.length >= 6 && topDirs.size >= 4) {
+        warnings.push({
+            code: "broad_change_surface",
+            severity: "warning",
+            message: "Changed files span several top-level areas. Avoid modifying completed or merely related features unless the current requirement explicitly needs it.",
+            files: uniqueFiles.slice(0, 20),
+            details: { top_level_dirs: Array.from(topDirs).slice(0, 12), total_dirs: topDirs.size },
+        });
+    }
+    for (const relPath of uniqueFiles) {
+        if (!isLikelySourceImplementationFile(relPath))
+            continue;
+        const absPath = path.isAbsolute(relPath) ? relPath : path.join(projectRoot, relPath);
+        let stat;
+        try {
+            stat = fs.statSync(absPath);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isFile())
+            continue;
+        const lineInfo = countFileLinesBounded(absPath, 2_000_000);
+        const lineCount = lineInfo?.lines ?? 0;
+        const tooManyLines = lineCount >= DEVELOPMENT_BLOCK_FILE_LINES;
+        const warnLines = lineCount >= DEVELOPMENT_WARN_FILE_LINES;
+        const warnBytes = stat.size >= DEVELOPMENT_WARN_FILE_BYTES;
+        if (!tooManyLines && !warnLines && !warnBytes)
+            continue;
+        warnings.push({
+            code: tooManyLines ? "very_large_file" : "large_file",
+            severity: tooManyLines ? "blocker" : "warning",
+            message: tooManyLines
+                ? "This implementation file is already very large. Do not add new feature code here by default; split into a focused module/service/component and keep this file as a thin entry."
+                : "This implementation file is getting large. Prefer extracting focused modules instead of continuing to pile unrelated responsibilities into it.",
+            files: [relPath],
+            details: {
+                lines: lineInfo?.truncated ? `${lineCount}+` : lineCount,
+                bytes: stat.size,
+                warn_lines: DEVELOPMENT_WARN_FILE_LINES,
+                block_lines: DEVELOPMENT_BLOCK_FILE_LINES,
+                warn_bytes: DEVELOPMENT_WARN_FILE_BYTES,
+            },
+        });
+    }
+    return warnings;
+}
+function compactDevelopmentWarningsText(warnings) {
+    if (!warnings.length)
+        return [];
+    const lines = ["development warnings:"];
+    for (const w of warnings.slice(0, 8)) {
+        const files = w.files?.length ? ` files=${w.files.slice(0, 5).join(",")}` : "";
+        lines.push(`- ${w.severity} ${w.code}: ${oneLine(w.message, 180)}${files}`);
+    }
+    return lines;
+}
 function extractSymbols(filePath, content) {
     const ext = path.extname(filePath).toLowerCase();
     if (ext === ".py")
@@ -1247,12 +2190,25 @@ const StartRequirementArgsSchema = ProjectRootArgSchema.merge(z.object({
     title: z.string().min(1),
     background: z.string().optional().default(""),
     close_previous: z.boolean().optional().default(true),
+    scope_allow: z.array(z.string().min(1)).optional(),
+    scope_deny: z.array(z.string().min(1)).optional(),
+    allowed_paths: z.array(z.string().min(1)).optional(),
+    denied_paths: z.array(z.string().min(1)).optional(),
 }));
 const SyncChangeIntentArgsSchema = ProjectRootArgSchema.merge(z.object({
     intent: z.string().min(1),
     files: z.array(z.string().min(1)).optional(),
     affected_files: z.array(z.string().min(1)).optional(),
 }));
+const PreflightChangeScopeArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
+    intent: z.string().optional().default(""),
+    files: z.array(z.string().min(1)).optional(),
+    planned_files: z.array(z.string().min(1)).optional(),
+    scope_allow: z.array(z.string().min(1)).optional(),
+    scope_deny: z.array(z.string().min(1)).optional(),
+    allowed_paths: z.array(z.string().min(1)).optional(),
+    denied_paths: z.array(z.string().min(1)).optional(),
+}));
 const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     query: z.string().min(1),
 }));
@@ -1352,6 +2308,19 @@ const SupersedeMemoryArgsSchema = ProjectRootArgSchema.merge(z.object({
     replacement_memory_id: z.number().int().positive().optional(),
     reason: z.string().min(1),
 }));
+const MaintainMemoryArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
+    dry_run: z.boolean().optional().default(true),
+    compact_old_memories: z.boolean().optional().default(true),
+    compact_notes: z.boolean().optional().default(false),
+    prune_stale_indexes: z.boolean().optional().default(true),
+    prune_ignored_paths: z.boolean().optional().default(true),
+    prune_filename_noise: z.boolean().optional().default(true),
+    prune_hidden_embeddings: z.boolean().optional().default(true),
+    compact_after_days: z.number().int().min(1).max(3650).optional().default(MAINTENANCE_COMPACT_AFTER_DAYS),
+    max_memory_items: z.number().int().min(1).max(5000).optional().default(MAINTENANCE_MAX_MEMORY_ITEMS),
+    max_index_files: z.number().int().min(1).max(50_000).optional().default(MAINTENANCE_MAX_INDEX_FILES),
+    vacuum: z.boolean().optional().default(false),
+}));
 const DEFAULT_PENDING_LIMIT = 10;
 const MAX_PENDING_LIMIT = 2000;
 const PendingPagingSchema = z.object({
@@ -1371,13 +2340,22 @@ const DEFAULT_RECENT_CHANGES_PER_REQ = 3;
 const DEFAULT_RECENT_NOTES = 3;
 const DEFAULT_CONVENTIONS_LIMIT = 0;
 const DEFAULT_DECISIONS_LIMIT = 5;
+const DEFAULT_CURRENT_CONTEXT_LIMIT = 8;
 const MAX_DECISIONS_LIMIT = 50;
+const MAX_CURRENT_CONTEXT_LIMIT = 50;
 const BrainDumpLimitsSchema = z.object({
     requirements_limit: z.number().int().min(1).max(20).optional().default(DEFAULT_RECENT_REQUIREMENTS),
     changes_limit: z.number().int().min(1).max(100).optional().default(DEFAULT_RECENT_CHANGES_PER_REQ),
     notes_limit: z.number().int().min(0).max(50).optional().default(DEFAULT_RECENT_NOTES),
     conventions_limit: z.number().int().min(0).max(200).optional().default(DEFAULT_CONVENTIONS_LIMIT),
     decisions_limit: z.number().int().min(0).max(MAX_DECISIONS_LIMIT).optional().default(DEFAULT_DECISIONS_LIMIT),
+    current_context_limit: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_CURRENT_CONTEXT_LIMIT)
+        .optional()
+        .default(DEFAULT_CURRENT_CONTEXT_LIMIT),
 });
 const GetPendingChangesArgsSchema = ProjectRootArgSchema.merge(z.object({
     offset: z.number().int().min(0).optional().default(0),
@@ -1560,6 +2538,7 @@ function compactGrepText(data) {
     const lines = [
         `grep ${data.backend}${fallback} mode=${data.mode} matches=${data.matches.length}/${total} truncated=${data.truncated}${candidateText} q="${oneLine(data.query, 100)}"`,
     ];
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings ?? []));
     if (data.ripgrep_error)
         lines.push(`ripgrep_error ${oneLine(data.ripgrep_error, 180)}`);
     for (const m of data.matches.slice(0, 80)) {
@@ -1589,15 +2568,18 @@ function compactReadTextFileText(data) {
     const offset = data.offset != null ? ` offset=${data.offset}` : "";
     const header = `file ${data.file_path}${offset} chars=${data.returned_chars}/${data.total_chars} truncated=${data.truncated}`;
     const hint = data.truncated ? "\nhint: continue with offset or read_file_lines; use format=json for metadata fields" : "";
-    return `${header}\n${data.text}${hint}`;
+    const warnings = compactDevelopmentWarningsText(data.development_warnings ?? []).join("\n");
+    return `${header}${warnings ? `\n${warnings}` : ""}\n${data.text}${hint}`;
 }
 function compactReadFileLinesText(data) {
     const header = `lines ${data.file_path}:${data.from_line}-${data.to_line} returned=${data.returned} truncated=${data.truncated}`;
     const hint = data.truncated ? "\nhint: narrow range or raise max_lines/max_chars; use format=json for metadata fields" : "";
-    return `${header}\n${data.text}${hint}`;
+    const warnings = compactDevelopmentWarningsText(data.development_warnings ?? []).join("\n");
+    return `${header}${warnings ? `\n${warnings}` : ""}\n${data.text}${hint}`;
 }
 function compactQueryCodebaseText(data) {
     const lines = [`query_codebase matches=${data.matches.length} q="${oneLine(data.query, 100)}"`];
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings ?? []));
     for (const m of data.matches.slice(0, 50)) {
         lines.push(`${m.file_path}: ${m.type} ${m.name}${m.signature ? ` — ${oneLine(m.signature, 160)}` : ""}`);
     }
@@ -1605,6 +2587,47 @@ function compactQueryCodebaseText(data) {
         lines.push("- no matches");
     return lines.join("\n");
 }
+function compactMaintenanceText(data) {
+    const prunedChunks = data.pruned.ignored_paths.chunks_deleted +
+        data.pruned.filename_noise.chunks_deleted +
+        data.pruned.stale_files.chunks_deleted;
+    const prunedSymbols = data.pruned.ignored_paths.symbols_deleted +
+        data.pruned.filename_noise.symbols_deleted +
+        data.pruned.stale_files.symbols_deleted;
+    const lines = [
+        `maintain_memory ok dry_run=${data.dry_run} trigger=${data.trigger} compacted=${data.compacted_memory.compacted}/${data.compacted_memory.candidates} archived=${data.compacted_memory.archived} pruned_chunks=${prunedChunks} pruned_symbols=${prunedSymbols} hidden_embeddings=${data.pruned.hidden_embeddings.embeddings_deleted}`,
+    ];
+    if (data.compacted_memory.summary_memory_id) {
+        lines.push(`summary memory_compaction #${data.compacted_memory.summary_memory_id}`);
+    }
+    if (data.compacted_memory.samples.length) {
+        lines.push("memory candidates:");
+        for (const s of data.compacted_memory.samples.slice(0, 8)) {
+            lines.push(`- #${s.id} ${s.kind} ${s.file_path ?? ""} ${oneLine(s.title ?? "", 80)} ${s.updated_at}`);
+        }
+    }
+    if (data.pruned.stale_files.samples.length) {
+        lines.push("stale index samples:");
+        for (const s of data.pruned.stale_files.samples.slice(0, 8))
+            lines.push(`- ${s}`);
+    }
+    lines.push("hint: dry_run=false applies changes; vacuum=true reclaims sqlite file space after pruning");
+    return lines.join("\n");
+}
+function compactPreflightChangeScopeText(data) {
+    const req = data.active_requirement ? `#${data.active_requirement.id} ${data.active_requirement.title}` : "none";
+    const lines = [
+        `preflight_change_scope ok=${data.ok} safe_to_edit=${data.safe_to_edit} requirement=${req} files=${data.files.length} intent="${oneLine(data.intent, 120)}"`,
+        `action: ${oneLine(data.recommended_action, 180)}`,
+    ];
+    if (data.scope_contract) {
+        lines.push(`scope allow_terms=${data.scope_contract.allow_terms.length} deny_terms=${data.scope_contract.deny_terms.length} allowed_paths=${data.scope_contract.allowed_paths.length} denied_paths=${data.scope_contract.denied_paths.length}`);
+    }
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings));
+    if (!data.development_warnings.length)
+        lines.push("- no development warnings");
+    return lines.join("\n");
+}
 function compactBootstrapText(data) {
     const lines = [];
     lines.push(`ok ctx ${data.root_source} watcher=${data.watcher_enabled ? (data.watcher_ready ? "ready" : "starting") : "off"} root=${data.project_root}`);
@@ -1615,6 +2638,11 @@ function compactBootstrapText(data) {
         for (const d of data.decisions.slice(0, 5))
             lines.push(`- ${compactMemoryLabel(d, 160)}`);
     }
+    if (data.current_context.length) {
+        lines.push("current context:");
+        for (const c of data.current_context.slice(0, 8))
+            lines.push(`- ${compactMemoryLabel(c, 160)}`);
+    }
     if (data.pending_total) {
         lines.push(`pending ${data.pending_changes.length}/${data.pending_total}${data.pending_truncated ? " truncated" : ""}: ${data.pending_changes
             .slice(0, 8)
@@ -1624,6 +2652,7 @@ function compactBootstrapText(data) {
     else {
         lines.push("pending 0");
     }
+    lines.push(...compactDevelopmentWarningsText(data.development_warnings ?? []));
     if (data.items.length) {
         lines.push("requirements:");
         for (const item of data.items) {
@@ -1719,8 +2748,8 @@ function runRtkProbe(spec) {
                     ? `Prefer prefixing shell commands with ${spec.displayCommand} for compact outputs. This is VectorMind's bundled RTK shim; first run auto-installs/caches rtk-ai/rtk if needed.`
                     : "Prefer prefixing shell commands with rtk for compact outputs, e.g. rtk git status / rtk npm run build / rtk rg pattern ."
                 : spec.source === "package_shim"
-                    ? "VectorMind's bundled RTK shim exists, but `gain` failed. Check network/cache or set VECTORMIND_RTK_REAL to an existing rtk-ai/rtk binary."
-                    : "An rtk binary exists, but `rtk gain` failed. This may be the wrong rtk project. Use install_rtk with uninstall_wrong_cargo_rtk=true only after confirming it is safe.",
+                    ? "VectorMind's bundled RTK shim exists, but `gain` failed. Check npm/cache or set VECTORMIND_RTK_REAL to an existing rtk-ai/rtk binary."
+                    : "An rtk binary exists, but `rtk gain` failed. This may be the wrong rtk project. Use install_rtk with uninstall_wrong_cargo_rtk=true only when you intentionally want to replace it.",
         };
     }
     return null;
@@ -1755,7 +2784,7 @@ function detectRtk() {
         path: shimPath ?? undefined,
         source: shimPath ? "package_shim" : undefined,
         note: shimPath
-            ? "rtk was not found on PATH, and VectorMind's bundled RTK shim could not verify rtk gain. VectorMind compact MCP output still works; check network/cache or set VECTORMIND_RTK_REAL."
+            ? "rtk was not found on PATH, and VectorMind's bundled RTK shim could not verify rtk gain. VectorMind compact MCP output still works; check npm/cache or set VECTORMIND_RTK_REAL."
             : "rtk was not found on PATH and the package RTK shim is unavailable. VectorMind compact MCP output still works; install rtk to compact shell command output too.",
     };
 }
@@ -2129,6 +3158,80 @@ function dotProduct(a, b) {
         s += a[i] * b[i];
     return s;
 }
+const SEMANTIC_TOKEN_STOPWORDS = new Set([
+    "a",
+    "an",
+    "and",
+    "are",
+    "as",
+    "at",
+    "be",
+    "by",
+    "for",
+    "from",
+    "has",
+    "have",
+    "if",
+    "in",
+    "into",
+    "is",
+    "it",
+    "its",
+    "of",
+    "on",
+    "or",
+    "that",
+    "the",
+    "this",
+    "to",
+    "with",
+]);
+const BOOTSTRAP_DEFAULT_CONTEXT_KINDS = [
+    "decision",
+    "convention",
+    "project_summary",
+    "memory_compaction",
+    "note",
+    "requirement",
+    "change_intent",
+];
+const TOKEN_SEARCH_DEFAULT_KINDS = [
+    "decision",
+    "convention",
+    "project_summary",
+    "memory_compaction",
+    "note",
+    "requirement",
+    "change_intent",
+    "code_chunk",
+    "doc_chunk",
+];
+const DECISION_CANDIDATE_KEYWORDS = [
+    "用户确认",
+    "用户要求",
+    "明确",
+    "架构决策",
+    "最终",
+    "默认",
+    "只保留",
+    "统一",
+    "不需要",
+    "无需",
+    "不再",
+    "改成",
+    "改为",
+    "直接通过",
+    "不用审核",
+    "decision",
+    "decided",
+    "confirmed",
+    "must",
+    "default",
+    "only",
+    "single",
+    "no longer",
+    "instead",
+];
 function parseMetadataJson(metadata) {
     if (!metadata)
         return {};
@@ -2150,6 +3253,13 @@ function isSupersededMemory(row) {
     const meta = parseMetadataJson(row.metadata_json);
     return meta.superseded === true || meta.status === "superseded";
 }
+function isCompactedMemory(row) {
+    const meta = parseMetadataJson(row.metadata_json);
+    return meta.compacted === true || meta.status === "compacted";
+}
+function isHiddenFromDefaultRecall(row) {
+    return isSupersededMemory(row) || isCompactedMemory(row);
+}
 function semanticRecencyWeight(updatedAt) {
     if (!updatedAt)
         return 0;
@@ -2168,7 +3278,7 @@ function semanticRecencyWeight(updatedAt) {
 function semanticKindWeight(kind) {
     switch (kind) {
         case "decision":
-            return 3.5;
+            return 16;
         case "convention":
             return 2.6;
         case "project_summary":
@@ -2179,16 +3289,20 @@ function semanticKindWeight(kind) {
             return 0.4;
         case "change_intent":
             return 0.2;
+        case "memory_compaction":
+            return 0.7;
         default:
             return 0;
     }
 }
 function adjustSemanticScore(row, rawScore) {
-    if (isSupersededMemory(row))
+    if (isHiddenFromDefaultRecall(row))
         return rawScore - 1000;
     let score = rawScore + semanticKindWeight(row.kind) + semanticRecencyWeight(row.updated_at);
     const status = metadataStatus(row);
-    if (status === "active" || status === "current")
+    if (status === "current")
+        score += row.kind === "decision" ? 24 : 1.2;
+    if (status === "active")
         score += 1.2;
     if (row.kind === "change_intent" && row.file_path && shouldIgnoreDbFilePath(row.file_path)) {
         // Human-synced intent for generated/build/runtime files is often the only durable
@@ -2197,11 +3311,110 @@ function adjustSemanticScore(row, rawScore) {
     }
     return score;
 }
+function normalizeSearchText(input) {
+    return (input ?? "").normalize("NFKC").toLowerCase();
+}
+function extractSearchTokens(raw) {
+    const text = normalizeSearchText(raw);
+    const tokens = new Set();
+    for (const token of text.match(/[a-z0-9_./:@#-]{2,}/g) ?? []) {
+        if (!SEMANTIC_TOKEN_STOPWORDS.has(token))
+            tokens.add(token);
+        for (const part of token.split(/[^a-z0-9]+/).filter((p) => p.length >= 2)) {
+            if (!SEMANTIC_TOKEN_STOPWORDS.has(part))
+                tokens.add(part);
+        }
+    }
+    for (const seq of text.match(/\p{Script=Han}+/gu) ?? []) {
+        if (seq.length >= 2 && seq.length <= 18)
+            tokens.add(seq);
+        for (const n of [2, 3, 4]) {
+            if (seq.length < n)
+                continue;
+            for (let i = 0; i <= seq.length - n; i++) {
+                tokens.add(seq.slice(i, i + n));
+            }
+        }
+    }
+    return Array.from(tokens)
+        .filter((token) => token.length >= 2 && !SEMANTIC_TOKEN_STOPWORDS.has(token))
+        .sort((a, b) => b.length - a.length)
+        .slice(0, 48);
+}
+function countNeedleOccurrences(haystack, needle) {
+    if (!haystack || !needle)
+        return 0;
+    let count = 0;
+    let idx = 0;
+    while ((idx = haystack.indexOf(needle, idx)) >= 0) {
+        count++;
+        idx += Math.max(1, needle.length);
+        if (count >= 8)
+            break;
+    }
+    return count;
+}
+function tokenLexicalScore(row, query, tokens) {
+    if (!tokens.length)
+        return 0;
+    const title = normalizeSearchText(row.title);
+    const content = normalizeSearchText(row.content);
+    const filePath = normalizeSearchText(row.file_path);
+    const metadata = normalizeSearchText(row.metadata_json);
+    const exact = normalizeSearchText(query).trim();
+    let score = 0;
+    if (exact.length >= 4) {
+        if (title.includes(exact))
+            score += 8;
+        if (content.includes(exact))
+            score += 6;
+        if (filePath.includes(exact))
+            score += 4;
+    }
+    let matched = 0;
+    for (const token of tokens) {
+        let tokenScore = 0;
+        if (title.includes(token))
+            tokenScore += 3.2;
+        if (filePath.includes(token))
+            tokenScore += 2.4;
+        const contentHits = countNeedleOccurrences(content, token);
+        if (contentHits)
+            tokenScore += Math.min(3.2, 0.75 + contentHits * 0.45);
+        if (metadata.includes(token))
+            tokenScore += 0.8;
+        if (tokenScore > 0) {
+            matched++;
+            score += tokenScore * Math.min(2.4, Math.max(1, token.length / 4));
+        }
+    }
+    if (matched >= Math.min(3, tokens.length))
+        score += 2;
+    score += matched / Math.max(1, tokens.length);
+    return score;
+}
+function looksLikeDecisionContent(content) {
+    const text = normalizeSearchText(content);
+    return DECISION_CANDIDATE_KEYWORDS.some((kw) => text.includes(normalizeSearchText(kw)));
+}
+function mergeSemanticMatches(sets, opts) {
+    const best = new Map();
+    for (const matches of sets) {
+        for (const match of matches) {
+            const prev = best.get(match.item.id);
+            if (!prev || match.score > prev.score)
+                best.set(match.item.id, match);
+        }
+    }
+    return Array.from(best.values())
+        .sort((a, b) => b.score - a.score || b.item.id - a.item.id)
+        .slice(0, opts.topK);
+}
 function filterAndRankSemanticRows(rows, scoreOf, opts) {
     return rows
         .map((r) => ({ row: r, score: adjustSemanticScore(r, scoreOf(r)) }))
         .filter(({ row }) => {
-        if (isSupersededMemory(row))
+        if (isHiddenFromDefaultRecall(row))
             return false;
         if (shouldIgnoreDbFilePath(row.file_path) && row.kind !== "change_intent")
             return false;
@@ -2290,10 +3503,43 @@ function getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars) {
         return [];
     const rows = listCurrentDecisionsStmt.all(Math.min(MAX_DECISIONS_LIMIT * 4, Math.max(decisionsLimit, decisionsLimit * 4)));
     return rows
-        .filter((d) => !isSupersededMemory(d))
+        .filter((d) => !isHiddenFromDefaultRecall(d))
         .slice(0, decisionsLimit)
         .map((d) => toMemoryItemPreview(d, false, previewChars, contentMaxChars));
 }
+function getCurrentContextPreviews(currentContextLimit, previewChars, contentMaxChars) {
+    if (currentContextLimit <= 0)
+        return [];
+    const picked = new Map();
+    const addRow = (row) => {
+        if (!row)
+            return;
+        if (isHiddenFromDefaultRecall(row))
+            return;
+        if (shouldIgnoreDbFilePath(row.file_path) && row.kind !== "change_intent")
+            return;
+        if (!picked.has(row.id)) {
+            picked.set(row.id, toMemoryItemPreview(row, false, previewChars, contentMaxChars));
+        }
+    };
+    const activeReqs = listActiveRequirementsStmt.all(Math.max(currentContextLimit, 10));
+    for (const req of activeReqs) {
+        const memId = getRequirementMemoryItemIdStmt.get(req.id)?.id;
+        if (memId != null)
+            addRow(getMemoryItemByIdStmt.get(memId));
+    }
+    const recentRows = listRecentContextItemsStmt.all(Math.max(currentContextLimit * 8, 40));
+    for (const row of recentRows) {
+        if (picked.size >= currentContextLimit)
+            break;
+        if (row.kind === "requirement" || row.kind === "change_intent") {
+            if (!looksLikeDecisionContent(`${row.title ?? ""}\n${row.content}`))
+                continue;
+        }
+        addRow(row);
+    }
+    return Array.from(picked.values()).slice(0, currentContextLimit);
+}
 function toRequirementPreview(req, includeContent, previewChars, contentMaxChars) {
     const context = req.context_data ?? null;
     const contextPreview = context ? makePreviewText(context, previewChars) : null;
@@ -2431,7 +3677,7 @@ async function semanticSearchInternal(opts) {
         .filter(Boolean);
     const filtered = matches
         .filter((m) => {
-        if (isSupersededMemory({ metadata_json: m.item.metadata_json }))
+        if (isHiddenFromDefaultRecall({ metadata_json: m.item.metadata_json }))
             return false;
         if (shouldIgnoreDbFilePath(m.item.file_path) && m.item.kind !== "change_intent")
             return false;
@@ -2591,24 +3837,212 @@ function likeSearchInternal(opts) {
     const matches = filterAndRankSemanticRows(rows, (r) => Number(r.score), opts);
     return { query: q, top_k: opts.topK, mode: "like", matches };
 }
-async function semanticSearchHybridInternal(opts) {
-    if (embeddingsEnabled) {
-        try {
-            return await semanticSearchInternal(opts);
-        }
-        catch (err) {
-            console.error("[vectormind] embeddings semantic_search failed; falling back:", err);
-        }
+function tokenSearchInternal(opts) {
+    const q = opts.query.trim();
+    if (!q)
+        return { query: "", top_k: opts.topK, mode: "token", matches: [] };
+    const tokens = extractSearchTokens(q);
+    if (!tokens.length)
+        return { query: q, top_k: opts.topK, mode: "token", matches: [] };
+    const rawLimit = Math.min(160, Math.max(opts.topK * 12, 80));
+    const searchTokens = tokens.slice(0, 8);
+    const effectiveKinds = opts.kinds?.length ? opts.kinds : TOKEN_SEARCH_DEFAULT_KINDS;
+    const kindClause = effectiveKinds.length
+        ? `AND kind IN (${effectiveKinds.map(() => "?").join(", ")})`
+        : "";
+    const recencyBoost = `
+      + CASE
+          WHEN updated_at >= datetime('now', '-2 days') THEN 4
+          WHEN updated_at >= datetime('now', '-14 days') THEN 2
+          WHEN updated_at >= datetime('now', '-60 days') THEN 1
+          ELSE 0
+        END`;
+    const candidateScore = `
+      (
+        CASE kind
+          WHEN 'decision' THEN 9
+          WHEN 'convention' THEN 7
+          WHEN 'project_summary' THEN 6
+          WHEN 'note' THEN 5
+          WHEN 'requirement' THEN 4
+          WHEN 'change_intent' THEN 3
+          ELSE 0
+        END
+        ${recencyBoost}
+      )`;
+    const includesIndexedChunks = effectiveKinds.some((k) => k === "code_chunk" || k === "doc_chunk");
+    if (!includesIndexedChunks) {
+        const candidateLimit = Math.min(1600, Math.max(rawLimit * 5, 800));
+        const stmt = db.prepare(`
+      SELECT
+        id,
+        kind,
+        title,
+        content,
+        file_path,
+        start_line,
+        end_line,
+        req_id,
+        metadata_json,
+        updated_at
+      FROM memory_items
+      WHERE 1=1
+        ${kindClause}
+      ORDER BY
+        ${candidateScore} DESC,
+        updated_at DESC,
+        id DESC
+      LIMIT ?
+    `);
+        const candidates = stmt.all(...effectiveKinds, candidateLimit);
+        const scoreMap = new Map();
+        const rows = candidates.filter((row) => {
+            const score = tokenLexicalScore(row, q, tokens);
+            if (score <= 0)
+                return false;
+            scoreMap.set(row.id, score);
+            return true;
+        });
+        const matches = filterAndRankSemanticRows(rows, (r) => scoreMap.get(r.id) ?? 0, opts);
+        return { query: q, top_k: opts.topK, mode: "token", matches };
+    }
+    const memoryFirstKinds = effectiveKinds.filter((k) => k !== "code_chunk" && k !== "doc_chunk");
+    const memoryFirstLimit = Math.min(1200, Math.max(rawLimit * 4, 300));
+    let memoryFirstRows = [];
+    const memoryFirstScores = new Map();
+    if (memoryFirstKinds.length) {
+        const memoryKindClause = `AND kind IN (${memoryFirstKinds.map(() => "?").join(", ")})`;
+        const memoryStmt = db.prepare(`
+      SELECT
+        id,
+        kind,
+        title,
+        content,
+        file_path,
+        start_line,
+        end_line,
+        req_id,
+        metadata_json,
+        updated_at
+      FROM memory_items
+      WHERE 1=1
+        ${memoryKindClause}
+      ORDER BY
+        ${candidateScore} DESC,
+        updated_at DESC,
+        id DESC
+      LIMIT ?
+    `);
+        const candidates = memoryStmt.all(...memoryFirstKinds, memoryFirstLimit);
+        memoryFirstRows = candidates.filter((row) => {
+            const score = tokenLexicalScore(row, q, tokens);
+            if (score <= 0)
+                return false;
+            memoryFirstScores.set(row.id, score);
+            return true;
+        });
     }
+    const conditions = [];
+    const values = [];
+    for (const token of searchTokens) {
+        const like = `%${escapeLike(token)}%`;
+        conditions.push(`content LIKE ? ESCAPE '\\'`);
+        values.push(like);
+        conditions.push(`title LIKE ? ESCAPE '\\'`);
+        values.push(like);
+        conditions.push(`file_path LIKE ? ESCAPE '\\'`);
+        values.push(like);
+    }
+    if (!conditions.length)
+        return { query: q, top_k: opts.topK, mode: "token", matches: [] };
+    const stmt = db.prepare(`
+    SELECT
+      id,
+      kind,
+      title,
+      content,
+      file_path,
+      start_line,
+      end_line,
+      req_id,
+      metadata_json,
+      updated_at
+    FROM memory_items
+    WHERE (${conditions.join(" OR ")})
+      ${kindClause}
+    ORDER BY
+      ${candidateScore} DESC,
+      updated_at DESC,
+      id DESC
+    LIMIT ?
+  `);
+    const rows = stmt.all(...values, ...effectiveKinds, rawLimit);
+    const scoreMap = new Map(memoryFirstScores);
+    for (const row of rows) {
+        if (!scoreMap.has(row.id))
+            scoreMap.set(row.id, tokenLexicalScore(row, q, tokens));
+    }
+    const rowMap = new Map();
+    for (const row of memoryFirstRows)
+        rowMap.set(row.id, row);
+    for (const row of rows)
+        rowMap.set(row.id, row);
+    const matches = filterAndRankSemanticRows(Array.from(rowMap.values()), (r) => scoreMap.get(r.id) ?? 0, opts);
+    return { query: q, top_k: opts.topK, mode: "token", matches };
+}
+function chooseLexicalResult(opts) {
+    const tokenResult = tokenSearchInternal(opts);
+    const tokenTopScore = tokenResult.matches[0]?.score ?? 0;
+    const tokenEnough = tokenResult.matches.length >= Math.min(opts.topK, 3) && tokenTopScore >= 8;
+    if (tokenEnough || tokenResult.matches.length >= opts.topK) {
+        return { result: tokenResult, mode: "token" };
+    }
+    let textResult = null;
     if (ftsAvailable) {
         try {
-            return ftsSearchInternal(opts);
+            textResult = ftsSearchInternal(opts);
         }
         catch (err) {
             console.error("[vectormind] fts semantic_search failed; falling back:", err);
         }
     }
-    return likeSearchInternal(opts);
+    if (!textResult) {
+        textResult = likeSearchInternal(opts);
+    }
+    const merged = mergeSemanticMatches([textResult.matches, tokenResult.matches], opts);
+    const tokenIds = new Set(tokenResult.matches.map((m) => m.item.id));
+    const ftsKept = textResult.matches.some((m) => !tokenIds.has(m.item.id));
+    if (tokenResult.matches.length && ftsKept) {
+        return {
+            result: { query: opts.query.trim(), top_k: opts.topK, mode: "hybrid", matches: merged },
+            mode: "hybrid",
+        };
+    }
+    if (tokenResult.matches.length) {
+        return { result: { query: opts.query.trim(), top_k: opts.topK, mode: "token", matches: merged }, mode: "token" };
+    }
+    return { result: textResult, mode: textResult.mode === "fts" ? "fts" : "like" };
+}
+async function semanticSearchHybridInternal(opts) {
+    const lexical = chooseLexicalResult(opts).result;
+    if (!embeddingsEnabled)
+        return lexical;
+    const embeddingsResult = await Promise.race([
+        semanticSearchInternal(opts),
+        new Promise((resolve) => setTimeout(resolve, SEMANTIC_EMBEDDINGS_TIMEOUT_MS, null)),
+    ]).catch((err) => {
+        console.error("[vectormind] embeddings semantic_search failed; falling back:", err);
+        return null;
+    });
+    if (!embeddingsResult)
+        return lexical;
+    const merged = mergeSemanticMatches([lexical.matches, embeddingsResult.matches], opts);
+    return {
+        query: opts.query.trim(),
+        top_k: opts.topK,
+        mode: merged.length ? "hybrid" : embeddingsResult.mode,
+        matches: merged,
+    };
 }
 function escapeRegExp(literal) {
     return literal.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -3313,7 +4747,7 @@ function listProjectFilesInternal(opts) {
 function buildServerInstructions() {
     return [
         "VectorMind MCP is available in this session. Use it to avoid guessing project context.",
-        "Development guideline scope: VectorMind instructions define development conventions, project-memory conventions, code-organization conventions, and delivery-quality expectations only. They are unrelated to AI access permissions, runtime permissions, command permissions, filesystem/network permissions, approval mechanisms, or sandbox behavior.",
+        "Development guideline scope: VectorMind instructions define development conventions, project-memory conventions, code-organization conventions, and delivery-quality expectations.",
         "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).",
         "",
@@ -3329,6 +4763,9 @@ function buildServerInstructions() {
         "Built-in architecture and code-organization quality policy:",
         BUILTIN_ARCHITECTURE_AND_CODE_ORGANIZATION_INSTRUCTIONS,
         "",
+        "Built-in requirement boundary and modularity quality policy:",
+        BUILTIN_REQUIREMENT_BOUNDARY_AND_MODULARITY_INSTRUCTIONS,
+        "",
         "Built-in frontend output-purity quality policy:",
         BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS,
         "",
@@ -3348,24 +4785,30 @@ function buildServerInstructions() {
         "- Tool outputs are compact by default. Pass format=json only when you need full structured data.",
         "- 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 compact 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/decisions_limit, preview_chars, pending_limit/pending_offset.",
+        "  - bootstrap_context/get_brain_dump always include a small recency anchor named current_context (latest active requirements, recent notes, and recent change intents) in addition to query matches; tune output size with: requirements_limit/changes_limit/notes_limit/decisions_limit/current_context_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.",
         "- If rtk is installed or VectorMind's bundled RTK shim is verified (detect_rtk with gain_ok=true), prefix shell commands with the command returned by detect_rtk. Usually this is rtk (rtk git status, rtk npm run build, rtk rg ...); in npx/MCP-only installs it may be a package shim command such as node <...>/rtk-shim.js.",
-        "- If rtk is missing and the user asks to install it, use install_rtk first with dry_run=true to show the exact commands; execute with dry_run=false only after the user clearly approves installation/init choices.",
-        "- 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.",
+        "- If rtk is missing and the user asks to install it, use install_rtk first with dry_run=true to show the exact commands; execute with dry_run=false only when the user explicitly asks to install/init.",
+        "- 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 another local-file 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 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.",
+        "  - When the user names a narrow feature/domain, pass scope_allow/allowed_paths and scope_deny/denied_paths when useful. These are generic project-specific scope boundaries, not business-specific built-ins.",
+        "- BEFORE editing once target files/modules are known: call preflight_change_scope(intent, files/planned_files, optional scope_allow/scope_deny/allowed_paths/denied_paths). If ok=false/safe_to_edit=false or it returns development_warnings, stop before editing and narrow the plan unless the user explicitly expands the requirement.",
+        "- Treat the active requirement as the only change boundary. Do not add extra business behavior, new flows, new fields, new interfaces, or touch completed/related features unless the user explicitly asked or the change is strictly necessary.",
+        "- Do not keep piling new feature code into a large single file. Prefer small modules/services/components; if an implementation file is already large, split it before adding more responsibilities.",
         "- 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.)",
+        "- If preflight_change_scope, read_file_lines, grep, query_codebase, get_pending_changes, or sync_change_intent returns development_warnings, address those warnings before continuing or explain why the current requirement truly needs that scope.",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
         "- When a requirement or user decision changes/reverses an older behavior, call upsert_decision(key, title, content, supersedes_req_ids?/supersedes_memory_ids?) and/or supersede_memory(...). Current decisions are shown in bootstrap_context/get_brain_dump and superseded memories are hidden from default semantic recall so stale requirements do not override newer facts.",
         "- If the user states a durable project convention (build commands, frameworks, naming rules, output paths): call upsert_convention(key, content, tags) so it is applied in future sessions.",
         "- 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.",
+        "- When you need to recall relevant context from history/code/docs: call semantic_search(query, ...) instead of guessing. It blends lexical/FTS recall with embeddings when enabled, so recent explicit wording and durable decisions are not hidden by older semantically similar matches.",
+        "- VectorMind automatically runs small, throttled memory maintenance to compact old completed history and prune stale indexes in long-lived projects. For large repos that feel slow, call maintain_memory({ dry_run: true }) first, then maintain_memory({ dry_run: false }) if the plan looks correct.",
         "- Use get_token_savings({ format: 'compact' }) when you need to verify how many tokens VectorMind compact outputs saved.",
         "",
         "If tool output conflicts with assumptions, trust the tool output.",
@@ -3483,6 +4926,15 @@ function initMemoryItemsFts() {
         ftsAvailable = false;
     }
 }
+function columnExists(table, column) {
+    try {
+        const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+        return rows.some((row) => row.name === column);
+    }
+    catch {
+        return false;
+    }
+}
 function initDatabase() {
     const vmDir = path.join(projectRoot, ".vectormind");
     try {
@@ -3535,7 +4987,8 @@ function initDatabase() {
       title TEXT NOT NULL,
       status TEXT DEFAULT 'active',
       context_data TEXT,
-      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
     );
 
     CREATE TABLE IF NOT EXISTS change_logs (
@@ -3634,6 +5087,49 @@ function initDatabase() {
 
     CREATE INDEX IF NOT EXISTS idx_token_savings_tool
       ON token_savings(tool);
+
+    CREATE TABLE IF NOT EXISTS memory_item_archive (
+      memory_id INTEGER PRIMARY KEY,
+      original_kind TEXT NOT NULL,
+      original_title TEXT,
+      original_content TEXT NOT NULL,
+      original_file_path TEXT,
+      original_start_line INTEGER,
+      original_end_line INTEGER,
+      original_req_id INTEGER,
+      original_metadata_json TEXT,
+      original_content_hash TEXT,
+      original_created_at DATETIME,
+      original_updated_at DATETIME,
+      archive_reason TEXT NOT NULL,
+      compacted_into_id INTEGER,
+      archived_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_memory_item_archive_compacted_into
+      ON memory_item_archive(compacted_into_id);
+
+    CREATE TABLE IF NOT EXISTS meta_kv (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL,
+      updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+  `);
+    if (!columnExists("requirements", "updated_at")) {
+        db.exec(`ALTER TABLE requirements ADD COLUMN updated_at DATETIME`);
+        db.exec(`UPDATE requirements SET updated_at = COALESCE(created_at, CURRENT_TIMESTAMP) WHERE updated_at IS NULL`);
+    }
+    db.exec(`
+    UPDATE requirements SET updated_at = COALESCE(updated_at, created_at, CURRENT_TIMESTAMP) WHERE updated_at IS NULL;
+    CREATE INDEX IF NOT EXISTS idx_requirements_status_updated_at
+      ON requirements(status, updated_at DESC, id DESC);
+    CREATE TRIGGER IF NOT EXISTS vectormind_requirements_touch_updated_at
+    AFTER UPDATE ON requirements
+    FOR EACH ROW
+    WHEN NEW.updated_at = OLD.updated_at
+    BEGIN
+      UPDATE requirements SET updated_at = CURRENT_TIMESTAMP WHERE id = NEW.id;
+    END;
   `);
     initMemoryItemsFts();
     insertRequirementStmt = db.prepare(`INSERT INTO requirements (title, context_data, status) VALUES (?, ?, 'active')`);
@@ -3642,11 +5138,16 @@ function initDatabase() {
     getActiveRequirementStmt = db.prepare(`SELECT id, title, status, context_data, created_at
      FROM requirements
      WHERE status = 'active'
-     ORDER BY created_at DESC, id DESC
+     ORDER BY updated_at DESC, created_at DESC, id DESC
      LIMIT 1`);
+    listActiveRequirementsStmt = db.prepare(`SELECT id, title, status, context_data, created_at
+     FROM requirements
+     WHERE status = 'active'
+     ORDER BY updated_at DESC, created_at DESC, id DESC
+     LIMIT ?`);
     listRecentRequirementsStmt = db.prepare(`SELECT id, title, status, context_data, created_at
      FROM requirements
-     ORDER BY created_at DESC, id DESC
+     ORDER BY updated_at DESC, created_at DESC, id DESC
      LIMIT ?`);
     completeAllActiveRequirementMemoryItemsStmt = db.prepare(`UPDATE memory_items
      SET metadata_json = ?, updated_at = CURRENT_TIMESTAMP
@@ -3723,6 +5224,11 @@ function initDatabase() {
      WHERE kind = 'note'
      ORDER BY updated_at DESC, id DESC
      LIMIT ?`);
+    listRecentContextItemsStmt = db.prepare(`SELECT id, kind, title, content, file_path, start_line, end_line, req_id, metadata_json, content_hash, created_at, updated_at
+     FROM memory_items
+     WHERE kind IN ('note', 'requirement', 'change_intent')
+     ORDER BY updated_at DESC, id DESC
+     LIMIT ?`);
     getLatestChangeIntentForFileStmt = db.prepare(`SELECT id, kind, title, content, file_path, start_line, end_line, req_id, metadata_json, content_hash, created_at, updated_at
      FROM memory_items
      WHERE kind = 'change_intent' AND file_path = ?
@@ -3801,6 +5307,10 @@ function initDatabase() {
      FROM token_savings
      ORDER BY created_at DESC, id DESC
      LIMIT ?`);
+    getKvStmt = db.prepare(`SELECT value FROM meta_kv WHERE key = ?`);
+    setKvStmt = db.prepare(`INSERT INTO meta_kv (key, value)
+     VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP`);
     indexFileSymbolsTx = db.transaction((filePath, symbols) => {
         deleteSymbolsForFileStmt.run(filePath);
         for (const s of symbols) {
@@ -3816,6 +5326,9 @@ function initDatabase() {
     // Clean up common "file name noise" recorded by older versions.
     // (These files are ignored by current index rules; keep the DB consistent automatically.)
     pruneFilenameNoiseIndexes();
+    // Bounded, throttled maintenance keeps long-lived project memory fast without
+    // deleting durable decisions/conventions/project summaries.
+    runAutoMaintenanceIfDue();
 }
 function initWatcher() {
     watcherReady = false;
@@ -3947,14 +5460,19 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         tools: [
             {
                 name: "start_requirement",
-                description: "MUST call BEFORE editing code. Starts/activates a requirement so all subsequent code changes can be linked to a concrete intent (do not edit code without an active requirement).",
+                description: "MUST call BEFORE editing code. Starts/activates the concrete user requirement so subsequent changes stay inside that requirement boundary and do not accumulate unrelated work. Supports scope_allow/scope_deny and allowed_paths/denied_paths to prevent unrelated domain drift.",
                 inputSchema: toJsonSchemaCompat(StartRequirementArgsSchema),
             },
             {
                 name: "sync_change_intent",
-                description: "MUST call AFTER you edit code and save files. Archives the intent summary and links affected files to the current active requirement. If you omit files, the server will auto-link all pending changed files since the last sync.",
+                description: "MUST call AFTER you edit code and save files. Archives the intent summary, links affected files to the current active requirement, and returns development_warnings for oversized files, broad change scope, or missing file targets.",
                 inputSchema: toJsonSchemaCompat(SyncChangeIntentArgsSchema),
             },
+            {
+                name: "preflight_change_scope",
+                description: "MUST call BEFORE editing once you know the intended files/modules. Checks planned files against the active requirement and optional generic scope_allow/scope_deny/allowed_paths/denied_paths. If ok=false/safe_to_edit=false, stop before editing and narrow the plan or scope contract.",
+                inputSchema: toJsonSchemaCompat(PreflightChangeScopeArgsSchema),
+            },
             {
                 name: "get_brain_dump",
                 description: "Restore recent requirements/changes/notes/summary/pending changes. Prefer bootstrap_context() at session start when you also want recall from the local memory store.",
@@ -3962,12 +5480,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "bootstrap_context",
-                description: "MUST call at the start of every new chat/session. Returns brain dump + pending changes, and (if you pass query) matches from the local memory store to avoid guessing.",
+                description: "MUST call at the start of every new chat/session. Returns brain dump + pending changes + development_warnings, and (if you pass query) matches from the local memory store to avoid guessing.",
                 inputSchema: toJsonSchemaCompat(BootstrapContextArgsSchema),
             },
             {
                 name: "get_pending_changes",
-                description: "List files that changed locally but have not been acknowledged by sync_change_intent yet. Use this to see what needs syncing (or omit files in sync_change_intent to auto-link them).",
+                description: "List files that changed locally but have not been acknowledged by sync_change_intent yet. Also returns development_warnings to catch god-file growth, broad change scope, and requirement-boundary drift.",
                 inputSchema: toJsonSchemaCompat(GetPendingChangesArgsSchema),
             },
             {
@@ -4012,7 +5530,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: "grep",
-                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.",
+                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. Returns development_warnings for cross-project paths or huge implementation-file matches.",
                 inputSchema: toJsonSchemaCompat(GrepArgsSchema),
             },
             {
@@ -4022,12 +5540,12 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 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.",
+                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 another local-file 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.",
+                description: "Read a specific line range from a file under project_root (with strict size limits). Prefer this over Get-Content for deterministic reads. Returns development_warnings when the target is a huge implementation file.",
                 inputSchema: toJsonSchemaCompat(ReadFileLinesArgsSchema),
             },
             {
@@ -4037,7 +5555,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 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.",
+                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. Returns development_warnings when matches point at huge implementation files.",
                 inputSchema: toJsonSchemaCompat(QueryCodebaseArgsSchema),
             },
             {
@@ -4070,6 +5588,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: "maintain_memory",
+                description: "Compact old completed memory and prune stale/noisy indexes to keep long-lived large projects fast. Defaults to dry_run=true; automatic safe maintenance also runs periodically.",
+                inputSchema: toJsonSchemaCompat(MaintainMemoryArgsSchema),
+            },
             {
                 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.",
@@ -4086,6 +5609,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (toolName === "start_requirement") {
             const args = StartRequirementArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
+            const scope_contract = buildRequirementScopeContract({
+                title: args.title,
+                background: args.background,
+                scope_allow: args.scope_allow,
+                scope_deny: args.scope_deny,
+                allowed_paths: args.allowed_paths,
+                denied_paths: args.denied_paths,
+            });
+            const development_warnings = buildRequirementStartWarnings({
+                title: args.title,
+                background: args.background,
+                close_previous: args.close_previous,
+            });
             if (args.close_previous) {
                 try {
                     completeAllActiveRequirementsStmt.run();
@@ -4099,13 +5635,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const id = Number(info.lastInsertRowid);
             const background = args.background?.trim() ?? "";
             const content = background ? `${args.title}\n\n${background}` : args.title;
-            const memoryInfo = insertMemoryItemStmt.run("requirement", args.title, content, null, null, null, id, safeJson({ status: "active" }), sha256Hex(content));
+            const memoryInfo = insertMemoryItemStmt.run("requirement", args.title, content, null, null, null, id, safeJson({ status: "active", scope_contract }), sha256Hex(content));
             const memory_id = Number(memoryInfo.lastInsertRowid);
             enqueueEmbedding(memory_id);
             logActivity("start_requirement", {
                 req_id: id,
                 title: args.title,
                 closed_previous: args.close_previous,
+                scope_contract,
+                development_warnings: development_warnings.length,
             });
             return {
                 content: [
@@ -4116,6 +5654,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             requirement: { id, title: args.title },
                             memory_item: { id: memory_id },
                             closed_previous: args.close_previous,
+                            scope_contract,
+                            development_warnings,
                         }),
                     },
                 ],
@@ -4257,6 +5797,78 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        if (toolName === "maintain_memory") {
+            const args = MaintainMemoryArgsSchema.parse(rawArgs);
+            flushPendingChangeBuffer();
+            const result = runMemoryMaintenance(args, "manual");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolCompactOrJson("maintain_memory", result, compactMaintenanceText(result), args.format),
+                    },
+                ],
+            };
+        }
+        if (toolName === "preflight_change_scope") {
+            const args = PreflightChangeScopeArgsSchema.parse(rawArgs);
+            flushPendingChangeBuffer();
+            const files = (args.files ?? args.planned_files ?? []).filter((f) => typeof f === "string" && f.length > 0);
+            const active = getActiveRequirementStmt.get();
+            const explicitContract = buildRequirementScopeContract({
+                title: active?.title ?? "",
+                background: active?.context_data ?? "",
+                scope_allow: args.scope_allow,
+                scope_deny: args.scope_deny,
+                allowed_paths: args.allowed_paths,
+                denied_paths: args.denied_paths,
+            });
+            const fileInputs = files.map((file_path) => ({ file_path }));
+            const development_warnings = [
+                ...buildDevelopmentWarnings(fileInputs, { includeUnspecified: fileInputs.length === 0 }),
+                ...buildScopeDriftWarnings({
+                    requirement: active,
+                    contract: explicitContract,
+                    intent: args.intent,
+                    files: fileInputs,
+                    includeMissingContractHint: true,
+                }),
+            ];
+            const scope_contract = mergeScopeContracts(active ? getRequirementScopeContract(active.id) : null, explicitContract);
+            logActivity("preflight_change_scope", {
+                req_id: active?.id ?? null,
+                intent_preview: makePreviewText(args.intent, 200),
+                files: files.slice(0, 25),
+                files_total: files.length,
+                development_warnings: development_warnings.length,
+            });
+            const hasTargetFiles = fileInputs.length > 0;
+            const hasBlockingWarnings = development_warnings.some((w) => w.severity === "blocker" || w.severity === "warning");
+            const safeToEdit = hasTargetFiles && !hasBlockingWarnings;
+            const recommendedAction = !hasTargetFiles
+                ? "Identify the intended target files/modules and rerun preflight_change_scope before editing."
+                : hasBlockingWarnings
+                    ? "Stop before editing. Narrow the planned files or explicitly expand the current requirement/scope contract."
+                    : "Planned files are within the current generic scope checks.";
+            const outputValue = {
+                ok: safeToEdit,
+                safe_to_edit: safeToEdit,
+                recommended_action: recommendedAction,
+                active_requirement: active ? { id: active.id, title: active.title } : null,
+                intent: args.intent,
+                files: files.map(normalizeToDbPath),
+                scope_contract,
+                development_warnings,
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolCompactOrJson("preflight_change_scope", outputValue, compactPreflightChangeScopeText(outputValue), args.format),
+                    },
+                ],
+            };
+        }
         if (toolName === "sync_change_intent") {
             const args = SyncChangeIntentArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
@@ -4341,12 +5953,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
             });
             insertTx();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(synced_files, {
+                    includeUnspecified: synced_files.some((f) => f.file_path === "(unspecified)"),
+                }),
+                ...buildScopeDriftWarnings({
+                    requirement: active,
+                    intent: args.intent,
+                    files: synced_files,
+                }),
+            ];
             logActivity("sync_change_intent", {
                 req_id: active.id,
                 title: active.title,
                 intent_preview: makePreviewText(args.intent, 200),
                 files: synced_files.slice(0, 25),
                 files_total: synced_files.length,
+                development_warnings: development_warnings.length,
             });
             return {
                 content: [
@@ -4357,6 +5980,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                             linked_to_requirement: { id: active.id, title: active.title },
                             synced_files,
                             created,
+                            development_warnings,
                         }),
                     },
                 ],
@@ -4373,6 +5997,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const notesLimit = args.notes_limit;
             const conventionsLimit = args.conventions_limit;
             const decisionsLimit = args.decisions_limit;
+            const currentContextLimit = args.current_context_limit;
             const recent = listRecentRequirementsStmt.all(requirementsLimit);
             const items = recent.map((req) => {
                 const changes = listChangeLogsForRequirementStmt.all(req.id, changesLimit);
@@ -4388,6 +6013,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
             const decisions = getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars);
             const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
+            const current_context = getCurrentContextPreviews(currentContextLimit, previewChars, contentMaxChars);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
             const pendingDbRows = listPendingChangesStmt.all();
@@ -4395,13 +6021,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const pending_total = mergedPending.total;
             const pending_truncated = mergedPending.truncated;
             const pending_changes = mergedPending.page;
+            const activeForScope = getActiveRequirementStmt.get();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(pending_changes),
+                ...(activeForScope
+                    ? buildScopeDriftWarnings({ requirement: activeForScope, files: pending_changes })
+                    : []),
+            ];
             const q = args.query?.trim() ?? "";
+            const semanticKinds = args.kinds?.length ? args.kinds : BOOTSTRAP_DEFAULT_CONTEXT_KINDS;
             const semantic = q
                 ? await Promise.race([
                     semanticSearchHybridInternal({
                         query: q,
                         topK: args.top_k,
-                        kinds: args.kinds?.length ? args.kinds : null,
+                        kinds: semanticKinds,
                         includeContent,
                         previewChars,
                         contentMaxChars,
@@ -4418,6 +6052,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_returned: pending_changes.length,
                 requirements_returned: items.length,
                 decisions_returned: decisions.length,
+                current_context_returned: current_context.length,
                 conventions_returned: conventions.length,
                 semantic_mode: semantic?.mode ?? null,
                 semantic_matches: semantic?.matches?.length ?? 0,
@@ -4444,17 +6079,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     changes_limit: changesLimit,
                     notes_limit: notesLimit,
                     decisions_limit: decisionsLimit,
+                    current_context_limit: currentContextLimit,
                     conventions_limit: conventionsLimit,
                 },
                 project_summary,
                 decisions,
                 conventions,
+                current_context,
                 recent_notes,
                 pending_total,
                 pending_offset,
                 pending_limit,
                 pending_truncated,
                 pending_changes,
+                development_warnings,
                 items,
                 semantic,
             };
@@ -4478,6 +6116,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const notesLimit = args.notes_limit;
             const conventionsLimit = args.conventions_limit;
             const decisionsLimit = args.decisions_limit;
+            const currentContextLimit = args.current_context_limit;
             const recent = listRecentRequirementsStmt.all(requirementsLimit);
             const items = recent.map((req) => {
                 const changes = listChangeLogsForRequirementStmt.all(req.id, changesLimit);
@@ -4493,6 +6132,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
             const decisions = getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars);
             const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
+            const current_context = getCurrentContextPreviews(currentContextLimit, previewChars, contentMaxChars);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
             const pendingDbRows = listPendingChangesStmt.all();
@@ -4500,12 +6140,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const pending_total = mergedPending.total;
             const pending_truncated = mergedPending.truncated;
             const pending_changes = mergedPending.page;
+            const activeForScope = getActiveRequirementStmt.get();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(pending_changes),
+                ...(activeForScope
+                    ? buildScopeDriftWarnings({ requirement: activeForScope, files: pending_changes })
+                    : []),
+            ];
             logActivity("get_brain_dump", {
                 pending_total,
                 pending_returned: pending_changes.length,
                 requirements_returned: items.length,
                 notes_returned: recent_notes.length,
                 decisions_returned: decisions.length,
+                current_context_returned: current_context.length,
                 conventions_returned: conventions.length,
             });
             const outputValue = {
@@ -4530,17 +6178,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     changes_limit: changesLimit,
                     notes_limit: notesLimit,
                     decisions_limit: decisionsLimit,
+                    current_context_limit: currentContextLimit,
                     conventions_limit: conventionsLimit,
                 },
                 project_summary,
                 decisions,
                 conventions,
+                current_context,
                 recent_notes,
                 pending_total,
                 pending_offset,
                 pending_limit,
                 pending_truncated,
                 pending_changes,
+                development_warnings,
                 items,
                 semantic: null,
             };
@@ -4563,18 +6214,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const total = mergedPending.total;
             const truncated = mergedPending.truncated;
             const pending = mergedPending.page;
+            const activeForScope = getActiveRequirementStmt.get();
+            const development_warnings = [
+                ...buildDevelopmentWarnings(pending),
+                ...(activeForScope ? buildScopeDriftWarnings({ requirement: activeForScope, files: pending }) : []),
+            ];
             logActivity("get_pending_changes", {
                 total,
                 offset,
                 limit,
                 returned: pending.length,
                 truncated,
+                development_warnings: development_warnings.length,
             });
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({ ok: true, total, offset, limit, truncated, pending }),
+                        text: toolJson({ ok: true, total, offset, limit, truncated, pending, development_warnings }),
                     },
                 ],
             };
@@ -4765,6 +6422,10 @@ 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 development_warnings = [
+                ...buildCrossProjectPathWarnings(includePaths),
+                ...buildCrossProjectPathWarnings(excludePaths),
+            ];
             const caseSensitive = args.case_sensitive ?? (smartCase ? hasUppercaseAscii(q) : true);
             const ripgrepResult = runRipgrepSearch({
                 query: q,
@@ -4776,6 +6437,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 maxResults,
             });
             if (ripgrepResult.ok) {
+                const grepDevelopmentWarnings = [
+                    ...development_warnings,
+                    ...buildMatchedFileDevelopmentWarnings(ripgrepResult.matches.map((m) => m.file_path)),
+                ];
                 logActivity("grep", {
                     backend: ripgrepResult.backend,
                     rg_command: ripgrepResult.rg_command,
@@ -4788,6 +6453,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     matches: ripgrepResult.matches.length,
                     total_matches: ripgrepResult.total_matches,
                     truncated: ripgrepResult.truncated,
+                    development_warnings: grepDevelopmentWarnings.length,
                 });
                 const outputValue = {
                     ok: true,
@@ -4802,6 +6468,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     matches: ripgrepResult.matches,
                     total_matches: ripgrepResult.total_matches,
                     truncated: ripgrepResult.truncated,
+                    development_warnings: grepDevelopmentWarnings,
                 };
                 return {
                     content: [
@@ -4867,6 +6534,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            const grepDevelopmentWarnings = [
+                ...development_warnings,
+                ...buildMatchedFileDevelopmentWarnings(indexedResult.matches.map((m) => m.file_path)),
+            ];
             logActivity("grep", {
                 backend: indexedResult.backend,
                 fallback_reason: "ripgrep_unavailable",
@@ -4883,6 +6554,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 candidates_scanned: indexedResult.candidates.scanned,
                 matches: indexedResult.matches.length,
                 truncated: indexedResult.truncated,
+                development_warnings: grepDevelopmentWarnings.length,
             });
             const outputValue = {
                 ok: true,
@@ -4901,6 +6573,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 candidates: indexedResult.candidates,
                 matches: indexedResult.matches,
                 truncated: indexedResult.truncated,
+                development_warnings: grepDevelopmentWarnings,
             };
             return {
                 content: [
@@ -5020,6 +6693,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 total_chars: result.totalChars,
                 truncated: result.truncated,
             });
+            const development_warnings = buildFileReadDevelopmentWarnings(resolved.dbFilePath, resolved.absPath, st);
             const outputValue = {
                 ok: true,
                 file_path: resolved.dbFilePath,
@@ -5027,6 +6701,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 returned_chars: result.returnedChars,
                 total_chars: result.totalChars,
                 truncated: result.truncated,
+                development_warnings,
                 text: result.text,
             };
             return {
@@ -5156,6 +6831,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 returned: result.returned,
                 truncated: result.truncated,
             });
+            const development_warnings = buildFileReadDevelopmentWarnings(resolved.dbFilePath, resolved.absPath, st);
             const outputValue = {
                 ok: true,
                 file_path: resolved.dbFilePath,
@@ -5163,6 +6839,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 to_line: toLine,
                 returned: result.returned,
                 truncated: result.truncated,
+                development_warnings,
                 text: result.text,
             };
             return {
@@ -5181,12 +6858,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const like = `%${escaped}%`;
             const rows = searchSymbolsStmt.all(like, like, q, like, 250);
             const filtered = rows.filter((r) => !shouldIgnoreDbFilePath(r.file_path)).slice(0, 50);
+            const development_warnings = buildMatchedFileDevelopmentWarnings(filtered.map((m) => m.file_path));
             logActivity("query_codebase", {
                 query: q,
                 matches: filtered.length,
+                development_warnings: development_warnings.length,
                 sample: filtered.slice(0, 10).map((m) => ({ name: m.name, type: m.type, file_path: m.file_path })),
             });
-            const outputValue = { ok: true, query: q, matches: filtered };
+            const outputValue = { ok: true, query: q, matches: filtered, development_warnings };
             return {
                 content: [
                     {