neurodivergent-memory

neurodivergent-memory MCP サーバー

📽️ クリックしてプレビュー

プロジェクトの概要 これは、ニューロダイバージェントな思考パターンを中心に設計されたナレッジグラフ向けの Model Context Protocol サーバーです。 この TypeScript ベースの MCP サーバーは、ニューロダイバージェントな認知スタイルに着想を得た記憶システムを実装しています。思考を 5 つの地区（知識ドメイン）に整理し、BM25 セマンティックランキングを使用して検索結果を順位付けし、双方向のつながりを持つ永続的なナレッジグラフとして記憶を保存します。 設計上の注記：地区モデルは、FractalSemantics (FractalStat) のアドレス体系に基づいています。この体系では、すべてのエンティティが LUCA（Last Universal Common Ancestor）と呼ばれる単一のアンカーポイントから祖先関係を継承します。これらの概念は、Warbler-CDA とthe seedでも使用されています。5 つの標準地区は、デフォルトのスキーマにおける LUCA の 5 つの直接の子です。後続のマイルストーンで追加するカスタム地区には、有効な LUCA 由来のアドレスを宣言する必要があり、祖先関係を暗黙の前提とせず、明示的かつ追跡可能にします。

クイックスタート

Windows

# Download and install Chocolatey:
powershell -c "irm https://community.chocolatey.org/install.ps1|iex"

# Download and install Node.js:
choco install nodejs --version="24.14.1"

# Verify the Node.js version:
node -v # Should print a Node.js 24.x version.

# Verify npm version:
npm -v # Should print an npm 11.x version.

# Run the packaged neurodivergent-memory CLI without a global install
npx neurodivergent-memory@latest init-agent-kit

Linux/macOS

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash

# in lieu of restarting the shell
. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 24

# Verify the Node.js version:
node -v # Should print a Node.js 24.x version.

# Verify npm version:
npm -v # Should print an npm 11.x version.

# Run the packaged neurodivergent-memory CLI without a global install
npx neurodivergent-memory@latest init-agent-kit

モデルのフロー

flowchart LR
  A[Client MCP Request] --> B[MCP Server Stdio Transport]
  B --> C{Request Type}
  C -->|Tools| D[Tool Handler]
  C -->|Resources| E[Resource Handler]
  C -->|Prompts| F[Prompt Handler]

  D --> G[NeurodivergentMemory Core]
  E --> G
  F --> G

  G --> H[Memory Graph Store]
  G --> I[BM25 Index]
  H --> J[Persisted JSON Snapshot]

  D --> K[MCP JSON Response]
  E --> K
  F --> K
  K --> A

フローに関する注記：

• 記憶操作は、グラフの状態と BM25 インデックスの両方を更新します。
• 永続化により、再起動後も状態を維持できるよう、ローカルのスナップショットファイルに書き込みます。
• すべての MCP レスポンスは、stdio トランスポートを介して返されます。

機能

5 つの記憶地区

記憶は認知ドメインごとに整理されます。

• logical_analysis — 構造的思考、問題解決、分析プロセス
• emotional_processing — 感情、感情的な反応、情動状態
• practical_execution — 行動志向の思考、タスク、実装
• vigilant_monitoring — 意識、安全上の懸念、防御的な思考
• creative_synthesis — 新たなつながり、創造的な洞察、革新的な思考

リソース

• memory:// URI を使って、記憶地区や個々の記憶を確認できます
• 各記憶には、内容、タグ、感情に関するメタデータ、つながりの情報が含まれます
• 完全なメタデータを含む JSON リソースとして記憶にアクセスできます

ツール

• store_memory — 感情価と強度を任意で指定して、新しいメモリノードを作成します
• retrieve_memory — ID を指定して特定のメモリを取得します
• update_memory — 内容、タグ、district、emotional_valence、intensity、またはプロジェクトの関連付けを変更します
• delete_memory — メモリとそのすべての接続を削除します
• connect_memories — メモリノード間に双方向のエッジを作成します
• search_memories — 目標のコンテキスト、直近性の重み付け、フィルター（district、project_id、tags、認識ステータス、emotional_valence、intensity、min_score）を任意で指定できる、BM25 順位付けによるセマンティック検索です
• traverse_from — 起点となるメモリから最大 N ホップまでグラフをたどります
• related_to — グラフ上の近接性と BM25 セマンティック検索を組み合わせ、目標のコンテキストと認識ステータスのフィルターを任意で指定してメモリを検索します
• list_memories — district、archetype、project_id、認識ステータスのフィルターを任意で指定できる、ページ分割された一覧を取得します
• memory_stats — プロジェクトの範囲を任意で指定できる集計統計（合計数、district／プロジェクト別の件数、アクセス数の多いメモリ、孤立したメモリ）を返します
• server_handshake — クライアント側で明示的にバージョンを確認するため、実行中のサーバーの ID／バージョン情報を返します
• storage_diagnostics — 解決されたスナップショットパス、WAL パス、有効な永続化元を 1 回の応答で表示します
• import_memories — インライン JSON エントリまたはスナップショットの file_path から一括インポートします。dry_run、重複排除ポリシー、明示的なスナップショット移行フラグを指定できます
• prepare_memory_city_context — MCP プロンプトを呼び出さず、ツールをサポートするクライアント向けに、explore_memory_city をツールとして提供します
• prepare_synthesis_context — プロンプトに制限のあるクライアント向けに、synthesize_memories をツールとして提供します
• prepare_packetized_synthesis_context — プロンプトに制限のあるクライアント、または添付ファイルに制約のあるクライアント向けに、synthesize_memory_packets をツールとして提供します

