Related Pages

Related topics: Change Gate, Constitution & Policy Enforcement, Memory Graph, Storage & Data Flow, Agent Integrations, Lifecycle Hooks & Synthesis Providers

Overview, Repository Layout & System Architecture

Purpose & Scope

hunch is a repository-local memory and grounding layer for coding agents (Claude Code, Codex CLI, Cursor Agent, and other MCP-compatible assistants). It builds a derived index from the working tree — symbols, dependency edges, FTS5 full-text, embeddings — and overlays human-authored knowledge (decisions, bugs, constraints, runbooks) so that agents retrieve context with one round-trip instead of grepping the filesystem each session.

A single-binary CLI (hunch) exposes commands for graph construction, capture, query, and repair; the same engine powers an MCP server and a VS Code surface, so every agent reads and writes through one resolver (hunch shared --repo <url> route introduced in v0.40.0). Source: README.md:1-40.

The project is written in TypeScript and runs on Node.js ≥ 22.13. Since v1.0.0 the storage layer uses the built-in node:sqlite module, eliminating native build steps and Windows install friction that plagued the prior better-sqlite3 dependency. Source: package.json:60-95.

Repository Layout

The source tree follows a layered convention: an entrypoint CLI, a transport-agnostic core, storage and graph modules that the core depends on, and provider/hook adapters that vary per environment.

System Architecture

The system is a three-tier pipeline: a transport tier (CLI / MCP / VS Code) translates user or agent intent into structured calls; a core tier validates, grounds, and resolves those calls through a single pipeline; and a storage tier persists derived index and author-memorial data inside one SQLite database per repository.

flowchart LR
  A[CLI / MCP / VS Code] --> B[Command Parser]
  B --> C[pipeline.ts]
  C --> D[provider adapter]
  C --> E[graph builder]
  C --> F[storage/sqlite.ts]
  F --> G[(node:sqlite DB)]
  C --> H[hooks/lifecycle]
  H -->|post-commit| G
  H -->|pre-push| C

Every write — capture, drift edit, auto-commit (default-on since v0.40.0) — flows through the resolver in core/pipeline.ts, which normalises the topic anchor (auth.session style) before delegating to a provider adapter and finally to the SQLite layer. The hooks subsystem (src/hooks/lifecycle.ts) emits events that other adapters can subscribe to without coupling to a specific agent runtime. Source: src/core/pipeline.ts:1-80, src/hooks/lifecycle.ts:1-60.

The MCP server in src/mcp/server.ts re-exports the same operations as MCP tools (hunch_structure, hunch_capture, hunch_heal, …); the Claude Code plugin installed from v1.1.1 wraps each tool as a slash command, so behaviour stays consistent across surfaces. Source: src/mcp/server.ts:1-120.

Request Lifecycle & Data Flow

A typical hunch structure <file> request follows this path:

1. The transport parses arguments and emits a typed StructureRequest defined in src/core/types.ts.
2. core/pipeline.ts resolves the active repo (auto-detected via hunch shared resolver), checks the SQLite cache, and either serves from the derived index or rebuilds via graph/builder.ts.
3. The response is grounded against any topic-anchored decisions or hunch:topic … markers in AGENTS.md (drift surface introduced in v1.1.0). Collisions surface to the caller; doc≠graph gaps trigger a fragile flag.
4. For capture paths, the pipeline prompts the chosen provider (provider selection introduced in v1.7.0), writes a record, fires the post-commit hook, and returns a structured outcome whose committed boolean reflects the truth (v1.2.2 fixed a misleading “committed” reply on skipped commits).

Configuration precedence is lowest-to-highest: built-in defaults in core/config.ts → .hunchrc → environment variables such as HUNCH_SYNTH_PROVIDER → explicit CLI flags. Provider selection in auto-mode only fires when exactly one supported coding-assistant CLI is detected locally, preventing the silent-billing regression that v1.7.0 was published to remove. Source: src/core/config.ts:1-90, src/providers/index.ts:1-70, src/core/version.ts:1-30.

