projectmind

projectmind

AI コーディングエージェント向けの、永続的でコンパクトなプロジェクトメモリーです。 エージェントはセッションのたびにコードベースを再スキャンする代わりに、小さなダイジェストを読みます。また、ローカルの記録台帳で、節約できたトークン数（および金額）を正確に確認できます。

AI コーディングセッションは毎回、同じ状態から始まります。エージェントはプロジェクトの記憶を持たないため、ファイルを読み直し、アーキテクチャを再び推測するか、数か月前に決めたことをもう一度説明するよう求めてきます。トークン、時間、誤った推測という形で、毎回、すべてのマシンで、チームメイト全員がそのコストを支払うことになります。

projectmind は、構造化された永続的なプロジェクトマップ（.projectmind/map.json）でこの問題を解決します。マップには、モジュールとその依存関係、アーキテクチャ上の決定事項、規約、ドメイン用語集が含まれます。エージェントはまず約 400 トークンのダイジェストを読み、必要なときだけ個々のノードを詳しく確認し、学んだ内容を書き戻します。そのため、次のセッション（あなた自身、チームメイト、別の AI ツールのいずれのセッションでも）は、すでにプロジェクトを把握した状態で始まります。

ダイジェストのサイズは、プロジェクトのバイト数ではなく、概念上の規模（モジュールや決定事項）に応じて増えます。そのため、リポジトリが大きくなるほど節約効果も高まります。

クイックスタート — 1 つのコマンド

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

この init コマンドだけで、すべて完了します。マップのひな形を作成し、リポジトリの構成から初期データを投入し、マシンにインストールされている AI エージェントを検出してそれぞれに接続します（MCP サーバーと、最新のマップを含むルールファイル）。さらに、.projectmind/ を .gitignore に追加して（マップはローカルに保存されるため、プッシュするものはありません）、コミットのたびにマップを最新に保つ git フックをインストールします。

次に必要なのは、ツールでは代わりに実行できない唯一の手順、エージェントの再起動です（または新しいチャットセッションの開始）。AI エージェントはセッション開始時に設定とルールファイルを読み込みます。すでに開いているチャットには以前のコンテキストが残りますが、それ以降のセッションでは毎回マップが自動的に読み込まれます。VS Code の savings 拡張機能を使っている場合は、Cmd+Shift+P → 「Developer: Reload Window」 を一度実行してください。

今後のすべてのプロジェクトで、init を実行しなくても利用できるようにしますか？

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

（個別に設定したい場合は、projectmind init --bare でひな形だけを作成し、projectmind setup で必要に応じてエージェントを再接続できます。）

節約効果を確認 — 約束ではなく、実測値です

MCP サーバーはローカルの節約台帳を保持します。エージェントがファイルをスキャンする代わりにマップを読むたびに、実際に提供されたトークン数と、代わりにエージェントが読んでいたであろうファイルの推定トークン数を記録します。

いつでも確認できます：

$ 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月時点で、入力1 MTokあたりHaikuは$1、Sonnetは$3、Opusは$5、Fableは$10）。どの前提を使用したかも正確に表示されます。別のモデルを使う場合は、.projectmind/config.jsonでsavings.model（または正確なsavings.inputPricePerMTok）を設定できますが、設定は必須ではありません。

（test/fixtures/内のサンプルプロジェクトで、スクリプトによる1日のエージェント作業から得られた実際の出力です — セッション開始12回、モジュールの詳細確認6回、タスクコンテキストの読み取り4回。セッションごとの数値はnpm run benchmarkで再現できます。）

VS Codeのステータスバー： integrations/vscode拡張機能には、同じローカル台帳を読み取るライブカウンター✦ 約20.5kトークンを節約が表示されます。依存関係もネットワーク接続も不要です。

この台帳は、設計上、正直な数値を示します。すべての数値に推定値（ceil(bytes ÷ 4)、英語とコードを合わせた大まかな平均値）と明記し、節約数はゼロを下回らないようにし、ファイルはgitignoreの対象にしています。データはお使いのマシン上の個人データで、いつでも削除できます。