プロンプト

• explore_memory_city — district とメモリの構成をガイド付きで探索します
• synthesize_memories — 既存のメモリを結び付けて、新たな洞察を作成します
• synthesize_memory_packets — 添付ファイルに制約のあるクライアント向けのパケット化された統合プロンプトです。より広範なグラフを要約する、網羅性マニフェスト 1 つとサイズ制限付きのメモリスライスを出力します

MCP クライアントが多数の生のメモリリソースを無理なく利用できる場合は、synthesize_memories を使用してください。呼び出し経路が添付ファイルに制約されている場合や、少数の構造化リソースでより広範なグラフを網羅する必要がある場合は、synthesize_memory_packets を使用してください。

MCP クライアント間で最大限の相互運用性を確保するため、サーバーは統合／探索のコンテキストを 2 つの形式で提供します。

• MCP プロンプト呼び出しを実装しているクライアント向けの、prompts/list + prompts/get によるプロンプト。
• MCP ツールをサポートしているものの、プロンプトを無視する、または十分にサポートしていないクライアント向けの、prepare_*_context ツールによるツール。

Cline など一部のクライアントでは、MCP プロンプトは /<prompt-name> ではなく、/mcp:<server-name>:<prompt-name> 形式の名前空間付きスラッシュコマンドとして表示されます。

コア概念

メモリのアーキタイプ

各メモリには、その district に関連付けられたアーキタイプが割り当てられます。

• scholar — 論理的分析
• merchant — 実践的な実行
• mystic — 感情の処理と創造的な統合
• guard — 警戒を要する監視

セマンティック順位付け

検索では、埋め込みやクラウド呼び出しを必要としない Okapi BM25 順位付け（k1=1.5、b=0.75）を使用します。結果は 0～1 のスコア範囲に正規化されます。

感情メタデータ

各メモリには、次の情報を任意で付与できます。

• emotional_valence（-1～1）— 感情の強さや感情的なトーン
• intensity（0～1）— 精神的なエネルギーまたは重要度の重み

認識論的ステータス

メモには、暫定的な計画と検証済みの知識を区別するため、任意で epistemic_status を設定できます。

• draft — 暫定的、または計画を目的とするもの
• validated — 確認済みで、確立された事実として扱っても問題ないもの
• outdated — 新しい内容に置き換えられたものの、履歴として保持されるもの

store_memory または import_memories が epistemic_status の明示的な指定なしに、新しい practical_execution メモを作成すると、そのメモにタスクタグがある場合、サーバーはデフォルトで draft に設定します。正式なタスクタグは kind:task です。サーバーは互換性を保つため、同義の type:task と task 単体も受け付けます。これにより、計画メモが確定事項として誤って提示されることを防ぎます。

プロジェクトの帰属とスコープ指定による検索

複数のプロジェクトにまたがるグラフで、帰属の明示とスコープ指定による検索を行うため、メモには任意で第一級の project_id を設定できます。

• 書き込み時（store_memory、update_memory、import_memories）の project_id の指定は任意です。
• update_memory では、既存のプロジェクト帰属を解除するために project_id: null を指定できます。
• search_memories、list_memories、memory_stats では、任意の project_id フィルターを指定できます。
• search_memories、list_memories、related_to では、任意の epistemic_statuses フィルターを指定できます。これにより、必要に応じて古くなった計画メモを除外できます。
• search_memories では、任意の context パラメーターと recency_weight パラメーターを指定できます。コンテキストは軽量な BM25 ブーストとしてランキングに反映されます。recency_weight は 0 から 1 の範囲で指定する必要があり、意味的な関連性を置き換えることなく、最近の情報を優先するブーストを加えます。
• search_memories では、強度フィルター名として min_intensity / max_intensity を使用することを推奨します。従来の intensity_min / intensity_max エイリアスも、互換性のため引き続きサポートされます。
• related_to では、呼び出し元の現在の目標に関連メモのランキングを寄せるため、任意の context パラメーターを指定できます。
• 統計には perProject の内訳が含まれるようになりました。
• スコープを指定した memory_stats では、両端のノードがスコープ内にあるエッジのみが totalConnections に報告されます。
• list_memories の各行には project: ... というセグメントが含まれます（プロジェクトへの帰属がない場合は unset）。
• 検証仕様：project_id は ^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$ に一致する必要があります（最大長は 64 文字です）。
• 無効な値に対しては、復旧方法の案内を含む安定したエラーコード NM_E020 が返されます。

