@jussmor/commit-memory-mcp 0.3.5 → 0.3.7

package/README.md

@@ -1,60 +1,225 @@
 # @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
+})
+```
+
+Use this before planning when you need fresh PR descriptions, comments, and reviews.
+
+### List active worktrees
+
+```text
+list_active_worktrees({
+  baseBranch: "main"
+})
+```
+
+Use this when your team works on multiple features in parallel and wants session-aware context.
+
+### Build a scoped context pack
+
+```text
+build_context_pack({
+  domain: "billing",
+  feature: "invoice-retry",
+  branch: "feat/invoice-retry",
+  taskType: "coding",
+  includeDraft: false,
+  limit: 12
+})
+```
+
+Use this before invoking a coding subagent to keep prompts small and focused.
+
+### Promote draft facts after review
+
+```text
+promote_context_facts({
+  domain: "billing",
+  feature: "invoice-retry",
+  branch: "feat/invoice-retry"
+})
+```
+
+Use this when discussion outcomes are approved and should become durable context.
+
+### Archive completed feature context
+
+```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 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
+})
 ```
 
-## VS Code MCP registration
+Use this as the default entrypoint for async team planning.
+
+## Multi-session git worktree flow
 
-Copy `mcp.config.example.json` entries into your user MCP config and adjust paths/env values.
+For parallel AI coding sessions:
 
-For MCP Registry publication, keep `package.json` `mcpName` and `server.json` `name` in sync.
+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.
 
-## Environment
+This pattern avoids one giant shared context and scales better as features grow.
 
-- `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
+## Data model overview
 
-If `OLLAMA_EMBED_MODEL` is not set, the package uses deterministic local fallback embeddings.
+The package stores local context for:
 
-### Copilot LLM reranking (optional)
+- commits
+- pull requests
+- PR comments
+- PR reviews
+- promoted decision/blocker summaries
+- worktree session checkpoints
 
-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.
+## Publishing
 
-- `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`)
+```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,7 +1,32 @@
 import Database from "better-sqlite3";
-import type { CommitChunk } 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;
 export declare function upsertChunk(db: RagDatabase, chunk: CommitChunk, embedding: number[]): void;
 export declare function touchIndexState(db: RagDatabase): void;
+export declare function upsertPullRequest(db: RagDatabase, pr: PullRequestRecord): void;
+export declare function replacePullRequestComments(db: RagDatabase, repoOwner: string, repoName: string, prNumber: number, comments: PullRequestCommentRecord[]): void;
+export declare function replacePullRequestReviews(db: RagDatabase, repoOwner: string, repoName: string, prNumber: number, reviews: PullRequestReviewRecord[]): void;
+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

@@ -39,6 +39,114 @@ export function openDatabase(dbPath) {
       id INTEGER PRIMARY KEY CHECK (id = 1),
       last_indexed_at TEXT NOT NULL
     );
+
+    CREATE TABLE IF NOT EXISTS prs (
+      repo_owner TEXT NOT NULL,
+      repo_name TEXT NOT NULL,
+      pr_number INTEGER NOT NULL,
+      title TEXT NOT NULL,
+      body TEXT NOT NULL,
+      author TEXT NOT NULL,
+      state TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      merged_at TEXT,
+      url TEXT NOT NULL,
+      PRIMARY KEY (repo_owner, repo_name, pr_number)
+    );
+
+    CREATE TABLE IF NOT EXISTS pr_comments (
+      id TEXT PRIMARY KEY,
+      repo_owner TEXT NOT NULL,
+      repo_name TEXT NOT NULL,
+      pr_number INTEGER NOT NULL,
+      author TEXT NOT NULL,
+      body TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL,
+      url TEXT NOT NULL,
+      FOREIGN KEY (repo_owner, repo_name, pr_number)
+        REFERENCES prs(repo_owner, repo_name, pr_number)
+    );
+
+    CREATE TABLE IF NOT EXISTS pr_reviews (
+      id TEXT PRIMARY KEY,
+      repo_owner TEXT NOT NULL,
+      repo_name TEXT NOT NULL,
+      pr_number INTEGER NOT NULL,
+      author TEXT NOT NULL,
+      state TEXT NOT NULL,
+      body TEXT NOT NULL,
+      submitted_at TEXT NOT NULL,
+      FOREIGN KEY (repo_owner, repo_name, pr_number)
+        REFERENCES prs(repo_owner, repo_name, pr_number)
+    );
+
+    CREATE TABLE IF NOT EXISTS pr_decisions (
+      id TEXT PRIMARY KEY,
+      repo_owner TEXT NOT NULL,
+      repo_name TEXT NOT NULL,
+      pr_number INTEGER NOT NULL,
+      source TEXT NOT NULL,
+      author TEXT NOT NULL,
+      summary TEXT NOT NULL,
+      severity TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      FOREIGN KEY (repo_owner, repo_name, pr_number)
+        REFERENCES prs(repo_owner, repo_name, pr_number)
+    );
+
+    CREATE TABLE IF NOT EXISTS pr_sync_state (
+      repo_owner TEXT NOT NULL,
+      repo_name TEXT NOT NULL,
+      last_synced_at TEXT NOT NULL,
+      PRIMARY KEY (repo_owner, repo_name)
+    );
+
+    CREATE TABLE IF NOT EXISTS worktree_sessions (
+      path TEXT PRIMARY KEY,
+      branch TEXT NOT NULL,
+      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;
 }
@@ -90,3 +198,296 @@ export function touchIndexState(db) {
         last_indexed_at = excluded.last_indexed_at
     `).run(now);
 }
