Hunch documentation

Install#

Hunch needs Node ≥ 22.13. Install the CLI globally — that puts a hunch binary on your PATH:

npm install -g @davesheffer/hunch

If the shell reports that hunch is not found, no global binary is required. From the repository directory, run npx -y @davesheffer/hunch@latest init.

Or run from source (for hacking on Hunch itself):

git clone https://github.com/davesheffer/hunch && cd hunch
npm install
npm run build        # compile to dist/
npm link             # optional: global `hunch` from source

The optional Hunch editor companion is available from Open VSX. It reads the same memory home as the CLI and MCP server; its version is separate from the CLI version.

Initialize a repo#

Run hunch init in the repo you want a memory for. One command scaffolds everything:

hunch init               # scaffold .hunch/, index, install hooks, wire up assistants
hunch backfill --since 90d # cold start: seed decisions from recent git history

hunch init does the following, idempotently (re-running is safe and merges into existing files):

• Scaffolds .hunch/ and indexes the repo into a symbol/dependency graph.
• Installs a post-commit hook (the learning loop) and a pre-commit Constraint Guard.
• Writes .mcp.json + slash commands + an auto-maintained CLAUDE.md, and registers a git merge driver for the graph.
• Wires up every detected assistant — Claude Code, Cursor, VS Code (Copilot), Windsurf, Codex, Antigravity — to the same .hunch/ graph.

Update Hunch#

Ask an agent to “update Hunch”, or run hunch update from the repository root. If the shell reports that hunch is not found, run npx -y @davesheffer/hunch@latest update instead. It installs the latest release and aligns all configured harness pins while preserving existing settings.

For standalone npm projects, the command keeps Hunch in its current dependency section and saves an exact version. Without a repository dependency it updates the global CLI. Add --global to update both, or --dry-run to preview the commands. Other package managers and workspaces should update their dependency explicitly, then run hunch integrations repair-pins.

The update also repairs known legacy hook commands while preserving unrelated settings and intentionally disabled hooks. Restart or reconnect active assistant sessions afterward. In Codex, open /hooks to review and trust changed commands, then start a new session. Changing the pinned version changes the command and requires renewed trust; Hunch does not approve it for you. Each invocation updates the current repository; repeat it in other repositories as needed.

Installed interactive CLI commands may show a cached update notice. At most once every 24 hours, a detached worker asks npm for the package's public latest version. Hooks, MCP, CI, servers, the updater, non-interactive commands, and source checkouts skip that request. Set HUNCH_NO_UPDATE_CHECK=1 or NO_UPDATE_NOTIFIER=1 to disable it.

hunch integrations check --harness codex --probe --require mcp
hunch integrations check --harness codex --require context

The first command checks a fresh MCP process. Run the second after trusted hooks have run in a new Codex session: it checks recorded host delivery on the expected Hunch version. Configuration, delivery, and the agent's use of memory are different evidence. Requiring edit-blocking additionally needs strict firmness and a delivered pre-edit event.

Your first query#

Ask the codebase why — from the CLI, or in your assistant once the MCP server is registered:

hunch why src/auth/session.ts   # decisions / bugs / invariants behind a file
hunch doctor                    # git, schema version, synthesis mode

…and in your assistant: “why is the session module built this way?” — the assistant consults Hunch and answers with citations (record ids + provenance).

Synthesis & billing#

Optional synthesis drafts memory from commits and failures. Agent-initiated work stays with that agent's provider and its CLI authentication; an unavailable or unknown origin uses the deterministic local fallback. Human terminal invocations can use an explicitly selected provider. Installing a CLI alone does not select it. See agent origin and provider routing.

A terminal provider preference lives in gitignored local config. It does not override a known initiating agent with another provider. hunch provider shows availability and why a provider was selected:

hunch provider codex-cli               # local: Claude / Codex / Cursor / openai-compat / deterministic
hunch provider                         # see availability + why this provider is selected
export HUNCH_SYNTH_PROVIDER=claude-cli # one-shell override; `auto` disables the local choice