The Change Gate added in v1.5.0 sits on top of this lifecycle: any working diff or target is inspected for decisions, constraints, blast radius, and bug history before the first edit, across CLI, MCP, and VS Code uniformly.

Related Pages

Related topics: Overview, Repository Layout & System Architecture, Memory Graph, Storage & Data Flow

Change Gate, Constitution & Policy Enforcement

Overview

The Change Gate is the deterministic pre-flight check that sits in front of every mutation an agent (or user) wants to make against a hunch-managed repository. Introduced as a unified surface across the CLI, MCP, and VS Code in v1.5.0, it materializes the project's "memory that gates, not just recalls" philosophy: a working diff or target is inspected before any write, and the gate returns the decisions, constraints, blast radius, and bug history that already matter for that surface Source: src/core/strictgate.ts:1-120. The Constitution system layered on top — bootstrap, compiler, plan, proof — gives that gate a reproducible policy substrate, while conformance.ts enforces the resulting rules against the live graph.

The boundary between the three subsystems is intentional: the Change Gate is the *runtime* call site, the Constitution is the *build-time* artifact that defines what the gate is allowed to enforce, and Conformance is the *audit-time* check that proves the graph still obeys the constitution after the fact.

The Change Gate

Inputs and produced context

strictgate.ts is the single chokepoint for "I want to change X." A call supplies either a working diff or a target (file, symbol, or topic anchor such as the AGENTS.md <!-- hunch:topic … --> markers introduced in v1.1.0), and the gate returns a deterministic bundle of:

• Active decisions — the current history state of topic-anchored decisions, never the rejected branch, joined on the topic key.
• Constraints — non-negotiable rules attached to the target, including the safety backstop that v1.2.2 fixed for truthful reporting.
• Blast radius — fan-in / dependency-graph reach derived from the FTS5 + vectors index running on node:sqlite since v1.0.0.
• Bug history — prior incidents linked to the same symbols or directory, sourced from the unified capture resolver introduced in v0.40.0.

Because the gate is deterministic, two agents running the same target on the same graph get byte-identical context — which is what makes the CLI, MCP, and VS Code surfaces interchangeable without re-discovering structure via grep Source: src/core/strictgate.ts:120-260.

Surface parity

The gate is wired into three entry points without divergent code paths:

The shared hook contract from v1.6.0 — agent-agnostic lifecycle hooks — sits above this layer so any agent runtime can subscribe to pre-gate, post-gate, and pre-commit events without coupling to a specific provider Source: src/core/strictgate.ts:260-360.

The Constitution pipeline

The constitution is not hand-written policy prose; it is *compiled* from the graph and the markdown topic anchors. The pipeline is four stages, each in its own file:

1. Bootstrap — constitution/bootstrap.ts materializes the inputs: the resolved decisions, constraints, and runbooks picked by the unified resolver, plus the AGENTS.md / CLAUDE.md drift surface. Output is an immutable working set.
2. Compile — constitution/compiler.ts lowers that working set into a normative policy object: named rules, severities, and the symbols / paths each rule binds to.
3. Plan — constitution/plan.ts orders rules into an evaluation plan, deduping overlapping bindings and tagging each rule with the gate phase that should enforce it (pre-flight vs. commit-time).
4. Proof — constitution/proof.ts produces a proof artifact describing *why* the plan is consistent — for example, that no two current decisions collide on the same topic — so the gate has a citable rationale when it denies a change Source: src/constitution/bootstrap.ts:1-90 Source: src/constitution/compiler.ts:1-120 Source: src/constitution/plan.ts:1-110.

The result is that the Change Gate never interprets free-form rules at request time; it evaluates a precomputed plan against the target bundle.

Conformance and policy enforcement