インポート診断と移行の動作

storage_diagnostics は、解決済みのスナップショットパス、WAL パス、および永続化パスの優先順位チェックで採用された設定ソースを報告します。

import_memories は、次の 2 つのソースモードに対応しています。

• 通常の一括登録にはインラインの entries を使用します。
• サーバーのスナップショットをインポートする場合は file_path を使用し、大きな MCP ペイロードを避けます。

インポートの検証フラグ：

• dry_run: true を指定すると、データを書き込まずにリクエストを検証し、would_import、would_skip、would_fail の確定的な件数を返します。
• dedupe には none、content_hash、content_plus_tags を指定できます。
• 重複として除外された行は、安定した理由コード DEDUPE_CONTENT_HASH または DEDUPE_CONTENT_PLUS_TAGS で報告されます。
• スナップショットの file_path インポートでは、デフォルトで解決済みの永続化ディレクトリ内にある .json ファイルを受け付けます。外部のスナップショットファイルを意図的にインポートする場合に限り、NEURODIVERGENT_MEMORY_IMPORT_ALLOW_EXTERNAL_FILE=true を設定してください。

スナップショット移行フラグ：

• preserve_ids は file_path と併用する場合にのみ有効です。稼働中のストアと ID が衝突すると、決定的に拒否されます。
• merge_connections は file_path と併用する場合にのみ有効です。参照される接続先は、インポート対象のスナップショットまたは稼働中のストアのいずれかに存在する必要があります。存在しない場合、その行は INVALID_CONNECTION_TARGET で検証に失敗します。
• 検証エラーがある場合、ドライラン以外のインポートは全体が拒否されます。再試行する前に dry_run: true を実行し、失敗リストを確認してください。

ナレッジグラフの永続化

メモリは、先行書き込みジャーナル（WAL）とスナップショットを組み合わせたモデルで永続化されます。

• すべての変更操作は、まず memories.json.wal.jsonl に追記されます。
• その後、インメモリーグラフが更新され、定期的に memories.json にスナップショットが作成されます。
• 起動時に、サーバーは memories.json を読み込み、WAL のエントリーを再生し、新しいスナップショットに圧縮してから WAL を切り詰めます。

これにより、スナップショットのみの永続化と比べて、クラッシュ後の復旧動作が改善されます。

明示的に制御するには、次の環境変数のいずれかを設定します。

• NEURODIVERGENT_MEMORY_DIR：memories.json を含むディレクトリを指定します
• NEURODIVERGENT_MEMORY_FILE：特定のスナップショットファイルを指定します
• NEURODIVERGENT_MEMORY_MAX：メモリの合計数の上限を設定します（整数。デフォルトは無制限）
• NEURODIVERGENT_MEMORY_EVICTION：上限に達したときの削除ポリシーを指定します。
  • lru（デフォルト）
  • access_frequency
  • district_priority

/home/node/.neurodivergent-memory へのマウントは、環境変数での上書きなしでも引き続き機能します。これはコンテナの node ユーザーのホームディレクトリであり、自動的に確認されます。

⚠️ 破壊的変更（v0.2.0）： イメージは node ユーザーとして実行され、/root を読み取れません。そのため、以前の /root/.neurodivergent-memory へのマウントは黙ってスキップされます。エージェントのすべてのメモリが失われたように見えることがあります。以下のアップグレード後のメモリの復旧を参照してください。

アップグレード後のメモリの復旧

以前に /root/.neurodivergent-memory にデータをマウントしていた場合、スナップショットはホストボリュームにそのまま残っています。次のいずれかの方法で再マウントしてください。

オプション A — /data に明示的にマウント（推奨）：

"-e", "NEURODIVERGENT_MEMORY_DIR=/data",
"-v", "mydata:/data"

オプション B — node ユーザーが所有するパスにマウント：

"-v", "mydata:/home/node/.neurodivergent-memory"

オプション B では NEURODIVERGENT_MEMORY_DIR の上書きは不要です。サーバーが既存のスナップショットを自動的に見つけます。

エージェント向け：コンテナのアップグレード後にメモリが見つからないように見える場合は、import_memories を使ってバックアップのエクスポートから読み込むか、ボリュームを正しく再マウントした後に AI アシスタントに memory_stats を再実行してもらい、復元を確認してください。

