Hunch

Hunch

A shared record for AI agents: what was decided, what happened, and what still needs doing.

[npm version] [GitHub stars] [license]

[Watch: Hunch Memory in 2 minutes]

▶ Watch Hunch Memory in 2 minutes, then the 7-episode series on setup, hooks, memory capture, delivery, rules, drift and teams.

[Hunch refuses a staged change that imports lodash, citing the blocking rule it breaks]

A new agent session should not mean explaining the project all over again. A second agent should be able to check a recorded decision, see the evidence behind completed work, and find an outstanding commitment.

Hunch keeps that record in Git and makes the relevant parts available to your agents. It started with engineering memory: why code exists, which approach failed before, and which rules a change must preserve. It also ships a state server for sharing decisions, action records, and commitments across authorized organization, team, user, and repository scopes.

The goal is simple: agents working from the same maintained record, with sources they can inspect. Hunch supplies memory and checks; the assistant still does the work.

Start with your coding assistant

Requires Node 22.13+ and a Git repository.

npm i -g @davesheffer/hunchcd your-repohunch inithunch backfill --since 90d   # optional: draft memory from recent history

If the shell reports that hunch is not found, initialize without a global binary from the repository directory: npx -y @davesheffer/hunch@latest init.

Reload your assistant, then ask:

Why is this built this way, and what should I preserve when changing it?

hunch init indexes the code, configures supported assistant integrations, and adds memory instructions while preserving existing settings. For Codex hooks, review and trust the commands in /hooks, then start a new session. Memory is advisory by default. Blocking requires an explicitly trusted rule and strict enforcement.

Hunch works with Claude Code, Codex, Cursor, VS Code/Copilot, Windsurf, Antigravity, and other MCP clients. Automatic context and hook coverage vary by assistant; a connected MCP server alone does not prove they are running. Check your integration.

What you get today

For example, a team fixes a logout bug by keeping sessions on the server. Months later, an agent proposes removing that code. Hunch can surface the original reason and rejected alternative before the edit. A supported, trusted rule can flag the conflict; strict mode can block it. Recording the lesson and configuring the integration are what make this possible.

Day-to-day

For enforcement after reviewing and trusting the relevant rules:

hunch firmness stricthunch check --staged --strict

Generated notes, observed habits, and imported documents do not silently gain blocking authority.

Update without losing your settings

From each repository that uses Hunch:

hunch update

If the shell reports that hunch is not found, run npx -y @davesheffer/hunch@latest update from the repository instead.

Or ask your agent to “update Hunch.” The command installs the latest release, aligns configured integration pins, repairs known legacy launch commands, and refreshes Hunch instructions. It preserves unrelated settings and intentionally disabled hooks.

Installed interactive CLI commands can also 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.

• A standalone npm project keeps Hunch in its existing dependency section at an exact version. Without a repository dependency, the global CLI is updated. Add --global to update both.
• For other package managers or workspaces, update the dependency with that package manager, then run hunch integrations repair-pins.
• Restart or reconnect active assistants. In Codex, open /hooks to review and trust changed commands, then start a new session. A changed version pin changes the command and requires renewed trust.

Verify the setup:

hunch integrations checkhunch integrations check --harness codex --probe --require mcphunch integrations check --harness codex --require context

The first command checks configuration. The probe starts a fresh MCP process and reads memory. The context check requires observed hook delivery on the expected version, so run it after the new assistant session begins. --require fails when the named capability is not verified; none of these checks proves that a model followed the advice.

Remove Hunch from a repository

hunch uninstall --dry-run   # show what would changehunch uninstall             # remove what Hunch installed; keep .hunch/ (your memory)hunch uninstall --purge     # also delete .hunch/, the derived cache and Hunch's .gitignore blocks

It removes the instruction blocks, MCP entries, agent and git hooks, merge driver, slash commands and CI workflow that Hunch installed, and leaves your own content in those files alone. If a file it needs to edit can't be parsed, it changes nothing and says which file. It writes .hunch-removed: while that file exists, no Hunch command sets Hunch up here again. Commit it so every clone stays opted out; to reinstall, delete it and run hunch init. Close running hunch mcp / hunch serve processes first, so they can't recreate files.

See what Hunch contributed

Task reports answer: what memory reached this task, what did the agent say it used, and what checks actually ran?

The normal agent instructions request a completion card with a link to a local evidence report. You can also inspect reports directly:

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

