forkmind

ForkMind [](https://www/package/forkmind) [ [](https:///medhovarsh/forkmind/actions/workflows/ci.yml) [](https://nodejs.org) [](./CONTRIBUTING[](./CONTRIBUTING.md) [](https://github.com/Medhovarsh/forkmind/graphributors) [](https://medhovarsh.github.io/forkmind/) **本地优先的LLM状态分支和调试。** ForkMind 将AI上下文窗口视为Git仓库：它捕获每个LLM调用的`.forkmind/`目录，将视化为有向无环图（DAG），并允许您从历史中的任何一点**分支提示或模型参数 - 所有操作机器上，无需云，无需帐户。 适用于**任何OpenAI兼容**，默认情况下，通过[Ollama](https://ollama使用**免费、开源的模型**。还支持Anthropic和的免费层（Groq，OpenRouter，Together，M，LM Studio）。  > Live demo: a conversation tree with a branch off the root, the node inspector > (request/response, tokens, provenance), and the **Fork from here** dialog. <details> <summary>Static screenshot</summary>  </details> --- ## 为什么 调试代理/工具调用流程意味着相同的提示，并进行微小的修改。每次运行为一个节点，因此您可以- **查看**整个对话树，包括工具调用和令牌使用情况。 - **从节点分支** - 编辑提示，交换模型，。 - **比较**结果可视化终端日志。 都存储在磁盘纯JSON。无需遥测。 安装 ```bash 运行无需安装（到npm） npxind initpx forkmind# … 或全局 npm install -g forkmind for start ``` 无需npm注册表 - ForkMindgit链接运行，仪表板在安装时自动 ```bash # 运行无需安装，从GitHub npx github:medhov/forkmind init npx github:medsh/forkmind start # … 或克隆以进行修改 git clone https://github.com/medhov/forkmind kmind && npm``` ### 作为Claude Code插件安装 ForkMind了一个Claude Code插件（技能 + `/forkmind`命令），以便Claude知道何时以及如何驱动它 - 与任何市场插件相同的安装流程： ```text /plugin marketplace add Medhovarsh/forkmind /plugin install forkmind ``` 插件捆绑： - **`forkmind`技能** - 当您要求Claude调试提示、比较模型、从过去的某个步骤分支或回归测试调用时，会调用ForkMind。 - **`/forkmind`命令**需启动/测试/mcp。 - **`forkmind-debug代理** - 在隔离的上下文中运行模型/，并返回一个紧凑的判决结果，而不是转录记录。 - **MCP服务器，自动连接** - 代理查询自己的`.forkmind/`历史记录（回忆尝试，跟踪血统，自我纠正），无需。 CLI仍然运行代理+仪表板；插件是aude如何使用它的粘合剂。 ## 快速开始（免费，无需API密钥） ```bash # 1. 安装免费的本地模型 # （从https://ollama.com安装Ollama） llama3 # 2. 初始化+ npx github:medhovarshind init # 在项目中创建.forkmnpx github:medhovarsh/forkmind # 代理在http://localhost:4500 +板 # 3. 将代码指向参见下面的SDK），进行一些调用 # 打开仪表板 open http://localhost:4500 ``` ### 替换SDK（自动构建树） npm i openai # 包装器扩展了官方SDK ``` ```js const { ForkMind } = require('forkmind'); const new ForkMindOpenAI({ apiKey: 'ollama', // 被Ollama忽略；由 upstream:://localhost:11434', // 免费的本地开源模型 }); //调用都被记录；顺序调用自动链接成对话树。 const res = await client.chat.completions.create({ : 'llama messages: [{ roleuser', content: 'Explain backpropagation simply.'``` 运行完整示例： ```bash node examples/chain.js ``` ### 任意语言 - 将客户端 SDK包装器是一种方便，但不是必需ForkMind的代理使用**OpenAI兼容的**，因此捕获适用于*任何*语言：将基准URL设置为`http://localhost:4500`，您就可以被记录。链条变成下一个请求的`x-forkmind-parent`传递前一个响应的`x-forkmind-node-id`。 ```python # Python - 官方openai客户端，无需ForkMind代码 from openai import OpenAI client = OpenAI(base_url="http://localhost:4500/v1", api_key="ollama") res = client.chat.completions.create( model="llama3", messages=[{"role": "user", "content": "Explain backpropagation simply."}], extra_headers={"x-forkmind-upstream": "http://localhost:11434"}, ) # read res via .with_raw_response to grab x-forkmind-node-id and chain the next call ``` ```bash # curl - 任何可以POST JSON的工具 curl http://localhost:4500/v1/chat/completions \ -H 'content-type: application/json' \ -H 'x-forkmind-upstream: http://localhost:11434' \ -d '{"model":"llama3","messages":[{"role":"user","content":"hi"}]}' -i # 响应头 `x-forkmind-node-id: <id>` → 作为下一个调用的 `x-forkmind-parent`传递 ``` Go，Ruby，Rust，Java - 相同的交易：基准URL + 两个头。仪表板，分支，MCP和回归测试都适用，无论源语言如何。 --- ## 框架集成 ForkMind为两个最大的JS LLM生态系统提供了薄适配器。两者都通过同一个代理路由，因此捕获，分支，仪表板，MCP和回归都适用 - 无需模型类交换，无需回调。 ### LangChain.js ```bash npm i @langchain/openai @langchain/core ``` ```js const { ChatOpenAI } = require('@langchain/openai'); const { forkmind } = require('forkmind/langchain'); const fm = forkmind({ upstream: 'http://localhost:11434 // 免费的本地Ollama const model = new ChatOpenAI({ apiKey: '', model: 'llama3', configuration: fm.configuration, // baseURL → 代理 + 链接获取 }); await model.invoke('Explain backpropagation simply.'); // 在`fm`上顺序调用会自动链接；fm.setParent（id）从节点分支。 ``` ### Vercel AI SDK ```bash npm i ai @ai-sdk/openai ``` ```js const { generateText } = require('ai'); const { forkmindOpenAI } = require('forkmind/vercel'); const openai = forkmindOpenAI({ upstream: 'http://localhost:11434' }); const { text } = await generateText({ model: openai('llama3'), prompt: 'Explain backpropagation simply.', }); //.setParent(id) / openai.resetParent() 控制分支点。 ``` 两者都遵循`FORKMIND_PROXY`（代理基准URL），并为每个实例采用显式`baseURL` / `upstream`。 --- ## 使用其他免费/开源提供商 ForkMind是提供商无关的 - 它原样转发身份验证头，并允许您按客户端设置上游。任何OpenAI兼容的服务都适用： | 提供商 | `upstream` | `apiKey` | | --------------------- | ----------------------------------- | -------------------- | | **Ollama** （本地） | `http:11434` | 任意字符串 | | **LM Studio** （本地） | `http://localhost:1234` | 任意字符串 | | **Groq** （免费层） | `https://api.groq.com/openai` `gsk_...` | OpenRouter** `https://openrouter.ai/api` | `sk-or-...` | |** | `api.t` | 您的密钥 | | **OpenAI** `https://api.openai.com` （默认） | `...` js newOpenAI({ apiKey: process.env.GRO_KEY, upstream: 'https://roq.com/openai' }); ``` 您也可以x-forkmind`头覆盖每个请求的设置，如果您直接调用通过SDK。 ### Anthropic（） ```bash i @anthropic-ai/sdk ``` ```js const { Forkthropic } =forkmind'); const client = new ForkMindropic({ apiKey: process.envTHROPIC_API_KEY client.messages.create({ model: 'claude-5-latest', max 512, : [{ role:', content:' }] }); ``` 工作原理 ``` 您的应用程序 ──▶ ForkMindOpenAI （基准URL = localhost:/v1） │ 注入xind-parent ▼ ForkMind（Express，:4500） │ 原样转发（您的密钥，您的上游） 提供商（Ollama / Gro OpenAI / ...） │ 响应 ▼ 代理重建Node（） ──▶ .forkmodes/<id>.json │ 返回x-forkmind-node-id ▼ 包装器链接它作为下一个调用的父节点 ``` - **确定性节点ID。** `sha256（请求+ parentId）` → 前12个十六进制字符。 相同提示在相同父节点下折叠为一个节点。ID不依赖于响应，因此可以在主体完成之前作为头返回。 - **流式** 字节原样传递给您的真实的SSE）；代理分流它们，重消息（**文本和** 分段工具），并在流结束时保存节点分支。** 每个节点记录其提供商+上游，因此仪表板中的“从”使用相同的宿主重放编辑，并链接到历史父节点。 --- ## 让代理查询自己的历史记录 Fork带一个[MCP](https://modelcontext)服务器，以便AI代理可以读取自己的`.ind/`历史记录在任务中途纠正 - 回忆它已经尝试过查看它如何达到某个状态，或搜索过去的尝试。 ```bash forkmind mcp输入/输出MCP服务器（或ind-mcp） ``` 通过[Smithhttps://smithery.ai)（在[`.yaml`](./smithery.yaml)中配置）进行一次性安装 - 从您的项目根目录运行它看到您的`.forkmind/`： npx -y @smithery/clikmind --client claude ``` … 或使用任何MCP客户端（Claude Desktop / / Cursor / Cline）手动注册：jsonc { "mcpServers": { "forkmind": { "command": "npx", "args": ["-y", "github:arsh/forkm "mcp"] } } } ``` 暴露的工具： | 工具 | 目的 | | ------------------- | -------------------------------------------------------- | | `forkmind_recent` 捕获的回合（紧凑） | | `forkmind_get_node` | 某个节点的完整请求+响应 | | `for_lineage` | 根→节点的 产生状态的精确上下文 | | `forkmind_children` | 从节点分出的兄弟分支 | | `forkmind_search` | 跨所有请求/响应的子 | | `for_stats` | 树总数：节点，根，叶，供应商 | | `forkmind_context_save` | 将上下文卸载到加密的DAG胶囊中 | | `forkmind_context_list` | 列出已保存的胶囊（标题，摘要，大小，年龄） | | `forkmind_context_digest` | 摘要+分段映射 — 廉价预恢复探针 | | `forkmind_context_restore` | 完整或按分段恢复，完整性验证 | | `forkmind_context_forget` | 不可逆加密粉碎（需要ID回声） | | `forkmind_context_replicas`| 副本（RAID）健康状况，可选同步 | | `forkmind_context_stats` | 聚合统计：计数，字节，估计令牌 | | `forkmind_context_export` | 便携式密码短语加密捆绑 | | `forkmind_context_import` | 导入+重新验证捆绑，本地重新包装 | 服务器读取其工作目录中的`.forkmind/` —的`cwd`指向您的项目。 ## 上下文胶囊 — 将上下文卸载为加密的DAG 大多数上下文管理器将整个窗口视为缓存驱逐问题：截断并丢失它。ForkMind **胶囊**将其逆转 - *先持久化，再验证，然后压缩*。胶囊是不可变，基于内容的DAG加密存储在磁盘上，支持按需恢复。 ```bash # 保存（来自文件或stdin的JSON项目），获取一个12字符句柄 echo '{"title":"auth debug","items":[{"role":"user","content":"..."}]}' \ | forkmind context save --digest "oauth loopused; fix in token.js" forkmind context list # 所有胶囊，按最新顺序 forkmind context show 9f3ac21b7e04 # 解密 + 验证 + 打印 forkmind context verify 9f3ac21b7e04 # DAG完整性：父节点， acyclicity，哈希 forkmind context forget 9f3ac21b7e04 --confirm 9f3ac21b7e04 # 加密粉碎 ``` 与HTTP（`POST/GET/DELETE :4500/api/context…`）和通过五个MCP工具（5个MCP工具）以及Claude Code插件中的 **`forkmind-archivist`** 技能+子代理，实现了相同的功能，教导Claude关闭合约：**保存→在磁盘上验证在磁盘上验证后删除** 保证： - **按构造不可变且无环** — 分段ID是内容+父节点的哈希（Git风格）；循环需要一个哈希值包含自身。 - **静止状态下无明文** — 每胶囊的密钥，由存储在外部的主密钥（`~/.forkmind-keys/`）包装；意外提交的`.forkmind/`只会泄露密文和结构。 - **摘要是可选的** — 代理写入≤5行的检索摘要，或完全省略以保持胶囊私有。 - **遗忘是真实的** — 删除首先销毁密钥（加密粉碎），然后标记ID，以便以后无法复活。 - **模型从不被触及** — 胶囊在客户端发送的内容上运行；提供者，权重和KV缓存因设计而被排除在外。 ### RAID — 独立磁盘冗余阵列 将胶囊镜像到任意数量的额外文件系统目标（第二个磁盘，同步文件夹，网络挂载）。副本**密文+清单** — 密钥从不复制。如果主副本丢失或损坏，恢复将从第一个通过验证的自我修复；修复的副本不会获得信任捷径（仍然运行完整的完整性检查）。 ```bash forkmind context replicas add D:\backup\forkmind # 添加目标 + 同步 forkmind context replicas list # 每个目标的覆盖率kmind context replicas sync # 赶线目标， # 传播墓碑 ``` 遗忘到达每个副本：可达的立即被粉碎；离线的副本在其下一次`sync`（墓碑传播）时删除时的密文 -它本来就无法读取，因为胶囊密钥在遗忘时就。墓碑还会使愈合拒绝复活任何被遗忘的东西。 ### 便携式导出/导入 将胶囊移动到另一台机器或项目 — 一共享该项目`~/.ind-keys/`主密钥的笔记本电脑，一个队友，冷存储： ```bash forkm export 9f3ac21b7e04 --passphrase "correct horse battery staple" --out capsule.json # ... 将capsule.json移动到任何地方... forkmind context import capsule.json -- "correct horse battery staple" ``` 该包携带其自身的scrypt派生密钥材料（N=32768，刻意缓慢以抵御离线强行破解弱口令）- 它永远不会依赖源机器，并且口令永远不会写入包本身。在导入时，每个分段都会独立重新验证（重新计算ID，重新计算哈希，解析父节点，非循环DFS），在任何内容触摸磁盘之前 — 包永远不会被盲目信任，只有被证明是正确的。导入是幂等的墓碑，与新鲜保存一样。 ###捕获的DAG存档 两个半连接：任何代理捕获的对话都可以存档到一个中，无需手动组装JSON — 并在以后恢复为提供者就绪的`messages[]`数组，随时插入到下一个请求中： ```bash # 将结束于捕获整个血统存档 forkmind context save --from-node a1b2c3d4e5f6 --digest "auth debug, resolved" # 恢复为聊天消息（或GET /api/context/:id/messages） forkm show 9f3ac21b7e04 --messages ``` 通过MCP执行相同操作：`forkmind_context_save { fromNodeId }`和`forkmind_context_restore { asMessages: true }` — 代理可以在存档其捕获的历史记录，并在需要时将其剪接到下一个请求中。胶囊保留`sourceNodeIds`链接回DAG中的回合。 ### 代币节省 `forkmind context save`和`forkmind context stats`报告从上下文窗口中释放的估计代币数量（`~4 bytes/token`，标准的粗略启发式）— 胶囊实际节省的确切 ## 回归测试 — 固定良好输出，捕获性能下降 调整系统或更换模型可能会无声地降低结果。ForkMind允许您将一个已知的良好捕获节点固定为**基准**，然后在稍后重新运行其确切的请求，并检查新输出是否有漂移。 ```bash # 1. 固定一个良好的节点（从仪表板或 forkmind_recent 中获取其 ID） forkmind regression pin a1b2c3d4e5f6 \ --name octopus-fact \ --contains "心脏" \ --regex "蓝色|铜" \ --min-similarity 0.5 # 2. 列出/删除案例 forkmind regression list forkmind regression remove octopus-fact # 3. 在更改提示/模型后重新运行（如果任何案例失败，则退出代码 1 — CI-ready） forkmind regression run # 无密钥本地（Ollama） forkmind regression run --key $GROQ_API_KEY --upstream https://api.groq.com/openai ``` 每个案例都会将重放的输出与以下内容进行检查： - **`contains`** — 必须出现的子字符串 - **`not-contains`** — 必须不出现的子字符串 - **`regex`** — 必须匹配的模式 - **`min-similarity`** — 与基准的 Jaccard 词重叠率（漂移保护；默认为 `0.3`，因此即使没有明确的断言，差异很大的答案也会失败）。LLM 输出是非确定性的，因此优先使用断言而不是精确匹配。 案例以 JSON 格式存储在 `.forkmind/regressions/` 目录中 — 提交它们以共享基准并在 CI 中控制提示更改。 ## 零成本和本地 - **无需付费 API** — 默认情况下，通过 Ollama 使用免费的本地模型。 - **无需数据库** — 每次对话都是一个位于 `.forkmind/` 目录下的纯 JSON 文件。 - **无需账户，无需遥测** — 除了您已经进行的 LLM 调用（原样中继到您选择的提供商）之外，机器上不会留下任何内容。 ## `.forkmind/` 目录布局 ``` .forkmind/ ├── nodes/ │ ├── a1b2c3d4e5f6.json # 每个对话一个节点 │ └── ... ├── contexts/ # 加密的上下文胶囊 │ └── 9f3ac21b7e04/ │ ├── manifest.json # 公共：DAG 形状、哈希、选择加入摘要 │ └── seg-<id>.enc # 每个分段的 AES-256-GCM 密文 ├── tombstones.json # 遗忘的胶囊 ID（永远不会复活） └── manifest.json # 版本 + 根节点 ID ``` 节点模式： ```jsonc { "id": "a1b2c3d4e5f6", "parentId": null, # null = 根节点 "timestamp": "2026-01-01T00:00:00.000Z", "request": { /* 确切的请求体 */ }, "response": { /* 完整或流重构的响应 */ }, "meta": { "provider": "openai", "upstream": "http://localhost:11434", "stream": true }, "children": ["..."] # 子节点 ID } ``` --- ## 命令行界面 | 命令 | 功能 | | -------------------- | -------------------------------------------------------- | | `forkmind init` | 在当前目录中创建 `.forkmind/` 目录 | | `forkmind start` | 启动代理（:4500）+ 如果已构建，则提供仪表板 | | `forkmind context save/list/show/verify/forget` | 加密的上下文胶囊（见上文） | 环境变量：`FORKMIND_PORT`、`FORKMIND_HOST`（默认为 `127.0.0.1` — 仅限回环；设置为 `0.0.0.0` 以自行风险暴露在 LAN 上）、`FORKMIND_OPENAI_UPSTREAM`、`FORKMIND_ANTHROPIC_UPSTREAM`、`FORKMIND_PROXY`（SDK 目标基 URL）、`FORKMIND_KEY_DIR`（胶囊主密钥位置，默认为 `~/.forkmind-keys`）。 --- ## 开发 ```bash npm install # 安装代理 + 仪表板（npm 工作区） npm test # jest：哈希、存储、流重建、API npm run dashboard:dev # vite 开发服务器在 :5173，代理 API 到 :4500 npm run dashboard:build npm run lint ``` ### 发布到 npm 发布是通过 `.github/workflows/release.yml`（需要具有发布权限的 `NPM_TOKEN` 仓库密钥）驱动的： ```bash npm version patch # 升级 package.json + 标签 git push --follow-tags # 标签推送 → CI 校验、测试、构建仪表板、发布 ``` `prepack` 重新构建 `dashboard/dist`，因此 tarball 始终会附带 UI。 参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 --- ## 路线图 - [x] 命令行界面 + 确定性存储引擎 - [x] 提供者无关的代理（OpenAI 兼容 + Anthropic）带有流媒体 - [x] 替换 SDK 包装器并自动链接 - [x] React Flow 仪表板 + 分支执行 - [x] MCP 集成 — 让代理查询其自己的 `.forkmind/` 历史记录 - [x] 自动回归：固定“良好”的分支，在提示编辑时重新运行 - [x] 上下文胶囊 — 将上下文卸载为加密的、不可变的 DAG；完整或按分段恢复；加密销毁以忘记 - [x] RAID — 独立 DAG 的冗余阵列：在文件系统目标上复制胶囊，具有自我愈合的恢复和墓碑传播 - [x] 胶囊导出/导入 — 便携式、基于口令的加密包，用于在机器和项目之间移动上下文，导入时独立重新验证 - [x] 仪表板胶囊面板 — 浏览胶囊，检查 DAG 分段地图，并从 UI 运行完整性验证（按设计只读） ## 许可证 [MIT](./LICENSE)