意図的に対象外としているものを明記します： 台帳がカウントするのはツール呼び出し（mind_digest、mind_query、mind_context）のみです。以下で説明する埋め込みダイジェストはツール呼び出しを必要としません — それがまさに目的です — そのため、ここでは節約量が数値として表示されません。projectmind savingsは、実際には観測できないトークン数を捏造する代わりに、どのルールファイルにダイジェストが含まれているかを示します。

セッションの引き継ぎ — 中断したところからそのまま再開

エージェントのセッションで失われるのは、作業中の状態です。何をしている途中だったか、次に何をするか、たった今気づいた注意点などです。コードグラフでは記録できず、チャット履歴はセッションとともに消えてしまいます。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

エージェントは、セッション終了前（またはコンテキストが圧縮される前）にmind_handoffを呼び出します。メモは次のダイジェストの先頭に表示されるため、今夜はノートPCで、明日はデスクトップで、あるいはまったく別のAIツールで始める次のセッションでも、タスクを再構築せずに1回読むだけで再開できます。メモはgitignore対象のローカルオーバーレイに保存されます。これは個人用の作業状態であり、コミットされることはありません。作業が終わったらmind_handoff({clear: true})で消去できます。人間も使用できます：projectmind handoff "note"。

チームが働くあらゆる環境で利用できます

言語にもプラットフォームにも依存しません。git-hook のエンドツーエンドテストとオフライン保証テストを含むテストスイート全体（85 件）が、CI で Linux、macOS、Windows × Node 18/20/22 において実行されます。パス、glob、アトミックな名前変更、インストール済みの git hook は、3 つすべての環境でテストされます。マップ形式はプレーンな JSON なので、OS 固有のものがリポジトリに書き込まれることはありません。

実際のオープンソースリポジトリで検証済み（新規クローン → 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トークン

これが実環境における、中核的なスケーリング特性です。ダイジェストはプロジェクトの概念的なサイズを反映し、リポジトリが150kトークンでも500kトークンでも、約100トークンに収まります。 （シード直後のダイジェストはスターター用の骨組みです。判断や規約をまとめたマップは、ベンチマーク用フィクスチャのように約400トークンになります。正直なセッションあたりの削減率として、リポジトリ全体の比率ではなく、ベンチマークの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

マップをトークンを消費せずに最新の状態に保つ更新経路が2つあります。

• 決定論的： git hook（および任意の projectmind watch）が、glob を使って変更されたファイルをモジュールに対応付け、鮮度を更新します。すべてローカルでの計算で、LLM は一切使いません。
• エージェントによる記録： エージェントがアーキテクチャ上の判断を下したり、規約を把握したりしたときは、mind_update を呼び出します。毎セッション再発見する代わりに、一度だけ少数のトークンを使います。

このツールが節約するためにあるトークンを消費してしまうため、バックグラウンドでのLLM要約は意図的に行いません。

エージェントが実際に読む内容

# 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トークンです。長いフィールド（notes、rationale、ファイル一覧）はダイジェストから除外されており、mind_query を通じてのみ表示されます。デフォルトでは低コストで、詳細は必要に応じて取得できます。

MCP ツール

ツール	目的
mind_digest()	毎セッション、最初に読みます。 コンパクトなマップです。
mind_context({files})	タスクに限定されます。 タスクが扱うモジュールとその直接の依存関係のみを取得します。対象ファイルが分かっている場合、最も低コストで読み取れます。
mind_query(node)	1つのノードの詳細をすべて取得します：ファイル、メモ、エッジ。
mind_search(term)	キーワードでノード／判断／用語集を検索します。
mind_update(delta)	構造上の変更、判断、規約を記録します。
mind_handoff(note)	次のセッションのダイジェストに引き継ぐ「ここから再開」というメモを残します。
mind_stats()	マップのサイズ、ダイジェストのコスト、トークン削減の記録を表示します。

