hunch

Hunch

为 AI Agent 共享的记录：做出了什么决定、发生了什么，以及还有哪些事待办。

开启一个新的 Agent 会话，不该意味着要把整个项目从头解释一遍。第二个 Agent 应该能够查看已记录的决定，了解已完成工作的依据，并找到尚未履行的承诺。

Hunch 将这些记录保存在 Git 中，并向你的 Agent 提供相关内容。它最初专注于工程记忆：代码为何存在、哪些方案曾经失败，以及更改必须遵守哪些规则。它还提供一个状态服务，用于在经过授权的组织、团队、用户和仓库范围内共享决定、行动记录和承诺。

目标很简单：让 Agent 基于同一份持续维护的记录开展工作，并能查看记录来源。Hunch 提供记忆和检查；实际工作仍由助手完成。

▶ 观看 2 分钟了解 Hunch Memory，然后观看介绍设置、钩子、记忆捕获、交付、规则、偏移和团队的7 集系列视频。

从你的编码助手开始

需要 Node 22.13+ 和一个 Git 仓库。

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

如果 shell 提示找不到 hunch，请在仓库目录中不使用全局二进制文件来初始化：npx -y @davesheffer/hunch@latest init。

重新加载你的助手，然后提问：

为什么要这样构建？更改时应该保留什么？

hunch init 会为代码编制索引、配置受支持的助手集成，并添加记忆说明，同时保留现有设置。对于 Codex 钩子，请检查并信任 /hooks 中的命令，然后开始一个新会话。**记忆默认仅供参考。**只有明确受信任的规则和严格执行机制才能阻止操作。

Hunch 适用于 Claude Code、Codex、Cursor、VS Code/Copilot、Windsurf、Antigravity 及其他 MCP 客户端。自动上下文和钩子的覆盖情况因助手而异；仅连接 MCP 服务并不能证明它们正在运行。检查你的集成。

如今你能获得什么

需求	Hunch 如何提供帮助
不再反复解释过去的决策	保存决策、被否决的替代方案、错误历史、修正内容和未解决的发现，并注明来源。
做出更改前先了解情况	将记忆与代码符号及依赖关系关联起来；展示受影响的代码和记录在案的架构意图。
让 Agent 在不同会话间掌握信息	通过 MCP 和受支持的生命周期钩子，为任务提供重点简报。
检查团队选定的规则	在阻塞流程中不经过大模型，评估受支持的约束和代码关系。
查看任务期间发生了什么	在贡献报告中分别呈现已交付的记忆、Agent 报告的使用情况、规则结果和观测到的命令结果。
与队友共享项目记忆	将仓库记忆保存在 Git 中，并可选择使用专用的私有记忆仓库。
在多个 Agent 间共享工作状态	通过 HTTP、MCP、状态 CLI，以及具备类型定义的 TypeScript 和 Python 客户端，提供经过授权的记录。
检查 Agent 了解的内容	只读浏览器视图会展示当前记录、承诺、已完成工作和撰写者提供的引文。
明确访问权限和约定	可选的逐条记录受众、绑定密钥的凭据和注明来源的约定，使用相同的状态契约。

例如，团队修复一个登出错误时，让会话保留在服务器上。几个月后，某个 Agent 提议移除这段代码。Hunch 可以在编辑前呈现最初的原因和被否决的替代方案。受支持且可信的规则可以标记冲突；严格模式可以阻止更改。记录经验并配置集成，才能实现这一点。

日常使用

命令	用途
hunch context "<task>" --profile builder	开始前获取重点简报
hunch why <file-or-symbol>	了解代码背后的决策和过往错误
hunch structure [target]	检查已索引的文件和符号
hunch findings [scope]	查看仍待处理的已知问题
hunch impact origin/main	查看分支可能影响的内容
hunch check --working	根据已记录的规则检查当前更改
hunch conform	检查受支持的架构关系
hunch now	阅读近期决策和已记录的路线图
hunch doctor	诊断设置和存储问题

