Agent sessions are ephemeral. The decisions, the debugging dead ends, the three approaches you weighed before choosing this one, the non-obvious library gotcha you discovered at the end — all of it lives in the context window and disappears the moment the session closes. Git preserves what changed, but nothing about why. A commit message can capture some of that reasoning, but no one — human or agent — can faithfully reconstruct the full trail of decisions behind a change. There's simply too much context, and the most valuable parts are the ones you don't think to mention.

CommitContext makes that missing context durable. On every git commit, it reads your agent session and git metadata, distills the full decision-making process into a structured memory, enriches your commit message with the reasoning, and stores it in your git history as well as your MemNexus memories — where your agent can find it, traverse it, and reason about it in future sessions.

The result isn't just a better commit message. It's a smarter agent.

What a Commit Message Can't Tell You

A user reports intermittent 401 errors after last week's deploy. You ask your agent:

"Users are getting 401 errors since last Thursday's deploy. Search the recent commit context and determine if a recent change might be causing this."

Without CommitContext, your agent reads the commit log, finds a1b2c3d — fix: auth timeout in middleware from last Wednesday, and reads the diff — token expiry validation was added and some logic was centralized in jwt.ts.

That's useful, but it's surface-level. The agent can tell you what changed. It can't tell you why expiry checking was centralized instead of fixed inline, what the original root cause investigation looked like, or what gotchas were discovered about the library's behavior. The diff is the final answer — it doesn't show the work.

With CommitContext, your agent finds the structured reasoning behind that commit:

## CommitContext: fix: auth timeout in middleware (a1b2c3d)

### What changed
Added token expiry validation to the auth middleware. JWT tokens were
being accepted past their exp claim because the middleware only verified
signature, not expiry. Centralized expiry checking in jwt.ts.

### Key decisions
Chose to centralize expiry logic in jwt.ts rather than inline in the
middleware — three other middlewares validate tokens and would have needed
the same fix. Single source of truth.

### Debugging path
Initially suspected a clock skew issue between services (checked NTP sync
on both pods — fine). Then noticed the middleware was calling verify() with
ignoreExpiration defaulting to true in the options object. Root cause: a
merge from last sprint silently changed the default options.

### Gotchas
jsonwebtoken's verify() accepts a second argument that can be either a
string (secret) or an options object. When passing options, ignoreExpiration
defaults to false — but only when the key is explicitly present. Omitting
the key is not the same as setting it to false.

Now the agent connects the dots — and it doesn't stop at the commit message. It traverses the MemNexus knowledge graph, following entities and facts linked to this commit: the files that were touched, the branch it was on, the author who made it, the topics extracted from the session. It finds related memories — a gotcha about jsonwebtoken options handling from a different project, a past decision about middleware architecture from two sprints ago, a pattern established in PR #147 that explains why expiry logic was centralized. Each connection builds a more complete picture than any single commit message could hold.

From there, it reasons. It knows the fix was centralized because three other middlewares share the same token validation path — and it can check whether all three were updated. It knows the original bug was introduced by a merge that changed default options without flagging it — so it checks for similar merges since the fix. It finds the ignoreExpiration gotcha in the graph and scans for other call sites using the same pattern.

The agent reports back: "This commit centralized expiry checking for three middlewares, but api-gateway/middleware.ts calls jwt.verify() directly and wasn't part of the change. It's using the same options pattern that caused the original bug. This is likely your 401 source."

You didn't search for anything. You didn't know which commit was relevant. The agent traversed the graph, found a connection between the fix and an unrelated file, and identified the gap — because it had the reasoning behind the original change, not just the diff.

Enriched Commit Messages

CommitContext doesn't just store reasoning externally — it writes it back into your git history.

After distilling your agent session, CommitContext enriches the commit message itself with the structured context. Your original message is preserved, and the distilled reasoning — decisions, related changes, gotchas — is appended directly to the commit. The result is visible everywhere developers already look: GitHub PRs, git log, blame views, IDE hover.

Consider our auth example. Without CommitContext, the commit message is whatever the developer or their agent wrote in the moment:

fix: add token expiry validation to auth middleware

With CommitContext, the message is enriched after the session is distilled:

fix: add token expiry validation to auth middleware

