@jussmor/commit-memory-mcp 0.3.6 → 0.3.8

package/README.md

@@ -1,60 +1,242 @@
 # @jussmor/commit-memory-mcp
 
-Local commit-aware RAG package powered by sqlite-vec with MCP tool endpoints.
+A local MCP server for PR intelligence, author tracing, and worktree-aware async planning.
 
-## Features
+## Purpose
 
-- Indexes git commits across branches into commit-file chunks
-- Embeds chunks using a local embedding source (Ollama when configured)
-- Stores vectors in sqlite-vec (SQLite)
-- Exposes MCP tools for agent workflows
+This package helps agents answer:
 
-## MCP tools
+- who changed a file or area
+- why a change was made
+- what landed on main recently
+- what context should be reviewed before planning
+
+## Current MCP tools
+
+- `sync_pr_context`
+- `build_context_pack`
+- `promote_context_facts`
+- `archive_feature_context`
+- `list_active_worktrees`
+- `who_changed_this`
+- `why_was_this_changed`
+- `get_main_branch_overnight_brief`
+- `resume_feature_session_brief`
+- `pre_plan_sync_brief`
+
+## Removed tools
+
+The following legacy tools were removed:
 
 - `search_related_commits`
 - `explain_commit_match`
 - `get_commit_diff`
+- `reindex_commits`
 
 ## Quick start
 
 ```bash
 npm install @jussmor/commit-memory-mcp
-npx commit-memory-index --repo /path/to/repo --db /path/to/repo/.commit-rag.db --limit 400
 npx commit-memory-mcp
 ```
 
-## Publish
+For local development in this repository:
 
 ```bash
+cd packages/commit-rag-mcp
+npm install
 npm run build
-npm publish --access public
-mcp-publisher login github
-mcp-publisher publish
+node dist/mcp/server.js
+```
+
+## Requirements
+
+- Node.js 20+
+- `gh` CLI authenticated for GitHub PR sync features
+- a git repository available through `COMMIT_RAG_REPO`
+
+## Environment variables
+
+- `COMMIT_RAG_REPO` repository path used by the MCP server
+- `COMMIT_RAG_DB` SQLite database path
+- `COMMIT_RAG_LIMIT` default sync/query limit
+- `OLLAMA_BASE_URL` optional Ollama base URL
+- `OLLAMA_EMBED_MODEL` optional embedding model
+- `COPILOT_TOKEN` optional Copilot reranking token
+- `COPILOT_MODEL` optional Copilot model override
+- `COPILOT_BASE_URL` optional Copilot API base URL
+
+## Use cases
+
+### Sync GitHub PR context
+
+```text
+sync_pr_context({
+  owner: "MaxwellClinic-Development",
+  repo: "EverBetter-Pro",
+  domain: "billing",
+  feature: "invoice-retry",
+  branch: "feat/invoice-retry",
+  taskType: "planning",
+  limit: 20
+})
 ```
 
-## VS Code MCP registration
+Use this before planning when you need fresh PR descriptions, comments, and reviews.
 
-Copy `mcp.config.example.json` entries into your user MCP config and adjust paths/env values.
+### List active worktrees
 
-For MCP Registry publication, keep `package.json` `mcpName` and `server.json` `name` in sync.
+```text
+list_active_worktrees({
+  baseBranch: "main"
+})
+```
+
+Use this when your team works on multiple features in parallel and wants session-aware context.
 
-## Environment
+### Build a scoped context pack
+
+```text
+build_context_pack({
+  domain: "billing",
+  feature: "invoice-retry",
+  branch: "feat/invoice-retry",
+  taskType: "coding",
+  includeDraft: false,
+  limit: 12
+})
+```
 
-- `COMMIT_RAG_REPO` default repository path for MCP
-- `COMMIT_RAG_DB` sqlite db path
-- `COMMIT_RAG_LIMIT` max commits to index per run
-- `OLLAMA_BASE_URL` local ollama URL (default `http://127.0.0.1:11434`)
-- `OLLAMA_EMBED_MODEL` local embedding model name
+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.
 
-If `OLLAMA_EMBED_MODEL` is not set, the package uses deterministic local fallback embeddings.
+Important: if you provide `domain`/`feature`/`branch` tags in `build_context_pack`, use the same tags during `sync_pr_context` for best precision.
+
+### Promote draft facts after review
+
+```text
+promote_context_facts({
+  domain: "billing",
+  feature: "invoice-retry",
+  branch: "feat/invoice-retry"
+})
+```
 