Local & self-hosted models. No subscription CLI is required: point Hunch at an OpenAI-compatible endpoint — Ollama, vLLM, LM Studio, llama.cpp server, and anything else that speaks the chat-completions format. Select it like any other provider (hunch provider openai-compat, or the one-shell override):

export HUNCH_SYNTH_PROVIDER=openai-compat   # alias: ollama
export HUNCH_SYNTH_BASE_URL=http://localhost:11434/v1
export HUNCH_SYNTH_MODEL=llama3.1
export HUNCH_SYNTH_API_KEY=...                  # optional — omit for keyless local servers
export HUNCH_SYNTH_TIMEOUT_MS=300000             # optional, default 5 min — local models can be slow
export HUNCH_SYNTH_MAX_TOKENS=2048               # optional output cap
export HUNCH_SYNTH_ALLOW_METERED=1                # public remotes only; deliberate billing/trust opt-in

Opt-in only: leave these unset and Hunch behaves exactly as above. Localhost, private/link-local IPs, and conventional LAN names work directly. Every public remote requires HUNCH_SYNTH_ALLOW_METERED=1 so a newly launched paid provider can never bypass a stale hostname list; set it only when the endpoint is deliberately trusted and any billing is understood.

Deep Synthesis. --deep takes repeated samples through the bound provider and reconciles them. --verify checks the draft against the commit. These are model-assisted drafting steps, not independent proof; the result stays advisory. They do not fan out to another installed provider.

hunch backfill --deep        # higher-quality notes across history
hunch sync <sha> --deep       # a single commit (fact-check on)
hunch sync <sha> --verify     # fact-check a single note

MCP & assistants#

The Hunch MCP server lets supported clients query the same memory. hunch init writes MCP configuration and guidance for supported assistants. Automatic context delivery and edit blocking depend on the host's lifecycle hooks, settings and trust; an MCP connection alone proves neither.

The server runs over stdio and exposes memory tools under hunch_*. State tools under nuryel_* are exposed when enabled for the configuration or state root, not by default in every plain repository. Use hunch mcp --root <partition-dir> for a served partition. Other MCP clients can register a launcher manually; starting it is not a connectivity test:

hunch mcp   # serves Hunch over stdio (this is what .mcp.json launches)

Reload your assistant#

After hunch init or an update, a running assistant may still hold the old MCP process. Reload or reconnect your assistant in the repo so it loads the current tools. Codex hooks also require command trust: review changed commands with /hooks, then start a new session.

Private memory v0.17#

Keep sensitive decisions, bugs and constraints in a separate private overlay. Authorized local queries and checks can include that overlay; public-only outputs use the public store. Choose the destination when capturing private information and control access to the overlay through your local and Git permissions.

One command sets it up (no env var, no shell-profile edit):

hunch private                       # default ./.hunch-private (gitignored)
hunch private ~/work/secret-memory   # or a path you choose
hunch private --repo git@github.com:you/mem-private.git   # or clone a private repo

It writes a gitignored .hunch/local.json pointing at the store, installs the --private post-commit hook, and that’s it — Hunch, the MCP server, and the local VS Code extension auto-detect it; hunch doctor shows private: on → …. It’s opt-in and default-off: no local.json (and no HUNCH_PRIVATE_DIR) means the overlay is completely inert.

Record sensitive items with private: true on hunch_record_decision / hunch_record_correction; they’re written to the overlay, never the committed repo. Post-commit synthesis routes its auto-captured decisions there too, so a private-memory repo’s auto-decisions never land in the public tree. HUNCH_PRIVATE_DIR overrides local.json per-shell (e.g. for portability); the git hook lives in .git/hooks/ and is never committed.

Auto-commit is on by default. Captures attempt to commit to their actual memory home. A private/shared Git store can also be pushed; public memory in an application repository rides your next code-branch push. Managed grounding documents can be refreshed alongside memory. Failed or disabled synchronization can leave a record local, so inspect the saved durability result. Opt out with --no-auto-commit on hunch init, private or shared.