审核并信任相关规则后，可启用强制执行：

hunch firmness strict
hunch check --staged --strict

生成的笔记、观测到的习惯和导入的文档不会在未提示的情况下获得阻止权限。

更新而不丢失设置

对于每个使用 Hunch 的代码库：

hunch update

如果 shell 提示找不到 hunch，请改为在代码库中运行 npx -y @davesheffer/hunch@latest update。

或者让你的 Agent “更新 Hunch。” 该命令会安装最新版本、同步已配置集成的版本固定项、修复已知的旧版启动命令，并刷新 Hunch 指令。它会保留无关设置和有意禁用的钩子。

已安装的交互式 CLI 命令也可能显示缓存的更新通知。每 24 小时最多一次，后台分离运行的工作进程会向 npm 查询软件包公开的 latest 版本；钩子、MCP、CI、服务、更新程序、非交互式命令和源码检出会跳过此请求。设置 HUNCH_NO_UPDATE_CHECK=1 或 NO_UPDATE_NOTIFIER=1 可禁用此功能。

• 独立的 npm 项目会在现有依赖项部分中以精确版本保留 Hunch。若代码库没有声明依赖项，则更新全局 CLI。添加 --global 可同时更新两者。
• 对于其他软件包管理器或工作区，请使用相应的软件包管理器更新依赖项，然后运行 hunch integrations repair-pins。
• 重启或重新连接正在使用的助手。在 Codex 中，打开 /hooks 查看并信任已更改的命令，然后启动新会话。版本固定项变更会导致命令改变，因此需要重新信任。

验证设置：

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

第一个命令会检查配置。探测程序会启动一个全新的 MCP 进程并读取记忆。上下文检查要求观察到预期版本上的钩子交付，因此请在新的助手会话开始后运行。若指定的功能未经验证，--require 会失败；这些检查都不能证明模型遵循了建议。

从代码库中移除 Hunch

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

此命令会移除 Hunch 安装的指令块、MCP 条目、Agent 和 git 钩子、合并驱动、斜杠命令及 CI 工作流，并保留这些文件中的自有内容。如果需要编辑的文件无法解析，它不会进行任何更改，并会指出相应文件。它会写入 .hunch-removed：只要该文件存在，任何 Hunch 命令都不会在此处重新设置 Hunch。请提交该文件，以便所有克隆版本都保持退出状态；要重新安装，请删除该文件并运行 hunch init。请先关闭正在运行的 hunch mcp / hunch serve 进程，以免它们重新创建文件。

查看 Hunch 提供的内容

任务报告会回答：哪些记忆传递到了此任务，Agent 声称使用了什么，以及实际运行了哪些检查？

常规 Agent 指令会要求生成一张完成卡片，其中包含本地证据报告的链接。你也可以直接查看报告：

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

已交付的经验、Agent 的说法和通过的测试是不同的证据。Hunch 会将它们分开保存。自动展示取决于宿主是否遵循任务生命周期；缺失的证据仍会标记为未经验证。

与团队共享一份持续更新的代码库记忆

由一位维护者连接一个专用的私有 Git 代码库：

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

团队成员安装 Hunch、拉取代码，并在每台机器上运行一次 hunch shared --trust：该命令会显示 .hunch/team.json 中的存储库 URL，并且只有在明确同意后才会建立连接。然后运行 hunch init。在机器信任该存储库之前，Hunch 不会克隆它，也不会将记忆路由到那里。共享代码库的访问权限由常规 Git 访问控制管理。凭据、本地克隆路径和私有覆盖内容不会包含在已提交的指针文件中。使用 hunch shared --sync 重试同步；如果捕获的内容应等待手动同步，请添加 --no-auto-commit。

这会共享项目的工程记忆。下方的状态服务器则可通过身份验证，在多个作用域之间提供访问。

确定性组织状态

编码 Agent 需要知道某个模块为何存在。运营 Agent 可能需要了解客户操作是否已完成，或下一步跟进应由谁负责。两者都需要一份经过维护、可供查阅的记录。