マルチティアのメモリ永続化

このサーバーは、複数のプロジェクトにまたがって作業するエージェント向けに、3 層のメモリアーキテクチャをサポートしています。各層は それぞれ独自のディレクトリに配置され、個別に同期できます。

層	目的	一般的なパス	環境変数
project	リポジトリ単位のメモリ — 一時的で、CI に適しています	.github/agent-kit/memories	NEURODIVERGENT_MEMORY_PROJECT_DIR
user	プロジェクトをまたぐ個人のナレッジ — 永続的で、開発者ごとに保存されます	~/.neurodivergent-memory	NEURODIVERGENT_MEMORY_USER_DIR
org	共有する組織のナレッジ — 任意で、チーム全体が利用できます	任意の共有マウント	NEURODIVERGENT_MEMORY_ORG_DIR

プライマリサーバーは引き続き、NEURODIVERGENT_MEMORY_DIR（または自動検出されたデフォルト）からアクティブなスナップショットを読み込みます。層の環境変数は、sync-memories ヘルパー専用です。

同期するメモリへのタグ付け

ユーザー層または組織層に昇格させるメモリには、persistence:durable タグを追加します。 このタグのないメモリは一時的なものとして扱われ、プロジェクト層にとどまります。

["topic:typescript", "scope:global", "kind:pattern", "layer:architecture", "persistence:durable"]

昇格させたくないメモリには、明示的な除外指定として persistence:ephemeral を使用します。

層間でのメモリの同期

ビルド、マイルストーン、またはセッションの後に、プロジェクト層からユーザー層へ永続的なメモリを昇格させます。

NEURODIVERGENT_MEMORY_PROJECT_DIR=.github/agent-kit/memories \
NEURODIVERGENT_MEMORY_USER_DIR=~/.neurodivergent-memory \
  npm run sync-memories -- --from project --to user

または、パスを明示的に指定します。

node build/scripts/sync-memories.js \
  --from .github/agent-kit/memories \
  --to ~/.neurodivergent-memory

オプションの全リファレンス：

--from <path|tier>      Source snapshot directory, or tier name: project | user | org
--to   <path|tier>      Target snapshot directory, or tier name: project | user | org
--tags <tag1,tag2,...>  Promote only memories matching ALL listed tags (default: persistence:durable)
--any-tag               Match memories that have ANY of the listed tags (OR logic)
--dry-run               Report counts without writing any data

安全上の注意： 同期を実行する前に、対象の層の MCP サーバーを停止してください。このスクリプトはスナップショットファイルに直接書き込みます。また、対象ディレクトリの WAL が開いていることを検出すると警告します。

リリースのセキュリティ

• GitHub Actions は、CI とリリースの自動化に Node.js 24 LTS を使用します
• npm の公開では、npm publish --provenance --access public による OIDC provenance を使用します
• Docker イメージは Buildx でビルドし、Docker Hub に公開します。また、SBOM と provenance メタデータを付与します
• GitHub Actions は、npm の tarball とプッシュされたコンテナイメージのダイジェストに対する artifact attestations を生成します
• タグ付きリリースでは、npm の tarball、チェックサム、アテステーションバンドルをリリースアセットとしてアップロードします

開発版 RC チャンネル

development ブランチへのプッシュでは、同じ npm パッケージ名（neurodivergent-memory）とコンテナリポジトリを使ってリリース候補を公開します。

• npm のプレリリースは 0.x.x-rc.N として、npm の dist-tag rc で公開されます。
• npm のプレリリース接尾辞 N には run_number.run_attempt を使い、ワークフローの再実行時に衝突しないようにします。
• Docker イメージは、不変の rc-0.x.x-rc.N タグのみで公開します。ここでの N は run_number.run_attempt から生成されます。
• RC ビルドの GitHub リリースにはプレリリースのマークが付けられます。

これらのビルドは、研究プレビュー版よりも意図的に安定性が低くなっています。検証と初期の統合テストにのみ使用してください。

ライブ準備状況のスモークテスト（project_id）

決定論的なライブスモークテストハーネスを使用して、エンドツーエンドで project_id の帰属とスコープ付き検索を検証します。

• ローカルビルドのターゲット：

npm run smoke:project-id

• 最新の Docker RC ターゲット（PowerShell）：

$rc = (Invoke-RestMethod -Uri "https://hub.docker.com/v2/repositories/twgbellok/neurodivergent-memory/tags?page_size=25").results |
  Where-Object { $_.name -match '^rc-' } |
  Sort-Object { $_.last_updated } -Descending |
  Select-Object -First 1 -ExpandProperty name