Windows note#

On Windows, a global claude mcp add writes to ~/.claude.json keyed by the raw working-directory string. Drive letters are case-insensitive (c:\ and C:\ are the same folder) but Claude Code compares the key case-sensitively — so it can create two project blocks for one directory, and a session that resolves to the other casing sees no hunch_* tools.

If you hit this, run hunch doctor — on Windows it detects the split and heals it (merging the MCP servers across both casings, after backing up ~/.claude.json). hunch init runs the same heal automatically.

Shared state for agents#

Suppose one agent records a customer commitment and another agent ships the fix. Hunch can link the commitment, engineering decision and action receipt so either agent can check what is still open and what evidence supports completion. Agents continue to own their source tools and permissions.

Deterministic state means defined rules check record identity, repeated writes, access, conflicting current decisions and changes to supporting evidence. Hunch preserves the difference between an observation and a verified action record. It does not independently verify a CRM or email action merely because an agent records it.

hunch serve provides HTTP access to repository, user, team and organization partitions. Each token identifies a principal and its allowed partitions. To try one locally:

hunch serve init --config ./hunch-serve.json --partition user:demo --root ./demo-state --principal assistant@demo
hunch serve --config ./hunch-serve.json

Initialization prints the agent token once; keep it private. The server listens on 127.0.0.1. Use a Git repository for the partition when you need committed history; write results distinguish local, committed and pushed records. Read and write through HTTP, MCP, hunch state, or the typed TypeScript and repository-built Python clients. The Python package is not yet published to PyPI.

Open /operator on your server to inspect current records, completed work, commitments and writer-supplied field citations. The browser view is read-only. Optional per-record audiences limit which authorized principals can read or write a record. Optional key-bound credentials add proof from the configured private key on each request. Explicit user, team and organization conventions stay advisory.

Before enabling record visibility or key-bound authentication, upgrade and restart every serving process. Protected partitions refuse older state readers. Read the 1.33 upgrade guide, state CLI reference and Python client guide.

Engineering memory and this service ship today. Broader organizational results remain a pilot, with emulated runs and limited live use reported separately. Hunch is not a managed CRM, mail or chat connector service.

Read the product direction, state contract and setup reference, and dated pilot status.

Memory and Project DNA#

Memory records what matters: a decision and its reason, a rejected approach, a rule, a fixed bug or an open finding. Project DNA describes observed conventions: the repository's terminology, contribution habits and review expectations. It helps an agent fit the project without turning common habits into mandatory rules.

hunch why src/auth/session.ts
hunch dna inspect
hunch dna context

The code graph connects symbols and dependencies. Engineering Landscape records connect systems, services, owners and operational resources. hunch prove origin/main --public-only can bind an exact committed change to these records and its checks. A proof describes the evidence and gaps; it does not authorize a merge or deployment.

Read the Project DNA contract and change-proof guide.

See Hunch's contribution#

A task completion card and local report show what memory reached the agent, what the agent says it used, and which checks actually ran. A remembered lesson, an agent's attribution and a passing test are separate evidence; none alone proves that Hunch caused a better outcome.

hunch report
hunch report <task-id> --html

The agent reuses a task ID supplied by a trusted prompt hook, or starts one through hunch_task. It carries that ID through context and captures, runs relevant checks through the returned verification launcher, then finishes the task. Missing instrumentation stays unverified.

The HTML report is a saved local file and may contain private memory. Read task reports for evidence grades, privacy controls and the agent workflow.

The reasoning graph#

These core engineering records explain a project; the code graph connects them to files and symbols. Action records, commitments and other state extend the same store:

Durable memory is kept in readable files. Code and search indexes are derived data that Hunch can rebuild from the repository and its records.

Provenance & confidence#

