projectmind

projectmind

为 AI 编码 Agent 提供持久、精简的项目记忆。 每次会话中，Agent 只需读取一份简短摘要，无需重新扫描整个代码库；本地账本还会清楚显示节省了多少令牌（和美元）。

每次 AI 编码会话都是从同样的情况开始：Agent 对你的项目一无所知，因此会重新读取文件、重新推导架构，或者让你重讲几个月前做出的决定。每次会话、每台机器、每位队友都会因此消耗令牌和时间，还可能得到错误的推断。

projectmind 通过结构化、持久的项目映射文件（.projectmind/map.json）解决这个问题，其中包含模块、依赖关系、架构决策、约定和领域术语表。Agent 会先读取一份约 400 个令牌的摘要，仅在需要时深入查看单个节点，并将学到的信息写回——这样，下一次会话（无论属于你、队友还是其他 AI 工具）开始时就已经了解项目。

摘要会随着项目的概念规模（模块、决策）增长，而不是随着项目的字节大小增长，因此代码库越大，节省越多。

快速开始 — 一条命令

npm install -g @nodemint/projectmind
cd your-repo
projectmind init

这一条 init 命令就能完成所有操作：搭建映射文件、根据代码库布局填充初始内容、检测机器上安装了哪些 AI Agent，并逐一接入（MCP 服务 + 包含实时映射文件的规则文件）、将 .projectmind/ 添加到 .gitignore（映射文件仅保留在本地，无需推送），并安装 git 钩子，在每次提交时更新映射文件。

接下来还有一步工具无法代劳：重启 Agent（或开始新的聊天会话）。AI Agent 会在会话开始时加载配置和规则文件——已经打开的聊天会保留旧上下文，之后的每个会话都会自动获得映射文件。如果你使用 VS Code 节省统计扩展？只需执行一次 Cmd+Shift+P → “Developer: Reload Window”。

想让它在今后的每个项目中都可用，无需运行 init？

projectmind setup --global        # registers the MCP server once, user-wide

（如果你希望分开执行这些操作，projectmind init --bare 只会搭建项目，而 projectmind setup 可按需重新接入 Agent。）

看看它为你节省了多少——有实测，不是承诺

MCP 服务会维护一份本地节省记录：每当你的 Agent 读取地图而不是扫描文件时，它都会记录实际提供的 Token 数，以及 Agent 原本会读取的文件的估算 Token 数。

随时查看：

$ projectmind savings
projectmind savings (estimated — local ledger, never leaves this machine)

  Total saved:   ~20.5k tokens across 22 map read(s)
  ≈ $0.0614 at sonnet-tier input pricing ($3/MTok, as of 2026-06)
  Today:         ~20.5k tokens (22 read(s))

  By tool:
    mind_digest      12 reads   ~18.5k saved
    mind_query        6 reads   ~1210 saved
    mind_context      4 reads   ~712 saved

  Methodology: tokens ≈ ceil(bytes/4); baseline = files the agent would have read instead.

美元金额无需任何配置：默认采用内置费率表中的 Sonnet 级输入价格（截至 2026 年 6 月，Haiku 每 MTok 输入 $1 / Sonnet $3 / Opus $5 / Fable $10），并会明确说明使用了哪个假设。如果你使用其他模型，可以在 .projectmind/config.json 中设置 savings.model（或精确设置 savings.inputPricePerMTok）——但这不是必需的。

（这是在示例项目 test/fixtures/ 上进行一天脚本化 Agent 工作的实际输出——12 次会话启动、6 次模块深入查看、4 次任务上下文读取。运行 npm run benchmark 可复现每个会话的数字。）

VS Code 状态栏：integrations/vscode 扩展会显示实时的 ✦ ~20.5k tokens saved 计数器，读取同一份本地记录。零依赖，零网络。

这份记录的设计秉持诚实原则：每个数字都标注为估算值（ceil(bytes ÷ 4)，英语文本与代码的粗略平均值），节省量最低为零；记录文件已加入 gitignore，是你的私人数据，只保存在你的设备上，可随时删除。