node test/live-project-id-smoke.mjs "docker run --rm -i twgbellok/neurodivergent-memory:$rc"

スモークテストハーネスは、アサーションに失敗するとゼロ以外の終了コードを返すため、リリース準備状況のゲートとして使用できます。

エラーの仕様

変更ツールおよび検索ツールの失敗は、運用担当者向けの安定した形式でテキスト応答に含めて返されます。

❌ <summary>
Code: NM_EXXX
Message: Human-readable failure summary
Recovery: Suggested next action

先頭の要約行は状況に応じて変わりますが、Code／Message／Recovery ブロックは、運用担当者が解析・検索できる安定した形式です。これにより、チャットクライアントでは MCP の応答を読みやすく保ちながら、運用担当者がログやリリースノートで検索できる安定したコードを提供します。構造化ログは Pino を使って stderr に出力され、既知の失敗経路では同じ code フィールドを含みます。

並行処理の安全性

複数のエージェントが同時にサーバーを呼び出した際の書き込み競合を防ぐため、変更ツールは非同期ミューテックスを通じて直列化されます。

書き込みキューの動作：

• 保留中の書き込み操作数は NEURODIVERGENT_MEMORY_QUEUE_DEPTH（デフォルト：50）で制限されます。
• キューが満杯の場合、変更ツールは再試行を促すリカバリーメッセージとともに NM_E010 を返します。
• キューの高水位への到達と解消の遷移は、構造化された Pino の警告としてログに記録されます。

WIP ガードレールの動作：

• store_memory は、タスクタグに進行中を示すマーカーが含まれる場合、agent_id ごとの実用上の進行中タスクの飽和状態を確認します。
• 上限は NEURODIVERGENT_MEMORY_WIP_LIMIT（デフォルト：1。無効にするには 0 を設定）で制御します。
• 上限を超えると、ツールの応答に警告行が表示され、運用担当者が確認できるよう NM_E011 がログに記録されます。

ループのテレメトリとガードレール

サーバーはループのシグナルを追跡し、対象を絞ったガードレール応答を提示できます。

• store_memory での繰り返し検出では、トークナイザーと一貫性のあるトークン重複スコアリングと完全一致の高速処理を使用して、受信したコンテンツを直近10件のメモリ（agent_id が指定されている場合は同じ agent_id のもの）と比較します。
• 繰り返しのしきい値を満たす保存では、repeat_detected: true が設定され、一致したメモリの repeat_write_count が増加し、ツールの応答に No net-new info という警告が追加されます。
• emotional_processing メモリに対する logical_analysis の読み取りが繰り返され、設定されたしきい値を超えると、distill_memory の提案が追加されます。
• 読み取りと書き込みのピンポン遷移はローリング操作ウィンドウで追跡され、しきい値の条件を満たすと ping_pong_counter が増加します。また、任意で一時的な地区横断の書き込みクールダウンを開始できます。
• memory_stats には、以下を含む loop_telemetry ブロックが追加されました。
  • repeat_write_candidates（上位5件）
  • ping_pong_candidates（上位5件）
  • recent_high_similarity_writes（直近5件）

設定：

• NEURODIVERGENT_MEMORY_REPEAT_THRESHOLD（デフォルト：0.85）
• NEURODIVERGENT_MEMORY_LOOP_WINDOW（デフォルト：20）
• NEURODIVERGENT_MEMORY_PING_PONG_THRESHOLD（デフォルト：3）
• NEURODIVERGENT_MEMORY_DISTILL_SUGGEST_THRESHOLD（デフォルト：3）
• NEURODIVERGENT_MEMORY_CROSS_DISTRICT_COOLDOWN_MS（デフォルト：0、無効）

パフォーマンスベンチマークのベースライン

Issue #19 では、ビルド済みサーバーに対する MCP stdio のエンドツーエンド測定用に、決定論的なベンチマークハーネスが追加されました。

次のコマンドで実行します。

npm run benchmark

ベンチマークでは、以下を行います。

• 分離された一時的な永続化ディレクトリを使用するため、ローカルのメモリグラフは変更されません。
• 各データセット階層にデータを投入し、対象階層で100回の書き込みを行って store_memory のスループットを測定します。
• 1k、5k、10k件のメモリに対し、100回の反復で search_memories と list_memories のレイテンシを測定します。
• 500件のメモリが接続されたグラフで、深さ2、3、5の traverse_from のレイテンシを測定します。
• 自動処理で扱いやすいよう、構造化されたJSONレポートを標準出力に出力します。
• 実行ごとの出力を、タイムスタンプ付きのファイルとして benchmark-results/ に書き込みます。
• さらに、ローリング形式の最新エイリアスも書き込みます。
  • benchmark-results/memory-benchmark-latest.json
  • benchmark-results/memory-benchmark-latest.md