Records carry provenance and confidence so you can distinguish an agent's observation from human-confirmed intent. A source label does not independently prove the statement. Captured memory starts as advisory context; blocking needs human authority and a supported enforcement path. hunch escalations surfaces conflicts and decisions that still need human review.

Time-travel#

Decisions and constraints carry a git-anchored valid-time window. Supersession closes a window instead of deleting the record, so history stays auditable. Ask the graph what was believed at any past commit or tag:

hunch why src/auth/session.ts --as-of v0.7.0
hunch timeline src/auth/session.ts   # the full decision history, newest first

The hunch_why and hunch_context MCP tools take the same optional as_of ref.

Decision-grounding#

Architectural Conformance keeps the code honest to the graph; decision-grounding keeps your docs honest to it. A decision can be anchored to a topic (e.g. auth.session), and a topic always has one live answer — the current decision, its history, and what was rejected along the way.

Capture with /capture. It interviews the decision to a resolved state — topic, rationale, rejected alternatives — before anything is written, and the graph refuses to hold two live decisions on one topic. A git merge is the one thing that can create two; hunch reconcile-topics catches it for human resolution.

Markdown topic anchors — AGENTS.md as a drift surface

Anchor a section of AGENTS.md, CLAUDE.md, or any repo markdown to a topic with an HTML comment:

<!-- hunch:topic auth.session -->                 # grounds only
<!-- hunch:topic auth.session dec_a1b2c3d4e5 -->  # pinned: prose written against that decision

• Grounding: whenever an assistant edits the file, the pre-edit hook injects each declared topic's current decision and what it rejected — follow the graph, not the stale prose being edited.
• Drift: a pinned marker whose decision has been superseded fires doc-anchor-stale; a pin to a missing decision fires doc-anchor-dangling. Only an explicit pin can fire — never a semantic guess. Unpinned markers ground but never drift.
• Heal: hunch heal lists each drifted section with the decision to reconcile toward, then you update the pin. Read-only — it never rewrites your prose.

hunch drift             # ⛔ exits non-zero on any anchor-stale drift or topic collision — wire into CI
hunch heal              # what to reconcile, and toward which decision
hunch reconcile-topics  # >1 live decision on a topic (post-merge) — exits non-zero

The component wiki & specs ledger#

hunch wiki renders a component wiki from the graph — one page per component (why it's shaped this way, invariants, structure, bug history, relations) plus a specs ledger that grades every markdown doc in your repo deterministically: ✅ grounded (anchored to current decisions — safe to trust), ⚠ stale (pinned to a superseded decision, says "proposed" about shipped code, or references only deleted files), ◻ unverified (no anchors — Hunch can't vouch either way). No LLM in any grade.

Stale docs get adopted. The wiki copies a stale doc into wiki/docs/ as a wiki-managed page healed against the graph — every stale pin re-pinned to the current decision with a 🧭 correction inline quoting what changed and what was rejected. Your original file is never touched; heal it (or delete it) and the copy retires automatically. The ledger routes readers to the trustworthy version either way.

Freshness is drift, not a cron job. Each page's graph inputs are content-hashed into a manifest; when the graph moves, hunch drift names exactly which pages went stale and hunch wiki --heal regenerates only those. Hand-editing a generated page trips the same wire (the graph is the source of truth — edit records, not pages).

hunch wiki            # generate/refresh wiki/ + the specs ledger
hunch wiki --check    # CI gate: non-zero if any page is stale (green no-op if never adopted)
hunch wiki --heal     # regenerate ONLY the stale pages; retire orphans
hunch wiki --private  # render the FULL graph (private overlay included) into the OVERLAY repo

With a private overlay, the public wiki is built from the committed store only — a private record can never reach a committed page, by construction. --private writes the full-graph wiki into the overlay repo instead; nothing lands here.

MCP tools#

The tools your assistant calls under the hood. Read tools answer “why / what-must-not-break / blast radius”; write tools persist new memory.

Slash commands#