**明确说明一个有意保留的缺口：**记录只统计工具调用（mind_digest、mind_query、mind_context）。下文介绍的内嵌摘要从不需要工具调用——这正是它的意义所在——因此它带来的节省不会以数字显示在这里。projectmind savings 会指出哪些规则文件包含了这部分内容，而不会编造我们无法实际观测的 Token 数。

会话交接——准确接续上次进度

每个 Agent 会话都会丢失的，是工作状态：你正在处理什么、接下来要做什么，以及刚发现的注意事项。代码图谱无法捕捉这些信息；会话结束后，聊天记录也会随之消失。projectmind 可以帮你延续这些信息：

$ projectmind digest
# shopflow-api — project map
Order-management HTTP API with JWT auth, backed by PostgreSQL.
Stack: node, express, postgres

## ⏪ Handoff from last session (2026-07-02)
Adding refund support to orders-route; next: write the refund tests

你的 Agent 会在会话结束前（或上下文被压缩前）调用 mind_handoff；这条记录会置于下一份摘要的最前面，因此下一次会话——无论是在今晚的笔记本电脑上、明天的台式电脑上，还是使用完全不同的 AI 工具——都能在一次读取后继续工作，而不必重新推导任务。记录保存在 gitignore 的本地覆盖层中：它是个人工作状态，永远不会提交；完成后可通过 mind_handoff({clear: true}) 清除。人类也可以使用它： projectmind handoff "note"。

适用于团队日常工作的所有环境

不依赖特定语言，也不依赖特定平台：完整测试套件（85 项测试，包括 git 钩子端到端测试和离线保证测试）会在 CI 中运行，覆盖 Linux、macOS 和 Windows × Node 18/20/22。路径、glob、原子重命名和已安装的 git 钩子都会在这三个平台上接受测试。映射格式为纯 JSON — 不会向你的仓库写入任何特定于操作系统的内容。

已在真实开源仓库中验证（全新克隆 → projectmind init --seed， 2026-07-02）：

仓库	检测到的技术栈	已播种的节点	仓库大小（估算）	摘要
expressjs/express	node	examples、lib、test	约 175k 个 token / 152 个文件	约 86 个 token
pallets/flask	python	examples、src、tests	约 153k 个 token / 104 个文件	约 111 个 token
flutter/pinball	dart、flutter	lib、packages、test、web	约 513k 个 token / 637 个文件	约 99 个 token

这正是它在实际使用中的核心扩展特性：摘要反映的是项目的概念规模，无论仓库包含 150k 还是 500k 个 token，都能保持在约 100 个 token。（刚播种的摘要只是入门骨架 — 加入整理好的映射、决策和惯例后，约为 400 个 token，与基准测试样例相当。我们引用的是基准测试中每个会话节省的实际数字 — 78.9% — 而不是这些整个仓库的比例。）

工作原理

flowchart LR
    subgraph agents["Your AI agents"]
        A1[Claude Code]
        A2[Cursor]
        A3[Gemini / Codex / Copilot]
    end
    subgraph pm["projectmind"]
        MCP["MCP server\n(stdio, 6 tools)"]
        CORE["core\n(atomic writes, schema-validated)"]
        HOOK["git post-commit hook\n+ watch mode"]
    end
    subgraph repo["Your repo"]
        MAP[".projectmind/map.json\nnodes · edges · decisions\nconventions · glossary"]
        DIG[".projectmind/digest.md\n+ embedded in CLAUDE.md etc."]
    end
    LEDGER[".projectmind/ledger.json\nlocal savings ledger (gitignored)"]

    A1 <--> MCP
    A2 <--> MCP
    A3 <--> MCP
    MCP --> CORE
    HOOK --> CORE
    CORE <--> MAP
    CORE --> DIG
    MCP --> LEDGER

两种更新方式让映射保持最新，同时不消耗 token：

• 确定性更新： git 钩子（以及可选的 projectmind watch）通过 glob 将变更文件映射到模块，并更新新鲜度。完全在本地计算，不需要 LLM。
• Agent 记录： 当 Agent 做出架构决策或了解某项惯例时，它会调用 mind_update — 只需消耗少量 token 一次，而不必在每个会话中重新发现。

我们刻意不进行后台 LLM 摘要 — 因为这会消耗此工具旨在帮你节省的 token。