1 つのコマンドでエージェントを接続 — モデルが読み込むかどうかに左右されません

projectmind setup は各エージェントの MCP 設定 と ワークフロールールのブロックを冪等に書き込みます。既存の設定にマージし、上書きはしません（解析できない設定はバックアップしてスキップします）。

重要なのはここです。MCP ツールはあくまで 促し であり、サーバーがモデルにツールを呼び出させることはできません。そのためエージェントは、特に作業の途中では、「このプロジェクトについて説明して」という単純な質問に対して mind_digest をスキップすることがあります。しかし、ルールファイル（CLAUDE.md、.cursorrules、.windsurfrules、GEMINI.md、AGENTS.md、.github/copilot-instructions.md）は、モデルの選択に一切左右されず、すべてのエージェントのコンテキストに 無条件で 読み込まれます。これが偶然ではなく、実際の仕組みです。そのため setup は mind_digest を呼び出すよう指示を書き込むだけではありません。`` マーカーの間に最新のダイジェストそのものを 埋め込み、その後 mind_update、CLI での編集、git-commit フックの実行、watch による保存があるたびに 自動で再同期 します。プロジェクトマップはすべてのエージェントのコンテキストに最初のメッセージから含まれ、ツールを呼び出す必要もありません。コンテキストを注入するフックと同等の信頼性を、フックなしで実現します。

（埋め込まれるのは リポジトリにコミットされた マップだけです。gitignore 対象のローカルオーバーレイや引き継ぎメモは含まれないため、個人的な情報がコミット対象のファイルに漏れることはありません。）

エージェント	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 で対象を 1 つ指定できます。手動で接続する場合は、どの環境でも 1 行です。

{ "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 の場合、内部設定ファイルを直接編集するのではなく、グローバル登録に codegraph などのツールが使うのと同じ仕組みで、Claude Code 自身の claude mcp add --scope user を呼び出します。それ以外の環境では、プロジェクトごとのセットアップと同じ冪等な方法で、グローバル設定（~/.cursor/mcp.json、~/.codeium/windsurf/mcp_config.json、~/.gemini/settings.json）にマージします。

設計上、できないことが 2 つあります。

• ルールファイルはプロジェクトごとのままです。 CLAUDE.md／.cursorrules などはプロジェクトにコミットされる規約であり、「グローバル」版を設けるのは現実的ではありません。そのため --global で登録されるのは MCP サーバー だけで、促しのテキストは対象外です。プロジェクトの .projectmind/ マップがない場合、mind_digest は空でも有効なダイジェストを返します。問題はありませんが、エージェントに呼び出しを促す効果は弱くなります。
• すでに開いているチャットセッションには反映されません。 MCP クライアント（Claude Code、Cursor など）は、すべてセッション開始時にサーバー一覧を読み込みます。これは MCP クライアント側の動作であり、どのサーバーも変更できません。グローバルスコープでは、今後開くすべてのプロジェクトの 新しい セッションで自動的に利用できるようになりますが、進行中の会話に遡って追加されるわけではありません。--global の実行後にエージェントを一度再起動すれば、以降は設定不要です。

projectmind の役割（そして、あえて担わないこと）

	構造的なコードグラフ（例：codegraph）	コーディングポリシーのプラグイン（例：ponytail）	projectmind
記録するもの	シンボル、呼び出し経路 — どのように	エージェントがどのようにコードを書くべきか	意図、決定、規約 — なぜ
情報源	コードを解析	プロンプトポリシー	あなたとエージェントが整理
JWT をセッションより選んだ 理由 がわかるか	いいえ	いいえ	はい
セッションをまたいで作業状態を引き継げるか	いいえ	いいえ	はい（引き継ぎ）
保存した内容を確認できるか	いいえ	いいえ	はい（ローカル台帳）
オフラインで動作するか	さまざま	はい	常に（CI で強制）

「金額は常に整数のセント単位」や「水平スケーリングのために JWT を選んだ」といったことは、ソースコードから解析できません。projectmind が担うのはそのレイヤーです。

そのため、projectmind は構造的なツールを複製するのではなく、補完します。リポジトリに .codegraph/ インデックスが存在する場合、mind_digest、mind_query、mind_context は自動的に、シンボルレベルの詳細情報について 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> にバックアップされ、空の有効なマップでセッションが続行されます。エージェントが不正なファイルによってクラッシュすることはありません。
• 書き込みはすべてスキーマ検証のうえアトミックに行われます（一時ファイル + fsync + rename）。そのため、書き込みが競合するエージェントと 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)