core/conformance.ts is the post-hoc sibling of the gate. Where strictgate.ts answers "may this change proceed?", conformance.ts answers "did the graph stay in policy?" It replays the constitution's plan against the current graph state, reports drift between the prose surface (AGENTS.md / CLAUDE.md) and the graph spoke (the v1.1.0 doc≠graph detection), and emits a verdict the heal flow can act on Source: src/core/conformance.ts:1-150. The deterministic ordering matters here too: conformance output is stable across runs so CI can gate merges on it.

End-to-end flow

flowchart LR
  A[Working diff or target] --> B[strictgate.ts<br/>Change Gate]
  D[constitution/bootstrap.ts] --> E[constitution/compiler.ts]
  E --> F[constitution/plan.ts]
  F --> G[constitution/proof.ts]
  G --> B
  B --> H{Allow?}
  H -- yes --> I[Capture / commit<br/>v0.40.0 unified resolver]
  H -- no --> J[Deny with decisions + blast radius]
  I --> K[core/conformance.ts<br/>audit]
  K --> L[Heal if drift detected]

Practical implications

• One loop, every agent. Because the gate and the constitution behind it are agent-agnostic, swapping the synthesis provider via hunch provider claude-cli (v1.7.0) does not change what is enforceable — only who writes the explanation.
• Truthful outcomes. v1.2.2 made the gate's auto-commit path honest: skipped commits (held lock, safety backstop, empty stage) are reported as skipped, not as committed, and deferred overlay pushes surface a retry hint rather than a silent success Source: src/core/strictgate.ts:360-440.
• Drift is a first-class signal. The same topic anchors that the constitution compiles are what conformance.ts re-checks, so a prose change in AGENTS.md without a matching graph decision is caught on the next audit, not on the next incident.

Related Pages

Related topics: Change Gate, Constitution & Policy Enforcement, Agent Integrations, Lifecycle Hooks & Synthesis Providers

Memory Graph, Storage & Data Flow

The Memory Graph is the durable substrate that lets Hunch remember decisions, bugs, constraints, runbooks, and document anchors across agent sessions. It is the join key between every surface Hunch exposes (CLI, MCP, VS Code, Claude Code plugin) and the only place where grounding evidence and drift signals converge before they are surfaced back to an agent.

Storage Layer

Hunch stores its graph in a single SQLite database opened through Node's built-in node:sqlite (since v1.0.0). This replaces better-sqlite3 and removes native build steps, prebuild-install, and Windows EPERM issues during global upgrades. Source: src/store/db.ts.

The schema is owned by a dedicated module so migrations and derived tables (FTS5 virtual tables, graph edges, vector rows) can evolve without leaking into call sites. Source: src/store/schema.ts. The store facade — hunchStore.ts — is the only object most callers touch; it owns connection lifetime, transaction boundaries, and the read/write API the rest of the system uses. Source: src/store/hunchStore.ts.

Key properties of the storage layer:

• Embedded engine. No external service, no native module — the graph lives next to the repo in .hunch/.
• FTS5 + graph + vectors co-resident. Full-text search, dependency-style edges, and embedding rows share one file, so a single open + transaction yields all three. Source: src/store/schema.ts.
• One writer per process. The facade serializes writes so capture, heal, and merge never interleave partial rows.

Memory Graph Model

A "memory" in Hunch is a typed node with a stable id, a topic anchor, and grounded metadata. The four primitive node kinds are:

Source: src/store/schema.ts. The topic anchor is the join key for drift detection between the graph and prose files (AGENTS.md, CLAUDE.md); a decision anchored to auth.session can be cross-checked against any doc that claims authority over that topic. Source: src/store/hunchStore.ts.

Embeddings live alongside rows so semantic lookup does not require an external index. Source: src/store/embedder.ts. Embedding selection is provider-driven (Claude CLI, Codex CLI, Cursor agent, or deterministic fallback) and is configurable per-shell via HUNCH_SYNTH_PROVIDER or per-repo via hunch provider …. Source: src/store/embedder.ts.

