Commit Memory MCP Surreal
Commit-aware MCP with SurrealDB-backed traceability, async team coordination, and business knowledge tools
Ask AI about Commit Memory MCP Surreal
Powered by Claude · Grounded in docs
I know everything about Commit Memory MCP Surreal. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
AI Plans
A worktree-aware PR intelligence system for GitHub Copilot and async engineering teams.
What it does
This repository provides a local MCP server that helps teams answer:
- Who changed this area?
- Why was it changed?
- What landed on main while I was away?
- What should I review before planning new work?
Instead of relying only on commit search, the current system combines:
- local git history
- GitHub PR descriptions
- GitHub PR comments and reviews
- promoted decision/blocker context
- active git worktrees for parallel feature sessions
Current MCP tools
sync_pr_contextbuild_context_packpromote_context_factsarchive_feature_contextlist_active_worktreeswho_changed_thiswhy_was_this_changedget_main_branch_overnight_briefresume_feature_session_briefpre_plan_sync_brief
Breaking change
These old tools were removed:
search_related_commitsexplain_commit_matchget_commit_diffreindex_commits
See .github/copilot-instructions.md for the current workflow contract.
Why this exists
Async teams lose context in three places:
- Commit messages describe a small change but not the final feature decision.
- PR comments contain important discussion, but they are noisy and hard to recover later.
- Engineers switch branches and worktrees and need a fast "what changed while I was sleeping" brief before planning.
This project makes PR description the canonical feature narrative, treats review discussion as secondary evidence, and produces a pre-plan sync brief before implementation starts.
Quick start
1. Install and build
npm install
cd packages/commit-rag-mcp
npm run build
2. Configure MCP in VS Code
The workspace already includes mcp.json.
Reload VS Code and enable the commit-memory-mcp server in the MCP tools panel.
3. Authenticate GitHub CLI
gh auth status
If gh is not authenticated, PR sync tools cannot fetch PR descriptions/comments/reviews.
4. Start with the pre-plan brief
Ask Copilot to run:
Run pre_plan_sync_brief for MaxwellClinic-Development/EverBetter-Pro
Or invoke the tool directly through MCP.
Recommended team workflow
- Start every coding session with
pre_plan_sync_brief. - Review blocker-level decisions before making code changes.
- Check
resume_feature_session_briefafter rebases or major merges. - Keep PR descriptions updated with final decisions from review threads.
Context partition flow
To avoid oversized prompts as features grow, keep changing context in scoped partitions:
- Sync context with
sync_pr_contextusing domain/feature/branch/task metadata. - Keep non-final discussion as
draftfacts. - Promote approved facts with
promote_context_facts. - Build small task-focused packs using
build_context_pack. - Archive completed feature context with
archive_feature_context.
This keeps agents thin and gives subagents only the context slice they need.
Git worktree for multiple AI coding sessions
git worktree lets your team run parallel AI coding sessions without branch collisions.
Typical pattern:
- Create one worktree per feature/session.
- Run
list_active_worktreesto discover all active sessions. - Run
resume_feature_session_briefinside the target worktree. - Run
build_context_packfor that feature/task before handing work to a subagent.
This allows multiple subagents to work concurrently with scoped context instead of one large global prompt.
Use cases
1. Start-of-day sync
Problem:
You were offline overnight and want to know what changed on main before continuing work.
Use:
Run get_main_branch_overnight_brief for main in the last 12 hours
Outcome: You get a compact author/date/subject summary of recent main-branch commits.
2. Resume an unfinished feature in another worktree
Problem: You have multiple features open in different git worktrees and need to know whether your branch is behind or colliding with main.
Use:
Run resume_feature_session_brief for this worktree against main
Outcome: You get branch divergence and overlapping file risk before you start planning or rebasing.
3. Understand who changed a file recently
Problem: A file is behaving differently and you want the likely authors and recent commits.
Use:
Run who_changed_this for src/features/auth/session.ts
Outcome: You get top authors, recent commits, and a fast ownership trail.
4. Explain why a change was made
Problem: A commit or file changed, but the commit alone is not enough to explain the reasoning.
Use:
Run why_was_this_changed for src/features/auth/session.ts
Or:
Run why_was_this_changed for sha abc1234
Outcome: The agent combines commit metadata with synced PR description and promoted decision context.
5. Sync PR context before implementation planning
Problem: Your team writes strong PR descriptions and review discussions, and you want plans to reflect that context.
Use:
Run sync_pr_context for MaxwellClinic-Development/EverBetter-Pro
Outcome: PR descriptions, comments, and reviews are stored locally for later author/why analysis.
6. One-command pre-plan briefing
Problem: You want a single command that syncs GitHub context, checks main, checks your feature session, and tells you what to do first.
Use:
Run pre_plan_sync_brief for MaxwellClinic-Development/EverBetter-Pro with baseBranch main
Outcome: You get:
- PR sync status
- overnight main changes
- branch ahead/behind counts
- overlap files
- recommended first actions
7. Build a small context pack for a subagent
Problem: Feature knowledge is too large for one prompt and you need a focused pack for a coding subagent.
Use:
Run build_context_pack with domain billing, feature invoice-retry, branch feat/invoice-retry, taskType coding, limit 12
Outcome: You get a ranked, bounded context set so the subagent receives only relevant facts.
Architecture
GitHub Copilot / MCP Client
|
v
commit-memory-mcp
|
+-- git history
+-- GitHub PR metadata via gh
+-- SQLite context store
+-- worktree session tracking
Project structure
packages/
commit-rag-mcp/ MCP server and local context engine
.github/
agents/ Agent specifications
copilot-instructions.md
mcp.json Workspace MCP configuration
SETUP.md Setup guide
README.md Overview and workflow guide
Documentation
- SETUP.md
- .github/copilot-instructions.md
- .github/agents/README.md
- .github/agents/commit-rag.md
- packages/commit-rag-mcp/README.md
Development notes
- Node.js 20+
ghCLI is required for PR sync features- SQLite is used as the local durable context store
- Worktree-aware planning is a first-class use case
Next documentation step
SETUP.md still needs the migration and sync-before-plan update to fully match the current tool contract.