Hunch 提供 hunch serve：一个用于组织、团队、用户和仓库记录的可自托管 HTTP 服务。配置的身份决定 Agent 可以访问哪些范围。可选的记录受众可进一步限制访问；可选的密钥绑定凭据要求每次请求都使用已配置的私钥进行证明。

在服务器上打开 /operator，即可通过只读浏览器视图检查当前记录、已完成的工作和承诺。写入者提供的引用可以指向确切的摘要字段或文本段落，以及记录的来源。它们体现可追溯性，但不能证明来源支持某项主张。

Agent 可以通过 MCP、hunch state read|write|records|subscribe、@davesheffer/hunch/state TypeScript 客户端或 Python 客户端使用相同的契约。Python 包在此仓库中构建和测试；目前尚未发布到 PyPI。分范围的约定允许人员记录有来源依据的用户、团队或组织偏好。这些偏好仅供参考，不会悄然变成阻止性规则。

记录可以描述决策、行动结果、承诺、实体、关系，以及注明依赖项的摘要。行动会保留其状态，包括未知或未经验证的结果。重复写入具有稳定的标识，冲突的当前决策会被拒绝，而经确认的人工记录受到保护，不会被 Agent 覆盖。这些是针对结构化记录定义的检查；Hunch 无法独自确认外部世界中的所有事实。

这就是此处所说的确定性状态：明确的规则管理存储的记录，而不是让每个 Agent 都从头重建记录。Git 保存持久数据；SQLite 是可重建的索引。服务器绑定到 loopback，其部署和 Agent 集成由运营者负责。Hunch 不提供托管式 CRM 或电子邮件连接器服务。

请参阅完整文档。

愿景，以及仍在测试的内容

愿景是让人员、工具和 Agent 之间保持连续性：运营 Agent 记录客户问题，编码 Agent 找到相关决策并修复问题根源，然后运营 Agent 使用修复证据关闭承诺。

底层记忆和状态工具现已提供。更广泛的主张——不同 Agent 能否可靠地使用共享状态并避免相互矛盾的工作——仍在测量中。

Hunch 仍是产品名称。 nuryel.state/1 协议和 nuryel_* 工具名称是现有的技术标识；未来是否更名尚未决定。

项目 DNA：帮助 Agent 理解项目的运作方式

项目 DNA 描述观察到的仓库约定：术语、贡献习惯、评审预期和工程模式。工程记忆记录决策及其原因。两者都可以为任务提供参考，但频繁出现的行为不会因此成为政策。

hunch dna inspect
hunch dna context
hunch dna diff <older-ref> <newer-ref>

配置文件会保留其修订版本、来源、置信度和新鲜度。

您的数据与您的权限

• 仓库采用本地优先模式，无需托管的 Hunch 账户。共享记忆通过 Git 访问；可选的状态服务使用已配置的身份和授权。
• hunch private --repo <url> 会将敏感的项目推理保存在私有覆盖层中。公开导出和 CI 应使用仅包含公开内容的视图。
• 起草内容可以使用选定的编码助手订阅、本地端点或确定性回退方案。使用按量计费的公共端点需要明确选择加入。合成与计费。
• Agent 对外部操作和连接器权限负责。存储的记录并不授权发送电子邮件、部署或更改 CRM。
• npm 和编辑器版本发布采用相互独立的发布关卡，并进行软件包完整性和来源证明检查。

了解更多

• 完整文档
• 复制粘贴指南
• 更新日志
• VS Code 扩展
• 参与贡献

FSL-1.1-ALv2（功能源代码许可证）。您可以将其用于、修改并运行在自己的工作中，无论是内部用途还是商业用途；但不得在与 Hunch 或基于其构建的服务构成竞争的商业产品或服务中向他人提供（请参阅 LICENSE 中的 Permitted Purpose）。每个版本发布两年后都会转换为 Apache-2.0。本次变更之前发布的版本继续采用发布时所附的许可证。