Hunch

Your repo remembers why.

For the precise rules your team explicitly trusts and proves, Hunch gives a concrete guarantee:
your agents do not re-make a decided decision or re-introduce a fixed bug without a deterministic
violation being surfaced. The mechanism is an engineering-memory and architectural-conformance
layer — the decisions, constraints, rejected approaches, and bug history behind your code, delivered
as evidence before an assistant changes anything, with the result checked deterministically after.

Memory starts advisory. Nothing blocks until you explicitly trust a precise rule and choose
strict enforcement.

Memory is the input. The product boundary is the receipt: relevant evidence before an edit,
then a deterministic check of the change against the rules your team has explicitly trusted.

Release candidate v1.19.0-rc.1: correction search now keeps the flat top five but adds
transfer-tested semantic declaration families and an efficiency-tested progressive queue.
Evidence receipts are read-only annotations: they never reorder candidates or claim an exact
owner. Install the candidate explicitly with npm i -g @davesheffer/[email protected].

New in v1.18.0: YAML and Helm now enter the same dependency graph as application code.
Anchors and aliases become reference edges; chart-scoped define, include, and template
relationships survive pre-render syntax without weakening fail-closed handling for ordinary
invalid YAML.

Read the v1.18 release story
for the graph semantics, chart boundaries, honest limits, and Oliver Sampson's contribution.

See the public roadmap for what is next and what is deliberately out of scope.

Start in five minutes

Requires Node 22.13+ and a git repository.

npm i -g @davesheffer/hunch
cd your-repo
hunch init
hunch backfill --since 90d   # optional: seed memory from recent history

Reload your coding assistant, then ask:

Why is this built this way?

hunch init indexes the repo, installs the local memory hooks, and connects supported assistants
to the same graph. It merges into existing configuration instead of replacing it.

What Hunch gives you

• Durable context — decisions and corrections survive the chat session that produced them.
• One memory for every assistant — Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex,
  and any MCP client see the same evidence.
• Change receipts — review a working tree, commit, or branch against recorded intent and get a
  cited PASS / WARN / BLOCK result.
• Bug lineage — understand which old incident a line fixed before accidentally undoing it.
• Code awareness — TypeScript, JavaScript, Python, Go, YAML, and chart-scoped Helm templates
  feed dependency, blast-radius, and redundancy checks. The reasoning layer works with any language.
• ADR interop — hunch import-adr populates the graph from an existing MADR/Nygard corpus;
  hunch export-adr projects it back as standard MADR any ADR reader understands, and the
  projection then tracks the graph automatically and reports its own drift.

The source of truth is readable JSON in .hunch/. A local SQLite index makes retrieval fast but
is always rebuildable.

Day-to-day

Most memory work happens automatically after commits. These commands cover the common manual paths:

hunch evidence-map accepts a bounded JSON receipt containing a red target, a distinct green
control, optional execution counts, and optional intervention outcomes. It reports target-only and
shared execution plus behavior-sensitive files. It does not run the probes, edit the repository, or
claim that behaviorally influential code owns the correction. Use --json for the machine-readable
map; MCP clients can submit the same receipt through hunch_evidence_map.

hunch shortlist --evidence attaches authenticated observations to the relevant candidates but does
not reorder them. Three fresh transfer experiments failed to prove that execution or intervention
influence identifies the correction owner, so the production path converts that result into a hard
safeguard: no candidate is promoted or displaced by evidence. JSON output still includes a
deterministic receipt and the explicit exact_owner_enabled: false policy.

Every shortlist also preserves its flat top five and adds a deterministic hierarchical inspection
view anchored to those files: at most five files, two semantic declaration families per file, and
three declarations per family. On a preregistered 12-case fresh transfer, the preserved union found
6/12 changed declarations versus 3/12 for the flat top five (+25 percentage points, three
rescues), while correct-file coverage improved from 8/12 to 10/12. The view averaged 18.8 unique
declarations and never exceeded 24. This promotes the clusters as a supplemental diagnostic, not as
a top-five accuracy claim; exact-owner output and per-case confidence remain disabled. JSON output
includes the deterministic cluster receipt and the transfer calibration.

The default output also turns those clusters into a progressive inspection queue. It preserves the
flat shortlist, adds only the strongest members of already-selected semantic families, stops at ten
when the behavior is explained, and permits one final fallback declaration before reporting
uncertainty. Development replay retained all 21/36 combined hits from the full cluster view while
reducing the hard inspection ceiling to 11 from an average of 19.8 declarations (44% less). On a
separate preregistered 12-case ArkType transfer it retained all 5 full-cluster hits with zero losses
and reduced mean inspection from 18.9 declarations to 11 (41.9% less). It found no additional fresh
hit, so the queue is retained as an efficiency advisory rather than promoted as an accuracy gain.

Follow-up optimization attempts stay out of production. Replacing cluster slots with same-file
declarations produced four development rescues but also three losses. Appending two same-file slots
removed those development losses, but a second blind 12-case ArkType transfer produced 3/12 hits for
both the existing and expanded plans, with zero rescues. Product-source filtering lost one prior hit,
one-hop relationship expansion added none, and evidence/causal rerankers also failed their frozen
transfer gates. The receipts remain in bench/external/results; rejected mechanisms cannot silently
change the production ordering.