Agent 实际读取的内容

# shopflow-api — project map
Order-management HTTP API with JWT auth, backed by PostgreSQL.
Stack: node, express, postgres

## Active
- **auth**: Issues/verifies JWT access tokens; exposes requireAuth Express middleware. [active]
- **orders-route**: Create and list orders for the authenticated user; totals in integer cents. [active]

## Modules
- **db**: PostgreSQL pool wrapper: query() helper and withTransaction().
…

## Key decisions
- Store money as integer cents, never floats. (2026-06-10)
- JWT for stateless auth instead of server sessions. (2026-06-15)

## Conventions
- Never read process.env outside src/config.js.
…

全部内容约 412 个 token。较长的字段（notes、rationale、文件列表）不会计入摘要，仅通过 mind_query 提供 — 默认开销低，按需查看详情。

MCP 工具

工具	用途
mind_digest()	每个会话首先读取。 紧凑的映射。
mind_context({files})	限定任务范围。 只包含任务涉及的模块及其直接依赖项。已知文件时，这是开销最低的读取方式。
mind_query(node)	查看单个节点的完整详情：文件、备注和边。
mind_search(term)	按关键词查找节点、决策和术语表。
mind_update(delta)	记录结构变更、决策或惯例。
mind_handoff(note)	留下一条“从这里继续”的备注，让下一会话的摘要优先显示它。
mind_stats()	映射大小、摘要开销和节省记录。

一条命令接入 Agent —— 无需依赖模型主动选择读取

projectmind setup 会以幂等方式写入 MCP 配置，并为每个 Agent 添加工作流规则块——合并到现有配置中，绝不覆盖（无法解析的配置会备份并跳过）。

关键在于：MCP 工具只是一种提示——没有任何服务能强制模型调用工具，因此 Agent 可能（有时确实会）在收到“解释一下这个项目”这样简单的问题时跳过 mind_digest，尤其是在任务进行到一半时。但规则文件（CLAUDE.md、.cursorrules、.windsurfrules、GEMINI.md、AGENTS.md、.github/copilot-instructions.md）会无条件加载到每个 Agent 的上下文中，不涉及任何模型选择——这才是真正的机制，并非巧合。因此，setup 不只是写入调用 mind_digest 的说明；它还会在 `` 标记之间嵌入实时摘要本身，之后每次 mind_update、CLI 编辑、git 提交钩子运行或 watch 保存时，都会自动重新同步。从第一条消息开始，项目概览就会出现在每个 Agent 的上下文中，完全无需调用工具——其可靠性与注入上下文的钩子同级，而且不需要钩子。

（嵌入的始终只有提交到仓库中的概览——绝不会包含被 git 忽略的本地覆盖内容或交接笔记，因此个人信息不会泄漏到你提交的文件中。）

Agent	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 / 通用	—	AGENTS.md
GitHub Copilot	—	.github/copilot-instructions.md

使用 projectmind setup --agent cursor 指定目标 Agent。手动接入只需一行命令，适用于所有 Agent：

{ "mcpServers": { "projectmind": { "command": "npx", "args": ["-y", "@nodemint/projectmind", "mcp"] } } }

安装一次，处处可用 — 全局设置

上面的 projectmind setup 适用于单个项目。改为运行 projectmind setup --global，即可一次性注册 MCP 服务，让它从此在你打开的每个项目中都可用——无需为每个仓库单独配置 .mcp.json，也无需重复运行设置命令。支持：Claude Code、Cursor、Windsurf、Gemini CLI。

projectmind setup --global

对于 Claude Code，此命令会调用它自带的 claude mcp add --scope user（与 codegraph 等工具用于全局注册的机制相同），而不是手动编辑其内部配置文件。对于其他工具，它会以与单项目设置相同的幂等方式合并到各自的全局配置中（~/.cursor/mcp.json、~/.codeium/windsurf/mcp_config.json、~/.gemini/settings.json）。

有两件事是它无法做到的，这是有意为之：