For Claude Code, hunch init also writes ergonomic slash commands:

Firmness levels#

hunch init installs supported lifecycle hooks and guidance for the assistant. Where the host loads and trusts those hooks, they can deliver relevant memory before work. Firmness controls how Hunch responds; use integration checks to see which capabilities were actually observed in your host.

hunch firmness          # print the current level
hunch firmness strict   # change it (takes effect on the next edit; no restart)

The memory loop — it runs itself#

Captured memory becomes available as advisory context without routine manual triage. Genuine conflicts and authority decisions can still need review. Blocking power requires human confirmation. Configured hooks and synchronization handle much of the loop; task reports show what was observed:

hunch log              # the memory timeline: capture · adopt · supersede · prune · repair
hunch log --diff <sha>  # what one move changed
hunch revert-move <sha> # undo one move (local git revert, never pushed)
hunch escalations       # the decisions only YOU can make — normally empty
hunch repair --apply    # heal bindings after a rename (sync does this automatically)
hunch push              # the one deliberate outward step

In VS Code, the Hunch Memory panel is the same spine as a source-control view: the timeline with click-to-diff and one-click local revert, a ⚖ Needs your decision group that exists only while something real needs you, and a 🏛 Constitution group where activate / demote / withdraw / retire are each one audited click.

Never Twice v0.13#

The most expensive failure in AI coding is being corrected and then re-corrected: you say “no, never call X here”, the agent complies once, and next session it does it again — because the feedback was stored as advisory text, not enforced. Hunch closes that loop.

The agent can save your correction as a scoped Constraint through hunch_record_correction. A capture without a verified human interview token remains agent-reported testimony, capped at warning severity. Human confirmation can give a supported rule blocking authority; strict firmness and a working host hook or CI guard are also required.

You:   "no — never import lodash, we ship our own utils"
Agent: hunch_record_correction({ rule: "never import lodash; use src/utils",
                                 scope_hint_file: "src/cart.ts", severity: "blocking" })
→ con_… recorded as advisory testimony without a capture token.
  Confirm the rule through the supported human review flow before relying on a deny.

The UserPromptSubmit hook nudges the agent to persist a rule whenever your prompt reads like a correction. Scoping is conservative by default (the file you were in); a repo-wide rule is only blocking when you pass applies_to_all, so one correction can’t silently gate the whole tree.

Causal Merge Verdict v0.14#

A diff-only reviewer sees what changed. It can’t see that the line you’re deleting is the fix for an incident, that the symbol you’re re-adding was deliberately retired, or that the helper you’re adding already exists three modules over. Hunch can — because it holds the why and the whole graph.

hunch_merge_verdict (and hunch check / the CI guard) replays a diff against the graph and returns one cited verdict — BLOCK / WARN / PASS — that shows the reasoning, not just the rule:

VERDICT: ⛔ BLOCK — this change breaks a recorded invariant or re-opens a known bug.

⛔ pay() must verify the session before charging — con_pay
   🧠 why: "Charge must verify the session first" (dec_pay)
   🐞 guards against: Double-charge on unverified session — pay() charged without verifying (bug_…)

No model in the loop, so it’s safe as a merge gate: it blocks only on a high-confidence rule you’ve confirmed, and warns on everything softer. Call it with {} to check staged changes, or pass base: "origin/main" for a PR range.

Decision Guard (Veto) v0.15#

Decisions record not just what you chose but the alternatives you rejected. The Decision Guard flags a change that reverses a decision — re-introducing an approach an in-force decision rejected — so the agent can’t quietly walk back a deliberate call.

hunch veto              # flag changes that reverse a rejected alternative

Like the other gates: it warns by default and blocks under strict only on a rejected approach you’ve explicitly vouched for — the one-click activation in the VS Code Hunch Memory panel, or hunch review --accept <id> in the terminal. Blocking power is never granted automatically.

Regression Guard#

