Hunch – a Git-native decision graph your AI assistant obeys

Hunch — your codebase remembers why

the problem

why this section leadsEngineers trust a symptom they've felt over a feature list. The page opens with the failure mode, not the product.

Every AI session starts from zero.

The model re-reads your code, re-guesses the intent, and happily "fixes" the thing you deliberately did last month — because the reasoning lives in PRs, Slack, and people's heads, not in the repo.

Stateless by design

Typical assistant memory is ephemeral RAG over your current code. The horizon is this session — value stays flat.

Intent evaporates

The codebase records the final state, never the rejected alternative or the invariant you must never break.

The same mistakes, again

Without memory, the agent re-discovers the bug you already fixed — and undoes the workaround that prevents it.

how it works

why three numbered stepsThe pipeline really has three layers — index, learn, ground. The numbers are the architecture, not marketing rhythm.

Memory as a byproduct of normal work.

No documentation chore. The index is deterministic, learning happens on every commit, and grounding reaches your assistant through every door it has.

01 / index

Map the code, no LLM

Hunch maps how functions, files, and components connect, so it can see the ripple effect of any change. Fast, entirely on your machine.

hunch index

02 / learn

Turn events into memory

Each commit becomes a structured decision; a failing test becomes a bug with its likely cause; recurring or severe bugs are promoted into constraints — rules the AI must respect.

post-commit → synthesis

03 / ground

Feed it back, with citations

Your assistant reads it through an MCP server, an auto-maintained CLAUDE.md, and slash commands — every answer cites its source, confidence, and evidence.

MCP + CLAUDE.md + hooks

the reasoning graph

A bug spawns a decision. A decision spawns a constraint.

The links are what let an agent answer "why" and "what must not break" with evidence — every node attached to its components, symbols, and commits.

bug_009 · critical

Leaked token usable after reset

A stateless JWT couldn't be revoked server-side. Caught by auth.revocation.spec.ts, root cause attributed.

→

dec_017 · accepted

Store sessions in Redis, not JWT-only

Sessions move server-side; the JWT carries only an opaque id. Alternatives rejected, consequences recorded, commit a1b2c3d as evidence.

→

con_004 · blocking

Revocation must be server-side