• 规则文件仍按项目配置。 CLAUDE.md / .cursorrules / 等文件属于已提交到仓库的项目约定——不存在合理的“全局”版本，因此 --global 只会注册 MCP 服务，不会注册提示文本。没有项目的 .projectmind/ 概览时，mind_digest 只会返回一个空但有效的摘要——没有危害，但 Agent 不会那么积极地被提醒去调用它。
• 已打开的聊天会话无法看到它。 每个 MCP 客户端（Claude Code、Cursor 等）都会在会话开始时加载一次服务列表——这是 MCP 客户端的行为，不是任何服务能够覆盖的。全局范围意味着每个新会话从此都能在未来的每个项目中自动使用它；它不会追溯添加到正在进行的对话中。运行 --global 后重启一次 Agent，以后就一劳永逸了。

projectmind 的定位（以及它刻意不做什么）

	结构化代码图（例如 codegraph）	编码策略插件（例如 ponytail）	projectmind
捕获内容	符号、调用路径——如何实现	Agent 应该如何编写代码	意图、决策、约定——为什么这样做
来源	从代码解析	提示词策略	由你和你的 Agent 整理
能否知道你为什么选择 JWT 而不是会话？	不能	不能	能
能否跨会话保留你的工作状态	不能	不能	能（交接）
能否展示保存的内容	不能	不能	能（本地记录）
能否离线运行	视情况而定	能	始终可以（由 CI 强制执行）

你无法从源代码中解析出 “金额始终使用整数分” 或 “我们选择 JWT 是为了水平扩展”。这是 projectmind 负责的层面。

因此，它会补充结构化工具，而不是克隆它们：如果仓库中存在 .codegraph/ 索引，mind_digest、mind_query 和 mind_context 会自动引导 Agent 使用 codegraph 获取符号级细节。没有依赖，也没有重复——projectmind 负责解释为什么，codegraph 负责说明如何实现。

保持知识图谱准确