Data Flow

The end-to-end loop is: capture → write → ground → query → synthesize → drift-check.

flowchart LR
  A[Agent / MCP tool] -->|capture decision/bug/constraint/runbook| B[hunchStore.write]
  B --> C[(SQLite: rows + FTS5 + vectors)]
  C --> D[read-time grounding]
  A -->|hunch_structure / hunch_why| D
  D --> E[synthesis provider]
  E --> F[grounded answer + topic citations]
  C -->|doc≠graph check| G[drift report in AGENTS.md / CLAUDE.md]

1. Capture. A hunch capture call (CLI, MCP, or skill) lands in hunchStore.write with a typed payload and a topic. Source: src/store/hunchStore.ts.
2. Persist + index. The facade writes the row, mirrors it into the FTS5 virtual table, and enqueues an embedding. Source: src/store/db.ts.
3. Compact. Periodic compaction merges redundant rows, retires superseded decisions, and prunes orphaned edges. Source: src/store/compact.ts.
4. Merge. When hunch shared --repo <url> is used, the unified resolver routes every capture to one home (public or private) and reconciles via merge.ts. Source: src/store/merge.ts.
5. Read. hunch_structure, hunch_why, and Change Gate lookups open a read transaction, ground against current vs. rejected collisions, and return topic-cited evidence. Source: src/store/hunchStore.ts.

Consistency, Commits, and Drift

Auto-commit is on by default (v0.40.0); the store reports the *real* outcome — skipped commits, held locks, and deferred overlay pushes are surfaced truthfully rather than claimed as committed (v1.2.2 fix). Source: src/store/hunchStore.ts. Read-time grounding re-checks each cited node against the current graph state so a current decision that has since been rejected is not silently cited as authoritative. Source: src/store/db.ts. Drift between graph nodes and AGENTS.md / CLAUDE.md topic blocks is the signal heal and the Change Gate act on; the spoke that owns this comparison is the schema + store pair, not the prose file. Source: src/store/schema.ts.

Related Pages

Related topics: Overview, Repository Layout & System Architecture, Change Gate, Constitution & Policy Enforcement, Memory Graph, Storage & Data Flow

Agent Integrations, Lifecycle Hooks & Synthesis Providers

Purpose and Scope

The src/integrations/ directory is the adapter layer between Hunch's grounded memory graph and the coding-agent ecosystem it serves. It does three things at once: (a) route synthesis of topic-anchored decisions to whichever local CLI subscription the user selects, (b) install agent-agnostic lifecycle hooks so any assistant — Claude Code, Cursor, Codex, VS Code — observes the same pre/post-commit gates, and (c) bridge the graph with prose files such as CLAUDE.md / AGENTS.md and a deterministic merge driver. Together these modules turn Hunch from an index into a working loop that every agent can join without bespoke wiring (Source: src/integrations/providers.ts:1-40).

Synthesis Providers & Selection

providers.ts enumerates the four synthesis backends Hunch can bill against: claude-cli, codex-cli, cursor-agent, and deterministic (an offline rule-based option). Resolution follows a strict precedence so the CLI never silently guesses a subscription:

The detection routine avoids vendor lock-in by probing each CLI's presence and version, returning a normalized enum rather than opaque string IDs (Source: src/integrations/providers.ts:100-140). scaffold.ts complements this by generating the per-repo skeleton (hunch init) and pre-creating the configuration block where the chosen provider is persisted across sessions (Source: src/integrations/scaffold.ts:1-60).

Agent-Agnostic Lifecycle Hooks

Released in v1.6.0, the hook system was deliberately decoupled from any single agent runtime. hooks.ts exposes a small contract — PreContext and PostCommit events — that wrappers translate into the native hook format of each agent (Claude Code settings.json, Cursor hooks.json, VS Code task hooks, generic shell). The single rule is: if Hunch gates a commit, every agent on the repo sees the same gate and the same auto-commit outcome (Source: src/integrations/hooks.ts:10-90).

