CommitContext

Automatically capture the reasoning behind every commit — decisions, debugging paths, and patterns — as searchable MemNexus memories.

Every commit tells you what changed. CommitContext captures why.

On every git commit, CommitContext automatically reads your git context and AI agent session, distills the reasoning into a structured memory, and stores it in MemNexus — searchable by meaning, enriched with entities and facts, and automatically injected into future agent sessions.

Prerequisites

mx CLI installed and authenticated (installation guide)
A git repository

Setup

Install the hook

Run mx setup from inside your project directory:

cd ~/my-project
mx setup

The interactive setup configures your AI agent's MCP connection and installs the CommitContext post-commit hook in one step.

To install just the hook separately:

mx setup hooks

If you use Husky, Lefthook, or another hook manager, mx setup hooks detects it and appends to your existing hook file rather than replacing it.

Verify it works

Make any commit:

git commit --allow-empty -m "test: verify commit context"

Wait a few seconds (the hook runs in the background), then check:

mx commit-context list

You should see your commit listed with a summary.

That's it. Every commit from now on is automatically captured.

What gets captured

On each commit, CommitContext collects:

Data	Source	Example
Commit metadata	Git	SHA, branch, author, message, files changed, insertions/deletions
Code diff	Git	What actually changed in the code
Session transcript	AI agent (if active)	The full reasoning chain from your Claude Code session
Tool calls	AI agent (if active)	Which files were read, edited, and what commands were run
User prompts	AI agent (if active)	The instructions that produced the code

This raw data is sent to the MemNexus API, where it's distilled into a structured summary by an LLM.

What gets stored

The distilled memory includes:

What was done — A concise summary of the changes
Key decisions — Why this approach was chosen, alternatives considered
Debugging path — Dead ends, root cause analysis (if applicable)
Patterns used — Techniques and conventions applied
Gotchas — Mistakes, surprises, edge cases encountered

Deterministic enrichment

In addition to LLM-extracted knowledge, CommitContext creates guaranteed entities and facts from the structured git metadata:

Entities (confidence 1.0):

Type	Value
`COMMIT`	Short SHA (e.g., `a1b2c3d`)
`BRANCH`	Branch name (e.g., `feature/auth`)
`PERSON`	Author name
`FILE`	Each changed file path (up to 20)

Facts (confidence 1.0):

Relationship	Example
`a1b2c3d MODIFIED src/auth.ts`	Which files a commit touched
`a1b2c3d ON_BRANCH feature/auth`	Which branch a commit was on
`a1b2c3d AUTHORED_BY Jane`	Who made the commit
`a1b2c3d HAS_MESSAGE fix: auth timeout`	The commit message
`a1b2c3d CHANGES +42 -15`	Lines added/removed

These deterministic facts enable precise graph queries — "what files did commit X touch?" or "what commits were made on branch Y?" — without relying on LLM extraction.

Browsing commit contexts

# List recent commit contexts
mx commit-context list

# Filter by branch
mx commit-context list --branch feature/auth

# Filter by agent
mx commit-context list --agent claude-code

# Filter by time
mx commit-context list --recent 7d

# View a specific commit's context
mx commit-context show a1b2c3d

Searching commit contexts

Commit contexts are standard MemNexus memories — search them with mx memories search:

# Semantic search — find by meaning
mx memories search --query "how did we handle rate limiting?"

# Search for a specific decision
mx memories search --query "why Redis instead of Memcached?"

# Timeline view of recent commit contexts
mx memories search --query "authentication" --timeline --recent 7d

# AI-synthesized digest across multiple commits
mx memories digest --query "all auth changes this sprint" --recent 14d

Automatic context injection

CommitContext memories are automatically surfaced by build-context when you start a new agent session. This means your AI agent starts each session already knowing:

What you worked on recently
What decisions were made and why
What files were touched and by which commits
Recurring gotchas from past sessions

No manual setup required — build-context discovers commit contexts through the entity and fact graph.

# See what build-context would inject for a given task
mx memories build-context \
  --context "refactor auth middleware" \
  --files "src/middleware/auth.ts"

How it works

git commit
    │
    ▼
post-commit hook (backgrounded, non-blocking)
    │
    ├── Read git context (SHA, branch, diff, files)
    ├── Detect AI agent session (Claude Code transcript)
    ├── Privacy filter (strip API keys, tokens, secrets)
    │
    ▼
POST /api/commit-context
    │
    ├── LLM distillation → structured memory content
    ├── Embedding generation → semantic search
    ├── Entity/fact extraction → knowledge graph
    ├── Deterministic enrichment → guaranteed COMMIT/FILE/BRANCH/PERSON entities
    └── Relationship detection → links to related memories

The hook runs in the background and never blocks your commit. Even if the API is unreachable, the commit succeeds and the context is cached locally at .mx/commit-context/ for later sync.

Privacy

CommitContext applies a privacy filter before any data leaves your machine:

API keys and tokens (sk-..., ghp_..., Bearer ...) are redacted
Passwords and connection strings are stripped
PEM keys and certificates are removed
Files in .gitignore are excluded

You can review exactly what was captured:

mx commit-context show a1b2c3d --local

Offline support

If the API is unreachable when you commit:

The commit context is cached locally at .mx/commit-context/<sha>.json
When connectivity returns, sync pending contexts:

mx commit-context sync

Configuration

CommitContext is configured during mx setup. To manage it independently:

# Install the hook
mx setup hooks

# Remove the hook
mx setup hooks --remove

# Preview what would be installed (dry run)
mx setup hooks --dry-run

The hook calls mx hook post-commit under the hood. You can also run it manually:

# Dry run — see what would be captured without creating a memory
mx hook post-commit --dry-run

Troubleshooting

No commit contexts appearing:

Check the hook is installed: ls .husky/post-commit or ls .git/hooks/post-commit
Verify the hook contains mx hook post-commit
Check mx is in your PATH (the hook runs in a non-interactive shell)
Check auth: mx auth status

Commit contexts are sparse (no decisions/reasoning):

This happens for non-agent commits (manual coding). The hook captures git metadata but can't read a session transcript.
For richer context, use an AI agent (Claude Code, etc.) — the transcript provides the reasoning.

Hook slowing down commits:

The hook runs backgrounded (&) and should add zero perceived latency. If it's blocking, check that your hook file ends with mx hook post-commit 2>/dev/null & (note the &).

Next steps

Search guide — Advanced search techniques
AI Agent setup — Configure Claude Code with MemNexus
Knowledge graphs — How entities and facts power discovery