$ projectmind doctor
Nodes pointing at files that no longer exist:
  - legacy-auth (globs: src/old-auth/**)
Nodes untouched for more than 90 days:
  - reports (last touched 2026-03-12, 112 days ago)

• projectmind doctor——检测偏差：失效的文件 glob、过时的节点。
• projectmind validate——检查架构完整性并警告偏差。
• projectmind watch——保存时实时更新（fs.watch、防抖、本地运行）。
• map.json 损坏了？系统会将其备份为 map.json.corrupt-<ts>，并使用空的有效知识图谱继续会话——Agent 不会因文件损坏而崩溃。
• 每次写入都会进行架构验证并以原子方式完成（临时文件 + fsync + 重命名），因此并发运行的 Agent 和 git 钩子不会损坏知识图谱。

基准测试（亲自复现）

$ npm run benchmark
Project: sample-project
Baseline (files an agent would read):  ~1953 tokens  (8 files)
projectmind digest:                    ~412 tokens
Savings:                               78.9%  (~1541 tokens/session)

方法说明如下：基线是 Agent 为了解项目而可能读取的文件内容拼接结果（README + package.json + 已提交的测试项目中所有 src/ 文件）；token 数量按 ceil(chars ÷ 4) 估算。这些是估算值，并非精确计数——测试项目和脚本都在 test/ 中，因此这个数字可以审查并复现。在实际仓库中，节省量通常要大得多，因为实际仓库往往远不止 8 个文件，而摘要的大小基本保持不变。

CLI 参考

projectmind init [--seed]                       # scaffold .projectmind/ (+ starter map from repo layout)
projectmind seed                                # propose starter nodes (never overwrites curated ones)
projectmind setup [--agent <name>]              # wire MCP + rules into agents (default: all)
projectmind digest                              # print the digest (what the agent sees)
projectmind context [--files a,b] [--node id] [--term t] [--depth 1]
projectmind query <id>                          # full node detail
projectmind search <term>
projectmind add-node <id> "summary" [status]    # active | stable | deprecated
projectmind add-edge <from> <to> <rel>
projectmind decide "text" ["rationale"]
projectmind convention "text"
projectmind handoff ["note"] [--clear]          # leave/show/clear the resume-here note
projectmind stats                               # sizes + estimated digest tokens
projectmind savings                             # your local savings ledger
projectmind validate                            # map integrity + drift warnings
projectmind doctor [--stale <days>]             # drift report
projectmind watch                               # live freshness updates on save
projectmind install-hook                        # git post-commit auto-updater

Options: --local (per-developer overlay), --root <dir>

20 秒了解知识图谱

{
  "version": 1,
  "project": { "name": "shopflow-api", "stack": ["node", "express", "postgres"] },
  "nodes": {
    "auth": {
      "type": "service",                      // module | component | service | doc | concept
      "summary": "Issues/verifies JWTs; requireAuth middleware.",  // one line — the token budget
      "files": ["src/auth.js"],               // globs; the hook maps commits → nodes with these
      "status": "active",                     // active | stable | deprecated
      "notes": "Longer detail — never in the digest, only via mind_query."
    }
  },
  "edges": [{ "from": "auth", "to": "config", "rel": "depends-on" }],
  "decisions": [{ "id": "d3", "text": "JWT over sessions.", "rationale": "…", "date": "2026-06-15" }],
  "conventions": ["Money is integer cents."],
  "glossary": { "SKU": "Stock Keeping Unit." }
}

默认本地优先：init 会将整个 .projectmind/ 目录加入 git 忽略列表——原始知识图谱、你的个人覆盖层（“正在重构 X”、交接信息）以及节省量记录都会留在你的机器上。无需推送，也无需审查。可共享的知识仍会随仓库传播，因为摘要嵌入在已提交的规则文件（CLAUDE.md 等）中，并会在每次更改时自动同步。

**团队模式（可选）：**想要将完整的原始知识图谱纳入 git，让队友和 CI 共用一个事实来源？从 .gitignore 中删除 .projectmind/ 这一行即可——这就是全部切换操作。每次写入都是确定性的（键已排序、原子写入），因此 map.json 和 digest.md 会生成清晰、易于审查的 PR 差异。做出选择后，init 不会覆盖它。

信任常见问题

它会把我的代码发送到任何地方吗？ 不会，而且你不必只听我们一面之词。CI 测试（test/offline.test.js）会扫描整个源代码树，如果发现任何网络 API（http、net、fetch、套接字等），测试就会失败。只有两个运行时依赖项（@modelcontextprotocol/sdk、picomatch），没有遥测、没有 LLM 调用，也不需要账户。

哪些内容会被提交？ 默认情况下，.projectmind/ 下的内容都不会提交——映射优先存储在本地，并且在 init 时会被添加到 gitignore。会提交的是嵌入在规则文件（CLAUDE.md、.cursorrules 等）中的摘要，这正是设计为供他人共享的部分；其中绝不会包含你的个人覆盖内容或交接备注（已通过回归测试验证）。团队可以删除一行 .gitignore 配置，选择提交完整映射。

节省量的数据真实吗？ 这些是诚实的估算，并且有明确标注；每个数字旁都会列出计算方法，仓库中还有可复现的基准测试。我们宁愿少报，也不愿夸大。

它能在已经打开的聊天会话中运行吗？ 部分可以，我们更愿意明确说明界限：每个 MCP 客户端都会在会话开始时加载服务和规则文件，因此，在 init 运行前就已打开的对话会保留旧上下文——任何工具（无论是我们的还是其他人的）都无法向其中注入内容。从下一个会话开始，一切都会自动运行。如果 MCP 服务已全局注册（setup --global），那么即使在一个全新的项目中，也可以在会话中途使用 mind_* 工具——只有嵌入规则文件的摘要要等到下一个会话才会更新。

映射会变得过时吗？ git hook（由 init 安装）和监视模式会持续免费保持文件↔模块信息的更新；doctor 会标记悬空和过时节点；validate 会检查完整性；每次写入映射时，嵌入的摘要都会重新同步，因此 Agent 看到的内容不会落后于记录的信息。

它会让我只能使用某一种 AI 工具吗？ 不会。任何支持 MCP 的 Agent 都可以使用它，规则文件则能兼容其他工具，而映射本身是任何工具都能读取的纯 JSON。

开发

npm install
npm test              # 85 tests: schema, atomicity, corruption self-heal, scopes,
                      # globs, MCP round-trip, ledger, handoff, offline guarantee
npm run benchmark     # prints the estimated savings number

MIT © 贡献者。请参阅 CHANGELOG.md。