flowchart LR
    A[Agent: edit staged] --> B[hooks.ts dispatch]
    B --> C{PreContext gate}
    C -- groundable --> D[Return topic-anchored decisions]
    C -- ungroundable --> E[Block with constraint list]
    D --> F[Agent commits]
    F --> G[PostCommit hook]
    G --> H[auto-commit truth:<br/>skipped|committed|deferred]

The hook module also reports commit outcomes truthfully: a skipped commit (held lock, empty stage, or safety backstop) is no longer claimed as committed, and a deferred overlay push returns a retry hint (Source: src/integrations/hooks.ts:92-160). This honesty is what makes the deterministic Change Gate (v1.5.0) reproducible across CLI, MCP, and VS Code entry points (Source: src/integrations/hooks.ts:160-210).

Claude Code & MCP Plugin Surface

claudeConfig.ts writes the Claude Code plugin manifest, MCP server entry, and the five skill stubs — /hunch:capture, /hunch:heal, /hunch:why, /hunch:fix, /hunch:fragile — installed via /plugin marketplace add davesheffer/hunch. The function is idempotent: re-running hunch init overwrites only the Hunch-owned keys in ~/.claude/settings.json, leaving unrelated user configuration intact (Source: src/integrations/claudeConfig.ts:1-80). It also pins the MCP tool names with the hunch_* prefix so the host's tool registry cannot collide with adjacent plugins (Source: src/integrations/claudeConfig.ts:80-140).

A second surface, hunch_structure from v1.2.0, is registered through the same MCP entry: given no target it returns a repo map (components + directories by symbol weight); given a directory it lists files with symbols and fan-in; given a file it returns an outline — eliminating the grep/glob round-trips agents usually spend rediscovering structure (Source: src/integrations/claudeConfig.ts:140-200).

Markdown Anchors & the Merge Driver

claudemd.ts is the doc↔graph bridge. It scans CLAUDE.md and AGENTS.md for <!-- hunch:topic ... --> markers and treats them as a third spoke: prose anchors that pin a paragraph to a decision row by hash. Read-time grounding resolves these anchors against the graph and flags drift when the canonical decision moves while the prose still cites the old hash (Source: src/integrations/claudemd.ts:1-90). Because teams funnel tribal knowledge into these files, anchoring them is what prevents drift in the first place (Source: src/integrations/claudemd.ts:90-160).

mergeDriver.ts registers a Git merge driver so topic-anchored blocks merge deterministically: when two branches diverge on the same <!-- hunch:topic ... --> section, the driver keeps the row whose hash matches the graph's current decision and marks the loser for rejected review — never producing a silent textual conflict (Source: src/integrations/mergeDriver.ts:1-70). Auto-commit (default since v0.40.0) routes through this driver before the commit is recorded, so the post-commit report handed back to the agent reflects the merged state, not the staged state (Source: src/integrations/mergeDriver.ts:70-130).

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/davesheffer/hunch

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/davesheffer/hunch

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/davesheffer/hunch

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/davesheffer/hunch

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/davesheffer/hunch

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/davesheffer/hunch

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/davesheffer/hunch

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using hunch with real data or production workflows.

• v1.7.0 — user-selected synthesis providers - github / github_release
• v1.6.0 — agent-agnostic lifecycle hooks - github / github_release
• Hunch v1.5.0 — Change Gate and private workflows - github / github_release
• v1.2.2 - github / github_release
• v1.2.0 — your agent greps; a grounded agent asks - github / github_release
• v1.1.1 — Claude Code plugin - github / github_release
• v1.1.0 — AGENTS.md as a drift surface - github / github_release
• v1.0.0 — zero native SQLite dependency - github / github_release
• v0.40.0 — single source of truth + auto-commit by default - github / github_release
• v0.39.0 — decision-grounding - github / github_release
• Configuration risk requires verification - GitHub / issue