+export function upsertPullRequest(db, pr) {
+    db.prepare(`
+      INSERT INTO prs (
+        repo_owner,
+        repo_name,
+        pr_number,
+        title,
+        body,
+        author,
+        state,
+        created_at,
+        updated_at,
+        merged_at,
+        url
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(repo_owner, repo_name, pr_number) DO UPDATE SET
+        title = excluded.title,
+        body = excluded.body,
+        author = excluded.author,
+        state = excluded.state,
+        created_at = excluded.created_at,
+        updated_at = excluded.updated_at,
+        merged_at = excluded.merged_at,
+        url = excluded.url
+    `).run(pr.repoOwner, pr.repoName, pr.number, pr.title, pr.body, pr.author, pr.state, pr.createdAt, pr.updatedAt, pr.mergedAt, pr.url);
+}
+export function replacePullRequestComments(db, repoOwner, repoName, prNumber, comments) {
+    db.prepare(`
+      DELETE FROM pr_comments
+      WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+    `).run(repoOwner, repoName, prNumber);
+    const insert = db.prepare(`
+      INSERT INTO pr_comments (
+        id,
+        repo_owner,
+        repo_name,
+        pr_number,
+        author,
+        body,
+        created_at,
+        updated_at,
+        url
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    for (const comment of comments) {
+        insert.run(comment.id, repoOwner, repoName, prNumber, comment.author, comment.body, comment.createdAt, comment.updatedAt, comment.url);
+    }
+}
+export function replacePullRequestReviews(db, repoOwner, repoName, prNumber, reviews) {
+    db.prepare(`
+      DELETE FROM pr_reviews
+      WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+    `).run(repoOwner, repoName, prNumber);
+    const insert = db.prepare(`
+      INSERT INTO pr_reviews (
+        id,
+        repo_owner,
+        repo_name,
+        pr_number,
+        author,
+        state,
+        body,
+        submitted_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    for (const review of reviews) {
+        insert.run(review.id, repoOwner, repoName, prNumber, review.author, review.state, review.body, review.submittedAt);
+    }
+}
+export function replacePullRequestDecisions(db, repoOwner, repoName, prNumber, decisions) {
+    db.prepare(`
+      DELETE FROM pr_decisions
+      WHERE repo_owner = ? AND repo_name = ? AND pr_number = ?
+    `).run(repoOwner, repoName, prNumber);
+    const insert = db.prepare(`
+      INSERT INTO pr_decisions (
+        id,
+        repo_owner,
+        repo_name,
+        pr_number,
+        source,
+        author,
+        summary,
+        severity,
+        created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+    for (const decision of decisions) {
+        insert.run(decision.id, repoOwner, repoName, prNumber, decision.source, decision.author, decision.summary, decision.severity, decision.createdAt);
+    }
+}
+export function touchPullRequestSyncState(db, repoOwner, repoName) {
+    db.prepare(`
+      INSERT INTO pr_sync_state (repo_owner, repo_name, last_synced_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(repo_owner, repo_name) DO UPDATE SET
+        last_synced_at = excluded.last_synced_at
+    `).run(repoOwner, repoName, new Date().toISOString());
+}
+export function upsertWorktreeSession(db, session) {
+    db.prepare(`
+      INSERT INTO worktree_sessions (path, branch, base_branch, last_synced_at)
+      VALUES (?, ?, ?, ?)
+      ON CONFLICT(path) DO UPDATE SET
+        branch = excluded.branch,
+        base_branch = excluded.base_branch,
+        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 clauses = [];
+    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.taskType) {
+        clauses.push("scope_task_type IN (?, 'general')");
+        params.push(options.taskType);
+    }
+    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.45) + (confidence * 0.35) +
+        CASE
+          WHEN scope_task_type = ? THEN 0.20
+          WHEN scope_task_type = 'general' THEN 0.10
+          ELSE 0.0
+        END) AS score
+    FROM context_facts
+    ${where}
+    ORDER BY score DESC, updated_at DESC
+    LIMIT ?
+  `;
+    const taskType = options.taskType ?? "general";
+    const rows = db.prepare(sql).all(taskType, ...params, options.limit);
+    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 ?? ""),
+    }));
+}
+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);
+}