Centralized expiry checking in jwt.ts — three other middlewares
(api-gateway, webhook-validator, admin-auth) share the same token
validation path per the pattern established in PR #147. Root cause
was a silent default change from last sprint's merge (see commit
context for b3c4d5e). Note: jsonwebtoken's ignoreExpiration behaves
differently when the key is omitted vs. set to false.

The enriched message references a past PR, a related commit, and a library gotcha — context drawn from MemNexus that the developer might have forgotten and a conventional agent never had access to. A reviewer reading this PR on GitHub gets the full picture without leaving the page.

But the enriched commit message is only the surface. The same structured reasoning is stored in MemNexus, connected to entities and facts in the knowledge graph. When your agent starts a new session, MemNexus's build-context automatically queries the graph for relevant commit contexts — matching on the files you're touching, the topics you're working on, and the entities connected to your task — and delivers them as part of your agent's briefing before you write a single prompt. The commit message makes the context visible to humans. The graph makes it usable by agents.

This is the flywheel: every session's reasoning is captured, which makes the next session's agent smarter, which leads to better decisions — fewer repeated mistakes, fewer rediscovered gotchas, fewer hours spent re-deriving context that already existed. The knowledge compounds, and the output is better software.

Why Diffs Aren't Enough

A git diff is the final state of a change — the answer with no work shown. For an agent investigating an issue, that means it can see the outcome but can't reason about how or why the code arrived there.

CommitContext gives your agent the full picture:

Who made the change and when
What was tried first, including approaches that were ruled out
Why this specific approach was chosen over alternatives
What else is connected — which other files share the same pattern, which decisions were made in relation to other work
What to watch out for — the gotchas and edge cases discovered during the session

An agent with this context doesn't just read history — it reasons about it. It connects a fix in one file to an unfixed instance of the same pattern in another. It recognizes that a debugging dead end from three weeks ago is the same theory a new session is about to waste time on. It surfaces a design decision from a past sprint that explains why the current code looks the way it does.

What Gets Captured

CommitContext hooks into git commit at the post-commit stage. The hook runs in the background and never blocks your commit — it fires and exits while git continues normally.

On each commit, it collects two things.

Git context: SHA, branch, author, commit message, the list of changed files, insertions, deletions, and the actual diff. Fully structured, deterministic data.

Agent session: If you're working with Claude Code, CommitContext reads your session transcript — the full reasoning chain: your prompts, the agent's analysis, the tool calls it made, the errors it hit, and how it worked through them. The whole session goes to the server, not a summary or truncated excerpt.

All of it passes through a privacy filter before leaving your machine. API keys, tokens, PEM keys, passwords, and connection strings are stripped by pattern matching before the data touches the network.

The server distills the session into a structured memory, then queries the knowledge graph for related memories — past decisions on the same files, gotchas from similar work, patterns established in previous commits. All of this is synthesized into a structured digest that captures not just what happened in this session, but how it connects to everything that came before. The digest is stored in MemNexus and written back into the commit message — so the reasoning is visible in your git history and searchable in the knowledge graph.

From Session to Structured Knowledge

A Claude Code session transcript can run to hundreds of thousands of characters. Raw transcripts capture every tool call, every incremental response, every iteration. That's valuable signal, but it's not searchable, and it's not the right unit for an agent to reason about.

CommitContext distills the session into structured content a few kilobytes in size. The server-side pipeline reads your full transcript — no truncation, and for very large sessions it uses map-reduce, processing the transcript in parallel chunks before the final distillation call. The output is a five-section memory:

What changed — a concise description of the actual code changes
Key decisions — why this approach was chosen, alternatives considered
Debugging path — the route from problem to solution, including dead ends
Patterns used — design conventions and techniques applied
Gotchas — non-obvious edge cases and pitfalls encountered

Everything important from the session survives — structured for an agent to parse, connect, and reason about.

Deterministic Enrichment at Confidence 1.0

In addition to the LLM-distilled content, CommitContext creates a second layer of enrichment from the structured git metadata — and this one is guaranteed.

Every commit context gets entities and facts created at confidence 1.0, derived from data that doesn't need interpretation:

Entities:

COMMIT — the short SHA
BRANCH — the branch name
PERSON — the commit author
FILE — each changed file path (up to 20)

Facts:

a1b2c3d MODIFIED src/middleware/auth.ts
a1b2c3d ON_BRANCH feature/auth-refactor
a1b2c3d AUTHORED_BY Jane
a1b2c3d HAS_MESSAGE fix: auth timeout in middleware
a1b2c3d CHANGES +42 -15

