@jussmor/commit-memory-mcp 0.4.0 → 0.4.2

package/README.md

@@ -108,7 +108,8 @@ build_context_pack({
 ```
 
 Use this before invoking a coding subagent to keep prompts small and focused.
-If no rows are found in strict scope, the server now falls back automatically to broader scope levels.
+The pack is assembled main-first: promoted facts on `main` are treated as baseline truth, then branch/feature facts are added as in-flight overlay.
+If no rows are found in strict scope, the server falls back automatically to broader scope levels.
 
 Important: if you provide `domain`/`feature`/`branch` tags in `build_context_pack`, use the same tags during `sync_pr_context` for best precision.
 

package/dist/db/client.js

@@ -372,6 +372,7 @@ export function promoteContextFacts(db, options) {
 }
 export function buildContextPack(db, options) {
     const taskType = options.taskType ?? "general";
+    const GLOBAL_BRANCH = "main";
     function runQuery(params) {
         const clauses = [];
         const values = [taskType];
@@ -383,7 +384,11 @@ export function buildContextPack(db, options) {
             clauses.push("scope_feature = ?");
             values.push(options.feature);
         }
-        if (params.includeBranch && options.branch) {
+        if (params.forcedBranch) {
+            clauses.push("scope_branch = ?");
+            values.push(params.forcedBranch);
+        }
+        else if (params.includeBranch && options.branch) {
             clauses.push("scope_branch = ?");
             values.push(options.branch);
         }
@@ -444,27 +449,61 @@ export function buildContextPack(db, options) {
             updatedAt: String(row.updated_at ?? ""),
         }));
     }
-    const strictRows = runQuery({
+    const seenIds = new Set();
+    const pack = [];
+    const addRows = (rows) => {
+        for (const row of rows) {
+            if (pack.length >= options.limit) {
+                return;
+            }
+            if (seenIds.has(row.id)) {
+                continue;
+            }
+            seenIds.add(row.id);
+            pack.push(row);
+        }
+    };
+    // 1) Main branch domain context is the durable source-of-truth baseline.
+    if (pack.length < options.limit) {
+        addRows(runQuery({
+            includeDomain: true,
+            includeFeature: false,
+            includeBranch: false,
+            forcedBranch: GLOBAL_BRANCH,
+        }));
+    }
+    // 2) Main branch global context fills any remaining baseline slots.
+    if (pack.length < options.limit) {
+        addRows(runQuery({
+            includeDomain: false,
+            includeFeature: false,
+            includeBranch: false,
+            forcedBranch: GLOBAL_BRANCH,
+        }));
+    }
+    // 3) Branch-local feature context overlays main for active, in-flight work.
+    addRows(runQuery({
         includeDomain: true,
         includeFeature: true,
         includeBranch: true,
-    });
-    if (strictRows.length > 0) {
-        return strictRows;
+    }));
+    // 4) Domain-wide branch context provides additional short-lived signal.
+    if (pack.length < options.limit) {
+        addRows(runQuery({
+            includeDomain: true,
+            includeFeature: false,
+            includeBranch: false,
+        }));
     }
-    const broadRows = runQuery({
-        includeDomain: true,
-        includeFeature: false,
-        includeBranch: false,
-    });
-    if (broadRows.length > 0) {
-        return broadRows;
+    // 5) Final safety net from all promoted context.
+    if (pack.length < options.limit) {
+        addRows(runQuery({
+            includeDomain: false,
+            includeFeature: false,
+            includeBranch: false,
+        }));
     }
-    return runQuery({
-        includeDomain: false,
-        includeFeature: false,
-        includeBranch: false,
-    });
+    return pack;
 }
 export function archiveFeatureContext(db, options) {
     const now = new Date().toISOString();

package/dist/git/insights.d.ts

@@ -60,6 +60,28 @@ export declare function mainBranchOvernightBrief(options: {
         subject: string;
     }>;
 };
+export declare function extractFeatureBranchCommits(options: {
+    repoPath: string;
+    featureBranch: string;
+    baseBranch: string;
+    limit: number;
+}): {
+    featureName: string;
+    featureBranch: string;
+    baseBranch: string;
+    commits: Array<{
+        sha: string;
+        author: string;
+        date: string;
+        subject: string;
+        files: string[];
+    }>;
+    topFiles: Array<{
+        filePath: string;
+        touchCount: number;
+    }>;
+    affectedModules: string[];
+};
 export declare function resumeFeatureSessionBrief(options: {
     worktreePath: string;
     baseBranch: string;

package/dist/git/insights.js

@@ -154,6 +154,85 @@ export function mainBranchOvernightBrief(options) {
         commits,
     };
 }
+export function extractFeatureBranchCommits(options) {
+    const repoPath = path.resolve(options.repoPath);
+    const featureName = options.featureBranch
+        .replace(/^feature\//, "")
+        .replace(/[^a-zA-Z0-9-_]/g, "-");
+    const limit = Math.max(1, options.limit);
+    let commitsRaw;
+    try {
+        commitsRaw = runGit(repoPath, [
+            "log",
+            `--format=%H%x1f%an%x1f%aI%x1f%s`,
+            `-n${limit}`,
+            `${options.baseBranch}..${options.featureBranch}`,
+        ]).trim();
+    }
+    catch {
+        return {
+            featureName,
+            featureBranch: options.featureBranch,
+            baseBranch: options.baseBranch,
+            commits: [],
+            topFiles: [],
+            affectedModules: [],
+        };
+    }
+    if (!commitsRaw) {
+        return {
+            featureName,
+            featureBranch: options.featureBranch,
+            baseBranch: options.baseBranch,
+            commits: [],
+            topFiles: [],
+            affectedModules: [],
+        };
+    }
+    const fileCounts = new Map();
+    const commits = commitsRaw.split("\n").map((line) => {
+        const [sha = "", author = "", date = "", subject = ""] = line.split("\x1f");
+        let files = [];
+        try {
+            const filesRaw = runGit(repoPath, [
+                "show",
+                "--name-only",
+                "--pretty=format:",
+                sha,
+            ]).trim();
+            files = filesRaw
+                .split("\n")
+                .map((f) => f.trim())
+                .filter(Boolean);
+        }
+        catch {
+            // ignore per-commit failures
+        }
+        for (const f of files) {
+            fileCounts.set(f, (fileCounts.get(f) ?? 0) + 1);
+        }
+        return { sha, author, date, subject, files };
+    });
+    const topFiles = Array.from(fileCounts.entries())
+        .map(([filePath, touchCount]) => ({ filePath, touchCount }))
+        .sort((a, b) => b.touchCount - a.touchCount)
+        .slice(0, 15);
+    const moduleSet = new Set();
+    for (const { filePath } of topFiles) {
+        const parts = filePath.split("/");
+        if (parts.length >= 2) {
+            moduleSet.add(parts.slice(0, 2).join("/"));
+        }
+    }
+    return {
+        featureName,
+        featureBranch: options.featureBranch,
+        baseBranch: options.baseBranch,
+        commits,
+        topFiles,
+        affectedModules: Array.from(moduleSet).slice(0, 10),
+    };
+}
 export function resumeFeatureSessionBrief(options) {
     const worktreePath = path.resolve(options.worktreePath);
     const branch = runGit(worktreePath, [

package/dist/mcp/server.js

@@ -6,10 +6,14 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { archiveFeatureContext, buildContextPack, openDatabase, promoteContextFacts, upsertWorktreeSession, } from "../db/client.js";
-import { commitDetails, explainPathActivity, latestCommitForFile, mainBranchOvernightBrief, resumeFeatureSessionBrief, whoChangedFile, } from "../git/insights.js";
+import { archiveFeatureContext, buildContextPack, openDatabase, promoteContextFacts, upsertContextFact, upsertWorktreeSession, } from "../db/client.js";
+import { commitDetails, explainPathActivity, extractFeatureBranchCommits, latestCommitForFile, mainBranchOvernightBrief, resumeFeatureSessionBrief, whoChangedFile, } from "../git/insights.js";
 import { listActiveWorktrees } from "../git/worktree.js";
 import { syncPullRequestContext } from "../pr/sync.js";
+import { callOllamaLlm } from "../search/embeddings.js";
+function normalizeFeatureName(branch) {
+    return branch.replace(/^feature\//, "").replace(/[^a-zA-Z0-9-_]/g, "-");
+}
 function fetchRemote(repoPath) {
     execFileSync("git", ["-C", repoPath, "fetch", "--all", "--prune"], {
         stdio: ["ignore", "pipe", "pipe"],
@@ -287,6 +291,41 @@ export async function startMcpServer() {
                     required: [],
                 },
             },
+            {
+                name: "learn_feature",
+                description: "Save feature knowledge to the RAG DB. If agentContent is provided (recommended), it is stored directly as the feature's understanding — the agent should investigate the source code itself and pass its findings here. If agentContent is omitted, falls back to git-commit-based inference.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        featureBranch: {
+                            type: "string",
+                            description: "e.g. feature/messaging",
+                        },
+                        baseBranch: { type: "string" },
+                        limit: { type: "number" },
+                        agentContent: {
+                            type: "string",
+                            description: "Plain-text description of what the feature does, written by the agent after reading actual source files. When provided, this becomes the stored knowledge (confidence 0.95) and git metadata is appended as supporting context.",
+                        },
+                    },
+                    required: ["featureBranch"],
+                },
+            },
+            {
+                name: "sync_feature_knowledge",
+                description: "Update the AI knowledge for a feature branch using new commits and PR decisions since the last sync. Bootstraps automatically if no prior knowledge exists.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        featureBranch: { type: "string" },
+                        baseBranch: { type: "string" },
+                        owner: { type: "string" },
+                        repo: { type: "string" },
+                        limit: { type: "number" },
+                    },
+                    required: ["featureBranch"],
+                },
+            },
             {
                 name: "pre_plan_sync_brief",
                 description: "Run sync + overnight + feature resume analysis before planning work.",
@@ -641,6 +680,320 @@ export async function startMcpServer() {
                 content: [{ type: "text", text: JSON.stringify(prePlan, null, 2) }],
             };
         }
+        if (request.params.name === "learn_feature") {
+            const featureBranch = String(request.params.arguments?.featureBranch ?? "").trim();
+            const baseBranch = String(request.params.arguments?.baseBranch ?? "").trim() || "main";
+            const limit = Number(request.params.arguments?.limit ?? 50);
+            const agentContent = String(request.params.arguments?.agentContent ?? "").trim() || null;
+            if (!featureBranch) {
+                return {
+                    content: [{ type: "text", text: "featureBranch is required" }],
+                    isError: true,
+                };
+            }
+            const featureName = normalizeFeatureName(featureBranch);
+            const data = extractFeatureBranchCommits({
+                repoPath,
+                featureBranch,
+                baseBranch,
+                limit: Number.isFinite(limit) && limit > 0 ? limit : 50,
+            });
+            const authors = [...new Set(data.commits.map((c) => c.author))].join(", ");
+            const now = new Date().toISOString();
+            let content;
+            let confidence;
+            let aiGenerated;
+            if (agentContent) {
+                // Agent investigated the source code directly — highest confidence.
+                // Append git metadata as supporting context.
+                const gitMeta = [
+                    ``,
+                    `--- Git metadata (${data.commits.length} commits, authors: ${authors || "unknown"}) ---`,
+                    `Top files: ${data.topFiles
+                        .slice(0, 5)
+                        .map((f) => f.filePath)
+                        .join(", ") || "(none)"}`,
+                    `Top modules: ${data.affectedModules.slice(0, 4).join(", ") || "(none)"}`,
+                ].join("\n");
+                content = agentContent + gitMeta;
+                confidence = 0.95;
+                aiGenerated = true;
+            }
+            else {
+                // Fallback: infer from git commits + optional Ollama synthesis.
+                const fileList = data.topFiles
+                    .map((f) => `  - ${f.filePath} (touched ${f.touchCount}x)`)
+                    .join("\n");
+                const commitList = data.commits
+                    .slice(0, 20)
+                    .map((c) => `  - ${c.subject} (${c.author})`)
+                    .join("\n");
+                const prompt = [
+                    `You are analyzing a Git feature branch called "${featureBranch}".`,
+                    ``,
+                    `Top changed files:`,
+                    fileList || "  (none)",
+                    ``,
+                    `Commit history (most recent first):`,
+                    commitList || "  (none)",
+                    ``,
+                    `Answer in 3-5 sentences:`,
+                    `1. What does this feature do?`,
+                    `2. What modules/areas of the codebase does it affect?`,
+                    `3. What does it NOT do or what is explicitly out of scope?`,
+                ].join("\n");
+                const llmSummary = await callOllamaLlm(prompt);
+                const fallbackSummary = [
+                    `Feature "${featureName}" spans ${data.commits.length} commit(s) by ${authors || "(unknown)"}.`,
+                    `Top modules: ${data.affectedModules.slice(0, 4).join(", ") || "(unknown)"}.`,
+                    `Top files: ${data.topFiles
+                        .slice(0, 3)
+                        .map((f) => f.filePath)
+                        .join(", ") || "(none)"}.`,
+                    `Commit subjects: ${data.commits
+                        .slice(0, 5)
+                        .map((c) => c.subject)
+                        .join("; ")}.`,
+                ].join(" ");
+                content = llmSummary ?? fallbackSummary;
+                confidence = llmSummary ? 0.85 : 0.6;
+                aiGenerated = llmSummary !== null;
+            }
+            const db = openDatabase(dbPath);
+            try {
+                upsertContextFact(db, {
+                    id: `feature-knowledge:${featureName}`,
+                    sourceType: "feature-agent",
+                    sourceRef: featureBranch,
+                    domain: "",
+                    feature: featureName,
+                    branch: featureBranch,
+                    taskType: "feature-knowledge",
+                    title: `Feature knowledge: ${featureName}`,
+                    content,
+                    priority: 0.9,
+                    confidence,
+                    status: "promoted",
+                    createdAt: now,
+                    updatedAt: now,
+                });
+            }
+            finally {
+                db.close();
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            featureName,
+                            learned: content,
+                            filesAnalyzed: data.topFiles.length,
+                            commitsAnalyzed: data.commits.length,
+                            agentProvided: agentContent !== null,
+                            aiGenerated,
+                            confidence,
+                            savedAt: now,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        if (request.params.name === "sync_feature_knowledge") {
+            const featureBranch = String(request.params.arguments?.featureBranch ?? "").trim();
+            const baseBranch = String(request.params.arguments?.baseBranch ?? "").trim() || "main";
+            const owner = String(request.params.arguments?.owner ?? "").trim();
+            const repo = String(request.params.arguments?.repo ?? "").trim();
+            const limit = Number(request.params.arguments?.limit ?? 50);
+            if (!featureBranch) {
+                return {
+                    content: [{ type: "text", text: "featureBranch is required" }],
+                    isError: true,
+                };
+            }
+            const featureName = normalizeFeatureName(featureBranch);
+            const safeLimit = Number.isFinite(limit) && limit > 0 ? limit : 50;
+            // Load existing knowledge from DB
+            let existingKnowledge = null;
+            let existingUpdatedAt = null;
+            let existingCreatedAt = null;
+            const dbRead = openDatabase(dbPath);
+            try {
+                const existing = dbRead
+                    .prepare("SELECT content, created_at, updated_at FROM context_facts WHERE id = ? LIMIT 1")
+                    .get(`feature-knowledge:${featureName}`);
+                existingKnowledge = existing?.content ?? null;
+                existingUpdatedAt = existing?.updated_at ?? null;
+                existingCreatedAt = existing?.created_at ?? null;
+            }
+            finally {
+                dbRead.close();
+            }
+            // Bootstrap via learn_feature logic if no prior knowledge
+            if (!existingKnowledge) {
+                const bootData = extractFeatureBranchCommits({
+                    repoPath,
+                    featureBranch,
+                    baseBranch,
+                    limit: safeLimit,
+                });
+                const bootFileList = bootData.topFiles
+                    .map((f) => `  - ${f.filePath} (touched ${f.touchCount}x)`)
+                    .join("\n");
+                const bootCommitList = bootData.commits
+                    .slice(0, 20)
+                    .map((c) => `  - ${c.subject} (${c.author})`)
+                    .join("\n");
+                const bootPrompt = [
+                    `You are analyzing a Git feature branch called "${featureBranch}".`,
+                    `Top changed files:\n${bootFileList || "  (none)"}`,
+                    `Commit history:\n${bootCommitList || "  (none)"}`,
+                    `Answer in 3-5 sentences: 1. What does this feature do? 2. What modules does it affect? 3. What is out of scope?`,
+                ].join("\n\n");
+                const bootLlm = await callOllamaLlm(bootPrompt);
+                existingKnowledge =
+                    bootLlm ??
+                        `Feature "${featureName}" has ${bootData.commits.length} commit(s). Top modules: ${bootData.affectedModules.slice(0, 4).join(", ") || "(unknown)"}.`;
+                const now = new Date().toISOString();
+                const dbBoot = openDatabase(dbPath);
+                try {
+                    upsertContextFact(dbBoot, {
+                        id: `feature-knowledge:${featureName}`,
+                        sourceType: "feature-agent",
+                        sourceRef: featureBranch,
+                        domain: "",
+                        feature: featureName,
+                        branch: featureBranch,
+                        taskType: "feature-knowledge",
+                        title: `Feature knowledge: ${featureName}`,
+                        content: existingKnowledge,
+                        priority: 0.9,
+                        confidence: bootLlm ? 0.85 : 0.6,
+                        status: "promoted",
+                        createdAt: now,
+                        updatedAt: now,
+                    });
+                }
+                finally {
+                    dbBoot.close();
+                }
+                existingUpdatedAt = now;
+                existingCreatedAt = now;
+            }
+            // Fetch remote and extract commits
+            fetchRemote(repoPath);
+            const data = extractFeatureBranchCommits({
+                repoPath,
+                featureBranch,
+                baseBranch,
+                limit: safeLimit,
+            });
+            // Only process commits newer than last sync
+            const newCommits = existingUpdatedAt
+                ? data.commits.filter((c) => c.date > existingUpdatedAt)
+                : data.commits;
+            // Gather PR decisions for referenced PRs in new commits
+            const referencedPrNumbers = newCommits
+                .map((c) => detectReferencedPrNumber(c.subject))
+                .filter((n) => n !== null);
+            let prDecisionsSummary = "";
+            if (referencedPrNumbers.length > 0) {
+                const dbPr = openDatabase(dbPath);
+                try {
+                    const parts = [];
+                    for (const prNum of referencedPrNumbers.slice(0, 5)) {
+                        const { pr, decisions } = loadPullRequestContext(dbPr, prNum, owner || undefined, repo || undefined);
+                        if (pr) {
+                            parts.push(`PR #${prNum} "${pr["title"]}": ${decisions
+                                .slice(0, 3)
+                                .map((d) => d["summary"])
+                                .join("; ")}`);
+                        }
+                    }
+                    prDecisionsSummary = parts.join("\n");
+                }
+                finally {
+                    dbPr.close();
+                }
+            }
+            const newCommitList = newCommits
+                .slice(0, 20)
+                .map((c) => `  - ${c.subject} (${c.author})`)
+                .join("\n");
+            const updatePrompt = [
+                `You previously documented this feature:`,
+                `"${existingKnowledge}"`,
+                ``,
+                `New commits since last sync:`,
+                newCommitList || "  (no new commits)",
+                prDecisionsSummary ? `\nPR decisions:\n${prDecisionsSummary}` : "",
+                ``,
+                `Write an updated 3-5 sentence understanding of the feature. If nothing changed, return the previous text unchanged.`,
+            ].join("\n");
+            const updatedSummary = newCommits.length > 0
+                ? ((await callOllamaLlm(updatePrompt)) ?? existingKnowledge)
+                : existingKnowledge;
+            const now = new Date().toISOString();
+            const dbWrite = openDatabase(dbPath);
+            try {
+                upsertContextFact(dbWrite, {
+                    id: `feature-knowledge:${featureName}`,
+                    sourceType: "feature-agent",
+                    sourceRef: featureBranch,
+                    domain: "",
+                    feature: featureName,
+                    branch: featureBranch,
+                    taskType: "feature-knowledge",
+                    title: `Feature knowledge: ${featureName}`,
+                    content: updatedSummary,
+                    priority: 0.9,
+                    confidence: 0.85,
+                    status: "promoted",
+                    createdAt: existingCreatedAt ?? now,
+                    updatedAt: now,
+                });
+                // Audit log row (status: draft — invisible to default build_context_pack)
+                if (newCommits.length > 0) {
+                    const auditDate = now.split("T")[0] ?? now;
+                    upsertContextFact(dbWrite, {
+                        id: `feature-change-log:${featureName}:${auditDate}`,
+                        sourceType: "feature-agent",
+                        sourceRef: featureBranch,
+                        domain: "",
+                        feature: featureName,
+                        branch: featureBranch,
+                        taskType: "change-log",
+                        title: `Change log: ${featureName} on ${auditDate}`,
+                        content: `New commits: ${newCommits
+                            .map((c) => c.subject)
+                            .join("; ")}. ${prDecisionsSummary}`.trim(),
+                        priority: 0.7,
+                        confidence: 0.8,
+                        status: "draft",
+                        createdAt: now,
+                        updatedAt: now,
+                    });
+                }
+            }
+            finally {
+                dbWrite.close();
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            featureName,
+                            previousKnowledge: existingKnowledge,
+                            updatedKnowledge: updatedSummary,
+                            newCommitsAnalyzed: newCommits.length,
+                            totalCommitsInBranch: data.commits.length,
+                            syncedAt: now,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
         return {
             content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
             isError: true,

package/dist/search/embeddings.d.ts

@@ -1,2 +1,3 @@
 export declare function embedText(text: string): Promise<number[]>;
+export declare function callOllamaLlm(prompt: string): Promise<string | null>;
 export declare function getExpectedDimension(): number;

package/dist/search/embeddings.js

@@ -52,6 +52,30 @@ export async function embedText(text) {
     }
     return normalize(payload.embedding);
 }
+export async function callOllamaLlm(prompt) {
+    const model = process.env.OLLAMA_CHAT_MODEL;
+    if (!model) {
+        return null;
+    }
+    const baseUrl = process.env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434";
+    try {
+        const response = await fetch(`${baseUrl}/api/generate`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model, prompt, stream: false }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const payload = (await response.json());
+        return typeof payload.response === "string" && payload.response.trim()
+            ? payload.response.trim()
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function getExpectedDimension() {
     return process.env.OLLAMA_EMBED_MODEL
         ? Number.parseInt(process.env.COMMIT_RAG_DIMENSION ?? "", 10) ||

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jussmor/commit-memory-mcp",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "mcpName": "io.github.jussmor/commit-memory",
   "description": "Commit-aware RAG with sqlite-vec and MCP tools for local agent workflows",
   "license": "MIT",