便利なエイリアスもあります。

npm run bench

コミット済みのベースラインは、RC と安定版の比較における相対的な回帰基準として使用することを想定しており、マシンを問わず絶対的なパフォーマンスを保証するものではありません。

コミット済みのベースラインファイルを意図的にその場で更新するには、次のコマンドを実行します。

npm run benchmark -- --update-baseline

開発

依存関係をインストールします。

npm install

サーバーをビルドします。

npm run build

自動再ビルドを使用して開発する場合：

npm run watch

インストール

Claude Desktop で使用するには、サーバー設定を追加します。

macOS の場合：~/Library/Application Support/Claude/claude_desktop_config.json Windows の場合：%APPDATA%/Claude/claude_desktop_config.json

npm の場合：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "command": "npx",
      "args": ["neurodivergent-memory"]
    }
  }
}

Docker の場合：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEURODIVERGENT_MEMORY_DIR=/data",
        "-v",
        "neurodivergent-memory-data:/data",
        "docker.io/twgbellok/neurodivergent-memory:0.3.0"
      ]
    }
  }
}

完全に自動承認されるツール：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "autoApprove": [
        "store_memory",
        "retrieve_memory",
        "connect_memories",
        "search_memories",
        "update_memory",
        "delete_memory",
        "traverse_from",
        "related_to",
        "list_memories",
        "memory_stats",
        "storage_diagnostics",
        "import_memories",
        "distill_memory",
        "prepare_memory_city_context",
        "prepare_synthesis_context",
        "prepare_packetized_synthesis_context",
        "register_district"
      ],
      "disabled": false,
      "timeout": 120,
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEURODIVERGENT_MEMORY_DIR=/data",
        "-v",
        "neurodivergent-memory-data:/data",
        "docker.io/twgbellok/neurodivergent-memory:0.3.0"
      ],
      "env": {}
    }
  }
}

Github Copilot Agent Workflows で MCP サーバーを使用する場合（github は実行のたびに新しいVMを起動するため、ワークフローをまたいだメモリは存在しません。セッションメモリは機能しますが、ジョブ完了時に消去されます）：

{
  "mcpServers": {
    "neurodivergent-memory": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "[email protected]"
      ],
      "env": {
        "NEURODIVERGENT_MEMORY_DIR": ".neurodivergent-memory"
      },
      "tools": [
        "retrieve_memory",
        "connect_memories",
        "update_memory",
        "delete_memory",
        "traverse_from",
        "related_to",
        "import_memories",
        "storage_diagnostics",
        "distill_memory",
        "prepare_memory_city_context",
        "prepare_synthesis_context",
        "prepare_packetized_synthesis_context",
        "register_district",
        "list_memories",
        "store_memory",
        "search_memories",
        "memory_stats"
      ]
    }
  }
}

共有のグローバルメモリファイルではなく、プロジェクトごとに分離する場合は、プロジェクト専用のホストディレクトリをマウントし、コンテナー側のターゲットは同じままにします。OS に応じたパス区切り文字を使用してください。

• Windows：${workspaceFolder}\.neurodivergent-memory:/data
• macOS / Linux：${workspaceFolder}/.neurodivergent-memory:/data

{
  "mcpServers": {
    "neurodivergent-memory": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "NEURODIVERGENT_MEMORY_DIR=/data",
        "-v",
        "${workspaceFolder}/.neurodivergent-memory:/data",
        "docker.io/twgbellok/neurodivergent-memory:0.3.0"
      ]
    }
  }
}

注： Windows では / を \ に置き換えてください：${workspaceFolder}\.neurodivergent-memory:/data

Docker ランタイム

明示的なバージョンタグを使用してください。公開されている Docker イメージでは、意図的に変動する latest タグを維持していません。

パッケージ化されたサーバーイメージを直接実行することもできます。

docker run --rm -i twgbellok/neurodivergent-memory:0.3.0

デバッグ

MCP サーバーは stdio を介して通信するため、デバッグは難しい場合があります。MCP Inspector の使用をおすすめします。パッケージスクリプトとして利用できます。

npm run inspector

Inspector は、ブラウザーでデバッグツールにアクセスするための URL を表示します。

エージェントのワークフロー設定

このリポジトリには、再利用可能なエージェントカスタマイズキットが含まれており、作成元は .github/agent-kit/ にあります。 このリポジトリで生成済みのエージェントファイルを追跡するのではなく、パッケージ化されたインストーラーを使ってテンプレートを利用先リポジトリの .github/... フォルダーに配置してください。

内容