手法を明確に説明します。ベースラインは、エージェントが状況把握のために読みそうなファイル（README + package.json + コミット済みのフィクスチャプロジェクト内のすべての src/ ファイル）の内容を連結したものです。トークン数は 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/ ディレクトリ全体を gitignore に追加します。生のマップ、個人用オーバーレイ（「X のリファクタリング途中」、引き継ぎ）、節約額の台帳は、すべて自分のマシンに残ります。プッシュもレビューも不要です。共有可能なナレッジは、コミット済みのルールファイル（CLAUDE.md など）にダイジェストが埋め込まれ、変更のたびに自動同期されるため、引き続きリポジトリとともに共有されます。

チームモード（オプトイン）： チームメイトと CI が単一の信頼できる情報源を共有できるよう、完全な生のマップを git に含めますか？ .gitignore から .projectmind/ の行を削除するだけで切り替えられます。キーをソートし、アトミックに書き込むことで、すべての書き込みが決定論的に行われるため、map.json と digest.md の PR 差分をすっきりと確認できます。一度選択すると、init がこの設定を上書きすることはありません。

信頼性に関するよくある質問

コードがどこかに送信されますか？ いいえ。私たちの言葉を信じる必要もありません。CI テスト（test/offline.test.js）がソースツリー全体をスキャンし、ネットワーク API（http、net、fetch、ソケットなど）が見つかると失敗します。実行時の依存関係は 2 つ（@modelcontextprotocol/sdk、picomatch）のみで、テレメトリも LLM 呼び出しもアカウントもありません。

何がコミットされますか？ デフォルトでは、.projectmind/ 以下のものは何もコミットされません。マップはローカル優先で、init 時に Git の追跡対象から除外されます。コミットされるのは、ルールファイル（CLAUDE.md、.cursorrules など）に埋め込まれたダイジェストです。共有を目的としているのはこの部分のみで、個人用のオーバーレイや引き継ぎメモが含まれることはありません（回帰テスト済み）。チームでマップ全体をコミットする場合は、.gitignore の行を 1 つ削除してください。

節約量の数値は本当ですか？ 正直な推定値であることを明記しており、各数値の横に算出方法を記載し、リポジトリには再現可能なベンチマークも用意しています。誇張するより、控えめに見積もる方を選びます。

すでに開いているチャットセッションでも動作しますか？ 一部は動作します。どこまで可能なのかを正確にお伝えします。すべての MCP クライアントはセッション開始時にサーバーとルールファイルを読み込むため、init の実行前から開いていた会話には古いコンテキストが残ります。どのツール（私たちのものも、他のものも）も、そこへ情報を注入できません。次のセッションからは、すべて自動的に動作します。MCP サーバーがすでにグローバルに登録されている場合（setup --global）、新しいプロジェクトではセッション中でも mind_* ツールが動作します。埋め込みルールファイルのダイジェストのみ、次のセッションまで反映されません。

マップが古くなることはありますか？ init でインストールされる Git フックと監視モードにより、ファイルとモジュールの最新状態が無料で維持されます。doctor は参照先のないノードや古いノードを検出し、validate は整合性を確認します。また、マップを書き込むたびに埋め込みダイジェストが再同期されるため、エージェントが見る内容が記録内容に遅れることはありません。

特定の AI ツールに縛られますか？ いいえ。MCP 対応のエージェントならどれでも使用でき、残りはルールファイルで対応できます。マップ自体は、どのツールでも読み取れるプレーンな 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 をご覧ください。