gitmem-mcp 1.4.4 → 1.5.1

package/dist/tools/definitions.js

@@ -2297,6 +2297,92 @@ export const TOOLS = [
             required: ["type", "tool", "description", "severity"],
         },
     },
+    {
+        name: "index_docs",
+        description: "Scan a directory of markdown files, chunk them, embed them, and store them in a local doc index for semantic search. Supports incremental indexing: only re-processes changed files. Use search_docs to query the indexed docs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: {
+                    type: "string",
+                    description: "Absolute path to directory containing .md files to index",
+                },
+                project: {
+                    type: "string",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
+                },
+                exclude: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Directory names to exclude (default: ['_archive', 'node_modules', '.git'])",
+                },
+                force: {
+                    type: "boolean",
+                    description: "Force re-index all files even if unchanged (default: false)",
+                },
+                clear: {
+                    type: "boolean",
+                    description: "Clear the doc index for this project before indexing (default: false)",
+                },
+            },
+            required: ["directory"],
+        },
+    },
+    {
+        name: "search_docs",
+        description: "Search indexed repository documentation using semantic similarity (pro/dev tier) or BM25 keyword search (free tier). Returns relevant chunks with file paths for targeted reading. Index docs first with index_docs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Natural language search query (e.g., 'how does authentication work', 'database schema')",
+                },
+                project: {
+                    type: "string",
+                    description: "Project namespace (e.g., 'my-project'). Scopes sessions and searches.",
+                },
+                category: {
+                    type: "string",
+                    description: "Filter results to a specific category (directory name, e.g., 'architecture', 'research')",
+                },
+                match_count: {
+                    type: "number",
+                    description: "Maximum number of results to return (default: 5)",
+                },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "gitmem-idx",
+        description: "Alias for index_docs. Scan a directory of markdown files and index them for semantic search.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                directory: { type: "string", description: "Absolute path to directory containing .md files" },
+                project: { type: "string", description: "Project namespace" },
+                exclude: { type: "array", items: { type: "string" }, description: "Directory names to exclude" },
+                force: { type: "boolean", description: "Force re-index all files" },
+                clear: { type: "boolean", description: "Clear index before indexing" },
+            },
+            required: ["directory"],
+        },
+    },
+    {
+        name: "gitmem-sd",
+        description: "Alias for search_docs. Search indexed repository documentation.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Natural language search query" },
+                project: { type: "string", description: "Project namespace" },
+                category: { type: "string", description: "Filter by category" },
+                match_count: { type: "number", description: "Max results (default: 5)" },
+            },
+            required: ["query"],
+        },
+    },
 ];
 /**
  * Alias tool names — filtered out by default to reduce context window cost.
@@ -2312,6 +2398,7 @@ export const ALIAS_TOOL_NAMES = new Set([
     "gitmem-pc", "gitmem-ao",
     "gitmem-lt", "gitmem-rt", "gitmem-ct", "gitmem-ps", "gitmem-ds",
     "gitmem-cleanup", "gitmem-health", "gitmem-al", "gitmem-graph", "gitmem-fb",
+    "gitmem-idx", "gitmem-sd",
     // gm-* aliases
     "gm-open", "gm-confirm", "gm-reflect", "gm-refresh", "gm-close",
     "gm-scar", "gm-search", "gm-log", "gm-analyze",

package/dist/tools/index-docs.d.ts

@@ -0,0 +1,30 @@
+/**
+ * index_docs Tool
+ *
+ * Scans a directory of markdown files, chunks them, embeds them,
+ * and stores them in the doc index for semantic search.
+ *
+ * Supports incremental indexing: only re-processes changed files.
+ */
+import type { Project } from "../types/index.js";
+export interface IndexDocsParams {
+    directory: string;
+    project?: Project;
+    exclude?: string[];
+    force?: boolean;
+    clear?: boolean;
+}
+export interface IndexDocsResult {
+    directory: string;
+    project: string;
+    files_scanned: number;
+    files_changed: number;
+    files_unchanged: number;
+    chunks_indexed: number;
+    chunks_embedded: number;
+    errors: number;
+    categories: Record<string, number>;
+    display: string;
+}
+export declare function indexDocs(params: IndexDocsParams): Promise<IndexDocsResult>;
+//# sourceMappingURL=index-docs.d.ts.map