-### Copilot LLM reranking (optional)
+Use this when discussion outcomes are approved and should become durable context.
 
-Set `COPILOT_TOKEN` to a GitHub token with Copilot access to enable LLM-based reranking.
-After initial vector/keyword retrieval, results are sent to Copilot for semantic scoring and re-sorted.
+### Archive completed feature context
 
-- `COPILOT_TOKEN` GitHub PAT or token with Copilot access (enables reranking)
-- `COPILOT_MODEL` model slug (default: `gpt-4o-mini`, supports `claude-sonnet-4-5`, `gpt-4o`, etc.)
-- `COPILOT_BASE_URL` API base URL (default: `https://api.githubcopilot.com`)
+```text
+archive_feature_context({
+  domain: "billing",
+  feature: "invoice-retry"
+})
+```
+
+Use this after merge/closure to prevent active context bloat.
+
+### Find ownership for a file
+
+```text
+who_changed_this({
+  filePath: "src/features/auth/session.ts",
+  limit: 15
+})
+```
+
+Use this to discover recent authors and commit history for a target file.
+
+### Explain what is happening in a Next.js folder
+
+```text
+explain_path_activity({
+  targetPath: "app/dashboard",
+  owner: "MaxwellClinic-Development",
+  repo: "EverBetter-Pro",
+  limit: 30
+})
+```
+
+Use this when you want a fast folder-level summary for areas like `app/dashboard`, `app/(authenticated)`, or `src/components`.
+It returns recent commits, top authors, most touched files, and related PR context/decisions when available.
+
+### Explain intent for a change
+
+```text
+why_was_this_changed({
+  filePath: "src/features/auth/session.ts",
+  owner: "MaxwellClinic-Development",
+  repo: "EverBetter-Pro"
+})
+```
+
+Use this to combine commit metadata with synced PR context.
+
+### Get an overnight main-branch brief
+
+```text
+get_main_branch_overnight_brief({
+  baseBranch: "main",
+  sinceHours: 12,
+  limit: 25
+})
+```
+
+Use this at the start of the day to review what landed while you were offline.
+
+### Resume a feature worktree
+
+```text
+resume_feature_session_brief({
+  worktreePath: "/path/to/worktree",
+  baseBranch: "main"
+})
+```
+
+Use this before resuming unfinished work in a separate worktree.
+
+### Run the full pre-plan sync flow
+
+```text
+pre_plan_sync_brief({
+  owner: "MaxwellClinic-Development",
+  repo: "EverBetter-Pro",
+  baseBranch: "main",
+  worktreePath: "/path/to/worktree",
+  sinceHours: 12,
+  limit: 25
+})
+```
+
+Use this as the default entrypoint for async team planning.
+
+## Multi-session git worktree flow
+
+For parallel AI coding sessions:
+
+1. Create one git worktree per feature branch.
+2. Use `list_active_worktrees` to enumerate active sessions.
+3. Use `resume_feature_session_brief` per worktree to check divergence and overlap risks.
+4. Generate a worktree-specific `build_context_pack` and hand it to the target subagent.
+
+This pattern avoids one giant shared context and scales better as features grow.
+
+## Data model overview
+
+The package stores local context for:
+
+- commits
+- pull requests
+- PR comments
+- PR reviews
+- promoted decision/blocker summaries
+- worktree session checkpoints
+
+## Publishing
+
+```bash
+npm run build
+npm publish --access public
+```
 
-Reranking works alongside or instead of Ollama — no embedding model required.
+For MCP Registry publication, keep `package.json` `mcpName` and `server.json` `name` aligned.

package/dist/db/client.d.ts

@@ -1,5 +1,5 @@
 import Database from "better-sqlite3";
-import type { CommitChunk, PullRequestCommentRecord, PullRequestDecisionRecord, PullRequestRecord, PullRequestReviewRecord, WorktreeSessionRecord } from "../types.js";
+import type { CommitChunk, ContextFactRecord, ContextPackRecord, PullRequestCommentRecord, PullRequestDecisionRecord, PullRequestRecord, PullRequestReviewRecord, WorktreeSessionRecord } from "../types.js";
 export type RagDatabase = Database.Database;
 export declare function openDatabase(dbPath: string): RagDatabase;
 export declare function hasChunk(db: RagDatabase, chunkId: string): boolean;