Corrections can become scoped rules, but captured memory cannot hard-block on its own. Enforcement is
deterministic and opt-in:

hunch firmness strict
hunch check --staged --strict

Share one living team memory

Matrix mode keeps the team's decisions, corrections, constraints, and proofs in one dedicated Git
repository, separate from the code repository. Hunch does not host that repository: create a private
Git repo that every teammate can access, install the Matrix release on team machines and CI, then
have one maintainer run:

npm i -g @davesheffer/[email protected]
hunch shared --repo [email protected]:acme/project-hunch-memory.git
git add .gitignore .hunch/team.json
git commit -m "chore: connect shared Hunch memory"
git push

Use a credential-free URL in the command; keep tokens in your Git credential helper or use SSH.
If this project already publishes memory in .hunch/ and you want to move it into the dedicated
repo, add --migrate, review the reported untrack/ignore changes, and follow the commit instructions
printed by Hunch. Omit --migrate for a new setup.

After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:

npm i -g @davesheffer/[email protected]
git pull
hunch init
hunch doctor

hunch init validates and connects an ignored local clone of the memory repo. Memory-reading and
writing CLI operations attempt a bounded refresh at startup; connected MCP sessions check for new
team memory at each tool-request boundary and rebuild their local index only when the JSON changed.
New captures route to that repo and are committed and synchronized automatically by default. If a
push cannot complete, a later capture or hunch shared --sync retries it.

The committed .hunch/team.json contains only the credential-free memory-repo locator and canonical
branch. The ignored .hunch/local.json contains local paths and preferences, not credentials;
authentication stays in SSH or the normal Git credential helper. Shared memory records,
.hunch/local.json, and .hunch-private/ stay out of code history. Use
hunch check --base origin/main --strict --public-only --format markdown for output that may be
posted publicly; omit --public-only for an internal check that should enforce team memory.
HUNCH_PRIVATE_DIR remains an explicit process-level override for CI and portability. When it
redirects a repo away from .hunch/local.json or bypasses an advertised team store, CLI and MCP
startup warn on stderr and hunch doctor labels the effective source.

For a correction that Hunch can express as a deterministic policy, create and inspect its
proof-backed proposal:

hunch policy upgrade-correction con_...
hunch policy card pol_...

The upgrade creates evidence, a plan, and a proof but leaves the policy proposed with
authority: none. A proved policy still requires explicit, audited human acceptance before it can
become advisory or blocking; Hunch never grants that authority automatically.

Need to pause or roll back without deleting memory?

hunch firmness off
hunch shared --repo [email protected]:acme/project-hunch-memory.git --no-auto-commit
# Later, publish any pending local memory explicitly:
hunch shared --sync

The first command turns off agent-hook enforcement; the second keeps shared reads and local captures
but stops automatic memory commits and pushes. As a team-coordinated rollback, revert the setup
commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
rollback. For this rollout, reinstall the previous published package with
npm i -g @davesheffer/[email protected]; the release receipt resolves and records the verified rollback
target from the npm registry instead of trusting Git tags. Pause enforcement first as shown above,
and keep every team client on the same release before resuming Matrix policy workflows.

Synthesis without surprise billing

Hunch can draft structured memory through:

• a selected Claude Code, Codex, or Cursor subscription CLI;
• an opt-in OpenAI-compatible local endpoint such as Ollama, vLLM, LM Studio, or llama.cpp; or
• the built-in deterministic fallback when no model is available.

When several subscription CLIs are installed, Hunch does not guess which plan to use:

hunch provider codex-cli

Local and private-network endpoints work without a billing flag. Every public remote requires the
explicit HUNCH_SYNTH_ALLOW_METERED=1 opt-in, because Hunch cannot infer cost from a hostname.
See Synthesis & billing for setup details.

Local-first and portable

Hunch has no hosted memory service or telemetry. Your graph travels with git and speaks MCP, so it
is not tied to one editor or model provider.

Sensitive reasoning can live in a separate private overlay:

hunch private --repo [email protected]:you/project-memory.git

Local tools see the combined graph; public CI and committed documentation stay public-only.

Releases you can trace to source

Hunch releases are built and tested without publication credentials. The resulting npm tarball or
VSIX is content-addressed, carried unchanged into a minimal publisher, and checked again against the
registry after publication. The npm path also runs native, atomic-write, and Matrix safety checks on
Windows and macOS and verifies provenance back to the exact source tag.

The editor companion is published from an exact vscode-v* tag to
Open VSX. The workflow verifies the
downloaded public VSIX has the same digest as the credential-free release candidate.

Learn more

• Full documentation
• Copy-paste cookbook
• VS Code extension guide
• Contributing
• Architecture benchmark
• Engineering Landscape Graph and ORC boundary
• ORC outcome/experience protocol
• Competitive landscape (dated; re-verify before quoting)

Apache-2.0