package/dist/tools/index-docs.js

@@ -0,0 +1,163 @@
+/**
+ * index_docs Tool
+ *
+ * Scans a directory of markdown files, chunks them, embeds them,
+ * and stores them in the doc index for semantic search.
+ *
+ * Supports incremental indexing: only re-processes changed files.
+ */
+import * as fs from "fs";
+import { scanDirectory, chunkDocument } from "../services/doc-chunker.js";
+import { indexChunks, getChangedFiles, getIndexStats, clearDocIndex, } from "../services/doc-index.js";
+import { getProject } from "../services/session-state.js";
+import { wrapDisplay, productLine, dimText } from "../services/display-protocol.js";
+export async function indexDocs(params) {
+    const directory = params.directory;
+    const project = params.project || getProject() || "default";
+    const exclude = params.exclude || ["_archive", "node_modules", ".git"];
+    const force = params.force || false;
+    // Validate directory exists
+    if (!fs.existsSync(directory)) {
+        const display = wrapDisplay([
+            productLine("index_docs", "error"),
+            "",
+            `Directory not found: ${directory}`,
+            "",
+            "Provide an absolute path to a directory containing .md files.",
+        ].join("\n"));
+        return {
+            directory,
+            project,
+            files_scanned: 0,
+            files_changed: 0,
+            files_unchanged: 0,
+            chunks_indexed: 0,
+            chunks_embedded: 0,
+            errors: 1,
+            categories: {},
+            display,
+        };
+    }
+    // Handle clear request
+    if (params.clear) {
+        const removed = clearDocIndex(project);
+        const display = wrapDisplay([
+            productLine("index_docs", `cleared ${removed} chunks for project="${project}"`),
+        ].join("\n"));
+        return {
+            directory,
+            project,
+            files_scanned: 0,
+            files_changed: 0,
+            files_unchanged: 0,
+            chunks_indexed: 0,
+            chunks_embedded: 0,
+            errors: 0,
+            categories: {},
+            display,
+        };
+    }
+    // Scan directory for .md files
+    const files = scanDirectory(directory, { exclude });
+    if (files.length === 0) {
+        const display = wrapDisplay([
+            productLine("index_docs", "no markdown files found"),
+            "",
+            `Scanned: ${directory}`,
+            `Excluded: ${exclude.join(", ")}`,
+        ].join("\n"));
+        return {
+            directory,
+            project,
+            files_scanned: 0,
+            files_changed: 0,
+            files_unchanged: 0,
+            chunks_indexed: 0,
+            chunks_embedded: 0,
+            errors: 0,
+            categories: {},
+            display,
+        };
+    }
+    // Incremental indexing: check which files changed
+    const fileHashes = new Map(files.map((f) => [f.relative_path, f.hash]));
+    let filesToProcess = files;
+    let filesUnchanged = 0;
+    if (!force) {
+        const changes = getChangedFiles(fileHashes, project);
+        const changedSet = new Set([...changes.changed, ...changes.new_files]);
+        if (changedSet.size === 0) {
+            const stats = getIndexStats(project);
+            const display = wrapDisplay([
+                productLine("index_docs", "up to date — no changes detected"),
+                "",
+                `${files.length} files scanned, all unchanged`,
+                `${stats.total_chunks} chunks in index`,
+                "",
+                dimText("Use force=true to re-index all files"),
+            ].join("\n"));
+            return {
+                directory,
+                project,
+                files_scanned: files.length,
+                files_changed: 0,
+                files_unchanged: files.length,
+                chunks_indexed: 0,
+                chunks_embedded: 0,
+                errors: 0,
+                categories: stats.categories,
+                display,
+            };
+        }
+        filesToProcess = files.filter((f) => changedSet.has(f.relative_path));
+        filesUnchanged = files.length - filesToProcess.length;
+    }
+    // Chunk the changed files
+    const allChunks = [];
+    for (const file of filesToProcess) {
+        allChunks.push(...chunkDocument(file));
+    }
+    // Index chunks (embed + store)
+    const result = await indexChunks(allChunks, project);
+    // Get updated stats
+    const stats = getIndexStats(project);
+    // Build display
+    const lines = [];
+    lines.push(productLine("index_docs", `${filesToProcess.length} files → ${result.indexed} chunks`));
+    lines.push("");
+    lines.push(`Directory: ${directory}`);
+    lines.push(`Project: ${project}`);
+    lines.push("");
+    lines.push(`Files scanned:   ${files.length}`);
+    lines.push(`Files changed:   ${filesToProcess.length}`);
+    lines.push(`Files unchanged: ${filesUnchanged}`);
+    lines.push(`Chunks indexed:  ${result.indexed}`);
+    lines.push(`Chunks embedded: ${result.embedded}`);
+    if (result.errors > 0) {
+        lines.push(`Errors:          ${result.errors}`);
+    }
+    lines.push("");
+    // Category breakdown
+    if (Object.keys(stats.categories).length > 0) {
+        lines.push("Categories:");
+        for (const [cat, count] of Object.entries(stats.categories).sort((a, b) => b[1] - a[1])) {
+            lines.push(`  ${cat.padEnd(20)} ${count} chunks`);
+        }
+        lines.push("");
+    }
+    lines.push(`Total index: ${stats.total_chunks} chunks across ${stats.total_files} files`);
+    const display = wrapDisplay(lines.join("\n"));
+    return {
+        directory,
+        project,
+        files_scanned: files.length,
+        files_changed: filesToProcess.length,
+        files_unchanged: filesUnchanged,
+        chunks_indexed: result.indexed,
+        chunks_embedded: result.embedded,
+        errors: result.errors,
+        categories: stats.categories,
+        display,
+    };
+}
+//# sourceMappingURL=index-docs.js.map