Re-adding a symbol or dependency that an in-force decision deliberately retired gets flagged — warns always, fails a strict commit only when the retirement is tied to a blocking invariant. The agent stops undoing intentional design. The pre-edit hook also surfaces what a decision retired from a file (“don’t re-add login here — dec_017 removed it”), and the commit-time hunch check does the actual gating.

Redundancy Guard v0.16#

Coding agents work from a local context window, so they re-implement a helper that already lives three modules over, or re-add a dependency the codebase already has — sprawl a diff-only reviewer can’t see. Hunch holds the whole symbol graph, so a diff that adds a function or class already defined elsewhere is flagged with its existing location.

Possibly re-implements 1 symbol(s) that already exist (advisory — review, never blocks):

  ⟲ adds function `formatDate` — already defined in src/util/date.ts

It’s advisory — it never blocks a commit; it surfaces in hunch check, the CI guard, and the merge verdict. It’s tuned to stay quiet, so a refactor that just moves code around isn’t mistaken for a duplicate.

CI Constraint Guard#

Memory that can hold a merge — when you've asked it to. hunch ci scaffolds a GitHub Action that runs hunch check on every PR and comments the affected invariants and decisions (with con_/dec_ ids and the causal why). The check fails only on a direct, high-confidence, non-stale blocking invariant — a rule you confirmed yourself.

hunch ci    # scaffold .github/workflows/ + the PR comment action

hunch check --staged --strict      # gate staged changes
hunch check --base origin/main      # gate a PR range (used in CI)

CLI reference#

Run hunch <command> --help for full flags. The everyday commands:

Common workflows#

Copy-paste sequences for the everyday tasks. Run hunch <command> --help for every flag.

Set up a new repo

hunch init                          # scaffold, index, install hooks, wire up assistants
hunch backfill --since 90d          # seed decisions from recent history (no empty day-1)
# …reload your assistant, then ask: "why is X built this way?"

Join a repo that already uses Hunch

git pull                            # the .hunch/ graph travels with the code
hunch init                          # wire YOUR assistants to the shared graph (idempotent)
# …reload your assistant — the team's memory is now in context

Ask why a file is the way it is

hunch why src/auth/session.ts                  # decisions, bugs & rules behind it
hunch timeline src/auth/session.ts             # how the thinking changed over time
hunch why src/auth/session.ts --as-of v1.2.0   # what was believed at a past release

Turn a correction into an enforced rule

Tell your assistant the rule (it records it for you), or do it from the CLI — then confirm it so it actually blocks. Name the actual violation with --forbid-dep (or --forbid-symbol): the rule then blocks the real change across the file's whole life and stays quiet on edits that don't break it, where a scope-only rule relaxes to advisory once the file is edited again.

hunch record-constraint "never import lodash; use src/utils" \
      --scope "src/**" --severity blocking --forbid-dep "lodash"
hunch review --accept <id>            # confirm → now held against every assistant