A delivered lesson, an agent's claim, and a passing test are different evidence. Hunch keeps them separate. Automatic presentation depends on the host following the task lifecycle; missing evidence stays unverified.

Share one living repository memory with your team

One maintainer connects a dedicated private Git repository:

hunch shared --repo [email protected]:acme/project-hunch-memory.gitgit add .gitignore .hunch/team.jsongit commit -m "chore: connect shared Hunch memory"git push

Teammates install Hunch, pull the code, and run hunch shared --trust once per machine: it shows the store URL from .hunch/team.json and connects only after that explicit consent. Then run hunch init. Until a machine trusts the store, Hunch refuses to clone it or route memory there. Normal Git access controls the shared repository. Credentials, local clone paths, and private overlays stay out of the committed pointer. Use hunch shared --sync to retry synchronization; add --no-auto-commit when captures should wait for explicit sync.

This shares a project's engineering memory. The state server below adds authenticated access across multiple scopes.

Deterministic organizational state

A coding agent needs to know why a module exists. An operations agent may need to know whether a customer action was completed or who owes the next follow-up. Both need a maintained record they can check.

Hunch ships hunch serve: a self-hosted HTTP service for organization, team, user, and repository records. A configured identity determines which scopes an agent may access. Optional record audiences further restrict access; optional key-bound credentials require proof from the configured private key on each request.

Open /operator on your server to inspect current records, completed work and commitments in a read-only browser view. Writer-supplied citations can point to an exact summary field or text passage and its recorded sources. They show traceability; they do not prove that a source supports a claim.

Agents can use the same contract through MCP, hunch state read|write|records|subscribe, the @davesheffer/hunch/state TypeScript client, or the Python client. The Python package is built and tested from this repository; it is not yet published to PyPI. Scoped conventions let a person record sourced user, team or organization preferences. Those preferences remain advisory and do not silently become blocking rules.

Records can describe decisions, action outcomes, commitments, entities, relationships, and summaries that name their dependencies. Actions retain their status, including unknown or unverified outcomes. Repeated writes have stable identities, conflicting current decisions are refused, and confirmed human records receive protections against agent overwrites. These are defined checks on structured records; Hunch cannot establish every fact in the outside world on its own.

This is what deterministic state means here: explicit rules govern the stored record, rather than having each agent reconstruct it from scratch. Git holds the durable data; SQLite is a rebuildable index. The server binds to loopback and requires deployment and agent integration by its operator. Hunch does not provide a managed CRM or email connector service.

See the full documentation.

The vision, and what is still being tested

The vision is continuity across people, tools, and agents: an operations agent records a customer issue, a coding agent finds the relevant decision and fixes the cause, and the operations agent closes the commitment using evidence of the fix.

The underlying memory and state tools ship today. The broader claim—that different agents reliably use that shared state and avoid contradictory work—is still being measured.

Hunch remains the product name. The nuryel.state/1 protocol and nuryel_* tool names are existing technical identifiers; a possible future rename is undecided.

Project DNA: help the agent understand how the project works

Project DNA describes observed repository conventions: terminology, contribution habits, review expectations, and engineering patterns. Engineering memory records decisions and their reasons. Both can inform a task, but frequent behavior does not become policy.

hunch dna inspecthunch dna contexthunch dna diff <older-ref> <newer-ref>

Profiles retain their revision, sources, confidence, and freshness.

Your data and your authority

• Repository use is local-first and needs no hosted Hunch account. Shared memory uses Git access; the optional state server uses configured identities and grants.
• hunch private --repo <url> keeps sensitive project reasoning in a private overlay. Public exports and CI should use public-only views.
• Drafting can use a selected coding-assistant subscription, a local endpoint, or the deterministic fallback. Public metered endpoints require explicit opt-in. Synthesis and billing.
• Agents keep responsibility for external actions and connector permissions. A stored record does not authorize an email, deployment, or CRM change.
• npm and editor releases use separate publication gates with package integrity and provenance checks.

Learn more

• Full documentation
• Copy-paste cookbook
• Changelog
• VS Code extension
• Contributing

FSL-1.1-ALv2 (Functional Source License). Use it, modify it, and run it for your own work, internal or commercial; you can't make it available to others in a commercial product or service that competes with Hunch or with services built on it (see Permitted Purpose in LICENSE). Each release converts to Apache-2.0 two years after it ships. Releases before this change keep the license they shipped with.