package/dist/tools/prepare-context.js

@@ -40,6 +40,13 @@ Proceed with caution — this may be new territory without documented lessons.`;
         formatNudgeHeader(scars.length),
         "",
     ];
+    // Citation protocol — provenance enforcement for any downstream claims
+    // Placed BEFORE results so agents see it before processing scars
+    lines.push("───────────────────────────────────────────────────");
+    lines.push("CITATION RULE: When referencing facts from these scars, cite the record ID.");
+    lines.push("Example: \"Edge improved to 3.07 [id:48ebca14]\" — not paraphrased numbers.");
+    lines.push("If you cannot cite a specific record for a claim, say \"not in institutional memory.\"");
+    lines.push("");
     // Blocking verification requirements first
     const blockingScars = scars.filter((s) => s.required_verification?.blocking);
     if (blockingScars.length > 0) {

package/dist/tools/recall.js

@@ -48,6 +48,13 @@ No past lessons match this plan closely enough. Scars accumulate as you work —
         lines.push(`${dimText("No project-specific lessons yet. Use create_learning to capture your first.")}`);
         lines.push("");
     }
+    // Citation protocol — provenance enforcement for any downstream claims
+    // Placed BEFORE results so agents see it before processing scars
+    lines.push("───────────────────────────────────────────────────");
+    lines.push("CITATION RULE: When referencing facts from these scars, cite the record ID.");
+    lines.push("Example: \"Edge improved to 3.07 [id:48ebca14]\" — not paraphrased numbers.");
+    lines.push("If you cannot cite a specific record for a claim, say \"not in institutional memory.\"");
+    lines.push("");
     // Display blocking verification requirements FIRST and prominently
     if (scarsWithVerification.length > 0) {
         lines.push(`${ANSI.yellow}VERIFICATION REQUIRED${ANSI.reset}`);
@@ -73,7 +80,9 @@ No past lessons match this plan closely enough. Scars accumulate as you work —
     for (const scar of scars) {
         const sev = SEV[scar.severity] || "[?]";
         const starterTag = scar.is_starter ? ` ${dimText("[starter]")}` : "";
-        lines.push(`${sev} **${scar.title}** (${scar.severity}, ${scar.similarity.toFixed(2)}) ${dimText(`id:${scar.id.slice(0, 8)}`)}${starterTag}`);
+        // Confidence tier: marginal matches (< 0.55) get flagged — 66% N/A rate in this range
+        const confidenceTag = scar.similarity < 0.55 ? ` ${dimText("[low confidence]")}` : "";
+        lines.push(`${sev} **${scar.title}** (${scar.severity}, ${scar.similarity.toFixed(2)}) ${dimText(`id:${scar.id.slice(0, 8)}`)}${starterTag}${confidenceTag}`);
         // Inline archival hint: scars with high dismiss rates get annotated
         if (dismissals) {
             const counts = dismissals.get(scar.id);

package/dist/tools/search-docs.d.ts

@@ -0,0 +1,38 @@
+/**
+ * search_docs Tool
+ *
+ * Semantic search over indexed repository documentation.
+ * Returns relevant chunks with file paths for targeted reading.
+ *
+ * Like search (for scars), but for docs.
+ */
+import type { Project } from "../types/index.js";
+export interface SearchDocsParams {
+    query: string;
+    project?: Project;
+    category?: string;
+    match_count?: number;
+}
+export interface SearchDocsResultEntry {
+    id: string;
+    file_path: string;
+    chunk_index: number;
+    title: string;
+    section_title: string;
+    category: string;
+    content: string;
+    similarity: number;
+}
+export interface SearchDocsResult {
+    query: string;
+    project: string;
+    results: SearchDocsResultEntry[];
+    total_found: number;
+    index_stats: {
+        total_chunks: number;
+        total_files: number;
+    };
+    display: string;
+}
+export declare function searchDocsHandler(params: SearchDocsParams): Promise<SearchDocsResult>;
+//# sourceMappingURL=search-docs.d.ts.map

package/dist/tools/search-docs.js

@@ -0,0 +1,94 @@
+/**
+ * search_docs Tool
+ *
+ * Semantic search over indexed repository documentation.
+ * Returns relevant chunks with file paths for targeted reading.
+ *
+ * Like search (for scars), but for docs.
+ */
+import { searchDocs as doSearch, getIndexStats } from "../services/doc-index.js";
+import { getProject } from "../services/session-state.js";
+import { wrapDisplay, productLine, dimText, truncate } from "../services/display-protocol.js";
+export async function searchDocsHandler(params) {
+    const query = params.query;
+    const project = params.project || getProject() || "default";
+    const category = params.category;
+    const matchCount = params.match_count || 5;
+    // Check if index exists
+    const stats = getIndexStats(project);
+    if (stats.total_chunks === 0) {
+        const display = wrapDisplay([
+            productLine("search_docs", "no docs indexed"),
+            "",
+            `No documents indexed for project="${project}".`,
+            "",
+            "Index docs first:",
+            '  index_docs({ directory: "/path/to/docs", project: "my-project" })',
+        ].join("\n"));
+        return {
+            query,
+            project,
+            results: [],
+            total_found: 0,
+            index_stats: {
+                total_chunks: stats.total_chunks,
+                total_files: stats.total_files,
+            },
+            display,
+        };
+    }
+    // Search
+    const results = await doSearch(query, {
+        project,
+        category,
+        match_count: matchCount,
+    });
+    // Build display
+    const lines = [];
+    lines.push(productLine("search_docs", `${results.length} results · "${truncate(query, 60)}"`));
+    if (category) {
+        lines.push(`Category filter: ${category}`);
+    }
+    lines.push("");
+    if (results.length === 0) {
+        lines.push("No matching docs found.");
+        lines.push("");
+        lines.push(`Index contains ${stats.total_chunks} chunks across ${stats.total_files} files.`);
+        lines.push("Available categories: " + Object.keys(stats.categories).join(", "));
+    }
+    else {
+        // Show results with file paths prominently
+        for (const r of results) {
+            const sim = `(${r.similarity.toFixed(2)})`;
+            const conf = r.similarity < 0.55 ? ` ${dimText("[low confidence]")}` : "";
+            const section = r.section_title ? ` > ${r.section_title}` : "";
+            lines.push(`${r.file_path}${section} ${sim}${conf}`);
+            lines.push(`  ${truncate(r.title, 60)} [${r.category}]`);
+            lines.push(`  ${truncate(r.content, 120)}`);
+            lines.push("");
+        }
+        lines.push(dimText(`Searched ${stats.total_chunks} chunks across ${stats.total_files} files`));
+    }
+    const display = wrapDisplay(lines.join("\n"));
+    return {
+        query,
+        project,
+        results: results.map((r) => ({
+            id: r.id,
+            file_path: r.file_path,
+            chunk_index: r.chunk_index,
+            title: r.title,
+            section_title: r.section_title,
+            category: r.category,
+            content: r.content,
+            similarity: r.similarity,
+        })),
+        total_found: results.length,
+        index_stats: {
+            total_chunks: stats.total_chunks,
+            total_files: stats.total_files,
+        },
+        display,
+    };
+}
+//# sourceMappingURL=search-docs.js.map

package/dist/tools/search.js

@@ -30,6 +30,14 @@ function buildSearchDisplay(results, total_found, query, filters) {
     if (fp.length > 0)
         lines.push(`Filters: ${fp.join(", ")}`);
     lines.push("");
+    // Citation protocol — provenance enforcement for any downstream claims
+    // Placed BEFORE results so agents see it before processing results
+    if (results.length > 0) {
+        lines.push("───────────────────────────────────────────────────");
+        lines.push("CITATION RULE: When referencing facts from these results, cite the record ID.");
+        lines.push("If you cannot cite a specific record for a claim, say \"not in institutional memory.\"");
+        lines.push("");
+    }
     if (results.length === 0) {
         lines.push("No results found.");
         return wrapDisplay(lines.join("\n"));
@@ -40,7 +48,9 @@ function buildSearchDisplay(results, total_found, query, filters) {
         const t = truncate(r.title, 50);
         const sim = `(${r.similarity.toFixed(2)})`;
         const issue = r.source_linear_issue ? `  ${r.source_linear_issue}` : "";
-        lines.push(`${te} ${se} ${t.padEnd(52)} ${sim}${issue}`);
+        // Confidence tier: marginal matches (< 0.55) get flagged
+        const conf = r.similarity < 0.55 ? ` ${dimText("[low confidence]")}` : "";
+        lines.push(`${te} ${se} ${t.padEnd(52)} ${sim}${issue}${conf}`);
         const starterTag = r.is_starter ? ` ${dimText("[starter]")}` : "";
         lines.push(`   ${truncate(r.description, 72)}  id:${r.id.slice(0, 8)}${starterTag}`);
     }

package/dist/tools/session-close.js

@@ -12,7 +12,7 @@ import * as supabase from "../services/supabase-client.js";
 import { embed, isEmbeddingAvailable } from "../services/embedding.js";
 import { hasSupabase, getTableName } from "../services/tier.js";
 import { getStorage } from "../services/storage.js";
-import { clearCurrentSession, getSurfacedScars, getConfirmations, getReflections, getObservations, getChildren, getThreads, getSessionActivity } from "../services/session-state.js";
+import { clearCurrentSession, getSurfacedScars, getConfirmations, getReflections, getObservations, getChildren, getThreads, getSessionActivity, isRecallCalled } from "../services/session-state.js";
 import { normalizeThreads, mergeThreadStates, migrateStringThread, saveThreadsFile } from "../services/thread-manager.js"; // 
 import { deduplicateThreadList } from "../services/thread-dedup.js";
 import { syncThreadsToSupabase, loadOpenThreadEmbeddings } from "../services/thread-supabase.js";
@@ -858,13 +858,56 @@ export async function sessionClose(params) {
                 `(${Math.round(activity.duration_min)} min, no substantive activity). ` +
                 `Proceeding with standard as requested.`);
         }
+        // Hard gate: quick close requires session under 30 minutes
+        if (params.close_type === "quick" && activity.duration_min >= 30) {
+            return {
+                success: false,
+                session_id: params.session_id || "",
+                close_compliance: {
+                    close_type: "quick",
+                    agent: detectAgent().agent,
+                    checklist_displayed: false,
+                    questions_answered_by_agent: false,
+                    human_asked_for_corrections: false,
+                    learnings_stored: 0,
+                    scars_applied: 0,
+                },
+                validation_errors: [
+                    `Session has been active for ${Math.round(activity.duration_min)} minutes. ` +
+                        `Quick close requires sessions under 30 minutes. Use close_type: "standard".`,
+                ],
+                performance: buildPerformanceData("session_close", timer.stop(), 0),
+            };
+        }
         if (params.close_type === "quick" && recommendedLevel === "full") {
-            // Warn but don't reject — agent chose quick on a substantive session
+            // Warn but don't reject — agent chose quick on a substantive session under 30 min
             console.error(`[session_close] Warning: "quick" close on substantive session ` +
                 `(${Math.round(activity.duration_min)} min, ${activity.recall_count} recalls, ` +
                 `${activity.observation_count} observations). Consider "standard" close.`);
         }
     }
+    // Hard gate: standard close requires at least one recall() call
+    // Exemptions: quick (micro sessions), autonomous (CODA-1), hasReflection (agent already wrote full reflection)
+    if (params.close_type === "standard" && !isRecallCalled() && !hasReflection) {
+        return {
+            success: false,
+            session_id: params.session_id || "",
+            close_compliance: {
+                close_type: "standard",
+                agent: detectAgent().agent,
+                checklist_displayed: false,
+                questions_answered_by_agent: false,
+                human_asked_for_corrections: false,
+                learnings_stored: 0,
+                scars_applied: 0,
+            },
+            validation_errors: [
+                `No recall() was run this session. Standard close requires at least one recall. ` +
+                    `Run recall("session close ceremony") first, then retry session_close.`,
+            ],
+            performance: buildPerformanceData("session_close", timer.stop(), 0),
+        };
+    }
     // Free tier: simple local persistence, skip Supabase recovery and compliance
     if (!hasSupabase()) {
         return sessionCloseFree(params, timer);

package/dist/tools/session-start.js

@@ -676,6 +676,20 @@ function formatStartDisplay(result, displayInfoMap, isFirstSession) {
     if (result.project)
         parts.push(result.project);
     visual.push(dimText(parts.join(" · ")));
+    // Line 3: duration + surfaced scars for resumed/refreshed sessions
+    if (result.resumed || result.refreshed) {
+        const session = getCurrentSession();
+        if (session?.startedAt) {
+            const durationMs = Date.now() - session.startedAt.getTime();
+            const totalMin = Math.floor(durationMs / 60000);
+            const hours = Math.floor(totalMin / 60);
+            const mins = totalMin % 60;
+            const durationStr = hours > 0 ? `${hours}h ${mins}m` : `${mins}m`;
+            const scarCount = session.surfacedScars?.length || 0;
+            const scarSuffix = scarCount > 0 ? ` · ${scarCount} scars loaded from earlier` : "";
+            visual.push(dimText(`Session active for: ${durationStr}${scarSuffix}`));
+        }
+    }
     // Threads section — top 5 by vitality, truncated to 60 chars
     const hasThreads = result.open_threads && result.open_threads.length > 0;
     const hasDecisions = result.recent_decisions && result.recent_decisions.length > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitmem-mcp",
-  "version": "1.4.4",
+  "version": "1.5.1",
   "mcpName": "io.github.gitmem-dev/gitmem",
   "description": "Persistent learning memory for AI coding agents. Memory that compounds.",
   "type": "module",