ファイル	用途
templates/neurodivergent-agent.agent.md	多機能な Memory-Driven Development Coordinator エージェントです。5 段階のワークフローで進行します：コンテキストを取得 → 調査 → メモリーを改善 → 計画 → 実行して引き継ぎ。
templates/memory-driven-template.agent.md	最小限の汎用エージェントテンプレートです。独自のワークフローを構築するための、よりシンプルな出発点です。
templates/nd-memory-workflow.instructions.md	明示的にエージェントを呼び出さなくても、日々のコーディングセッションでメモリー駆動型の習慣を促す共通の指示ファイルです。
templates/setup-nd-memory.prompt.md	インストールを開始する前に、ユーザーにインストールポリシーを選択してもらうガイド付きセットアッププロンプトです。
templates/copilot-instructions.md	GitHub Copilot のセッション向けブートストラップ用リファレンスです。タグのスキーマ、地区のテーブル、ツールのクイックリファレンス、セッションのチェックリストを 1 つのファイルにまとめています。
templates/explore_memory_city.prompt.md	メモリー地区とグラフ構造をガイド付きで探索するためのプロンプトです。
templates/memory-driven-issue-execution.prompt.md	メモリー駆動型のコンテキスト全体（取得 → 計画 → 実行 → 更新）を踏まえて、追跡中のイシューを実行するためのプロンプトです。

キットをプロジェクトにインストールする

現在のパッケージ化されたキットを、現在のディレクトリにあるリポジトリにインストールします。

npx neurodivergent-memory@latest init-agent-kit

便利なオプション：

• --target <path> は、別のリポジトリのルートにインストールします。
• --dry-run は、ファイルを書き込まずにコピー対象を表示します。
• --force は、インストール先にある既存のファイルを上書きします。
• --mode prompt-first|auto-setup は、テンプレートの文言を変更せずに、意図したインストールポリシーをコマンド出力に記録します。

インストーラーは、テンプレートを .github/agents/、.github/instructions/、.github/prompts/、.github/copilot-instructions.md などの標準的なカスタマイズ先にコピーします。

作成元と生成ファイル

正本は引き続き .github/agent-kit/templates/ にあります。インストール後のエージェントファイル .github/agents/neurodivergent-agent.agent.md は、追跡対象のリポジトリアーティファクトではなく、利用先で生成されるファイルとして意図的に扱われます。これにより、リモートの Copilot 更新によって、このリポジトリ内のファイルが繰り返し消去されることを防ぎます。

手動コピーによる代替方法

必要なファイルを、プロジェクトの標準的なカスタマイズ先にコピーしてください。元のファイルを今後のエージェントやコントリビューターが参照できるよう、移動はしないでください。

適切な配置先ディレクトリは、エージェントプラットフォームによって異なります。使用するエージェントが標準で読み込む場所を選んでください。一般的な例：

• エージェント定義には .github/agents/
• 共通の指示には .github/instructions/
• プロンプトには .github/prompts/
• copilot-instructions.md には .github/ 直下

インストールポリシーの確認

neurodivergent-memory MCP をプロジェクトにインストールする前に、どのポリシーを適用するかユーザーに確認してください。

• prompt-first（デフォルト）— インストール前に明示的な承認を求めます。
• auto-setup — 確認せずに自動でインストールします。

選択したポリシーが反映されるよう、インポートしたエージェントファイルのインストールセクションを更新してください。希望が示されていない場合は、prompt-first をデフォルトにします。

付録

以下は copilot-instructions.md の例です。

# neurodivergent-memory — Agent Bootstrap Instructions

This file is automatically read by GitHub Copilot and compatible agents at the start of every session.
It replaces the need to fetch the governance memory (`memory_11`) before working with this MCP server.

---

## What this server is

`neurodivergent-memory` is a **Model Context Protocol (MCP) server** that stores and retrieves memories as a
knowledge graph. It is designed for neurodivergent thinking patterns: non-linear, associative, tag-rich.

Memories are organised into five **districts** (knowledge domains) and connected via bidirectional edges.
Search uses **BM25 semantic ranking** — no embedding model or cloud LLM required.

---

## Canonical Tag Schema

Always apply tags from the five namespaces below when calling `store_memory`.
Multiple tags from different namespaces are expected on every memory.
When storing execution-heavy memories, include the reasoning behind the action and, when possible, connect the entry to a durable principle in `logical_analysis` or `creative_synthesis` so retrieval preserves understanding and not just activity.

| Namespace | Purpose | Examples |
|---|---|---|
| `topic:X` | Subject matter / domain | `topic:unity-ecs`, `topic:adhd-strategies`, `topic:rust-async` |
| `scope:X` | Breadth of the memory | `scope:concept`, `scope:project`, `scope:session`, `scope:global` |
| `kind:X` | Type of knowledge | `kind:insight`, `kind:decision`, `kind:pattern`, `kind:reference`, `kind:task` |
| `layer:X` | Abstraction level | `layer:architecture`, `layer:implementation`, `layer:debugging`, `layer:research` |
| `persistence:X` | Sync-tier eligibility | `persistence:durable`, `persistence:ephemeral` |