@@ -11,3 +11,22 @@ export declare function replacePullRequestReviews(db: RagDatabase, repoOwner: st
 export declare function replacePullRequestDecisions(db: RagDatabase, repoOwner: string, repoName: string, prNumber: number, decisions: PullRequestDecisionRecord[]): void;
 export declare function touchPullRequestSyncState(db: RagDatabase, repoOwner: string, repoName: string): void;
 export declare function upsertWorktreeSession(db: RagDatabase, session: WorktreeSessionRecord): void;
+export declare function upsertContextFact(db: RagDatabase, fact: ContextFactRecord): void;
+export declare function promoteContextFacts(db: RagDatabase, options: {
+    domain?: string;
+    feature?: string;
+    branch?: string;
+    sourceType?: string;
+}): number;
+export declare function buildContextPack(db: RagDatabase, options: {
+    domain?: string;
+    feature?: string;
+    branch?: string;
+    taskType?: string;
+    includeDraft?: boolean;
+    limit: number;
+}): ContextPackRecord[];
+export declare function archiveFeatureContext(db: RagDatabase, options: {
+    domain: string;
+    feature: string;
+}): number;

package/dist/db/client.js

@@ -109,6 +109,44 @@ export function openDatabase(dbPath) {
       base_branch TEXT NOT NULL,
       last_synced_at TEXT NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS context_facts (
+      id TEXT PRIMARY KEY,
+      source_type TEXT NOT NULL,
+      source_ref TEXT NOT NULL,
+      scope_domain TEXT NOT NULL,
+      scope_feature TEXT NOT NULL,
+      scope_branch TEXT NOT NULL,
+      scope_task_type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      content TEXT NOT NULL,
+      priority REAL NOT NULL,
+      confidence REAL NOT NULL,
+      status TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_context_scope
+      ON context_facts(scope_domain, scope_feature, scope_branch, scope_task_type, status, updated_at);
+
+    CREATE TABLE IF NOT EXISTS context_fact_archive (
+      id TEXT PRIMARY KEY,
+      source_type TEXT NOT NULL,
+      source_ref TEXT NOT NULL,
+      scope_domain TEXT NOT NULL,
+      scope_feature TEXT NOT NULL,
+      scope_branch TEXT NOT NULL,
+      scope_task_type TEXT NOT NULL,
+      title TEXT NOT NULL,
+      content TEXT NOT NULL,
+      priority REAL NOT NULL,
+      confidence REAL NOT NULL,
+      status TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      archived_at TEXT NOT NULL
+    );
   `);
     return db;
 }
@@ -270,3 +308,211 @@ export function upsertWorktreeSession(db, session) {
         last_synced_at = excluded.last_synced_at
     `).run(session.path, session.branch, session.baseBranch, session.lastSyncedAt);
 }
+export function upsertContextFact(db, fact) {
+    db.prepare(`
+      INSERT INTO context_facts (
+        id,
+        source_type,
+        source_ref,
+        scope_domain,
+        scope_feature,
+        scope_branch,
+        scope_task_type,
+        title,
+        content,
+        priority,
+        confidence,
+        status,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        source_type = excluded.source_type,
+        source_ref = excluded.source_ref,
+        scope_domain = excluded.scope_domain,
+        scope_feature = excluded.scope_feature,
+        scope_branch = excluded.scope_branch,
+        scope_task_type = excluded.scope_task_type,
+        title = excluded.title,
+        content = excluded.content,
+        priority = excluded.priority,
+        confidence = excluded.confidence,
+        status = excluded.status,
+        created_at = excluded.created_at,
+        updated_at = excluded.updated_at
+    `).run(fact.id, fact.sourceType, fact.sourceRef, fact.domain, fact.feature, fact.branch, fact.taskType, fact.title, fact.content, fact.priority, fact.confidence, fact.status, fact.createdAt, fact.updatedAt);
+}
+export function promoteContextFacts(db, options) {
+    const clauses = ["status = 'draft'"];
+    const params = [];
+    if (options.domain) {
+        clauses.push("scope_domain = ?");
+        params.push(options.domain);
+    }
+    if (options.feature) {
+        clauses.push("scope_feature = ?");
+        params.push(options.feature);
+    }
+    if (options.branch) {
+        clauses.push("scope_branch = ?");
+        params.push(options.branch);
+    }
+    if (options.sourceType) {
+        clauses.push("source_type = ?");
+        params.push(options.sourceType);
+    }
+    const sql = `
+    UPDATE context_facts
+    SET status = 'promoted', updated_at = ?
+    WHERE ${clauses.join(" AND ")}
+  `;
+    const now = new Date().toISOString();
+    const result = db.prepare(sql).run(now, ...params);
+    return Number(result.changes ?? 0);
+}
+export function buildContextPack(db, options) {
+    const taskType = options.taskType ?? "general";
+    function runQuery(params) {
+        const clauses = [];
+        const values = [taskType, taskType];
+        if (params.includeDomain && options.domain) {
+            clauses.push("scope_domain = ?");
+            values.push(options.domain);
+        }
+        if (params.includeFeature && options.feature) {
+            clauses.push("scope_feature = ?");
+            values.push(options.feature);
+        }
+        if (params.includeBranch && options.branch) {
+            clauses.push("scope_branch = ?");
+            values.push(options.branch);
+        }
+        if (options.includeDraft) {
+            clauses.push("status IN ('promoted', 'draft')");
+        }
+        else {
+            clauses.push("status = 'promoted'");
+        }
+        const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+        const sql = `
+    SELECT
+      id,
+      source_type,
+      source_ref,
+      title,
+      content,
+      scope_domain,
+      scope_feature,
+      scope_branch,
+      scope_task_type,
+      priority,
+      confidence,
+      status,
+      updated_at,
+      ((priority * 0.40) + (confidence * 0.30) +
+        CASE
+          WHEN scope_task_type = ? THEN 0.30
+          WHEN scope_task_type = 'general' THEN 0.15
+          ELSE 0.0
+        END +
+        CASE
+          WHEN source_type = 'pr_description' THEN 0.15
+          WHEN source_type LIKE 'pr_%' THEN 0.08
+          ELSE 0.0
+        END) AS score
+    FROM context_facts
+    ${where}
+    ORDER BY score DESC, updated_at DESC
+    LIMIT ?
+  `;
+        values.push(options.limit);
+        const rows = db.prepare(sql).all(...values);
+        return rows.map((row) => ({
+            id: String(row.id ?? ""),
+            sourceType: String(row.source_type ?? ""),
+            sourceRef: String(row.source_ref ?? ""),
+            title: String(row.title ?? ""),
+            content: String(row.content ?? ""),
+            domain: String(row.scope_domain ?? ""),
+            feature: String(row.scope_feature ?? ""),
+            branch: String(row.scope_branch ?? ""),
+            taskType: String(row.scope_task_type ?? ""),
+            priority: Number(row.priority ?? 0),
+            confidence: Number(row.confidence ?? 0),
+            score: Number(row.score ?? 0),
+            status: String(row.status ?? "promoted"),
+            updatedAt: String(row.updated_at ?? ""),
+        }));
+    }
+    const strictRows = runQuery({
+        includeDomain: true,
+        includeFeature: true,
+        includeBranch: true,
+    });
+    if (strictRows.length > 0) {
+        return strictRows;
+    }
+    const broadRows = runQuery({
+        includeDomain: true,
+        includeFeature: false,
+        includeBranch: false,
+    });
+    if (broadRows.length > 0) {
+        return broadRows;
+    }
+    return runQuery({
+        includeDomain: false,
+        includeFeature: false,
+        includeBranch: false,
+    });
+}
+export function archiveFeatureContext(db, options) {
+    const now = new Date().toISOString();
+    const tx = db.transaction(() => {
+        db.prepare(`
+        INSERT OR REPLACE INTO context_fact_archive (
+          id,
+          source_type,
+          source_ref,
+          scope_domain,
+          scope_feature,
+          scope_branch,
+          scope_task_type,
+          title,
+          content,
+          priority,
+          confidence,
+          status,
+          created_at,
+          updated_at,
+          archived_at
+        )
+        SELECT
+          id,
+          source_type,
+          source_ref,
+          scope_domain,
+          scope_feature,
+          scope_branch,
+          scope_task_type,
+          title,
+          content,
+          priority,
+          confidence,
+          'archived',
+          created_at,
+          updated_at,
+          ?
+        FROM context_facts
+        WHERE scope_domain = ? AND scope_feature = ?
+      `).run(now, options.domain, options.feature);
+        return db
+            .prepare(`
+          DELETE FROM context_facts
+          WHERE scope_domain = ? AND scope_feature = ?
+        `)
+            .run(options.domain, options.feature);
+    });
+    const result = tx();
+    return Number(result.changes ?? 0);
+}

package/dist/git/insights.d.ts

@@ -16,6 +16,27 @@ export declare function whoChangedFile(options: {
         lastCommitAt: string;
     }>;
 };
+export declare function explainPathActivity(options: {
+    repoPath: string;
+    targetPath: string;
+    limit: number;
+}): {
+    targetPath: string;
+    commits: Array<{
+        sha: string;
+        author: string;
+        date: string;
+        subject: string;
+    }>;
+    topAuthors: Array<{
+        author: string;
+        commitCount: number;
+    }>;
+    topFiles: Array<{
+        filePath: string;
+        touchCount: number;
+    }>;
+};
 export declare function latestCommitForFile(repoPath: string, filePath: string): string | null;
 export declare function commitDetails(repoPath: string, sha: string): {
     sha: string;

package/dist/git/insights.js

@@ -46,6 +46,66 @@ export function whoChangedFile(options) {
         authors,
     };
 }
+export function explainPathActivity(options) {
+    const repoPath = path.resolve(options.repoPath);
+    const limit = Math.max(1, options.limit);
+    const targetPath = options.targetPath.trim();
+    const commitsRaw = runGit(repoPath, [
+        "log",
+        `-n${limit}`,
+        "--format=%H%x1f%an%x1f%aI%x1f%s",
+        "--",
+        targetPath,
+    ]).trim();
+    if (!commitsRaw) {
+        return {
+            targetPath,
+            commits: [],
+            topAuthors: [],
+            topFiles: [],
+        };
+    }
+    const commits = commitsRaw.split("\n").map((line) => {
+        const [sha = "", author = "", date = "", subject = ""] = line.split("\x1f");
+        return { sha, author, date, subject };
+    });
+    const authorCounts = new Map();
+    const fileCounts = new Map();
+    for (const commit of commits) {
+        authorCounts.set(commit.author, (authorCounts.get(commit.author) ?? 0) + 1);
+        const filesRaw = runGit(repoPath, [
+            "show",
+            "--name-only",
+            "--pretty=format:",
+            commit.sha,
+            "--",
+            targetPath,
+        ]).trim();
+        if (!filesRaw) {
+            continue;
+        }
+        for (const filePath of filesRaw
+            .split("\n")
+            .map((line) => line.trim())
+            .filter(Boolean)) {
+            fileCounts.set(filePath, (fileCounts.get(filePath) ?? 0) + 1);
+        }
+    }
+    const topAuthors = Array.from(authorCounts.entries())
+        .map(([author, commitCount]) => ({ author, commitCount }))
+        .sort((a, b) => b.commitCount - a.commitCount)
+        .slice(0, 8);
+    const topFiles = Array.from(fileCounts.entries())
+        .map(([filePath, touchCount]) => ({ filePath, touchCount }))
+        .sort((a, b) => b.touchCount - a.touchCount)
+        .slice(0, 12);
+    return {
+        targetPath,
+        commits,
+        topAuthors,
+        topFiles,
+    };
+}
 export function latestCommitForFile(repoPath, filePath) {
     const output = runGit(path.resolve(repoPath), [
         "log",

package/dist/mcp/server.js

@@ -6,8 +6,8 @@ import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { openDatabase, upsertWorktreeSession } from "../db/client.js";
-import { commitDetails, latestCommitForFile, mainBranchOvernightBrief, resumeFeatureSessionBrief, whoChangedFile, } from "../git/insights.js";
+import { archiveFeatureContext, buildContextPack, openDatabase, promoteContextFacts, upsertWorktreeSession, } from "../db/client.js";
+import { commitDetails, explainPathActivity, latestCommitForFile, mainBranchOvernightBrief, resumeFeatureSessionBrief, whoChangedFile, } from "../git/insights.js";
 import { listActiveWorktrees } from "../git/worktree.js";
 import { syncPullRequestContext } from "../pr/sync.js";
 function fetchRemote(repoPath) {
@@ -26,6 +26,78 @@ function detectReferencedPrNumber(text) {
     }
     return value;
 }
+function parsePrNumberFromSourceRef(sourceRef) {
+    const match = sourceRef.match(/#(\d{1,8})\b/);
+    if (!match) {
+        return null;
+    }
+    const value = Number.parseInt(match[1] ?? "", 10);
+    if (!Number.isFinite(value) || value <= 0) {
+        return null;
+    }
+    return value;
+}
+function loadPathPullRequestContext(db, options) {
+    const prNumbers = new Set(options.referencedPrNumbers);
+    const likePattern = `%${options.targetPath}%`;
+    const sourceRows = db
+        .prepare(`
+      SELECT source_ref
+      FROM context_facts
+      WHERE (title LIKE ? OR content LIKE ?)
+        AND source_ref LIKE '%#%'
+      ORDER BY updated_at DESC
+      LIMIT 80
+    `)
+        .all(likePattern, likePattern);
+    for (const row of sourceRows) {
+        const number = parsePrNumberFromSourceRef(String(row.source_ref ?? ""));
+        if (number) {
+            prNumbers.add(number);
+        }
+    }
+    if (prNumbers.size === 0) {
+        return [];
+    }
+    const results = [];
+    for (const prNumber of Array.from(prNumbers).slice(0, 20)) {
+        const pr = options.owner && options.repo
+            ? (db
+                .prepare(`
+              SELECT repo_owner, repo_name, pr_number, title, body, author, state, created_at, updated_at, merged_at, url
+              FROM prs
+              WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+              LIMIT 1
+            `)
+                .get(options.owner, options.repo, prNumber) ?? null)
+            : (db
+                .prepare(`
+              SELECT repo_owner, repo_name, pr_number, title, body, author, state, created_at, updated_at, merged_at, url
+              FROM prs
+              WHERE pr_number = ?
+              ORDER BY updated_at DESC
+              LIMIT 1
+            `)
+                .get(prNumber) ?? null);
+        if (!pr) {
+            continue;
+        }
+        const decisions = db
+            .prepare(`
+        SELECT id, source, author, summary, severity, created_at
+        FROM pr_decisions
+        WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+        ORDER BY created_at DESC
+        LIMIT 20
+      `)
+            .all(pr.repo_owner, pr.repo_name, pr.pr_number);
+        results.push({
+            pr,
+            decisions,
+        });
+    }
+    return results;
+}
 function loadPullRequestContext(db, prNumber, repoOwner, repoName) {
     const pr = repoOwner && repoName
         ? (db
@@ -88,11 +160,57 @@ export async function startMcpServer() {
                             type: "array",
                             items: { type: "number" },
                         },
+                        domain: { type: "string" },
+                        feature: { type: "string" },
+                        branch: { type: "string" },
+                        taskType: { type: "string" },
                         limit: { type: "number" },
                     },
                     required: ["owner", "repo"],
                 },
             },
+            {
+                name: "build_context_pack",
+                description: "Build a scoped context pack for a task/domain/feature/branch to keep agent prompts small.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        domain: { type: "string" },
+                        feature: { type: "string" },
+                        branch: { type: "string" },
+                        taskType: { type: "string" },
+                        includeDraft: { type: "boolean" },
+                        limit: { type: "number" },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "promote_context_facts",
+                description: "Promote scoped draft facts into durable promoted context.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        domain: { type: "string" },
+                        feature: { type: "string" },
+                        branch: { type: "string" },
+                        sourceType: { type: "string" },
+                    },
+                    required: [],
+                },
+            },
+            {
+                name: "archive_feature_context",
+                description: "Archive all active facts for a domain/feature once work is complete.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        domain: { type: "string" },
+                        feature: { type: "string" },
+                    },
+                    required: ["domain", "feature"],
+                },
+            },
             {
                 name: "list_active_worktrees",
                 description: "List active git worktrees for multi-session feature work.",
@@ -116,6 +234,20 @@ export async function startMcpServer() {
                     required: ["filePath"],
                 },
             },
