coldstart

coldstart 是一个为 AI 编程智能体提供自我维护、持久化代码库记忆的工具。它由两层组成：笔记本（notebook）和导航（navigation），旨在让 Claude Code、Codex 和 Cursor 等智能体不再每次会话都重新探索代码库。

用途

AI 编程智能体在理解代码库时，往往把大量 token 浪费在寻找正确文件、以及重新推导上一次会话已经弄清楚的内容上。coldstart 专注于解决这两个问题：快速定位与任务相关的文件，并保存智能体在真实任务后写下的代码库知识，供后续任务复用。

主要能力

笔记本（coldstart kb）

笔记本是位于 .coldstart/notebook/ 的仓库本地知识库，由智能体写入和读取。笔记有三种形态：文件笔记（说明文件用途，可为单一摘要或针对枢纽文件的按符号分面）、流程笔记（跨文件的有序步骤与不变量）、经验教训（陷阱、规则、缺陷原因、理由或已确认的缺失）。每条笔记都带有锚点，即其主张所依赖的具体文件路径和符号。

笔记通过三种方式到达智能体：

• 摘要：出现在 find 结果中，是过去智能体对某文件的已验证概览，[fresh] 表示文件与验证时字节一致，可直接依赖。
• 提示时召回（可选钩子）：标题、别名或锚点与传入提示匹配的笔记会以紧凑的标题+要点+路径块呈现，有硬性上限，并作为参考数据。无匹配则不注入。
• kb search / kb lookup：对笔记本的搜索引擎，以及编辑文件前的精确地址查找（path [symbol]）。

可信度机制：每个锚点在写入时带有内容哈希，索引会随代码变化重新检查。漂移的笔记会显示 [evidence changed: <path>]，引导智能体重新验证，使过时知识降级为带标签的假设而非自信的错误。笔记存放在仅追加的 .raw 事件日志中（可提交，合并为并集，并行分支可无冲突调和），Markdown 笔记是派生的、机械再生成并被 gitignore。写入经过门控：新笔记的概念会先与现有笔记搜索比对，智能体必须显式合并（--into <id>）或声明为新（--new）。并发会话安全：每条笔记独立追加日志、新笔记 ID 独占创建、共享文件笔记无损合并、原子渲染。智能体若在上下文中发现笔记有误，应即时修正或撤回。

导航（coldstart find / coldstart gs）

导航是对文件路径、符号名、导出以及导入/调用图的快速静态索引，能在毫秒内回答“哪些文件与这个任务相关？”，并给出可检查的证据而非相似度分数。

• find：定位概念对应的文件。传入任务中所有显著标识符（符号、领域名词、半记忆的稀有 token），find 按每个文件覆盖的术语数量排序，并显示每个文件定义与导入的术语，以及术语聚集行的预览。速度上与原始 grep 竞争，仓库级引用遍历基于 ripgrep（可用 PATH 中的、捆绑的或编辑器的，COLDSTART_RG 可覆盖），带 git grep / grep 回退，排序页来自预建索引而非扫描。标志：--path GLOB、--tests、--via、--json。
• gs：深入单个文件。一次调用返回文件的符号（含行范围）、1 跳内部导入、谁导入它、以及每个符号的跨文件调用者。标志：--symbol a,b、--match TERM、--view symbols|imports|importers|callers、--json。
• graph：面向人类而非智能体。生成一个自包含 HTML 文件并打开，每个索引文件是球面上的点，按目录定位，点击可查看其连接关系，关系有名称标注。无依赖，无服务器，无构建步骤，数据不离开本机。标志：--out PATH、--no-open、--json。

使用方式

需要 Node.js 18+。运行 coldstart init 即可完成导航和笔记本的全部设置。它会询问体验方式（cli 推荐，或 mcp）和客户端，然后将面向智能体的指引写入客户端自己的规则文件，连接客户端，并设置笔记本（骨架、git 接线，以及 Claude Code、Codex、Cursor 的捕获/召回钩子）。可用 --experience / --client 跳过提示。客户端从不自动检测，始终由用户选择。

• Claude Code：写入 coldstart.md，确保 CLAUDE.md 通过 @coldstart.md 导入，并在 .claude/settings.json 注册 find/gs 搜索钩子和笔记本召回/捕获钩子，合并到现有设置而不覆盖。mcp 体验还会写入 .mcp.json。
• Codex：在 AGENTS.md 的标记块中内联完整 coldstart 指引，并在 .codex/hooks.json 注册 Codex 专用导航和笔记本钩子。mcp 体验还会写入 [mcp_servers.coldstart] 到 .codex/config.toml。
• Cursor：写入 .cursor/rules/coldstart.mdc，并在 .cursor/hooks.json 注册 Cursor 专用导航和笔记本钩子。mcp 体验还会写入 .cursor/mcp.json。
• 其他：仅写入 coldstart.md，并打印接线说明（mcp 体验还打印 MCP 服务器条目）。

init 会在后台预热索引，使首次查找即时完成。重复运行 init 安全，不会重复条目。版本戳使旧后台 keeper 在下次查找时关闭，新 keeper 从新二进制生成，无需手动重启。

coldstart 以单一二进制提供两个入口：CLI（主要，coldstart find / gs / kb，适用于有 shell 的智能体）和 MCP（适用于无 shell 客户端，如 Claude Desktop，提供 find、gs 以及 kb_search / kb_lookup / kb_write / kb_status / kb_repair / kb_repair_aliases 工具，与 CLI 字节一致）。kb commit 仅限 CLI/人类使用。

从 coldstart-mcp 迁移：包在 2.0.0 从 coldstart-mcp 更名为 @cstart/coldstart，coldstart-mcp 已弃用但仍可安装。切换命令：npm uninstall -g coldstart-mcp && npm install -g @cstart/coldstart && coldstart init。coldstart-mcp 二进制名保留为别名，现有 MCP 配置继续可用。

移除 coldstart：init 写入的每仓库接线无法被全局 npm uninstall 触及，因此提供 unwire 命令，仅移除 coldstart 拥有的标记（钩子条目、@coldstart.md 导入、AGENTS.md 块、MCP 服务器条目，以及 coldstart 完全拥有的文件），不触碰共享文件中的用户内容。它扫描全部四个客户端，幂等，默认保留笔记本（因其为提交的共享数据）。在每个项目运行后，再 npm uninstall -g @cstart/coldstart。

适用场景

最适合与 Claude Code、Codex 和 Cursor 配合使用，三者都能从 coldstart init 获得平台专用的 find/gs 钩子和笔记本召回/捕获钩子。其他客户端获得 coldstart.md 及打印的接线说明。笔记本的新鲜度机制基于内容哈希，因此适用于任何代码库，包括导航索引不解析的语言；在索引可解析处，笔记还能获得符号级新鲜度。

限制

coldstart 没有嵌入向量、没有生成的摘要、没有索引时计算的语义层，这是有意为之：语义层由智能体承担。索引只保留廉价且精确的内容——路径、符号、导出、导入/调用图——并返回每个文件排名靠前的原因。笔记本仍不自行计算含义，只存储、锚定和新鲜度检查智能体编写的含义。笔记本尚年轻，已验证的是：真实会话中智能体写的笔记经代码核对准确；过时笔记循环端到端闭合；捕获、召回和并发写入在压力下成立。其赌注是此类语料库会在仓库生命周期中复利增长。