@coreyuan/vector-mind 1.0.38 → 1.0.41

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_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_THREAD_HANDOFF_SWITCH_INSTRUCTIONS, BUILTIN_WRITE_POLICY_INSTRUCTIONS, } from "./builtin-instructions.js";
 const SERVER_NAME = "vector-mind";
-const SERVER_VERSION = "1.0.38";
+const SERVER_VERSION = "1.0.41";
 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());
@@ -164,9 +164,13 @@ let getConventionByKeyStmt;
 let insertConventionStmt;
 let updateConventionByIdStmt;
 let listConventionsStmt;
+let upsertDecisionStmt;
+let getDecisionByKeyStmt;
+let listCurrentDecisionsStmt;
 let upsertProjectSummaryStmt;
 let getProjectSummaryStmt;
 let listRecentNotesStmt;
+let getLatestChangeIntentForFileStmt;
 let deleteFileChunkItemsStmt;
 let getEmbeddingMetaStmt;
 let upsertEmbeddingStmt;
@@ -181,6 +185,10 @@ let deleteOldestPendingChangesStmt = null;
 let deleteSymbolsForFileStmt;
 let upsertSymbolStmt;
 let searchSymbolsStmt;
+let insertTokenSavingsStmt;
+let summarizeTokenSavingsStmt;
+let summarizeTokenSavingsByToolStmt;
+let listRecentTokenSavingsStmt;
 let indexFileSymbolsTx = null;
 let activitySeq = 0;
 const activityLog = [];
@@ -552,6 +560,89 @@ function shouldIgnoreDbFilePath(filePath) {
         return false;
     return pathHasIgnoredSegments(filePath);
 }
