projectmind

# projectmind **持久、精简的项目记忆，适用于人工智能编码代理。** 您的代理读取一个小型摘要，而不是每次会话都重新扫描代码库 - 而本地账本显示您节省了多少代币（和美元）。 [](https://github.com/Nodemint-dev/projectmind/actions/workflows/ci.yml)     -success)    每个AI编码会话都以相同的方式开始：代理没有您的项目记忆，因此它会重新读取文件，重新推导您的架构，或者要求您重新解释几个月前做出的决定。您为此支付代币、时间和错误猜测 - 每个会话、每台机器、每个团队成员都是如此。 `projectmind` 通过**结构化、git提交的项目地图**（`.projectmind/map.json`）解决了这个问题：您的模块、它们的依赖关系、您的架构决策、您的约定、您的领域词汇表。代理首先读取一个约400个代币的摘要，只有在需要时才会深入到单个节点，并写回它所学的内容 - 因此*下一个*会话（您的、同事的或不同的AI工具）已经知道该项目。 摘要根据项目的*概念*大小（模块、决策）缩放，而不是其*字节*大小 - 因此节省的代币会随着代码库的增长而增加。 ## 快速开始 ```bash npm install -g @nodemint/projectmind # 安装 `projectmind` CLI cd your-repo projectmind init --seed # 搭建 + 从代码库布局中提出一个启动地图 projectmind setup # 连接 MCP 服务器 + 规则到您使用的每个代理 projectmind install-hook # 可选：自动更新模块新鲜度提交 ``` 就这样。您的代理现在在任务开始时调用 `mind_digest`，而不是扫描文件。 ## 查看它为您节省了什么 - 衡量，而不是承诺 MCP服务器保留一个**本地节省账本**：每次您的代理读取地图而不是扫描文件时，它会记录实际节省的代币与估计的代币相比，如果代理读取文件。  随时检查： ``` $ projectmind savings projectmind savings（估计 - 本地账本，不会离开此机器） 总共节省：~20.5k 代币，跨越 22 次地图读取 ≈ $0.0614 按 sonnet-tier 输入定价（$3/MTok，截至 2026-06） 今日：~20.5k 代币（22 次读取） 按工具： mind_digest 12 次读取 ~18.5k 节省 mind_query 6 次读取 ~1210 节省 mind_context 4 次读取 ~712 节省 方法论：代币 ≈ ceil(bytes/4)；基线 = 代理将读取的文件 ``` 美元数字需要**零配置**：它默认为内置表格中的 Sonnet-tier 输入定价，并显示使用哪个假设。如果您运行不同的模型，请设置 `savings.model`（或确切的 `savings.inputPricePerMTok`）in `.projectmind/config.json` - 但没有人需要这样做。 *（实际输出来自脚本化的一天，在样本项目上的代理工作 - `test/fixtures/` - 12 次会话启动，6 次模块钻取，4 次任务上下文读取。使用 `npm run benchmark` 复制每个会话的数字。）* **VS Code 状态栏：** [`integrations/vscode`](integrations/vscode) 扩展显示一个实时的 `✦ ~20.5k 代币节省` 计数器，读取相同的本地账本。零依赖，零网络。 账本设计诚实：每个数字都标记为**估计**（`ceil(bytes ÷ 4)`，粗略的英语+代码平均值），节省金额以零为下限，文件被 gitignore - 它是您的私有数据，在您的机器上，可以随时删除。 ## 会话交接 - 正好从您离开的地方继续 每个代理会话都会失去的是*工作状态*：您正在做什么，接下来是什么，您刚刚发现的陷阱。代码图无法捕捉它；聊天记录在会话结束时就会消失。 `projectmind` 将其转移： ``` $ projectmind digest # shopflow-api — 项目地图 具有 JWT 身份验证的订单管理 HTTP API，由 PostgreSQL 支持。 栈：node, express, postgres ## ⏪ 从上次会话的交接（2026-07-02） 为订单路由添加退款支持；接下来：编写退款测试 ``` 您的代理在会话结束前调用 `mind_handoff`（或在其上下文被压缩之前）；注释**引导下一个摘要**，因此下一个会话（今晚在您的笔记本电脑上，明天在您的台式电脑上，或完全是不同的AI工具）从一个读取中恢复。 ## 在任何团队工作的环境中使用 没有语言假设，没有平台假设：完整的测试套件（63 个测试，包括 git-hook 端到端和离线保证测试）在 **Linux、macOS 和 Windows × Node 18/20/22** 上运行。路径、glob、原子重命名和已安装的 git 钩子在所有三个平台上都经过了测试。地图格式是纯 JSON - 您的代码库中永远不会写入任何特定于操作系统的内容。 针对真实的开源代码库进行验证（全新克隆 → `projectmind init --seed`，2026-07-02）： | 代码库 | 检测到的栈 | 种子节点 | 代码库大小（估计）| 摘要 | | --- | --- | --- | --- | --- | | expressjs/express | node | `examples`、`lib`、`test` | ~175k 代币 / 152 文件 | **~86 代币** | | pallets/flask | python | `examples`、`src`、`tests` | ~153k 代币 / 104 文件 | **~111 代币** | | flutter/pinball | dart, flutter | `lib`、`packages`、`test`、`web` | ~513k 代币 / 637 文件 | **~99 代币** | 这是核心的可扩展属性：在现实世界中，摘要跟踪项目的*概念*大小，保持 ~100 代币，无论代码库是 150k 还是 500k 代币。（全新种子摘要是一个启动骨架 - 一个精选的地图，决策和约定在 400 代币左右，如基准测试fixture。我们引用诚实的每个会话节省数字 - 78.9% - 来自基准测试，而不是这些整个代码库比率。） ## 它是如何工作的 ```mermaid flowchart LR subgraph agents["您的 AI 代理"] A1[Claude Code] A2[Cursor] A3[Gemini / Codex / Copilot] end subgraph pm["projectmind"] MCP["MCP 服务器\n（stdio，6 个工具）"] CORE["核心\n（原子写入，模式验证）"] HOOK["git post-commit 钩子\n+ 监视模式"] end subgraph repo["您的代码库（git 提交）"] MAP[".projectmind/map.json\n节点 · 边 · 决策\n约定 · 词汇表"] DIG[".projectmind/digest.md\n在 PR 中可审查"] end LEDGER[".projectmind/ledger.json\n本地节省账本（gitignored）"] A1 <--> MCP A2 <--> MCP A3 <--> MCP MCP --> CORE HOOK --> CORE CORE <--> MAP CORE --> DIG MCP --> LEDGER ``` 两条更新路径保持地图当前 **无需烧代币**: - **确定性：** git 钩子（和可选的 `projectmind watch`）将更改的文件映射到模块，通过 glob 和 bump 新鲜度。纯本地计算，零 LLM。 - **代理记录：** 当代理做出架构决策或学习约定调用 `mind_update` - 一次几个代币，而不是每次会话重新发现。 故意 **没有后台 LLM 总结** - 那将烧掉这个工具存在的代币。 ## 代理实际读取的内容 ```markdown # shopflow-api — 项目地图 具有 JWT 身份验证的订单管理 HTTP API，由 PostgreSQL 支持。 栈：node, express, postgres ## 活动 - **auth**: 发布/验证 JWT 访问令牌；公开 requireAuth Express 中间件。 [活动] - **orders-route**: 为身份验证的用户创建和列出订单；总计以整数美分表示。 [活动] ## 模块 - **db**: PostgreSQL 连接池包装器：query（）帮助程序和 withTransaction（）。 … ## 关键决策 - 将货币存储为整数美分，而不是浮点数。（2026-06-10） - 使用 JWT 进行无状态身份验证而不是服务器会话。（2026-06-15） ## 约定 - 永远不要在 src/config.js 外部读取 process.env。 … ``` 整个事情大约 **412 代币**。长字段（`notes`、`rationale`、`file lists`）**排除在摘要之外**，仅通过 `mind_query` 显示 - 默认情况下便宜，按需详细。 ## MCP 工具 | 工具 | 目的 | | --- | --- | | `mind_digest()` | **每次会话先读取**。紧凑的地图。 | | `mind_context({files})` | **任务范围**。仅任务触摸的模块 + 它们的直接依赖。 当您知道文件时，最便宜的读取。 | | `mind_query(node)` | 一个节点的完整详细信息：文件、注释、边。 | | `mind_search(term)` | 按关键词查找节点 / 决策 / 词汇表。 | | `mind_update(delta)` | 记录结构更改、决策或约定。 | | `mind_handoff(note)` | 留下一个“在这里恢复”注释，引导下一个会话的摘要。 | | `mind_stats()` | 地图大小、摘要成本和您的节省账本。 | ## 一命令代理连接 `projectmind setup` 幂等写入 MCP 配置 **和** 一个简短的工作流规则块，用于每个代理 - 合并到现有的配置中，永远不会覆盖（无法解析的配置会备份并跳过）： | 代理 | MCP 配置 | 规则文件 | | --- | --- | --- | | Claude Code | `.mcp.json` | `CLAUDE.md` | | Cursor | `.cursor/mcp.json` | `.cursorrules` | | Windsurf | `.windsurf/mcp.json` | `.windsurfrules` | | Gemini CLI | `.gemini/settings.json` | `GEMINI.md` | | Codex / generic | — | `AGENTS.md` | | GitHub Copilot | — | `.github/copilot-instructions.md` | 使用 `--agent cursor` 定位一个。手动连接是一行： ```json { "mcpServers": { "projectmind": { "command": "npx", "args": ["-y", "-p", "@nodemint/projectmind", "projectmind-mcp"] } } } ``` ## projectmind 适合哪里（以及它故意不适合哪里） | | 结构化代码图（例如 codegraph） | 编码策略插件（例如 ponytail） | **projectmind** | | --- | --- | --- | --- | | 捕获 | 符号、调用路径 - **如何** | 代理应如何编写代码 | 意图、决策、约定 - **为什么** | | 来源 | 从代码解析 | 提示策略 | 由您和您的代理策划 | | 它能知道 *为什么* 您选择 JWT 而不是会话？ | 否 | 否 | **是** | | 跨会话携带工作状态 | 否 | 否 | **是（交接）** | | 显示您节省了什么 | 否 | 否 | **是（本地账本）** | | 离线工作 | 变化 | 是 | **始终（CI 强制）** | 您无法从源代码中解析 *“货币始终是整数美分”* 或 *“我们选择 JWT 水平扩展”*。这是 projectmind 拥有的层。 因此，它 **补充** 结构化工具而不是克隆它们：如果存在 `.codegraph/` 索引，`mind_digest`、`mind_query` 和 `mind_context` 自动指向代理到 codegraph 获取符号级详细信息。无需依赖，无需重复 - projectmind 是原因，codegraph 是方法。 ## 保持地图诚实 ``` $ projectmind doctor 指向不再存在的节点的节点： - legacy-auth（glob：src/old-auth/**） - 未触摸超过 90 天的节点： - reports（上次触摸：2026-03-12，112 天前） ``` - `projectmind doctor` - 漂移检测：悬空文件 glob、过时节点。 - `projectmind validate` - 模式完整性 + 漂移警告。 - `projectmind watch` - 保存时的实时新鲜度（`fs.watch`，防抖，本地）。 - 损坏的 `map.json`？它备份到 `map.json.corrupt-<ts>`，会话继续使用有效的空地图 - 代理永远不会在损坏的文件上崩溃。 ## 基准测试（自己重现） ``` $ npm run benchmark 项目：sample-project 基线（代理将读取的文件）：~1953 代币（8 个文件） projectmind 摘要：~412 代币 节省：**78.9%**（~1541 代币/会话） ``` 方法论，明确说明：基线是代理合理定位所需的已提交fixture项目的连接内容；代币估计为`ceil(chars ÷ 4)`。这些是**估计值**，不是确切的计数 - fixture 和脚本在 `test/`中，因此数字是可审计和可重现的。实际代码库上的节省通常更大，因为实际代码库的节省通常比 8 个文件大得多，而摘要的大小保持不变。 ## CLI 参考 ``` projectmind init [--seed] # 搭建 .projectmind/ (+ 启动地图来自代码库布局) projectmind seed # 提出启动节点（永远不会覆盖精选节点） projectmind setup [--agent <name>] # 将 MCP + 规则写入代理（默认：全部） projectmind digest # 打印摘要（代理看到的内容） projectmind context [--files a,b] [--node id] [--term t] [--depth 1] projectmind query <id> # 完整节点详细信息 projectmind search <term> projectmind add-node <id> "summary" [status] # 活动 | 稳定 | 已弃用 projectmind add-edge <from> <to> <rel> projectmind decide "text" ["rationale"] projectmind convention "text" projectmind handoff ["note"] [--clear] # 留下/显示/清除恢复此处注释 projectmind stats # 大小 + 估计摘要代币 projectmind savings # 您的本地节省账本 projectmind validate # 地图完整性 + 漂移警告 projectmind doctor [--stale <days>] # 漂移报告 projectmind watch # 保存时实时更新 projectmind install-hook # git post-commit 自动更新 选项：--local（每个开发人员的叠加层），--root <dir> ## 地图，20 秒 ```jsonc { "version": 1, "project": { "name": "shopflow-api", "stack": ["node", "express", "postgres"] }, "nodes": { "auth": { "type": "service", // 模块 | 组件 | 服务 | 文档 | 概念 "summary": "发布/验证 JWT 访问令牌；公开 requireAuth Express 中间件。", // 一行 - 代币预算 "files": ["src/auth.js"], // glob；钩子将提交更改 → 节点与这些映射 "status": "active", // 活动 | 稳定 | 已弃用 "notes": "更详细的详细信息 - 仅通过 `mind_query`显示。" } }, "edges": [{ "from": "auth", "to": "config", "rel": "depends-on" }], "decisions": [{ "id": "d3", "text": "JWT over sessions.", "rationale": "…", "date": "…", "date": "2026-06-15" }], "conventions": ["Money is integer cents."], "glossary": { "SKU": "Stock Keeping Unit." } } ``` 两个范围：提交的 `map.json`（与团队共享）和可选的 gitignored `map.local.json` 叠加层，用于个人上下文（“我在 X 上进行重构”）。`digest.md` 也被提交，以便在 PR 中显示为 **可读的差异**。 ## 信任 FAQ **它会发送我的代码到任何地方吗？** - 不 - 你不必相信我们的话。CI 测试 (`test/offline.test.js`) 扫描整个源代码树，如果出现任何网络 API (`http`, `net`, `fetch`, 套接字，…)，测试就会失败。两个运行时依赖项 (`@modelcontextprotocol/sdk`, `picomatch`)，无遥测，无 LLM 调用，无帐户。 **提交的内容是什么？** `map.json`、`digest.md`、`config.json`。您的个人叠加层 (`map.local.json`) 和您的节省账本 (`ledger.json`) 自动被 gitignore。 **节省的数字是真实的吗？** 它们是诚实的估计，明确标记，带有方法论打印在每个数字旁边，以及存储库中的基准测试。 我们宁愿低估也不愿夸大。 **地图会腐烂吗？** git 钩子和监视模式免费保持文件↔模块的新鲜度；`doctor` 标志悬空和过时节点；`validate` 检查完整性。 如果 `map.json` 损坏？它备份到 `map.json.corrupt-<ts>`，会话继续使用有效的空地图 - 代理永远不会在损坏的文件上崩溃。 每一次写入都经过模式验证和原子化 (临时文件 + `fsync` + 重命名)，因此竞争代理和 git 钩子不会损坏地图。 ## 开发 ```bash npm install npm test # 63 个测试：模式、原子性、损坏自愈、作用域、glob、MCP 往返、账本、交接、离线保证 npm run benchmark # 打印估计节省数 ``` MIT 版权所有者。参见 [CHANGELOG.md](CHANGELOG.md)。