These live in the knowledge graph and give your agent precise traversal paths. It doesn't have to grep through commit messages hoping for a keyword match — it queries the graph directly: what commits touched this file, what branches contained this commit, what other files changed alongside this one, who made the change.

The Feedback Loop

CommitContext and build-context form a closed loop that makes your agent smarter over time.

You work with your agent, make progress, commit. CommitContext captures the reasoning. When you start a new session, build-context queries the knowledge graph, finds relevant commit contexts through entity and fact connections, and delivers them as part of your agent's briefing. Your agent starts the new session with the decisions and gotchas from past sessions already loaded.

The jsonwebtoken gotcha from the auth fix? When you start a session that touches jwt.ts or any token validation code, build-context surfaces it automatically. Your agent doesn't try the clock skew theory. It doesn't rediscover the ignoreExpiration trap. It starts where you left off.

# What build-context surfaces for a new session
mx memories build-context \
  --context "refactor auth middleware" \
  --files "src/middleware/auth.ts"

The loop compounds. A month of commits becomes a month of structured institutional knowledge. Your agent doesn't just have access to your codebase — it has access to the reasoning behind every change in it.

Searching What You've Built

Commit contexts are standard MemNexus memories. Everything that works for manually created memories works here — semantic search, timeline reconstruction, digest synthesis.

# Why did we handle rate limiting this way?
mx memories search --query "why did we choose Redis for rate limiting?" --timeline

# What happened on auth this sprint?
mx memories digest --query "all auth changes" --recent 14d

# What did commit a1b2c3d do?
mx commit-context show a1b2c3d

# Recent commits on a branch
mx commit-context list --branch feature/auth-refactor

Privacy by Default

The privacy filter runs client-side, before any data leaves your machine. It strips:

API keys and tokens matching known patterns (sk-..., ghp_..., Bearer headers)
Passwords and secrets from key-value patterns
PEM keys and certificate headers
Connection strings with embedded credentials

The server applies an additional filter before LLM calls as a second layer. If you want to review exactly what was captured:

mx commit-context show a1b2c3d --local

The --local flag reads from the on-disk cache at .mx/commit-context/ — the same data that was sent to the server, after client-side filtering, before the API received it.

Offline Support

If the API is unreachable when you commit — you're on a plane, your internet cuts out, the server has a hiccup — the commit context is cached locally. Your commit succeeds. Nothing is lost.

When connectivity returns:

mx commit-context sync

All pending contexts upload. The feedback loop catches up.

Setup Is One Command

CommitContext is included in mx setup. If you've already run setup, you can add the hook separately:

# From your project directory
mx setup hooks

The installer detects your hook manager. If you use Husky, it appends to your existing .husky/post-commit file rather than replacing it. Lefthook, pre-commit, and simple-git-hooks get instructions for adding the single line manually. If you're not using a hook manager, it installs directly using a backup-and-chain approach — your existing post-commit hook (if any) is preserved and called after CommitContext runs.

From that point, every commit is captured automatically. No flags, no commands to remember, no additional workflow.

A Different Approach to Commit History

There are tools that store raw agent transcripts alongside commits — typically on a git shadow branch, which bloats your repository with megabytes of JSONL per commit. The transcript is all there, but it's not structured, not searchable by meaning, and not connected to anything that would help an agent reason about it. It's raw data, not knowledge.

CommitContext doesn't store the transcript — it distills it. The output is a structured knowledge record: a few kilobytes of meaning extracted from megabytes of raw session data, stored in a database where it's connected to the entities and facts that make it traversable.

The reasoning lives in your commit history where humans can read it and in a knowledge graph where agents can traverse it.

Get Started

CommitContext is live now in CLI v1.7.75+. Full documentation at /docs/guides/cli/commit-context.

# Update to the latest CLI
mx update

# Run from your project directory — installs CommitContext hook + agent config
mx setup

# Make a commit and verify it was captured
git commit --allow-empty -m "test: verify commit context"
mx commit-context list

Every commit from that point forward builds your agent's knowledge of your codebase — not just what changed, but why, what else was tried, and what to watch out for next time.

CommitContext is available now in CLI v1.7.75+. Update with mx update or npm install -g @memnexus-ai/cli@latest. Docs: /docs/guides/cli/commit-context.

Every Commit Tells You What Changed. Now Your Agent Knows Why.