Never trust JWT expiry alone for logout. Scoped to src/auth/** — checked before any edit in that scope.

what's inside

why four groups, not a top-20 listTwenty numbered cards hide the architecture. The groups are the product's real jobs: remember, guard, retrieve, share.

Everything is local, diffable, and yours.

Twenty-one capabilities, four jobs. Unfold what you care about.

memory / — what the graph holds

Records with provenance, safe writes, and a time axis — memory you can audit.

Provenance on everythingsource, confidence, evidence — on every record+

Every record shows where it came from and how much to trust it. Auto-captured guesses stay advisory; only what you've confirmed is trusted enough to block.

Git is the syncplain files beside your code, merge-clean+

The graph lives in your repo and travels with it — reviewable in PRs, synced by push/pull. Teammates' edits merge cleanly, no conflict markers.

Atomic & durableinterrupted writes can't truncate the index+

An interrupted write can never corrupt the graph, and damaged state refuses to overwrite good data. Boring on purpose.

Time-travel memoryquery the graph as of any commit+

Ask what the team believed as of any commit or tag. History is closed, never deleted — superseded decisions stay auditable forever.

Private memoryopen-source the code, not the reasoning+

Open-source the code without open-sourcing the reasoning. Sensitive decisions live in a separate private repo you control — your local queries see them, public outputs never can.

Decision-groundingdoc≠graph drift, caught deterministically+

Docs drift; the graph doesn't. Your assistant is told which decision is current — including what was rejected — before it edits, and prose still describing a superseded decision is caught. CI can gate on it.

Component wiki & specs ledgerstale docs adopted & healed — never rewritten+

A wiki rendered from the graph, and every repo doc graded: grounded, stale, or unverified. Stale docs get a wiki-managed copy healed to the current decision — your original is never touched, and the copy retires once you heal it. Staleness is drift-gated, not scheduled.

guards / — what it stops

Deterministic checks over the graph. Advisory by default; blocking only on what you've confirmed.

Regression Guardstop re-adding what a decision retired+

Re-adding what a past decision deliberately removed gets flagged before it lands — the AI stops silently undoing intentional design.

Veto — Decision Guardstop re-introducing what you rejected+

Re-introducing an approach you rejected — even one that never existed in code — is caught with a receipt: what you rejected, what you chose instead, and why.

Redundancy Guard"this already exists, three modules over"+

The agent writes a helper that already exists three modules over; Hunch points at the original. Tuned quiet — a refactor that just moves code isn't mistaken for a duplicate.

CI Constraint Guardmemory that can hold a merge — when you ask it to+

Every PR gets a comment naming the invariants and decisions it touches — and the check fails when a confirmed blocking rule is actually broken.

Causal Merge VerdictBLOCK / WARN / PASS, with the why+

One verdict per diff — BLOCK / WARN / PASS — with each rule cited back to the decision behind it and the bug it prevents reopening. Catches what a diff-only reviewer can't.

Intent-conformancedoes pay still reach verifySession?+

Beyond "did the diff touch a guarded file": does the code still honor the recorded design — layering, must-reach, dependency direction? Drift is flagged even when nothing in scope changed.

Never Twicecorrect the agent once, it holds forever+

Correct the agent once — "no, never call X here" — and it becomes an enforced rule every assistant is held to, in every future session.

retrieval / — how the why comes back

Grounding that reaches the agent at reasoning time, with citations.

MCP-native, two-wayquery the why; write decisions back+

Assistants ask why a file is shaped the way it is, what breaks if it changes, and whether a bug has happened before — and record new decisions back as you work.

Structure without grepthe repo map, served from the graph+

Agents burn search rounds rediscovering structure the graph already holds. One call returns the repo map, a directory’s contents, a file’s outline, or a symbol’s definition site with its callers — so the agent knows exactly which file to read, first try.

Graph-augmented retrieval+41.7pt recall@10 over plain search+

Answers pull in the cross-file evidence plain search misses — measured +41.7pt recall@10 on a cross-file benchmark, no embeddings required.

Runbook memorythe proven steps for recurring tasks+

The how beside the why: proven procedures for recurring tasks, distilled from real work and returned on demand — so an agent reuses the procedure instead of re-deriving it.

Fragility reportthe riskiest code, with its bug history+

The riskiest code in your repo, ranked — with the real bug history behind each entry, not a generic lecture.

Deep Synthesisseveral takes, reconciled, fact-checked+

Several independent readings of a change, reconciled into one note that's trusted only where they agree. Always advisory.

team / — sharing and judging

One source of truth across branches, worktrees, teammates, and agents.

Works offline, $0 SaaSsubscription-billed synthesis, heuristic fallback+

No SaaS, no API key. Learning bills to the coding subscription you already pay for — and without one, a deterministic fallback keeps the loop alive.

Shared team memoryone store; fresh clones auto-connect+

One memory across branches, worktrees, teammates, and agents — and a fresh clone connects itself to the team's store on init.

Multi-candidate verdictrank 5 agent solutions in 10 minutes+

Five agent-generated solutions to one task? Ranked by architectural fit in one command — the best-behaved candidate wins.

why it's different

why no vendor namesThe contrast is stateless vs compounding — a property of the category, not a vendor war. Hunch's recorded positioning decision: compare on verifiable properties; name vendors only as clients it serves.

A stateless assistant reads the blueprints fresh each morning. Hunch has been on-site for ten years.

Typical agent memoryHunch

Core data modelEphemeral RAG over current codeCurated graph of decisions, bugs, constraints

Time horizonThis sessionThe lifetime of the codebase

What it indexesSyntax + embeddings of filesWhy — intent, causality, invariants

Write pathNone — read-only over codeFirst-class — it learns at commit & test time

Value over timeFlat — re-derived each timeCompounds — a flywheel

Failure it removes"AI can't see enough code""AI repeats past mistakes / breaks design"

get started

One npm install — wired into every assistant.

Install it

Node 22.13+. npm install -g @davesheffer/hunch puts a global hunch on your PATH. That's the whole install — no build step, no native compiles, no SaaS.

Initialize — wires every assistant

One hunch init indexes the repo, installs the hooks + merge driver, and writes MCP config + rules for Claude Code, Cursor, VS Code, Windsurf, Codex & Antigravity — all pointing at the same .hunch/ graph.

Seed the memory

hunch backfill --since 90d replays recent history, so an empty graph isn't your day-one experience.

Just ask

In any of those editors: "why is the session module built this way?" — answered from memory, with the commit as evidence.

Claude CodeCursorVS CodeWindsurfCodexAntigravityAGENTS.md

~/your-repo

install from npm — Node 22.13+

$ npm install -g @davesheffer/hunch

index + hooks + wire up every assistant

$ cd your-repo && hunch init

cold start: seed decisions from history

$ hunch backfill --since 90d

the "why" behind any file or symbol

$ hunch why src/auth/session.ts

npm i -g @davesheffer/hunch && hunch init

Claude Code? Install as a plugin instead:

/plugin marketplace add davesheffer/hunch → /plugin install hunch@hunch

Make your codebase remember why.

The longer it runs, the smarter it gets — and the more expensive it is to go back to a stateless AI.

Get started Read the docs

why the headline is set in monoThe product is a CLI. The headline is set in its own material — the terminal — at a light weight, so it reads calm, not loud.

this page is grounded — 5 decisions annotate why it looks the way it does. hover any dec_site_*.