+            {
+                name: "explain_path_activity",
+                description: "Given a file or folder path, summarize activity, top files/authors, and related PR context.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        targetPath: { type: "string" },
+                        owner: { type: "string" },
+                        repo: { type: "string" },
+                        limit: { type: "number" },
+                    },
+                    required: ["targetPath"],
+                },
+            },
             {
                 name: "why_was_this_changed",
                 description: "Explain intent for a commit or file using git history and synced PR decisions.",
@@ -192,6 +324,10 @@ export async function startMcpServer() {
                     .filter((value) => Number.isFinite(value) && value > 0)
                 : undefined;
             const limit = Number(request.params.arguments?.limit ?? 25);
+            const domain = String(request.params.arguments?.domain ?? "").trim();
+            const feature = String(request.params.arguments?.feature ?? "").trim();
+            const branch = String(request.params.arguments?.branch ?? "").trim();
+            const taskType = String(request.params.arguments?.taskType ?? "").trim();
             const summary = await syncPullRequestContext({
                 repoPath,
                 dbPath,
@@ -199,11 +335,94 @@ export async function startMcpServer() {
                 repoName: repo,
                 prNumbers,
                 limit,
+                domain: domain || undefined,
+                feature: feature || undefined,
+                branch: branch || undefined,
+                taskType: taskType || undefined,
             });
             return {
                 content: [{ type: "text", text: JSON.stringify(summary, null, 2) }],
             };
         }
+        if (request.params.name === "build_context_pack") {
+            const limit = Number(request.params.arguments?.limit ?? 20);
+            const domain = String(request.params.arguments?.domain ?? "").trim();
+            const feature = String(request.params.arguments?.feature ?? "").trim();
+            const branch = String(request.params.arguments?.branch ?? "").trim();
+            const taskType = String(request.params.arguments?.taskType ?? "").trim() || "general";
+            const includeDraft = Boolean(request.params.arguments?.includeDraft);
+            const db = openDatabase(dbPath);
+            try {
+                const pack = buildContextPack(db, {
+                    domain: domain || undefined,
+                    feature: feature || undefined,
+                    branch: branch || undefined,
+                    taskType,
+                    includeDraft,
+                    limit: Number.isFinite(limit) && limit > 0 ? limit : 20,
+                });
+                return {
+                    content: [{ type: "text", text: JSON.stringify(pack, null, 2) }],
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
+        if (request.params.name === "promote_context_facts") {
+            const domain = String(request.params.arguments?.domain ?? "").trim();
+            const feature = String(request.params.arguments?.feature ?? "").trim();
+            const branch = String(request.params.arguments?.branch ?? "").trim();
+            const sourceType = String(request.params.arguments?.sourceType ?? "").trim();
+            const db = openDatabase(dbPath);
+            try {
+                const promotedCount = promoteContextFacts(db, {
+                    domain: domain || undefined,
+                    feature: feature || undefined,
+                    branch: branch || undefined,
+                    sourceType: sourceType || undefined,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ promotedCount }, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
+        if (request.params.name === "archive_feature_context") {
+            const domain = String(request.params.arguments?.domain ?? "").trim();
+            const feature = String(request.params.arguments?.feature ?? "").trim();
+            if (!domain || !feature) {
+                return {
+                    content: [{ type: "text", text: "domain and feature are required" }],
+                    isError: true,
+                };
+            }
+            const db = openDatabase(dbPath);
+            try {
+                const archivedCount = archiveFeatureContext(db, {
+                    domain,
+                    feature,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ archivedCount }, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
         if (request.params.name === "list_active_worktrees") {
             const baseBranch = String(request.params.arguments?.baseBranch ?? "").trim() || "main";
             const worktrees = listActiveWorktrees(repoPath);
@@ -243,6 +462,52 @@ export async function startMcpServer() {
                 content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
             };
         }
+        if (request.params.name === "explain_path_activity") {
+            const targetPath = String(request.params.arguments?.targetPath ?? "").trim();
+            const owner = String(request.params.arguments?.owner ?? "").trim();
+            const repo = String(request.params.arguments?.repo ?? "").trim();
+            const limit = Number(request.params.arguments?.limit ?? 25);
+            if (!targetPath) {
+                return {
+                    content: [{ type: "text", text: "targetPath is required" }],
+                    isError: true,
+                };
+            }
+            const output = explainPathActivity({
+                repoPath,
+                targetPath,
+                limit: Number.isFinite(limit) && limit > 0 ? limit : 25,
+            });
+            const referencedPrNumbers = output.commits
+                .map((commit) => {
+                const details = commitDetails(repoPath, commit.sha);
+                return detectReferencedPrNumber(`${details.subject}\n${details.body}`);
+            })
+                .filter((value) => Number.isFinite(value));
+            const db = openDatabase(dbPath);
+            try {
+                const relatedPullRequests = loadPathPullRequestContext(db, {
+                    targetPath,
+                    owner: owner || undefined,
+                    repo: repo || undefined,
+                    referencedPrNumbers,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ...output,
+                                relatedPullRequests,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            finally {
+                db.close();
+            }
+        }
         if (request.params.name === "why_was_this_changed") {
             const owner = String(request.params.arguments?.owner ?? "").trim();
             const repo = String(request.params.arguments?.repo ?? "").trim();

package/dist/pr/sync.d.ts

@@ -6,4 +6,8 @@ export declare function syncPullRequestContext(options: {
     repoName: string;
     prNumbers?: number[];
     limit?: number;
+    domain?: string;
+    feature?: string;
+    branch?: string;
+    taskType?: string;
 }): Promise<PullRequestSyncSummary>;

package/dist/pr/sync.js

@@ -1,6 +1,6 @@
 import { execFileSync } from "node:child_process";
 import path from "node:path";
-import { openDatabase, replacePullRequestComments, replacePullRequestDecisions, replacePullRequestReviews, touchPullRequestSyncState, upsertPullRequest, } from "../db/client.js";
+import { openDatabase, replacePullRequestComments, replacePullRequestDecisions, replacePullRequestReviews, touchPullRequestSyncState, upsertContextFact, upsertPullRequest, } from "../db/client.js";
 function runGh(repoPath, args) {
     return execFileSync("gh", args, {
         cwd: repoPath,
@@ -180,6 +180,45 @@ export async function syncPullRequestContext(options) {
             replacePullRequestComments(db, options.repoOwner, options.repoName, parsed.pr.number, parsed.comments);
             replacePullRequestReviews(db, options.repoOwner, options.repoName, parsed.pr.number, parsed.reviews);
             replacePullRequestDecisions(db, options.repoOwner, options.repoName, parsed.pr.number, parsed.decisions);
+            const scopeDomain = (options.domain ?? options.repoName).trim();
+            const scopeFeature = (options.feature ?? `pr-${parsed.pr.number}`).trim() ||
+                `pr-${parsed.pr.number}`;
+            const scopeBranch = (options.branch ?? "main").trim() || "main";
+            const taskType = (options.taskType ?? "planning").trim() || "planning";
+            upsertContextFact(db, {
+                id: `pr:${options.repoOwner}/${options.repoName}#${parsed.pr.number}:description`,
+                sourceType: "pr_description",
+                sourceRef: `${options.repoOwner}/${options.repoName}#${parsed.pr.number}`,
+                domain: scopeDomain,
+                feature: scopeFeature,
+                branch: scopeBranch,
+                taskType,
+                title: parsed.pr.title,
+                content: parsed.pr.body,
+                priority: 0.85,
+                confidence: 0.9,
+                status: "promoted",
+                createdAt: parsed.pr.createdAt,
+                updatedAt: parsed.pr.updatedAt,
+            });
+            for (const decision of parsed.decisions) {
+                upsertContextFact(db, {
+                    id: `decision:${options.repoOwner}/${options.repoName}#${parsed.pr.number}:${decision.id}`,
+                    sourceType: `pr_${decision.source}`,
+                    sourceRef: `${options.repoOwner}/${options.repoName}#${parsed.pr.number}`,
+                    domain: scopeDomain,
+                    feature: scopeFeature,
+                    branch: scopeBranch,
+                    taskType,
+                    title: `Decision ${parsed.pr.number} (${decision.source})`,
+                    content: decision.summary,
+                    priority: decision.severity === "blocker" ? 1 : 0.75,
+                    confidence: 0.8,
+                    status: decision.source === "description" ? "promoted" : "draft",
+                    createdAt: decision.createdAt,
+                    updatedAt: decision.createdAt,
+                });
+            }
             syncedPrs += 1;
             syncedComments += parsed.comments.length;
             syncedReviews += parsed.reviews.length;

package/dist/types.d.ts

@@ -84,3 +84,36 @@ export type WorktreeSessionRecord = {
     lastSyncedAt: string;
     baseBranch: string;
 };
+export type ContextFactStatus = "draft" | "promoted" | "archived";
+export type ContextFactRecord = {
+    id: string;
+    sourceType: string;
+    sourceRef: string;
+    domain: string;
+    feature: string;
+    branch: string;
+    taskType: string;
+    title: string;
+    content: string;
+    priority: number;
+    confidence: number;
+    status: ContextFactStatus;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ContextPackRecord = {
+    id: string;
+    sourceType: string;
+    sourceRef: string;
+    title: string;
+    content: string;
+    domain: string;
+    feature: string;
+    branch: string;
+    taskType: string;
+    priority: number;
+    confidence: number;
+    score: number;
+    status: ContextFactStatus;
+    updatedAt: string;
+};

package/package.json

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