**Example tag set for a Unity ECS memory:**

```json
["topic:unity-ecs", "topic:dots", "scope:project", "kind:pattern", "layer:architecture"]

プロジェクトをまたいで長期的に使えるメモリー向けのタグセットの例：

["topic:typescript", "scope:global", "kind:pattern", "layer:architecture", "persistence:durable"]

---

地区

キー	目的
logical_analysis	構造化された思考、分析、調査結果
emotional_processing	感情、感情状態、情動反応
practical_execution	タスク、計画、実装、アクション項目
vigilant_monitoring	リスク、警告、制約、安全上の懸念
creative_synthesis	新たなつながり、創造的なアイデア、分野横断的な洞察

---

利用可能な MCP ツール（クイックリファレンス）

ツール	目的
store_memory	新しいメモリーノードを作成します
retrieve_memory	ID を指定してメモリーを 1 件取得します
update_memory	内容、タグ、地区、感情価、強度を変更します
delete_memory	メモリーとそのすべての接続を削除します
connect_memories	2 つのメモリーノード間にエッジを追加します
search_memories	BM25 による順位付け検索です。context、recency_weight、min_score、地区、タグ、感情価、強度によるフィルターを任意で指定できます
traverse_from	ノードを起点に、最大 N ホップまで BFS でグラフをたどります
related_to	指定したメモリー ID について、ホップ近接性と BM25 を組み合わせます。目標コンテキストによるブーストも任意で指定できます
list_memories	保存されたすべてのメモリーをページネーション形式で列挙します
memory_stats	合計数、地区別・プロジェクト別の件数、アクセス数の多いメモリー、孤立したメモリーを表示します
storage_diagnostics	解決済みのスナップショットパス、WAL パス、有効な永続化ソースを表示します
import_memories	ドライランと移行制御を使用して、インラインエントリーまたはスナップショットファイルから一括インポートします
distill_memory	emotional_processing のメモリーを、構造化された論理的成果物に変換します
prepare_memory_city_context	プロンプトに制限のあるクライアント向けに、explore_memory_city をツールとしてミラーリングします
prepare_synthesis_context	プロンプトに制限のあるクライアント向けに、synthesize_memories をツールとしてミラーリングします
prepare_packetized_synthesis_context	添付ファイルに制限のあるクライアント向けに、synthesize_memory_packets をツールとしてミラーリングします
register_district	LUCA の祖先検証を行い、カスタム地区を登録します

---

永続化

メモリーは書き込みのたびに ~/.neurodivergent-memory/memories.json へ自動的に保存されます。 グラフはサーバー起動時に復元されるため、再起動してもデータは失われません。

---

メモリー品質のガードレール

• 「何が起きたか」だけで終わらせないでください。重要なメモリーには、なぜその行動を取ったのか、どのようなトレードオフや原則が判断の根拠になったのか、そしてその洞察を再利用できるかを記録してください。
• practical_execution はアクションログとして扱い、より深い根拠を実装の詳細より長く残す必要がある場合は、logical_analysis または creative_synthesis と組み合わせてください。
• デバッグの経緯、引き継ぎ、感情的・生のメモリーにノイズが多い場合は、distill_memory または明示的なフォローアップメモリーを使用して、付随的な詳細を取り除きながら重要な情報を保持してください。
• 孤立したタスクログよりも、つながりを持たせた統合を優先してください。実装に関するメモリーを、暗黙的な状態より明示的な状態を優先すること、成長を制限すること、環境を考慮した検証など、長く残すべき原則に関連付けてください。

---

新しいエージェントセッションのブートストラップチェックリスト

1. memory_stats を呼び出して、メモリーがいくつあるか確認します。
2. search_memories で幅広いクエリを使い、関連する過去のコンテキストを探します。
3. 最近のメモリーに、直近の実行手順だけでなく、タスクの根拠や長く残すべき原則がすでに記録されているか確認します。
4. store_memory を呼び出す際は、標準タグスキーマを適用します。
5. connect_memories で新しいメモリーを、関連する既存のメモリーに接続します。
6. 検索を繰り返すのではなく、traverse_from または related_to を使って連想的に情報を取得します。
7. 簡単なタスクは免除対象ではありません：このリポジトリ内でのファイル編集、判断、発見はすべて記録する価値があります。先にメモリーを記録してから次に進んでください。「小さすぎる」と思ったら、それは省略する理由ではなく、記録する合図です。
8. 実行内容だけのメモリーも免除対象ではありません：変更内容を記すメモリーには、変更した理由も記すか、その理由を記したメモリーにリンクしてください。

---