--forbid-dep matches the parsed import (a comment or string naming the module can't trip it; a submodule like lodash/groupBy is caught). A correction your assistant records is given the same matcher automatically. --match <regex> remains as a lint-grade textual fallback. None of these are bypass-proof — deliberate indirection can still route around any rule.

Curate the draft queue

hunch review                        # segmented: ready-to-confirm vs needs-scrutiny
hunch review --accept-verified      # batch-accept the well-grounded ones
hunch compact                       # prune rejected / superseded / stale low-value drafts

Check a change before you merge

hunch check --staged --strict       # does this break a do-not-break rule?
hunch veto --staged                 # does it reverse a rejected decision?
hunch conform --strict              # does the code still honor recorded intent?
# …or check a whole PR range instead of staged files:
hunch check --base origin/main

Add the CI merge gate

hunch ci                            # scaffold the GitHub Action (runs on every PR)
git add .github && git commit -m "ci: add Hunch constraint guard"

Capture a higher-quality note for an important commit

hunch sync <sha> --deep             # reconcile several drafts + fact-check the note
hunch review                        # then confirm it

Make an existing public repo's memory private

hunch private --repo git@github.com:you/mem-private.git --migrate
# moves existing memory into the private store, makes this repo code-only,
# and prints the one git command to commit the now-clean public repo

Work across branches & worktrees

hunch worktree ../feature-x -b feature-x   # new worktree, already sharing memory
hunch doctor                        # confirms "worktree: linked — sharing the repo's memory"

It's not working

hunch doctor                        # git, synthesis provider, index freshness, drift
hunch index                         # rebuild the code map from current source
hunch migrate                       # after an upgrade, bring records to the latest schema

Where it’s stored#

The source of truth is plain, readable JSON in a Git repository you control: under .hunch/ in the code repo by default, or in a dedicated private memory repo in Matrix mode. The code repo then carries only the credential-free .hunch/team.json; local paths and the derived SQLite search index stay ignored and can be rebuilt at any time.

Doctor & troubleshooting#

hunch doctor is the first stop for anything that looks off — it reports git status, the resolved synthesis provider, schema version, index freshness, and record counts (and on Windows, heals the ~/.claude.json casing split).

hunch doctor

Working as a team — the Matrix v1.9#

Matrix mode gives a project one living engineering-memory spine across teammates, branches, worktrees, agents, and operating systems. The source of truth is a separate private Git repository you control; You provide the Git hosting; the committed pointer contains no credentials.

Create that repository first, grant the team normal Git access, and have one maintainer connect it:

npm i -g @davesheffer/hunch
hunch shared --repo git@github.com: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 HTTPS or SSH URL and leave authentication in SSH or the Git credential helper. Add --migrate only when moving existing public .hunch/ records into the dedicated store.

After the pointer commit lands, each teammate installs the same Hunch version, pulls, and runs hunch init. Hunch validates .hunch/team.json, creates an ignored .hunch-private/ clone, and merges the local path and preferences into ignored .hunch/local.json. An unparseable local config is never overwritten.

Always pumping. CLI operations attempt a bounded pull at startup; long-lived MCP servers refresh at tool-request boundaries. Captures commit and synchronize the memory-only repository by default, concurrent JSON records merge by identity, and a failed push stays local for hunch shared --sync to retry.

Authority stays fail-closed. Captures become advisory memory immediately. Blocking policy authority still requires an explicit audited human action, and public receipts should use --public-only so the shared graph never appears on a public surface.

Pause or roll back without deleting memory

hunch firmness off
hunch shared --repo git@github.com:acme/project-hunch-memory.git --no-auto-commit
# Keep the installed version; inspect the problem before choosing a rollback.

This preserves every shared and local memory record while disabling enforcement and automatic publication. Revert the .hunch/team.json setup commit only if new clones must stop discovering the Matrix; do not delete the memory repo or local overlay. Keep every client on the same supported Hunch version before resuming shared policy workflows, then run hunch shared --sync.

Maintenance#

Two housekeeping commands keep the graph healthy over time:

hunch compact   # prune rejected/superseded/stale low-value drafts
hunch stale     # list records whose files changed after they were last verified

Routine captures are available as advisory memory, and hunch escalations asks you inline about the few things the graph can't settle itself. Migrating an older repo? One hunch adopt-drafts clears a legacy queue, and hunch log shows every memory move — each one revertable.

Release integrity#

Hunch tests release artifacts before publication credentials are available. The immutable npm tarball and VSIX are then passed to isolated publishers, which verify the public registries converged on the expected version. npm publishes with GitHub Actions provenance; one tested VSIX goes unchanged to Open VSX and is downloaded again for byte verification.

npm view @davesheffer/hunch version dist.integrity dist.attestations --json
git tag --list 'v*' 'vscode-v*'

Inspect GitHub Actions, npm, and Open VSX for the public receipts.

Develop & contribute#

Hunch is open source under Apache-2.0. Contributions are welcome — see CONTRIBUTING.md and the repo to get started.