+function isProbablyGitRepository() {
+    try {
+        return fs.existsSync(path.join(projectRoot, ".git"));
+    }
+    catch {
+        return false;
+    }
+}
+function normalizeGitStatusPath(raw) {
+    const first = raw.split("\0")[0] ?? "";
+    return first.trim().replace(/\\/g, "/").replace(/^"(.*)"$/, "$1");
+}
+function collectGitPendingChanges(limit) {
+    if (limit <= 0 || !isProbablyGitRepository())
+        return [];
+    const git = spawnSync("git", ["status", "--porcelain=v1", "-z", "--untracked-files=normal"], {
+        cwd: projectRoot,
+        encoding: "utf8",
+        timeout: 5000,
+        windowsHide: true,
+        maxBuffer: 2_000_000,
+    });
+    if (git.error || git.status !== 0 || !git.stdout)
+        return [];
+    const parts = git.stdout.split("\0").filter(Boolean);
+    const rows = [];
+    for (let i = 0; i < parts.length && rows.length < limit; i++) {
+        const rec = parts[i] ?? "";
+        const status = rec.slice(0, 2);
+        let rawPath = rec.slice(3);
+        if (status.startsWith("R") || status.startsWith("C")) {
+            // Porcelain -z rename/copy records include the destination in the next NUL field.
+            rawPath = parts[i + 1] ?? rawPath;
+            i += 1;
+        }
+        const filePath = normalizeGitStatusPath(rawPath);
+        if (!filePath || filePath === ".vectormind" || filePath.startsWith(".vectormind/"))
+            continue;
+        rows.push({
+            file_path: filePath,
+            last_event: status.includes("D") ? "unlink" : status === "??" ? "add" : "change",
+            updated_at: new Date().toISOString(),
+            source: "git",
+            git_status: status.trim() || "modified",
+            file_state_hash: getFileStateHash(filePath) ?? undefined,
+        });
+    }
+    return rows;
+}
+function mergePendingWithGit(pending, opts) {
+    const byPath = new Map();
+    for (const p of pending) {
+        if (shouldIgnoreDbFilePath(p.file_path))
+            continue;
+        byPath.set(p.file_path, { ...p, source: p.source ?? "watcher" });
+    }
+    const gitRows = collectGitPendingChanges(Math.max(500, opts.offset + opts.limit * 4));
+    for (const g of gitRows) {
+        const latestSyncedHash = getLatestSyncedFileHash(g.file_path);
+        if (latestSyncedHash && g.file_state_hash && latestSyncedHash === g.file_state_hash)
+            continue;
+        const existing = byPath.get(g.file_path);
+        if (!existing) {
+            byPath.set(g.file_path, g);
+            continue;
+        }
+        byPath.set(g.file_path, {
+            ...existing,
+            source: existing.source === "watcher" ? "watcher" : g.source,
+            git_status: g.git_status,
+            file_state_hash: g.file_state_hash,
+        });
+    }
+    const all = Array.from(byPath.values()).sort((a, b) => {
+        const at = Date.parse(a.updated_at) || 0;
+        const bt = Date.parse(b.updated_at) || 0;
+        if (bt !== at)
+            return bt - at;
+        return a.file_path.localeCompare(b.file_path);
+    });
+    const page = all.slice(opts.offset, opts.offset + opts.limit);
+    return { total: all.length, page, truncated: all.length > opts.offset + opts.limit };
+}
 function pruneIgnoredPendingChanges() {
     if (!db)
         return;
@@ -1149,6 +1240,9 @@ function removeFileIndexes(absPath) {
 const ProjectRootArgSchema = z.object({
     project_root: z.string().optional(),
 });
+const OutputFormatSchema = z.object({
+    format: z.enum(["compact", "json"]).optional().default("compact"),
+});
 const StartRequirementArgsSchema = ProjectRootArgSchema.merge(z.object({
     title: z.string().min(1),
     background: z.string().optional().default(""),
@@ -1159,10 +1253,10 @@ const SyncChangeIntentArgsSchema = ProjectRootArgSchema.merge(z.object({
     files: z.array(z.string().min(1)).optional(),
     affected_files: z.array(z.string().min(1)).optional(),
 }));
-const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(z.object({
+const QueryCodebaseArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     query: z.string().min(1),
 }));
-const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
+const GrepArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     // Pattern to search for. Defaults to regex mode for parity with tools like ripgrep.
     query: z.string().min(1),
     mode: z.enum(["regex", "literal"]).optional().default("regex"),
@@ -1179,7 +1273,7 @@ const GrepArgsSchema = ProjectRootArgSchema.merge(z.object({
     // Compatibility knob for the indexed fallback when ripgrep is unavailable.
     max_candidates: z.number().int().min(1).max(50_000).optional(),
 }));
-const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
+const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     // Relative to project_root, or an absolute path under project_root.
     path: z.string().min(1),
     from_line: z.number().int().min(1).optional().default(1),
@@ -1190,7 +1284,7 @@ const ReadFileLinesArgsSchema = ProjectRootArgSchema.merge(z.object({
     max_lines: z.number().int().min(1).max(2000).optional().default(400),
     max_chars: z.number().int().min(200).max(200_000).optional().default(20_000),
 }));
-const ReadFileTextArgsSchema = ProjectRootArgSchema.merge(z.object({
+const ReadFileTextArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     // Relative to project_root, or an absolute path under project_root.
     path: z.string().min(1),
     // Character offset in the decoded UTF-8 text.
@@ -1200,14 +1294,14 @@ const ReadFileTextArgsSchema = ProjectRootArgSchema.merge(z.object({
     // Safety guard for raw reads; use read_file_lines on larger files.
     max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
 }));
-const ReadCodexTextFileArgsSchema = ProjectRootArgSchema.merge(z.object({
+const ReadCodexTextFileArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     // Absolute path, file:// URI, or a path under CODEX_HOME / AGENTS_HOME allowed roots.
     path: z.string().min(1),
     offset: z.number().int().min(0).optional().default(0),
     max_chars: z.number().int().min(1).max(200_000).optional().default(20_000),
     max_file_bytes: z.number().int().min(1_000).max(5_000_000).optional().default(1_000_000),
 }));
-const ListProjectFilesArgsSchema = ProjectRootArgSchema.merge(z.object({
+const ListProjectFilesArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     // Relative directory/file path under project_root. "." means the project root.
     path: z.string().optional().default("."),
     recursive: z.boolean().optional().default(false),
@@ -1242,29 +1336,48 @@ const UpsertConventionArgsSchema = ProjectRootArgSchema.merge(z.object({
     content: z.string().min(1),
     tags: z.array(z.string().min(1)).optional(),
 }));
-const DEFAULT_PENDING_LIMIT = 50;
+const UpsertDecisionArgsSchema = ProjectRootArgSchema.merge(z.object({
+    key: z.string().min(1),
+    title: z.string().optional().default(""),
+    content: z.string().min(1),
+    tags: z.array(z.string().min(1)).optional(),
+    supersedes_req_ids: z.array(z.number().int().positive()).optional(),
+    supersedes_memory_ids: z.array(z.number().int().positive()).optional(),
+    related_files: z.array(z.string().min(1)).optional(),
+}));
+const SupersedeMemoryArgsSchema = ProjectRootArgSchema.merge(z.object({
+    superseded_req_ids: z.array(z.number().int().positive()).optional(),
+    superseded_memory_ids: z.array(z.number().int().positive()).optional(),
+    replacement_req_id: z.number().int().positive().optional(),
+    replacement_memory_id: z.number().int().positive().optional(),
+    reason: z.string().min(1),
+}));
+const DEFAULT_PENDING_LIMIT = 10;
 const MAX_PENDING_LIMIT = 2000;
 const PendingPagingSchema = z.object({
     pending_offset: z.number().int().min(0).optional().default(0),
     pending_limit: z.number().int().min(1).max(MAX_PENDING_LIMIT).optional().default(DEFAULT_PENDING_LIMIT),
 });
-const DEFAULT_PREVIEW_CHARS = 200;
+const DEFAULT_PREVIEW_CHARS = 120;
 const PreviewSchema = z.object({
     preview_chars: z.number().int().min(50).max(10_000).optional().default(DEFAULT_PREVIEW_CHARS),
 });
-const DEFAULT_CONTENT_MAX_CHARS = 2000;
+const DEFAULT_CONTENT_MAX_CHARS = 1200;
 const ContentMaxSchema = z.object({
     content_max_chars: z.number().int().min(0).max(200_000).optional().default(DEFAULT_CONTENT_MAX_CHARS),
 });
-const DEFAULT_RECENT_REQUIREMENTS = 3;
-const DEFAULT_RECENT_CHANGES_PER_REQ = 5;
-const DEFAULT_RECENT_NOTES = 5;
-const DEFAULT_CONVENTIONS_LIMIT = 20;
+const DEFAULT_RECENT_REQUIREMENTS = 2;
+const DEFAULT_RECENT_CHANGES_PER_REQ = 3;
+const DEFAULT_RECENT_NOTES = 3;
+const DEFAULT_CONVENTIONS_LIMIT = 0;
+const DEFAULT_DECISIONS_LIMIT = 5;
+const MAX_DECISIONS_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),
 });
 const GetPendingChangesArgsSchema = ProjectRootArgSchema.merge(z.object({
     offset: z.number().int().min(0).optional().default(0),
@@ -1285,6 +1398,7 @@ const GetActivitySummaryArgsSchema = ProjectRootArgSchema.merge(z.object({
 }));
 const ClearActivityLogArgsSchema = ProjectRootArgSchema;
 const GetBrainDumpArgsSchema = ProjectRootArgSchema.merge(PendingPagingSchema)
+    .merge(OutputFormatSchema)
     .merge(PreviewSchema)
     .merge(ContentMaxSchema)
     .merge(BrainDumpLimitsSchema)
@@ -1293,16 +1407,17 @@ const GetBrainDumpArgsSchema = ProjectRootArgSchema.merge(PendingPagingSchema)
 }));
 const BootstrapContextArgsSchema = ProjectRootArgSchema.merge(z.object({
     query: z.string().optional(),
-    top_k: z.number().int().min(1).max(50).optional().default(5),
+    top_k: z.number().int().min(1).max(50).optional().default(3),
     kinds: z.array(z.string().min(1)).optional(),
     include_content: z.boolean().optional().default(false),
     pending_offset: z.number().int().min(0).optional().default(0),
     pending_limit: z.number().int().min(1).max(MAX_PENDING_LIMIT).optional().default(DEFAULT_PENDING_LIMIT),
 })
+    .merge(OutputFormatSchema)
     .merge(PreviewSchema)
     .merge(ContentMaxSchema)
     .merge(BrainDumpLimitsSchema));
-const SemanticSearchArgsSchema = ProjectRootArgSchema.merge(z.object({
+const SemanticSearchArgsSchema = ProjectRootArgSchema.merge(OutputFormatSchema).merge(z.object({
     query: z.string().min(1),
     top_k: z.number().int().min(1).max(50).optional().default(8),
     kinds: z.array(z.string().min(1)).optional(),
@@ -1311,6 +1426,21 @@ const SemanticSearchArgsSchema = ProjectRootArgSchema.merge(z.object({
     content_max_chars: z.number().int().min(0).max(200_000).optional().default(DEFAULT_CONTENT_MAX_CHARS),
 }));
 const ProjectRootOnlyArgsSchema = ProjectRootArgSchema;
+const GetTokenSavingsArgsSchema = ProjectRootArgSchema.merge(z.object({
+    limit: z.number().int().min(1).max(100).optional().default(10),
+    format: z.enum(["compact", "json"]).optional().default("compact"),
+}));
+const DetectRtkArgsSchema = ProjectRootArgSchema;
+const InstallRtkArgsSchema = ProjectRootArgSchema.merge(z.object({
+    dry_run: z.boolean().optional().default(true),
+    method: z.enum(["auto", "cargo", "brew", "shell_script"]).optional().default("auto"),
+    init: z
+        .enum(["none", "global_no_patch", "global_auto_patch", "global_hook_only", "local", "codex_global", "codex_local"])
+        .optional()
+        .default("none"),
+    uninstall_wrong_cargo_rtk: z.boolean().optional().default(false),
+    timeout_ms: z.number().int().min(10_000).max(1_800_000).optional().default(600_000),
+}));
 const ReadMemoryItemArgsSchema = ProjectRootArgSchema.merge(z.object({
     id: z.number().int().positive(),
     offset: z.number().int().min(0).optional().default(0),
@@ -1322,6 +1452,28 @@ function escapeLike(pattern) {
 function sha256Hex(input) {
     return crypto.createHash("sha256").update(input).digest("hex");
 }
+function getFileStateHash(dbOrAbsPath) {
+    try {
+        const abs = path.isAbsolute(dbOrAbsPath) ? dbOrAbsPath : path.join(projectRoot, dbOrAbsPath);
+        const st = fs.statSync(abs);
+        if (!st.isFile())
+            return sha256Hex(`non-file:${st.mtimeMs}:${st.size}`);
+        if (st.size <= 5_000_000) {
+            return crypto.createHash("sha256").update(fs.readFileSync(abs)).digest("hex");
+        }
+        return sha256Hex(`large:${st.size}:${Math.floor(st.mtimeMs)}`);
+    }
+    catch {
+        return sha256Hex("missing");
+    }
+}
+function getLatestSyncedFileHash(dbFilePath) {
+    const row = getLatestChangeIntentForFileStmt?.get(dbFilePath);
+    if (!row)
+        return null;
+    const meta = parseMetadataJson(row.metadata_json);
+    return typeof meta.file_state_hash === "string" ? meta.file_state_hash : null;
+}
 function safeJson(value) {
     if (value === undefined)
         return null;
@@ -1335,6 +1487,511 @@ function safeJson(value) {
 function toolJson(value) {
     return JSON.stringify(value, null, prettyJsonOutput ? 2 : undefined);
 }
+function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / 4);
+}
+function recordTokenSavings(tool, rawText, outputText) {
+    if (!db || !insertTokenSavingsStmt)
+        return;
+    const rawTokens = estimateTokens(rawText);
+    const outputTokens = estimateTokens(outputText);
+    const savedTokens = Math.max(0, rawTokens - outputTokens);
+    const savingsPct = rawTokens > 0 ? (savedTokens / rawTokens) * 100 : 0;
+    try {
+        insertTokenSavingsStmt.run(tool, rawTokens, outputTokens, savedTokens, savingsPct);
+    }
+    catch (err) {
+        console.error("[vectormind] token savings record failed:", err);
+    }
+}
+function toolText(tool, rawValue, compactText, format = "compact") {
+    const rawText = toolJson(rawValue);
+    if (format === "json")
+        return rawText;
+    recordTokenSavings(tool, rawText, compactText);
+    return compactText;
+}
+function toolCompactOrJson(tool, rawValue, compactText, format) {
+    return toolText(tool, rawValue, compactText, format);
+}
+function oneLine(input, max = 120) {
+    const text = (input ?? "").replace(/\s+/g, " ").trim();
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+function compactMemoryLabel(item, max = 120) {
+    const title = item.title ? ` ${oneLine(item.title, 48)}` : "";
+    const loc = item.file_path ? ` ${item.file_path}${item.start_line != null ? `:${item.start_line}` : ""}` : "";
+    const body = item.preview ? ` — ${oneLine(item.preview, max)}` : "";
+    return `#${item.id} ${item.kind}${title}${loc}${body}`;
+}
+function compactRequirementLabel(req) {
+    const ctx = req.context_preview ? ` — ${oneLine(req.context_preview, 100)}` : "";
+    const mem = req.memory_item_id ? ` mem#${req.memory_item_id}` : "";
+    return `req#${req.id}${mem} [${req.status}] ${oneLine(req.title, 80)}${ctx}`;
+}
+function compactChangeLabel(change) {
+    return `change#${change.id} ${change.file_path}: ${oneLine(change.intent_preview, 120)}`;
+}
+function compactPendingLabel(p) {
+    const source = "source" in p && p.source === "git" ? " git" : "";
+    const status = "git_status" in p && p.git_status ? ` ${p.git_status}` : "";
+    return `${p.last_event}${source}${status} ${p.file_path}`;
+}
+function compactSemanticSearchText(data) {
+    const lines = [
+        `semantic ${data.mode} ${data.matches.length}/${data.top_k} q="${oneLine(data.query, 100)}"`,
+    ];
+    for (const m of data.matches.slice(0, data.top_k)) {
+        lines.push(`- score=${m.score.toFixed(3)} ${compactMemoryLabel(m.item, 160)}`);
+    }
+    if (!data.matches.length)
+        lines.push("- no matches");
+    lines.push("hint: use format=json for full metadata; read_memory_item(id) for full content");
+    return lines.join("\n");
+}
+function compactGrepText(data) {
+    const total = data.total_matches ?? data.matches.length;
+    const fallback = data.fallback_reason ? ` fallback=${data.fallback_reason}` : "";
+    const candidateText = data.candidates ? ` candidates=${data.candidates.scanned}/${data.candidates.total}` : "";
+    const lines = [
+        `grep ${data.backend}${fallback} mode=${data.mode} matches=${data.matches.length}/${total} truncated=${data.truncated}${candidateText} q="${oneLine(data.query, 100)}"`,
+    ];
+    if (data.ripgrep_error)
+        lines.push(`ripgrep_error ${oneLine(data.ripgrep_error, 180)}`);
+    for (const m of data.matches.slice(0, 80)) {
+        lines.push(`${m.file_path}:${m.line}:${m.col}: ${oneLine(m.preview, 220)}`);
+    }
+    if (!data.matches.length)
+        lines.push("- no matches");
+    if (data.truncated)
+        lines.push("hint: refine query/include_paths or raise max_results; use format=json for full match objects");
+    return lines.join("\n");
+}
+function compactListProjectFilesText(data) {
+    const lines = [
+        `files path=${data.path} kind=${data.path_kind} returned=${data.returned} scanned=${data.scanned} recursive=${data.recursive} depth=${data.max_depth} truncated=${data.truncated}`,
+    ];
+    for (const e of data.entries.slice(0, 200)) {
+        const stat = e.size != null ? ` ${e.size}B` : "";
+        lines.push(`${e.kind === "dir" ? "d" : "f"} ${e.path}${stat}`);
+    }
+    if (!data.entries.length)
+        lines.push("- empty");
+    if (data.truncated)
+        lines.push("hint: narrow path/filters or raise max_results; use format=json for full entry metadata");
+    return lines.join("\n");
+}
+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}`;
+}
+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}`;
+}
+function compactQueryCodebaseText(data) {
+    const lines = [`query_codebase matches=${data.matches.length} q="${oneLine(data.query, 100)}"`];
+    for (const m of data.matches.slice(0, 50)) {
+        lines.push(`${m.file_path}: ${m.type} ${m.name}${m.signature ? ` — ${oneLine(m.signature, 160)}` : ""}`);
+    }
+    if (!data.matches.length)
+        lines.push("- no matches");
+    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}`);
+    if (data.project_summary)
+        lines.push(`summary ${compactMemoryLabel(data.project_summary, 140)}`);
+    if (data.decisions.length) {
+        lines.push("current decisions:");
+        for (const d of data.decisions.slice(0, 5))
+            lines.push(`- ${compactMemoryLabel(d, 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)
+            .map(compactPendingLabel)
+            .join("; ")}`);
+    }
+    else {
+        lines.push("pending 0");
+    }
+    if (data.items.length) {
+        lines.push("requirements:");
+        for (const item of data.items) {
+            lines.push(`- ${compactRequirementLabel(item.requirement)}`);
+            for (const c of item.recent_changes.slice(0, 3))
+                lines.push(`  - ${compactChangeLabel(c)}`);
+        }
+    }
+    else {
+        lines.push("requirements: none");
+    }
+    if (data.recent_notes.length) {
+        lines.push("notes:");
+        for (const n of data.recent_notes.slice(0, 3))
+            lines.push(`- ${compactMemoryLabel(n, 120)}`);
+    }
+    if (data.conventions.length) {
+        lines.push(`conventions ${data.conventions.length}: ${data.conventions
+            .slice(0, 5)
+            .map((c) => c.title ?? `#${c.id}`)
+            .join(", ")}`);
+    }
+    if (data.semantic) {
+        lines.push(`semantic ${data.semantic.mode} ${data.semantic.matches.length}/${data.semantic.top_k} for "${oneLine(data.semantic.query, 80)}":`);
+        for (const m of data.semantic.matches.slice(0, 5)) {
+            lines.push(`- score=${m.score.toFixed(3)} ${compactMemoryLabel(m.item, 120)}`);
+        }
+    }
+    lines.push("hint: use format=json for full structured output; read_memory_item(id) for full content");
+    return lines.join("\n");
+}
+function compactBrainDumpText(data) {
+    return compactBootstrapText(data);
+}
+function shellQuoteArg(arg) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg))
+        return arg;
+    if (process.platform === "win32")
+        return `"${arg.replace(/"/g, '\\"')}"`;
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+}
+function getPackageRtkShimPath() {
+    try {
+        const currentDir = path.dirname(fileURLToPath(import.meta.url));
+        const candidate = path.join(currentDir, "rtk-shim.js");
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    catch {
+        // import.meta.url may be unavailable only in unexpected runtimes.
+    }
+    return null;
+}
+function runRtkProbe(spec) {
+    const argsPrefix = spec.execArgsPrefix ?? [];
+    const result = spawnSync(spec.execCommand, [...argsPrefix, "--version"], {
+        encoding: "utf8",
+        timeout: 120_000,
+        windowsHide: true,
+        shell: spec.execShell ?? false,
+    });
+    if (result.status === 0) {
+        const gain = spawnSync(spec.execCommand, [...argsPrefix, "gain"], {
+            encoding: "utf8",
+            timeout: 120_000,
+            windowsHide: true,
+            shell: spec.execShell ?? false,
+        });
+        let resolvedPath = spec.path;
+        if (spec.source === "path") {
+            const whereCommand = process.platform === "win32" ? "where.exe" : "which";
+            const whereResult = spawnSync(whereCommand, ["rtk"], {
+                encoding: "utf8",
+                timeout: 2000,
+                windowsHide: true,
+            });
+            resolvedPath = whereResult.status === 0 ? oneLine(whereResult.stdout, 240) : resolvedPath;
+        }
+        const gainText = `${gain.stdout}${gain.stderr}`.trim();
+        return {
+            available: gain.status === 0,
+            command: spec.displayCommand,
+            version: `${result.stdout}${result.stderr}`.trim(),
+            gain_ok: gain.status === 0,
+            gain_preview: oneLine(gainText, 240),
+            path: resolvedPath,
+            source: spec.source,
+            exec_command: spec.execCommand,
+            exec_args_prefix: argsPrefix,
+            exec_shell: spec.execShell ?? false,
+            note: gain.status === 0
+                ? spec.source === "package_shim"
+                    ? `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.",
+        };
+    }
+    return null;
+}
+function detectRtk() {
+    const pathProbe = runRtkProbe({
+        source: "path",
+        displayCommand: "rtk",
+        execCommand: "rtk",
+        execShell: process.platform === "win32",
+    });
+    if (pathProbe?.available)
+        return pathProbe;
+    const shimPath = getPackageRtkShimPath();
+    if (shimPath) {
+        const displayCommand = `node ${shellQuoteArg(shimPath)}`;
+        const shimProbe = runRtkProbe({
+            source: "package_shim",
+            displayCommand,
+            execCommand: process.execPath,
+            execArgsPrefix: [shimPath],
+            path: shimPath,
+        });
+        if (shimProbe)
+            return shimProbe;
+    }
+    if (pathProbe)
+        return pathProbe;
+    return {
+        available: false,
+        command: shimPath ? `node ${shellQuoteArg(shimPath)}` : "rtk",
+        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 the package RTK shim is unavailable. VectorMind compact MCP output still works; install rtk to compact shell command output too.",
+    };
+}
+function commandExists(command) {
+    const probe = process.platform === "win32" ? "where.exe" : "which";
+    const result = spawnSync(probe, [command], { encoding: "utf8", timeout: 2000, windowsHide: true });
+    return result.status === 0;
+}
+function runInstallStep(command, args, timeoutMs) {
+    const result = spawnSync(command, args, {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        windowsHide: true,
+        shell: false,
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    return {
+        command: [command, ...args].join(" "),
+        status: result.status,
+        ok: result.status === 0,
+        output: oneLine(output, 1200),
+    };
+}
+function runDetectedRtkStep(detected, args, timeoutMs) {
+    const execCommand = detected.exec_command ?? "rtk";
+    const argsPrefix = detected.exec_args_prefix ?? [];
+    const result = spawnSync(execCommand, [...argsPrefix, ...args], {
+        encoding: "utf8",
+        timeout: timeoutMs,
+        windowsHide: true,
+        shell: detected.exec_shell ?? (execCommand === "rtk" && process.platform === "win32"),
+    });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
+    return {
+        command: [detected.command, ...args].join(" "),
+        status: result.status,
+        ok: result.status === 0,
+        output: oneLine(output, 1200),
+    };
+}
+function appendRtkInitStep(steps, detected, init, timeoutMs) {
+    if (init === "none")
+        return;
+    if (init === "global_no_patch")
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--no-patch"], timeoutMs));
+    if (init === "global_auto_patch")
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--auto-patch"], timeoutMs));
+    if (init === "global_hook_only") {
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--hook-only", "--no-patch"], timeoutMs));
+    }
+    if (init === "local")
+        steps.push(runDetectedRtkStep(detected, ["init"], timeoutMs));
+    if (init === "codex_global")
+        steps.push(runDetectedRtkStep(detected, ["init", "-g", "--codex"], timeoutMs));
+    if (init === "codex_local")
+        steps.push(runDetectedRtkStep(detected, ["init", "--codex"], timeoutMs));
+}
+function chooseRtkInstallMethod(method) {
+    if (method !== "auto")
+        return method;
+    if (process.platform === "darwin" && commandExists("brew"))
+        return "brew";
+    if (commandExists("cargo"))
+        return "cargo";
+    return "shell_script";
+}
+function buildRtkInstallPlan(args) {
+    const method = chooseRtkInstallMethod(args.method);
+    const commands = [];
+    const notes = [];
+    if (args.uninstall_wrong_cargo_rtk) {
+        commands.push("cargo uninstall rtk");
+        notes.push("Only use uninstall_wrong_cargo_rtk after verifying the existing rtk is the wrong Cargo package.");
+    }
+    if (method === "brew") {
+        commands.push("brew install rtk");
+    }
+    else if (method === "cargo") {
+        commands.push("cargo install --git https://github.com/rtk-ai/rtk");
+    }
+    else {
+        if (process.platform === "win32") {
+            notes.push("shell_script install is Linux/macOS-oriented; on Windows prefer method=cargo after installing Rust/Cargo.");
+            commands.push("cargo install --git https://github.com/rtk-ai/rtk");
+        }
+        else {
+            commands.push("curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh");
+        }
+    }
+    commands.push("rtk --version");
+    commands.push("rtk gain");
+    if (args.init === "global_no_patch")
+        commands.push("rtk init -g --no-patch");
+    if (args.init === "global_auto_patch")
+        commands.push("rtk init -g --auto-patch");
+    if (args.init === "global_hook_only")
+        commands.push("rtk init -g --hook-only --no-patch");
+    if (args.init === "local")
+        commands.push("rtk init");
+    if (args.init === "codex_global")
+        commands.push("rtk init -g --codex");
+    if (args.init === "codex_local")
+        commands.push("rtk init --codex");
+    if (args.init !== "none") {
+        notes.push("rtk init may modify Claude/RTK configuration. Use init=none for binary-only installation.");
+    }
+    return { method, commands, notes };
+}
+function installRtk(args) {
+    const detectedBefore = detectRtk();
+    const plan = buildRtkInstallPlan(args);
+    const steps = [];
+    const notes = [...plan.notes];
+    if (detectedBefore.available) {
+        notes.push("rtk is already installed and verified with `rtk gain`; installation skipped.");
+        if (!args.dry_run && args.init !== "none") {
+            appendRtkInitStep(steps, detectedBefore, args.init, args.timeout_ms);
+        }
+        return {
+            ok: true,
+            dry_run: args.dry_run,
+            already_available: true,
+            method: plan.method,
+            commands: plan.commands,
+            notes,
+            steps,
+            detected_before: detectedBefore,
+            detected_after: detectedBefore,
+        };
+    }
+    if (args.dry_run) {
+        notes.push("dry_run=true: no command was executed. Call install_rtk with dry_run=false to install.");
+        return {
+            ok: true,
+            dry_run: true,
+            already_available: false,
+            method: plan.method,
+            commands: plan.commands,
+            notes,
+            steps,
+            detected_before: detectedBefore,
+        };
+    }
+    if (plan.method === "brew") {
+        steps.push(runInstallStep("brew", ["install", "rtk"], args.timeout_ms));
+    }
+    else if (plan.method === "cargo") {
+        if (args.uninstall_wrong_cargo_rtk) {
+            steps.push(runInstallStep("cargo", ["uninstall", "rtk"], args.timeout_ms));
+        }
+        steps.push(runInstallStep("cargo", ["install", "--git", "https://github.com/rtk-ai/rtk"], args.timeout_ms));
+    }
+    else if (process.platform === "win32") {
+        notes.push("Windows fallback uses Cargo because the upstream shell installer targets POSIX shells.");
+        if (args.uninstall_wrong_cargo_rtk) {
+            steps.push(runInstallStep("cargo", ["uninstall", "rtk"], args.timeout_ms));
+        }
+        steps.push(runInstallStep("cargo", ["install", "--git", "https://github.com/rtk-ai/rtk"], args.timeout_ms));
+    }
+    else {
+        const script = "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh";
+        steps.push(runInstallStep("sh", ["-c", script], args.timeout_ms));
+    }
+    const detectedAfterInstall = detectRtk();
+    if (detectedAfterInstall.available && args.init !== "none") {
+        appendRtkInitStep(steps, detectedAfterInstall, args.init, args.timeout_ms);
+    }
+    const detectedAfter = detectRtk();
+    return {
+        ok: detectedAfter.available,
+        dry_run: false,
+        already_available: false,
+        method: plan.method,
+        commands: plan.commands,
+        notes,
+        steps,
+        detected_before: detectedBefore,
+        detected_after: detectedAfter,
+    };
+}
+function compactInstallRtkText(data) {
+    const lines = [];
+    lines.push(`install_rtk ok=${data.ok} dry_run=${data.dry_run} already_available=${data.already_available} method=${data.method}`);
+    lines.push(`before available=${data.detected_before.available} version=${data.detected_before.version ?? "none"} gain_ok=${data.detected_before.gain_ok ?? false}`);
+    if (data.detected_after) {
+        lines.push(`after available=${data.detected_after.available} version=${data.detected_after.version ?? "none"} gain_ok=${data.detected_after.gain_ok ?? false}`);
+    }
+    if (data.commands.length) {
+        lines.push("commands:");
+        for (const command of data.commands)
+            lines.push(`- ${command}`);
+    }
+    if (data.steps.length) {
+        lines.push("steps:");
+        for (const step of data.steps) {
+            lines.push(`- ${step.ok ? "ok" : "fail"} [${step.status ?? "null"}] ${step.command}: ${oneLine(step.output, 240)}`);
+        }
+    }
+    if (data.notes.length) {
+        lines.push("notes:");
+        for (const note of data.notes)
+            lines.push(`- ${note}`);
+    }
+    return lines.join("\n");
+}
+function tokenSavingsSummary(limit) {
+    const summary = summarizeTokenSavingsStmt.get();
+    const by_tool = summarizeTokenSavingsByToolStmt.all(limit);
+    const recent = listRecentTokenSavingsStmt.all(limit);
+    return {
+        ok: true,
+        summary: summary ?? { calls: 0, raw_tokens: 0, output_tokens: 0, saved_tokens: 0, avg_savings_pct: 0 },
+        by_tool,
+        recent,
+    };
+}
+function compactTokenSavingsText(data) {
+    const s = data.summary;
+    const pct = Number(s.raw_tokens) > 0 ? (Number(s.saved_tokens) / Number(s.raw_tokens)) * 100 : 0;
+    const lines = [
+        `token_savings calls=${s.calls} raw=${s.raw_tokens} out=${s.output_tokens} saved=${s.saved_tokens} (${pct.toFixed(1)}%)`,
+    ];
+    if (data.by_tool.length) {
+        lines.push("by_tool:");
+        for (const t of data.by_tool.slice(0, 10)) {
+            lines.push(`- ${t.tool}: calls=${t.calls} saved=${t.saved_tokens} raw=${t.raw_tokens} out=${t.output_tokens} avg=${Number(t.avg_savings_pct).toFixed(1)}%`);
+        }
+    }
+    if (data.recent.length) {
+        lines.push("recent:");
+        for (const r of data.recent.slice(0, 10)) {
+            lines.push(`- #${r.id} ${r.tool}: ${r.raw_tokens}->${r.output_tokens} saved=${r.saved_tokens}`);
+        }
+    }
+    return lines.join("\n");
+}
 function sliceTextForOutput(input, maxChars) {
     const total = input.length;
     if (maxChars <= 0)
@@ -1472,6 +2129,88 @@ function dotProduct(a, b) {
         s += a[i] * b[i];
     return s;
 }
+function parseMetadataJson(metadata) {
+    if (!metadata)
+        return {};
+    try {
+        const parsed = JSON.parse(metadata);
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+function metadataStatus(row) {
+    const meta = parseMetadataJson(row.metadata_json);
+    return typeof meta.status === "string" ? meta.status : "";
+}
+function isSupersededMemory(row) {
+    const meta = parseMetadataJson(row.metadata_json);
+    return meta.superseded === true || meta.status === "superseded";
+}
+function semanticRecencyWeight(updatedAt) {
+    if (!updatedAt)
+        return 0;
+    const t = Date.parse(updatedAt.endsWith("Z") ? updatedAt : `${updatedAt}Z`);
+    if (!Number.isFinite(t))
+        return 0;
+    const ageDays = Math.max(0, (Date.now() - t) / 86_400_000);
+    if (ageDays <= 1)
+        return 0.8;
+    if (ageDays <= 7)
+        return 0.45;
+    if (ageDays <= 30)
+        return 0.2;
+    return 0;
+}
+function semanticKindWeight(kind) {
+    switch (kind) {
+        case "decision":
+            return 3.5;
+        case "convention":
+            return 2.6;
+        case "project_summary":
+            return 2.2;
+        case "note":
+            return 1.1;
+        case "requirement":
+            return 0.4;
+        case "change_intent":
+            return 0.2;
+        default:
+            return 0;
+    }
+}
+function adjustSemanticScore(row, rawScore) {
+    if (isSupersededMemory(row))
+        return rawScore - 1000;
+    let score = rawScore + semanticKindWeight(row.kind) + semanticRecencyWeight(row.updated_at);
+    const status = metadataStatus(row);
+    if (status === "active" || status === "current")
+        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
+        // "why" for that change. Do not let built-in path ignores hide the decision trail.
+        score += 0.4;
+    }
+    return score;
+}
+function filterAndRankSemanticRows(rows, scoreOf, opts) {
+    return rows
+        .map((r) => ({ row: r, score: adjustSemanticScore(r, scoreOf(r)) }))
+        .filter(({ row }) => {
+        if (isSupersededMemory(row))
+            return false;
+        if (shouldIgnoreDbFilePath(row.file_path) && row.kind !== "change_intent")
+            return false;
+        return true;
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, opts.topK)
+        .map(({ row, score }) => toSemanticMatch(row, score, opts.includeContent, opts.previewChars, opts.contentMaxChars));
+}
 function makePreviewText(content, max) {
     if (max <= 0)
         return "";
@@ -1546,6 +2285,15 @@ function getConventionPreviews(conventionsLimit, previewChars, contentMaxChars)
     const stored = listConventionsStmt.all(remaining).map((c) => toMemoryItemPreview(c, false, previewChars, contentMaxChars));
     return [...builtin, ...stored];
 }
+function getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars) {
+    if (decisionsLimit <= 0)
+        return [];
+    const rows = listCurrentDecisionsStmt.all(Math.min(MAX_DECISIONS_LIMIT * 4, Math.max(decisionsLimit, decisionsLimit * 4)));
+    return rows
+        .filter((d) => !isSupersededMemory(d))
+        .slice(0, decisionsLimit)
+        .map((d) => toMemoryItemPreview(d, false, previewChars, contentMaxChars));
+}
 function toRequirementPreview(req, includeContent, previewChars, contentMaxChars) {
     const context = req.context_data ?? null;
     const contextPreview = context ? makePreviewText(context, previewChars) : null;
@@ -1590,6 +2338,46 @@ function completeAllActiveRequirementMemoryItems() {
         console.error("[vectormind] failed to complete all active requirement memory items:", err);
     }
 }
+function patchMemoryItemMetadata(id, patch) {
+    const row = getMemoryItemByIdStmt.get(id);
+    if (!row)
+        return;
+    const meta = { ...parseMetadataJson(row.metadata_json), ...patch };
+    db.prepare(`UPDATE memory_items SET metadata_json = ?, updated_at = CURRENT_TIMESTAMP WHERE id = ?`).run(safeJson(meta), id);
+}
+function supersedeMemoryItemIds(ids, replacement) {
+    const updated = [];
+    for (const id of Array.from(new Set(ids)).filter((n) => Number.isFinite(n) && n > 0)) {
+        const row = getMemoryItemByIdStmt.get(id);
+        if (!row)
+            continue;
+        patchMemoryItemMetadata(id, {
+            ...parseMetadataJson(row.metadata_json),
+            status: "superseded",
+            superseded: true,
+            superseded_at: new Date().toISOString(),
+            superseded_reason: replacement.reason,
+            superseded_by_req_id: replacement.req_id ?? null,
+            superseded_by_memory_id: replacement.memory_id ?? null,
+            superseded_by_decision_id: replacement.decision_id ?? null,
+        });
+        updated.push(id);
+    }
+    return updated;
+}
+function supersedeRequirementIds(reqIds, replacement) {
+    const updatedReqs = [];
+    for (const reqId of Array.from(new Set(reqIds)).filter((n) => Number.isFinite(n) && n > 0)) {
+        const info = db.prepare(`UPDATE requirements SET status = 'superseded' WHERE id = ?`).run(reqId);
+        if (info.changes > 0)
+            updatedReqs.push(reqId);
+        const rows = db
+            .prepare(`SELECT id FROM memory_items WHERE req_id = ? OR (kind = 'requirement' AND req_id = ?)`)
+            .all(reqId, reqId);
+        supersedeMemoryItemIds(rows.map((r) => r.id), replacement);
+    }
+    return updatedReqs;
+}
 async function semanticSearchInternal(opts) {
     if (!embeddingsEnabled) {
         throw new Error("Embeddings are disabled");
@@ -1641,7 +2429,31 @@ async function semanticSearchInternal(opts) {
         return toSemanticMatch(item, t.score, opts.includeContent, opts.previewChars, opts.contentMaxChars);
     })
         .filter(Boolean);
-    const filtered = matches.filter((m) => !shouldIgnoreDbFilePath(m.item.file_path)).slice(0, opts.topK);
+    const filtered = matches
+        .filter((m) => {
+        if (isSupersededMemory({ metadata_json: m.item.metadata_json }))
+            return false;
+        if (shouldIgnoreDbFilePath(m.item.file_path) && m.item.kind !== "change_intent")
+            return false;
+        return true;
+    })
+        .map((m) => ({
+        ...m,
+        score: adjustSemanticScore({
+            id: m.item.id,
+            kind: m.item.kind,
+            title: m.item.title,
+            content: m.item.content ?? m.item.preview,
+            file_path: m.item.file_path,
+            start_line: m.item.start_line,
+            end_line: m.item.end_line,
+            req_id: m.item.req_id,
+            metadata_json: m.item.metadata_json,
+            updated_at: m.item.updated_at,
+        }, m.score),
+    }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, opts.topK);
     return { query: q, top_k: opts.topK, mode: "embeddings", matches: filtered };
 }
 function buildFtsMatchQuery(raw) {
@@ -1710,10 +2522,7 @@ function ftsSearchInternal(opts) {
     `);
         return stmt.all(matchQuery, rawLimit);
     })();
-    const matches = rows
-        .map((r) => toSemanticMatch(r, -Number(r.rank), opts.includeContent, opts.previewChars, opts.contentMaxChars))
-        .filter((m) => !shouldIgnoreDbFilePath(m.item.file_path))
-        .slice(0, opts.topK);
+    const matches = filterAndRankSemanticRows(rows, (r) => -Number(r.rank), opts);
     return { query: q, top_k: opts.topK, mode: "fts", matches };
 }
 function likeSearchInternal(opts) {
@@ -1779,10 +2588,7 @@ function likeSearchInternal(opts) {
     `);
         return stmt.all(like, like, like, like, like, rawLimit);
     })();
-    const matches = rows
-        .map((r) => toSemanticMatch(r, Number(r.score), opts.includeContent, opts.previewChars, opts.contentMaxChars))
-        .filter((m) => !shouldIgnoreDbFilePath(m.item.file_path))
-        .slice(0, opts.topK);
+    const matches = filterAndRankSemanticRows(rows, (r) => Number(r.score), opts);
     return { query: q, top_k: opts.topK, mode: "like", matches };
 }
 async function semanticSearchHybridInternal(opts) {
@@ -2527,6 +3333,9 @@ function buildServerInstructions() {
         "Built-in frontend output-purity policy:",
         BUILTIN_FRONTEND_OUTPUT_PURITY_INSTRUCTIONS,
         "",
+        "Built-in git commit summary policy:",
+        BUILTIN_GIT_COMMIT_SUMMARY_INSTRUCTIONS,
+        "",
         "Built-in low-overhead execution and heavy-thread policy:",
         BUILTIN_LOW_OVERHEAD_WORKFLOW_INSTRUCTIONS,
         "",
@@ -2537,11 +3346,14 @@ function buildServerInstructions() {
         BUILTIN_THREAD_HANDOFF_SWITCH_INSTRUCTIONS,
         "",
         "Required workflow:",
-        "- On every new conversation/session for analysis/design/development work: call bootstrap_context({ query: <current goal> }) first (or at least get_brain_dump()) to restore context and retrieve relevant matches from the local memory store (vector if enabled; otherwise FTS/LIKE).",
+        "- 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, preview_chars, pending_limit/pending_offset.",
+        "  - Tune output size with: requirements_limit/changes_limit/notes_limit/decisions_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.",
         "- 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.",
@@ -2555,11 +3367,13 @@ function buildServerInstructions() {
         "- BEFORE editing code: call start_requirement(title, background) to set the active requirement.",
         "- AFTER editing + saving: call get_pending_changes() to see unsynced files, then call sync_change_intent(intent, files). (You can omit files to auto-link all pending changes.)",
         "- After major milestones/decisions: call upsert_project_summary(summary) and/or add_note(...) to persist durable context locally.",
+        "- 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.",
         "- If the current thread is already heavy or the user reports it has become slow, switch to a lighter workflow: avoid redundant retrieval, keep outputs compact, and if the user refuses thread switching, continue in light mode without repeating the switch reminder in that same session.",
+        "- 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.",
     ].join("\n");
@@ -2778,6 +3592,9 @@ function initDatabase() {
     CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_items_convention_key
       ON memory_items(kind, title) WHERE kind = 'convention';
 
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_items_decision_key
+      ON memory_items(kind, title) WHERE kind = 'decision';
+
     CREATE INDEX IF NOT EXISTS idx_memory_items_kind_updated_at
       ON memory_items(kind, updated_at DESC);
 
@@ -2808,6 +3625,22 @@ function initDatabase() {
 
     CREATE INDEX IF NOT EXISTS idx_pending_changes_updated_at
       ON pending_changes(updated_at DESC);
+
+    CREATE TABLE IF NOT EXISTS token_savings (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      tool TEXT NOT NULL,
+      raw_tokens INTEGER NOT NULL,
+      output_tokens INTEGER NOT NULL,
+      saved_tokens INTEGER NOT NULL,
+      savings_pct REAL NOT NULL,
+      created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_token_savings_created_at
+      ON token_savings(created_at DESC);
+
+    CREATE INDEX IF NOT EXISTS idx_token_savings_tool
+      ON token_savings(tool);
   `);
     initMemoryItemsFts();
     insertRequirementStmt = db.prepare(`INSERT INTO requirements (title, context_data, status) VALUES (?, ?, 'active')`);
@@ -2858,6 +3691,23 @@ function initDatabase() {
      WHERE kind = 'convention'
      ORDER BY updated_at DESC, id DESC
      LIMIT ?`);
+    upsertDecisionStmt = db.prepare(`INSERT INTO memory_items (kind, title, content, metadata_json, content_hash)
+     VALUES ('decision', ?, ?, ?, ?)
+     ON CONFLICT DO UPDATE SET
+       content = excluded.content,
+       metadata_json = excluded.metadata_json,
+       content_hash = excluded.content_hash,
+       updated_at = CURRENT_TIMESTAMP`);
+    getDecisionByKeyStmt = 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 = 'decision' AND title = ?
+     ORDER BY updated_at DESC, id DESC
+     LIMIT 1`);
+    listCurrentDecisionsStmt = 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 = 'decision'
+     ORDER BY updated_at DESC, id DESC
+     LIMIT ?`);
     getRequirementMemoryItemIdStmt = db.prepare(`SELECT id
      FROM memory_items
      WHERE kind = 'requirement' AND req_id = ?
@@ -2880,6 +3730,11 @@ function initDatabase() {
      WHERE kind = 'note'
      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 = ?
+     ORDER BY updated_at DESC, id DESC
+     LIMIT 1`);
     deleteFileChunkItemsStmt = db.prepare(`DELETE FROM memory_items
      WHERE file_path = ?
        AND (kind = 'code_chunk' OR kind = 'doc_chunk')`);
@@ -2929,6 +3784,30 @@ function initDatabase() {
        END,
        name
      LIMIT ?`);
+    insertTokenSavingsStmt = db.prepare(`INSERT INTO token_savings (tool, raw_tokens, output_tokens, saved_tokens, savings_pct)
+     VALUES (?, ?, ?, ?, ?)`);
+    summarizeTokenSavingsStmt = db.prepare(`SELECT
+       COUNT(*) as calls,
+       COALESCE(SUM(raw_tokens), 0) as raw_tokens,
+       COALESCE(SUM(output_tokens), 0) as output_tokens,
+       COALESCE(SUM(saved_tokens), 0) as saved_tokens,
+       COALESCE(AVG(savings_pct), 0) as avg_savings_pct
+     FROM token_savings`);
+    summarizeTokenSavingsByToolStmt = db.prepare(`SELECT
+       tool,
+       COUNT(*) as calls,
+       COALESCE(SUM(raw_tokens), 0) as raw_tokens,
+       COALESCE(SUM(output_tokens), 0) as output_tokens,
+       COALESCE(SUM(saved_tokens), 0) as saved_tokens,
+       COALESCE(AVG(savings_pct), 0) as avg_savings_pct
+     FROM token_savings
+     GROUP BY tool
+     ORDER BY saved_tokens DESC, calls DESC
+     LIMIT ?`);
+    listRecentTokenSavingsStmt = db.prepare(`SELECT id, tool, raw_tokens, output_tokens, saved_tokens, savings_pct, created_at
+     FROM token_savings
+     ORDER BY created_at DESC, id DESC
+     LIMIT ?`);
     indexFileSymbolsTx = db.transaction((filePath, symbols) => {
         deleteSymbolsForFileStmt.run(filePath);
         for (const s of symbols) {
@@ -3123,6 +4002,21 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Clear the in-memory debug activity log. Enable logging with VECTORMIND_DEBUG_LOG=1.",
                 inputSchema: toJsonSchemaCompat(ClearActivityLogArgsSchema),
             },
+            {
+                name: "detect_rtk",
+                description: "Detect whether rtk is available on PATH or via VectorMind's bundled RTK shim. When available, prefer the returned command as a shell prefix to reduce command-output tokens.",
+                inputSchema: toJsonSchemaCompat(DetectRtkArgsSchema),
+            },
+            {
+                name: "install_rtk",
+                description: "Install the rtk-ai/rtk Rust Token Killer binary when it is missing. Defaults to dry_run=true and never patches hooks unless init is explicitly requested.",
+                inputSchema: toJsonSchemaCompat(InstallRtkArgsSchema),
+            },
+            {
+                name: "get_token_savings",
+                description: "Show VectorMind compact-output token savings recorded by MCP tools. Use this to verify raw-vs-compact output reduction.",
+                inputSchema: toJsonSchemaCompat(GetTokenSavingsArgsSchema),
+            },
             {
                 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.",
@@ -3163,6 +4057,16 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
                 description: "Save a durable project note (decision, constraint, TODO, architecture detail). Use this to persist important context locally instead of relying on chat memory.",
                 inputSchema: toJsonSchemaCompat(AddNoteArgsSchema),
             },
+            {
+                name: "upsert_decision",
+                description: "Save/update the current authoritative project decision for a key. Use it when requirements change, reverse, or supersede older behavior so future sessions prefer the latest decision over old history.",
+                inputSchema: toJsonSchemaCompat(UpsertDecisionArgsSchema),
+            },
+            {
+                name: "supersede_memory",
+                description: "Mark old requirements or memory items as superseded by a newer requirement/decision. Superseded items are hidden from default semantic recall to avoid reverting to stale behavior.",
+                inputSchema: toJsonSchemaCompat(SupersedeMemoryArgsSchema),
+            },
             {
                 name: "upsert_convention",
                 description: "Save/update a project convention (framework choice, build command, naming rules, etc). Conventions are durable and should be applied automatically in future sessions.",
@@ -3394,24 +4298,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 }
                 else {
                     const pendingAll = listPendingChangesStmt.all();
-                    if (pendingAll.length) {
-                        const pending = pendingAll.filter((p) => !shouldIgnoreDbFilePath(p.file_path));
-                        if (pending.length) {
-                            for (const p of pending) {
-                                targets.push({
-                                    rawFile: p.file_path,
-                                    dbFilePath: p.file_path,
-                                    event: p.last_event,
-                                    source: "pending",
-                                });
-                            }
-                        }
-                        else {
+                    const merged = mergePendingWithGit(pendingAll, { offset: 0, limit: MAX_PENDING_LIMIT });
+                    if (merged.page.length) {
+                        for (const p of merged.page) {
                             targets.push({
-                                rawFile: "(unspecified)",
-                                dbFilePath: "(unspecified)",
-                                event: "manual",
-                                source: "unspecified",
+                                rawFile: p.file_path,
+                                dbFilePath: p.file_path,
+                                event: p.last_event,
+                                source: p.source === "git" ? "pending" : "pending",
                             });
                         }
                         deleteAllPendingChangesStmt.run();
@@ -3429,7 +4323,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     const isUnspecified = t.dbFilePath === "(unspecified)";
                     const changeInfo = insertChangeLogStmt.run(active.id, t.dbFilePath, args.intent);
                     const change_log_id = Number(changeInfo.lastInsertRowid);
-                    const memoryInfo = insertMemoryItemStmt.run("change_intent", active.title, args.intent, isUnspecified ? null : t.dbFilePath, null, null, active.id, safeJson({ change_log_id, event: t.event, source: t.source }), sha256Hex(args.intent));
+                    const memoryInfo = insertMemoryItemStmt.run("change_intent", active.title, args.intent, isUnspecified ? null : t.dbFilePath, null, null, active.id, safeJson({
+                        change_log_id,
+                        event: t.event,
+                        source: t.source,
+                        file_state_hash: isUnspecified ? null : getFileStateHash(t.rawFile),
+                    }), sha256Hex(args.intent));
                     const memory_item_id = Number(memoryInfo.lastInsertRowid);
                     enqueueEmbedding(memory_item_id);
                     synced_files.push({ file_path: t.dbFilePath, event: t.event, source: t.source });
@@ -3480,6 +4379,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const changesLimit = args.changes_limit;
             const notesLimit = args.notes_limit;
             const conventionsLimit = args.conventions_limit;
+            const decisionsLimit = args.decisions_limit;
             const recent = listRecentRequirementsStmt.all(requirementsLimit);
             const items = recent.map((req) => {
                 const changes = listChangeLogsForRequirementStmt.all(req.id, changesLimit);
@@ -3493,12 +4393,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
+            const decisions = getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars);
             const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
-            const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
-            const pending_truncated = pending_total > pending_offset + pending_limit;
-            const pending_changes = listPendingChangesPageStmt.all(pending_limit, pending_offset).filter((p) => !shouldIgnoreDbFilePath(p.file_path));
+            const pendingDbRows = listPendingChangesStmt.all();
+            const mergedPending = mergePendingWithGit(pendingDbRows, { offset: pending_offset, limit: pending_limit });
+            const pending_total = mergedPending.total;
+            const pending_truncated = mergedPending.truncated;
+            const pending_changes = mergedPending.page;
             const q = args.query?.trim() ?? "";
             const semantic = q
                 ? await Promise.race([
@@ -3521,47 +4424,52 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 pending_total,
                 pending_returned: pending_changes.length,
                 requirements_returned: items.length,
+                decisions_returned: decisions.length,
                 conventions_returned: conventions.length,
                 semantic_mode: semantic?.mode ?? null,
                 semantic_matches: semantic?.matches?.length ?? 0,
             });
+            const outputValue = {
+                ok: true,
+                generated_at: new Date().toISOString(),
+                project_root: projectRoot,
+                root_source: rootSource,
+                db_path: dbPath,
+                watcher_enabled: !!watcher,
+                watcher_ready: watcherReady,
+                embeddings: {
+                    enabled: embeddingsEnabled,
+                    model: embedModelName,
+                    embed_files: embedFilesMode,
+                },
+                output: {
+                    format: args.format,
+                    include_content: includeContent,
+                    preview_chars: previewChars,
+                    content_max_chars: contentMaxChars,
+                    requirements_limit: requirementsLimit,
+                    changes_limit: changesLimit,
+                    notes_limit: notesLimit,
+                    decisions_limit: decisionsLimit,
+                    conventions_limit: conventionsLimit,
+                },
+                project_summary,
+                decisions,
+                conventions,
+                recent_notes,
+                pending_total,
+                pending_offset,
+                pending_limit,
+                pending_truncated,
+                pending_changes,
+                items,
+                semantic,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            generated_at: new Date().toISOString(),
-                            project_root: projectRoot,
-                            root_source: rootSource,
-                            db_path: dbPath,
-                            watcher_enabled: !!watcher,
-                            watcher_ready: watcherReady,
-                            embeddings: {
-                                enabled: embeddingsEnabled,
-                                model: embedModelName,
-                                embed_files: embedFilesMode,
-                            },
-                            output: {
-                                include_content: includeContent,
-                                preview_chars: previewChars,
-                                content_max_chars: contentMaxChars,
-                                requirements_limit: requirementsLimit,
-                                changes_limit: changesLimit,
-                                notes_limit: notesLimit,
-                                conventions_limit: conventionsLimit,
-                            },
-                            project_summary,
-                            conventions,
-                            recent_notes,
-                            pending_total,
-                            pending_offset,
-                            pending_limit,
-                            pending_truncated,
-                            pending_changes,
-                            items,
-                            semantic,
-                        }),
+                        text: toolText("bootstrap_context", outputValue, compactBootstrapText(outputValue), args.format),
                     },
                 ],
             };
@@ -3576,6 +4484,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             const changesLimit = args.changes_limit;
             const notesLimit = args.notes_limit;
             const conventionsLimit = args.conventions_limit;
+            const decisionsLimit = args.decisions_limit;
             const recent = listRecentRequirementsStmt.all(requirementsLimit);
             const items = recent.map((req) => {
                 const changes = listChangeLogsForRequirementStmt.all(req.id, changesLimit);
@@ -3589,55 +4498,64 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ? toMemoryItemPreview(projectSummaryRow, includeContent, previewChars, contentMaxChars)
                 : null;
             const recent_notes = listRecentNotesStmt.all(notesLimit).map((n) => toMemoryItemPreview(n, includeContent, previewChars, contentMaxChars));
+            const decisions = getDecisionPreviews(decisionsLimit, previewChars, contentMaxChars);
             const conventions = getConventionPreviews(conventionsLimit, previewChars, contentMaxChars);
-            const pending_total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const pending_offset = args.pending_offset;
             const pending_limit = args.pending_limit;
-            const pending_truncated = pending_total > pending_offset + pending_limit;
-            const pending_changes = listPendingChangesPageStmt.all(pending_limit, pending_offset).filter((p) => !shouldIgnoreDbFilePath(p.file_path));
+            const pendingDbRows = listPendingChangesStmt.all();
+            const mergedPending = mergePendingWithGit(pendingDbRows, { offset: pending_offset, limit: pending_limit });
+            const pending_total = mergedPending.total;
+            const pending_truncated = mergedPending.truncated;
+            const pending_changes = mergedPending.page;
             logActivity("get_brain_dump", {
                 pending_total,
                 pending_returned: pending_changes.length,
                 requirements_returned: items.length,
                 notes_returned: recent_notes.length,
+                decisions_returned: decisions.length,
                 conventions_returned: conventions.length,
             });
+            const outputValue = {
+                ok: true,
+                generated_at: new Date().toISOString(),
+                project_root: projectRoot,
+                root_source: rootSource,
+                db_path: dbPath,
+                watcher_enabled: !!watcher,
+                watcher_ready: watcherReady,
+                embeddings: {
+                    enabled: embeddingsEnabled,
+                    model: embedModelName,
+                    embed_files: embedFilesMode,
+                },
+                output: {
+                    format: args.format,
+                    include_content: includeContent,
+                    preview_chars: previewChars,
+                    content_max_chars: contentMaxChars,
+                    requirements_limit: requirementsLimit,
+                    changes_limit: changesLimit,
+                    notes_limit: notesLimit,
+                    decisions_limit: decisionsLimit,
+                    conventions_limit: conventionsLimit,
+                },
+                project_summary,
+                decisions,
+                conventions,
+                recent_notes,
+                pending_total,
+                pending_offset,
+                pending_limit,
+                pending_truncated,
+                pending_changes,
+                items,
+                semantic: null,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            generated_at: new Date().toISOString(),
-                            project_root: projectRoot,
-                            root_source: rootSource,
-                            db_path: dbPath,
-                            watcher_enabled: !!watcher,
-                            watcher_ready: watcherReady,
-                            embeddings: {
-                                enabled: embeddingsEnabled,
-                                model: embedModelName,
-                                embed_files: embedFilesMode,
-                            },
-                            output: {
-                                include_content: includeContent,
-                                preview_chars: previewChars,
-                                content_max_chars: contentMaxChars,
-                                requirements_limit: requirementsLimit,
-                                changes_limit: changesLimit,
-                                notes_limit: notesLimit,
-                                conventions_limit: conventionsLimit,
-                            },
-                            project_summary,
-                            conventions,
-                            recent_notes,
-                            pending_total,
-                            pending_offset,
-                            pending_limit,
-                            pending_truncated,
-                            pending_changes,
-                            items,
-                        }),
+                        text: toolText("get_brain_dump", outputValue, compactBrainDumpText(outputValue), args.format),
                     },
                 ],
             };
@@ -3645,11 +4563,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         if (toolName === "get_pending_changes") {
             const args = GetPendingChangesArgsSchema.parse(rawArgs);
             flushPendingChangeBuffer();
-            const total = Number(countPendingChangesStmt.get()?.total ?? 0);
             const offset = args.offset;
             const limit = args.limit;
-            const truncated = total > offset + limit;
-            const pending = listPendingChangesPageStmt.all(limit, offset).filter((p) => !shouldIgnoreDbFilePath(p.file_path));
+            const pendingDbRows = listPendingChangesStmt.all();
+            const mergedPending = mergePendingWithGit(pendingDbRows, { offset, limit });
+            const total = mergedPending.total;
+            const truncated = mergedPending.truncated;
+            const pending = mergedPending.page;
             logActivity("get_pending_changes", {
                 total,
                 offset,
@@ -3818,6 +4738,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             clearActivityLog();
             return { content: [{ type: "text", text: toolJson({ ok: true }) }] };
         }
+        if (toolName === "detect_rtk") {
+            DetectRtkArgsSchema.parse(rawArgs);
+            const result = detectRtk();
+            const text = result.available
+                ? `rtk available: ${result.version ?? result.command}\ncommand=${result.command} source=${result.source ?? "unknown"} gain_ok=${result.gain_ok ?? false}${result.path ? ` path=${result.path}` : ""}\n${result.note}`
+                : `rtk unavailable: ${result.command}\nsource=${result.source ?? "none"} gain_ok=${result.gain_ok ?? false}${result.version ? ` version=${result.version}` : ""}${result.path ? ` path=${result.path}` : ""}\n${result.note}`;
+            return { content: [{ type: "text", text }] };
+        }
+        if (toolName === "install_rtk") {
+            const args = InstallRtkArgsSchema.parse(rawArgs);
+            const result = installRtk(args);
+            return { content: [{ type: "text", text: compactInstallRtkText(result) }] };
+        }
+        if (toolName === "get_token_savings") {
+            const args = GetTokenSavingsArgsSchema.parse(rawArgs);
+            const result = tokenSavingsSummary(args.limit);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: args.format === "json" ? toolJson(result) : compactTokenSavingsText(result),
+                    },
+                ],
+            };
+        }
         if (toolName === "grep") {
             const args = GrepArgsSchema.parse(rawArgs);
             const q = args.query;
@@ -3851,24 +4796,25 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     total_matches: ripgrepResult.total_matches,
                     truncated: ripgrepResult.truncated,
                 });
+                const outputValue = {
+                    ok: true,
+                    backend: ripgrepResult.backend,
+                    rg_command: ripgrepResult.rg_command,
+                    query: q,
+                    mode,
+                    case_sensitive: caseSensitive,
+                    smart_case: smartCase,
+                    include_paths: includePaths ?? [],
+                    exclude_paths: excludePaths ?? [],
+                    matches: ripgrepResult.matches,
+                    total_matches: ripgrepResult.total_matches,
+                    truncated: ripgrepResult.truncated,
+                };
                 return {
                     content: [
                         {
                             type: "text",
-                            text: toolJson({
-                                ok: true,
-                                backend: ripgrepResult.backend,
-                                rg_command: ripgrepResult.rg_command,
-                                query: q,
-                                mode,
-                                case_sensitive: caseSensitive,
-                                smart_case: smartCase,
-                                include_paths: includePaths ?? [],
-                                exclude_paths: excludePaths ?? [],
-                                matches: ripgrepResult.matches,
-                                total_matches: ripgrepResult.total_matches,
-                                truncated: ripgrepResult.truncated,
-                            }),
+                            text: toolCompactOrJson("grep", outputValue, compactGrepText(outputValue), args.format),
                         },
                     ],
                 };
@@ -3945,28 +4891,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 matches: indexedResult.matches.length,
                 truncated: indexedResult.truncated,
             });
+            const outputValue = {
+                ok: true,
+                backend: indexedResult.backend,
+                fallback_reason: "ripgrep_unavailable",
+                ripgrep_error: ripgrepResult.error,
+                ripgrep_attempts: ripgrepResult.attempts,
+                query: q,
+                mode,
+                case_sensitive: caseSensitive,
+                smart_case: smartCase,
+                hint: indexedResult.hint,
+                kinds,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                candidates: indexedResult.candidates,
+                matches: indexedResult.matches,
+                truncated: indexedResult.truncated,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            backend: indexedResult.backend,
-                            fallback_reason: "ripgrep_unavailable",
-                            ripgrep_error: ripgrepResult.error,
-                            ripgrep_attempts: ripgrepResult.attempts,
-                            query: q,
-                            mode,
-                            case_sensitive: caseSensitive,
-                            smart_case: smartCase,
-                            hint: indexedResult.hint,
-                            kinds,
-                            include_paths: includePaths ?? [],
-                            exclude_paths: excludePaths ?? [],
-                            candidates: indexedResult.candidates,
-                            matches: indexedResult.matches,
-                            truncated: indexedResult.truncated,
-                        }),
+                        text: toolCompactOrJson("grep", outputValue, compactGrepText(outputValue), args.format),
                     },
                 ],
             };
@@ -4018,28 +4965,29 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 truncated: result.truncated,
                 path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
             });
+            const outputValue = {
+                ok: true,
+                path: resolved.dbFilePath,
+                path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
+                recursive: args.recursive,
+                max_depth: args.recursive ? args.max_depth : 1,
+                include_files: args.include_files,
+                include_dirs: args.include_dirs,
+                include_hidden: args.include_hidden,
+                respect_ignore: args.respect_ignore,
+                include_paths: includePaths ?? [],
+                exclude_paths: excludePaths ?? [],
+                extensions: extensions ?? [],
+                returned: result.returned,
+                scanned: result.scanned,
+                truncated: result.truncated,
+                entries: result.entries,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            path: resolved.dbFilePath,
-                            path_kind: st.isFile() ? "file" : st.isDirectory() ? "dir" : "other",
-                            recursive: args.recursive,
-                            max_depth: args.recursive ? args.max_depth : 1,
-                            include_files: args.include_files,
-                            include_dirs: args.include_dirs,
-                            include_hidden: args.include_hidden,
-                            respect_ignore: args.respect_ignore,
-                            include_paths: includePaths ?? [],
-                            exclude_paths: excludePaths ?? [],
-                            extensions: extensions ?? [],
-                            returned: result.returned,
-                            scanned: result.scanned,
-                            truncated: result.truncated,
-                            entries: result.entries,
-                        }),
+                        text: toolCompactOrJson("list_project_files", outputValue, compactListProjectFilesText(outputValue), args.format),
                     },
                 ],
             };
@@ -4079,19 +5027,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 total_chars: result.totalChars,
                 truncated: result.truncated,
             });
+            const outputValue = {
+                ok: true,
+                file_path: resolved.dbFilePath,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+                text: result.text,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            file_path: resolved.dbFilePath,
-                            offset: args.offset,
-                            returned_chars: result.returnedChars,
-                            total_chars: result.totalChars,
-                            truncated: result.truncated,
-                            text: result.text,
-                        }),
+                        text: toolCompactOrJson("read_file_text", outputValue, compactReadTextFileText(outputValue), args.format),
                     },
                 ],
             };
@@ -4138,20 +5087,21 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 total_chars: result.totalChars,
                 truncated: result.truncated,
             });
+            const outputValue = {
+                ok: true,
+                file_path: resolved.displayPath,
+                allowed_root: resolved.allowedRoot,
+                offset: args.offset,
+                returned_chars: result.returnedChars,
+                total_chars: result.totalChars,
+                truncated: result.truncated,
+                text: result.text,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            file_path: resolved.displayPath,
-                            allowed_root: resolved.allowedRoot,
-                            offset: args.offset,
-                            returned_chars: result.returnedChars,
-                            total_chars: result.totalChars,
-                            truncated: result.truncated,
-                            text: result.text,
-                        }),
+                        text: toolCompactOrJson("read_codex_text_file", outputValue, compactReadTextFileText(outputValue), args.format),
                     },
                 ],
             };
@@ -4213,19 +5163,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 returned: result.returned,
                 truncated: result.truncated,
             });
+            const outputValue = {
+                ok: true,
+                file_path: resolved.dbFilePath,
+                from_line: fromLine,
+                to_line: toLine,
+                returned: result.returned,
+                truncated: result.truncated,
+                text: result.text,
+            };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({
-                            ok: true,
-                            file_path: resolved.dbFilePath,
-                            from_line: fromLine,
-                            to_line: toLine,
-                            returned: result.returned,
-                            truncated: result.truncated,
-                            text: result.text,
-                        }),
+                        text: toolCompactOrJson("read_file_lines", outputValue, compactReadFileLinesText(outputValue), args.format),
                     },
                 ],
             };
@@ -4242,11 +5193,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 matches: filtered.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 };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({ ok: true, query: q, matches: filtered }),
+                        text: toolCompactOrJson("query_codebase", outputValue, compactQueryCodebaseText(outputValue), args.format),
                     },
                 ],
             };
@@ -4287,6 +5239,95 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 ],
             };
         }
+        if (toolName === "upsert_decision") {
+            const args = UpsertDecisionArgsSchema.parse(rawArgs);
+            const key = args.key.trim();
+            const title = args.title.trim() || key;
+            const content = args.content.trim();
+            const meta = {
+                status: "current",
+                key,
+                title,
+                tags: args.tags ?? [],
+                supersedes_req_ids: args.supersedes_req_ids ?? [],
+                supersedes_memory_ids: args.supersedes_memory_ids ?? [],
+                related_files: (args.related_files ?? []).map((f) => normalizeToDbPath(f)),
+            };
+            upsertDecisionStmt.run(key, `${title}\n\n${content}`, safeJson(meta), sha256Hex(`${title}\n\n${content}`));
+            const row = getDecisionByKeyStmt.get(key);
+            if (row)
+                enqueueEmbedding(row.id);
+            const superseded_requirements = supersedeRequirementIds(args.supersedes_req_ids ?? [], {
+                decision_id: row?.id,
+                reason: `Superseded by decision ${key}: ${title}`,
+            });
+            const superseded_memory_items = supersedeMemoryItemIds(args.supersedes_memory_ids ?? [], {
+                decision_id: row?.id,
+                reason: `Superseded by decision ${key}: ${title}`,
+            });
+            logActivity("upsert_decision", {
+                key,
+                decision_id: row?.id ?? null,
+                superseded_requirements,
+                superseded_memory_items,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({
+                            ok: true,
+                            decision: row ? { id: row.id, key, updated_at: row.updated_at } : null,
+                            superseded_requirements,
+                            superseded_memory_items,
+                        }),
+                    },
+                ],
+            };
+        }
+        if (toolName === "supersede_memory") {
+            const args = SupersedeMemoryArgsSchema.parse(rawArgs);
+            const supersededReqIds = args.superseded_req_ids ?? [];
+            const supersededMemoryIds = args.superseded_memory_ids ?? [];
+            if (!supersededReqIds.length && !supersededMemoryIds.length) {
+                return {
+                    isError: true,
+                    content: [
+                        {
+                            type: "text",
+                            text: toolJson({
+                                ok: false,
+                                error: "Provide superseded_req_ids and/or superseded_memory_ids.",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const superseded_requirements = supersedeRequirementIds(supersededReqIds, {
+                req_id: args.replacement_req_id,
+                memory_id: args.replacement_memory_id,
+                reason: args.reason,
+            });
+            const superseded_memory_items = supersedeMemoryItemIds(supersededMemoryIds, {
+                req_id: args.replacement_req_id,
+                memory_id: args.replacement_memory_id,
+                reason: args.reason,
+            });
+            logActivity("supersede_memory", {
+                superseded_requirements,
+                superseded_memory_items,
+                replacement_req_id: args.replacement_req_id ?? null,
+                replacement_memory_id: args.replacement_memory_id ?? null,
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: toolJson({ ok: true, superseded_requirements, superseded_memory_items }),
+                    },
+                ],
+            };
+        }
         if (toolName === "upsert_convention") {
             const args = UpsertConventionArgsSchema.parse(rawArgs);
             const key = args.key.trim();
@@ -4345,11 +5386,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     score: m.score,
                 })),
             });
+            const outputValue = { ok: true, ...result };
             return {
                 content: [
                     {
                         type: "text",
-                        text: toolJson({ ok: true, ...result }),
+                        text: toolCompactOrJson("semantic_search", outputValue, compactSemanticSearchText(outputValue), args.format),
                     },
                 ],
             };