neuromcp

neuromcp — AI エージェントのための主権的メモリ

どんなモデルでも。あなたのメモリを。ローカルに保持。

neuromcp は、AI 向けの初の主権的メモリレイヤーです。Claude、GPT、Gemini、Ollama に永続的で検索可能なメモリを提供するオープンソースの MCP サーバーで、データはすべてお使いのマシンに保存されます。API キー不要。クラウド同期なし。あなたのことを記憶するためのサブスクリプションも不要です。

主権的メモリ＝完全にあなたが所有し、自分で管理するハードウェア上に保存され、使用するすべてのモデルで持ち運べるデータです。クラウドメモリ製品ではデータの所有権は提供元にありますが、主権的メモリなら、所有するのはあなたです。

npx neuromcp-init   # one command: detects your MCP clients, writes configs, sets up the wiki

セットアップ不要で、サーバーをそのまま実行することもできます：npx neuromcp。動作しない場合は、npx neuromcp-doctor を実行すると、デーモン、Ollama、埋め込み、データベースをまとめて診断できます。

組み込みのメモリブラウザー：名前空間内で最も多く接続されたエンティティと、それらの関係を、ドラッグ、ズーム、クリックできる力指向グラフとして表示します。localhost から配信され、クラウドから配信されることはありません。メモリブラウザーと Obsidian をご覧ください。

neuromcp を選ぶ理由

LLM はコモディティです。あなたのメモリが競争力の源です。 GPT-5、Claude 4、Gemini は、どれも似た方向へ進んでいます。来年使っているモデルは、今とは違うかもしれません。積み重ねてきた会話、判断、好みの記憶はあなたのものです。neuromcp はそのレイヤーをマシン上に保持し、MCP 互換クライアントならどれでも持ち運べるようにします。

ローカル優先は制約ではなく、設計上の選択です。 テレメトリーなし。データがノート PC の外に出ることはありません。会話のコピーを持つベンダーもありません。メモリに触れるコードは、すべて監査できます。SQLite とローカル埋め込みを採用し、すべてを 1 台のディスクに収めます。

インストールは 1 回。どのクライアントでも使えます。 Claude Desktop、Cursor、Windsurf、Codex CLI、Continue、LibreChat、Open WebUI — neuromcp は MCP に対応しているため、MCP をサポートするあらゆる環境で動作します。明日モデルを切り替えても、メモリはそのまま引き継がれます。

キーワード一致ではなく、本当の想起。 ハイブリッド検索では、ベクトル検索（nomic-embed-text、768 次元）、BM25 全文検索、グラフリンク、学習済みの有用性事前分布を組み合わせます。LongMemEval で 500 件のノイズを加えても、R@5 は 93.3% を維持します。コンテキストウィンドウに届くのは、単に最新のメモリではなく、適切なメモリです。

LongMemEval-S の精度

実行	スコア	サンプル	設定
v7（現行）	96.08%（98/102）	n=102	Opus の生成＋Opus の判定、単一モデル
v6	95.10%（97/102）	n=102	v7 と同じ、事前ヒントのセットのみ異なる

再現コマンド：OMB_ANSWER_LLM=claude OMB_ANSWER_MODEL=opus OMB_JUDGE_LLM=claude OMB_JUDGE_MODEL=opus uv run omb run --dataset longmemeval -s s -m neuromcp -c "single-session-user,single-session-assistant,multi-session,temporal-reasoning,knowledge-update,single-session-preference" --query-limit 17

サンプルサイズについて。 n=102（6 カテゴリー × 各 17 件）。98/102 の Wilson 95% 信頼区間は約 90.5～98.7% です。同じ設定での 500 問の完全な実行が、「トップクラス」と主張する前に達成すべき次のマイルストーンです。

ベンチマーク（v0.18.0）

オラクル分割（クリーン — 簡単なモード）

モード	R@5	R@10	ヒット率
抽出済み（ハイブリッド）	100%	100%	100%

オラクル分割の LongMemEval では、小規模なコーパスから正しいメモリを特定します。ローカル MCP メモリシステムは、どれもここで約 99% を達成すると主張しています。これは「クリーンな入力でランキング機能が動作するか」を測るものにすぎません。

ディストラクター分割（v0.18.0、実測）

同じ30問に、他の質問の候補群から抽出したランダムなディストラクター用メモリを1000件追加します。正解のメモリが実際のノイズと競合するようになりました。

埋め込みモデル	ディストラクター	N	R@5	R@10	MRR
Ollama nomic-embed-text	0（オラクル）	30	100%	100%	100%
Ollama nomic-embed-text	200	5	100%	100%	100%
Ollama nomic-embed-text	500	30	93.3%	93.3%	80.3%
Ollama nomic-embed-text	1000	5	100%	100%	74%

再現方法：npx tsx eval/longmemeval-distractor-runner.ts --limit 5 --distractors 1000

サンプル数。 ディストラクター500件の行は n=30 です（28/30 の Wilson 95% CI は R@5 で約78～99%）。ディストラクター1000件の行は n=5 で、予備的な結果です。Wilson 95% CI は [57%, 100%] です。ディストラクター1000件で n=30 の実行には、Ollama 1インスタンスで約36分かかります。ディストラクターのキャッシュ済みバッチ処理は v0.19.0 で対応予定です。ディストラクター500件の数値は信頼できるものとして、1000件の数値は方向性としては肯定的ですが、検出力不足として扱ってください。

直接比較は v0.19.0 で明示的に取り組む予定です。 Hindsight（ローカルのオープンソース MCP。LongMemEval で約94.6%を達成と主張）や Mem0／Zep は、それぞれ独自のハーネスで数値を公表しています。同一のコーパスと埋め込みモデルを使って比較するまでは、ローカルの MCP サーバーを「最先端」と呼ぶのは測定ではなくマーケティングです。neuromcp はサンプル数に関する注意事項とともに数値を公表しているため、傾向を判断できます。現時点では、絶対的な優位性を示すものと捉えないでください。

ハイブリッドランキングモデル（BM25 + ベクトル + アテンション + グラフ + 有用性の事前情報）は、観測されたサンプルにおいて、ディストラクターと対象の比率が1000:1でも R@5 = 100% を維持します。正解のメモリが1位にならないことがあるため、MRR は74%に低下しますが、確認した範囲では常に上位5件以内に入っています。以前の v0.18.0 の数値（R@5 23%）はテスト用の FakeEmbedder によるものでした。これは v0.18.1 で修正済みです。

このベンチマークでは証明できないこと： エンドツーエンドの回答の正確性、長期にわたる複数セッションの推論、または独自ベンチマークにおける商用クラウドシステム（Mem0、Zep）に対する優位性です。こうした比較には、同じディストラクター分割での各システムの数値が必要ですが、まだ公表されていません。

理由

AI エージェントはセッション間のすべてを忘れてしまいます。既存のソリューションは、単純なキーと値のペアを保存するだけで実用的な知識には役立たないか、クラウドインフラストラクチャと API キーを必要とします。

neuromcp は、次の2層のメモリを提供します。

1. MCP サーバー — ベクトル検索、全文検索、グラフ検索を組み合わせたハイブリッド検索、逐語的な想起、メモリのガバナンス、自動統合を、単一の SQLite ファイルで実現します
2. Wiki ナレッジベース — クラッシュ後も保持され、セッションをまたいで蓄積される Markdown の知識をコンパイルし、起動のたびにエージェントへプロジェクトを把握するためのコンテキストを提供します

Karpathy の LLM Wiki、Mastra の Observational Memory、Zep の時間的知識グラフに着想を得ていますが、どれよりもシンプルです。ベクトル DB も、埋め込みのパイプラインも、クラウドも不要です。Markdown ファイル、Git、フックだけです。

アーキテクチャ

~/.neuromcp/
├── memory.db               ← SQLite: hybrid search, MCP tools
├── wiki/                   ← Compiled knowledge (git-tracked)
│   ├── index.md            ← Routekaart — LLM reads this FIRST
│   ├── schema.md           ← Operating rules for the LLM
│   ├── log.md              ← Append-only changelog
│   ├── people/             ← User profiles, preferences
│   ├── projects/           ← Project knowledge (stack, auth, URLs)
│   ├── systems/            ← Infrastructure (tools, MCP servers)
│   ├── patterns/           ← Reusable patterns (error fixes, routing)
│   ├── decisions/          ← Architecture decisions with context
│   └── skills/             ← Repeatable procedures
└── raw/sessions/           ← Raw session logs (auto-generated)

Wiki の仕組み

タイミング	処理内容
セッション開始時	フックが index.md、ユーザープロファイル、自動検出したプロジェクトページ（約1300トークン）を注入します
セッション中	LLM が永続的な知識を得たときに Wiki ページを更新します
ツール呼び出し8回ごと	フックが LLM に Wiki の更新を促します
セッション終了時	フックが生のセッションログを書き込み、Git がすべての Wiki の変更を自動コミットします
クラッシュ時	5回のツール呼び出しごとにファイルへチェックポイントを保存します。ロールバックには Git の履歴を使います。

自己修復型の統合パイプライン（v0.15.0+）

約4時間ごとに launchd エージェントが run-consolidation.sh を実行し、次の4つのステップを最初から最後まで順に実行します。

1. consolidate-sessions.py — プロジェクトごとに生のセッションをまとめ、Claude に事実に基づく要約を依頼し、生のソースと照合して事実確認を行います。監査ツールが具体的な裏付けのない主張を指摘した場合、統合ツールが該当する行を自動的に削除して1回再監査するようになりました。そのため、推測に基づく一文だけでバッチ全体が失敗することはありません。
2. rescue-rejected.py — それでも失敗したバッチを解析し、裏付けのない主張を取り除いて、整理した要約を Wiki ページに追加します。テキストのみの処理で、LLM の呼び出しはありません。
3. entity-linker.py — すべてのページを相互リンクします。登録済みの別のエンティティ（people/、projects/、systems/）への単独の単語による言及を、ページの related: フロントマターに追加します。別途グラフデータベースを用意しなくても、Wiki をグラフのように機能させます。
4. rebuild-index.py — index.md とカテゴリごとの -index.md ファイルを再生成します。10ページを超えるカテゴリは自動的に分割されるため、Wiki の拡大後もセッション開始時のルーターをコンパクトに保てます。

このパイプラインは冪等性があり、いつでも安全に再実行できます。

セッション開始時に LLM が知っていること

Schema (operating rules) → How to maintain the wiki
Index (knowledge map)    → What knowledge exists
User profile             → Who you are, how you work
Project page             → Current project details (auto-detected from cwd)
Last session             → What happened last time

クイックスタート

コマンド1つで実行（推奨）

npx neuromcp-init

インストール済みの MCP クライアント（Claude Desktop、Claude Code、Cursor、Windsurf）を検出し、それぞれの設定に neuromcp エントリーを書き込みます（元の設定はバックアップされます）。Wiki とフックを初期化し、Ollama が利用可能かどうかも確認します。--dry-run を指定すると、書き込みを行わずにすべての処理をプレビューできます。

GUI クライアント（Claude Desktop、Codex Desktop）では、まず恒久的にインストールしてください：npm install -g neuromcp && neuromcp-init。恒久的にインストールした場合に限り、初期化処理でクライアントが必要とする node とスクリプトの絶対パスを書き込めます。素の npx キャッシュ（ガベージコレクションの対象）から実行した場合は、意図的に PATH に依存する npx エントリーにフォールバックしますが、通常 GUI クライアントでは解決できません。

手動での手順（初期化処理の内部で行われること）

1. MCP サーバーを起動する

npx neuromcp

2. Wiki とフックを初期化する（閉ループのアトリビューションに必須）

npx neuromcp-init-wiki

これにより、Wiki の構造を作成し、フック（Claude Code）とルール（その他のエディター）をインストールして、すべてを自動的に設定します。この手順を実行しない場合、npx neuromcp は 46個のツールを備えた通常の MCP サーバーとして引き続き動作しますが、アトリビューションのループを完結させる critic フックはインストールされません。検索は機能しますが、有用性スコアは蓄積されません。複数回実行しても安全で、既存の設定は上書きされません。

エディターとの互換性

neuromcp は MCP 互換のエディターであればどれでも動作します。統合方法は次の2段階です。

機能	Claude Code	Cursor / Windsurf / Cline / Copilot / JetBrains / Zed
MCP ツール（46個）	完全対応	完全対応
セッション開始時のコンテキスト	フック（自動）	ルール（LLM による実行、ベストエフォート）
セッション終了時の保存	フック（自動）	ルール（LLM による実行、ベストエフォート）
Wiki のリマインダー	ツール呼び出し8回ごと	なし
クラッシュ耐性のあるチェックポイント	あり	なし

Claude Code では、ネイティブフックによってすべての機能を利用できます。LLM が忘れた場合でも、コンテキストの挿入と保存は自動的に行われます。

その他のエディター では、セッションの開始時と終了時に neuromcp ツールを呼び出すよう LLM に指示するルールファイルが使われます。LLM の指示への準拠に依存するため、実際にはうまく機能しますが、フックのように保証されるものではありません。

# Auto-detect installed editors
npx neuromcp-init-wiki

# Target a specific editor
npx neuromcp-init-wiki --editor cursor

# Install rules for all supported editors
npx neuromcp-init-wiki --editor all

対応エディター：cursor、windsurf、cline、copilot（VS Code）、jetbrains、zed

推奨：Ollama を追加して、本格的なセマンティック検索を利用する

ollama pull nomic-embed-text

neuromcp が自動的に検出するため、設定は不要です。

英語以外のメモリ：多言語埋め込みモデルを使用する

nomic-embed-text は英語中心です。実際のオランダ語メモリストア（2,402 件のメモリ、言い換えたオランダ語のクエリ40件、トピック外のクエリ15件）では、正しいメモリが上位5件に入った割合はわずか2.5％で、トピック外のクエリのスコアが正しい一致よりも高くなりました。同じデータで bge-m3（多言語対応、1024次元）を使用した場合：

埋め込みモデル	Recall@5	MRR@10	関連性とトピック外を区別可能（AUROC）
nomic-embed-text	2.5%	0.03	0.08
bge-m3	65%	0.47	0.99

既存のインストールを切り替えるには：

ollama pull bge-m3
npx neuromcp-reembed                 # dry run on a copy
npx neuromcp-reembed --apply         # rebuild the index (keeps a backup)

NEUROMCP_EMBEDDING_MODEL=bge-m3 を設定して再埋め込みを実行します。その後、デフォルトの auto 設定を使用するすべてのクライアントで、インデックスの作成に使用されたモデルが使われるため、ほかに設定する必要はありません。bge-m3 を使うと、search_memory では調整済みの関連性しきい値（0.45）も適用され、トピック外のクエリにはノイズではなく何も返しません。キーワード（FTS）とナレッジグラフのヒットは常に通過します。

英語以外のメモリでは NEUROMCP_RERANKER=none を設定してください。同梱のクロスエンコーダー（ms-marco-MiniLM-L-6-v2）は英語専用で、上記のオランダ語ベンチマークでは MRR が 0.46 から 0.18 に低下しました。

アップグレード

npm install -g neuromcp@latest
npx neuromcp-init-wiki        # updates installed hooks; safe to re-run
npx neuromcp-doctor check     # confirms hooks, daemon and embeddings

neuromcp-init-wiki は Claude Code フックを一度だけコピーしていました。0.30.0 まではその後更新されなかったため、フックの修正が既存のインストールに反映されませんでした。現在は、変更されていない古い neuromcp バージョンのフックをすべて更新します（それぞれの隣にバックアップを保存します）。古い .js フックは .cjs に移行し（古いパスには転送用スタブを残します）、編集済みのフックはそのままにします。編集済みのフックは一覧表示され、--update-hooks を指定するとそれらも置き換えます。neuromcp-doctor check は古いフックを報告します。

インストール

確実な方法は npm install -g neuromcp && neuromcp-init です。これにより、検出されたすべてのクライアント設定に以下のエントリーが書き込まれます（先にバックアップを作成します）。npx を単独で実行するのではなく、永続的なインストール先から init を実行してください。npx のキャッシュから実行すると、GUI クライアントでは通常解決できない PATH 依存のエントリーに意図的にフォールバックします。手動で設定する場合は、次のとおりです。

Claude Code

// ~/.claude.json → mcpServers
{
  "neuromcp": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "neuromcp"]
  }
}

Claude Code はターミナルから起動され、PATH を引き継ぐため、ここでは npx を使用できます。

Claude Desktop / Codex Desktop / 任意の GUI クライアント

GUI アプリはログインシェルではなくウィンドウマネージャーによって起動されるため、通常は node も npx も含まない最小限の PATH を引き継ぎます（nvm、fnm、Volta、Homebrew はすべて /usr/bin の外にインストールされます）。絶対パスを使用してください。これは 0.29.3 以降に neuromcp-init が書き込む設定とまったく同じです。

// ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "neuromcp": {
      "command": "/opt/homebrew/opt/node@22/bin/node",
      "args": ["/opt/homebrew/lib/node_modules/neuromcp/bin/neuromcp.mjs"]
    }
  }
}

次のコマンドで、自分の2つのパスを確認できます。

which node                      # → "command"
npm root -g                     # → "args": ["<that>/neuromcp/bin/neuromcp.mjs"]

（bin/neuromcp.mjs は #!/usr/bin/env node のシバンを保持しているため、ターミナルから直接実行しても動作します。）

Cursor / Windsurf / Cline

同じ形式で、エディターの MCP 設定に追加します。すべてのクライアント向けのコピー＆ペースト用設定は examples/ にあります。

共有デーモン（複数のクライアントを実行する場合に推奨）

デフォルトでは、各クライアントが独自の neuromcp プロセスを起動します。代わりに、1つの共有バックグラウンドデーモンですべてのクライアントに対応できます。データベース接続は1つ、埋め込みパイプラインは1つとなり、クライアントごとのコールドスタートもありません。

npx neuromcp-enable-daemon --port 3200   # macOS launchd agent; verify with: curl -s http://127.0.0.1:3200/health

次に、クライアントをデーモンに接続します。

// Claude Code (~/.claude.json) — native HTTP transport
{ "neuromcp": { "type": "http", "url": "http://127.0.0.1:3200/mcp" } }

// Claude Desktop — stdio-only, bridge via neuromcp-connect.
// The bridge waits for the daemon on cold boot (plain mcp-remote exits
// fatally when the client starts before the daemon has bound its port,
// leaving a permanent "Server disconnected").
{ "neuromcp": { "command": "npx", "args": ["-y", "--package=neuromcp", "neuromcp-connect", "http://127.0.0.1:3200/mcp"] } }

デーモンはループバックインターフェースのみで待ち受け、許可リストにない Host ヘッダーと Origin ヘッダーを拒否します（DNS リバインディング対策）。この境界内では、設計上認証を行いません。アンインストールするには、npx neuromcp-enable-daemon --uninstall を実行します。

プラットフォームのサポート

コンポーネント	macOS	Linux	Windows
MCP サーバー（stdio + HTTP）	✅	✅（CI）	⚠️ 未テスト — ネイティブ依存関係は win-x64 のビルド済みバイナリを同梱。報告をお待ちしています
共有デーモンの自動起動（enable-daemon）	✅ launchd	手動で systemd	❌
自動統合（enable-consolidation）	✅ launchd	cron の設定例	❌
Claude Code フック	✅	✅	⚠️ 未テスト

プロジェクトごとの分離

// .mcp.json in project root
{
  "mcpServers": {
    "neuromcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "neuromcp"],
      "env": {
        "NEUROMCP_DB_PATH": ".neuromcp/memory.db",
        "NEUROMCP_NAMESPACE": "my-project"
      }
    }
  }
}

メモリブラウザーと Obsidian

見えないメモリは、信頼できるとは限りません。neuromcp には、エージェントが実際に把握している内容を確認する方法が2つ用意されています。どちらもローカルで動作し、読み取り専用です。

組み込みウェブビュー

共有デーモン の実行中に、http://127.0.0.1:<port>/ui（デフォルトのポートは3200）を開きます。

• グラフ — 名前空間内の主要なエンティティと、それらの間の関係を力学モデルのキャンバスに表示します。ノードをドラッグしたり、スクロールしてズームしたり、ノードをクリックして関連付けられたメモリを一覧表示したりできます（現在のメモリのみ表示され、置き換えられたメモリは表示を求めない限り非表示になります）。
• タイムライン — トピックを入力すると、そのトピックに関する事実が時間とともにどのように変化したか、どのメモリがどのメモリに置き換えられたかも含めて確認できます。

UIは外部アセットを使用しないシングルページです（厳格なCSPを採用し、CDNは使用しません）。ループバックでのみ提供されます。デーモンをループバック以外のホストにバインドすると、/ui と /api/* のルートは完全に無効になります。

WikiのObsidianグラフ

Wiki（~/.neuromcp/wiki）はプレーンなMarkdownなので、Obsidianの保管庫として直接開けます。Obsidianは[[wikilinks]]からグラフを描画しますが、neuromcpは関係をフロントマターに保持するため、ブリッジを一度実行してください（冪等で、--dry-runにも対応しています）。

npx neuromcp-obsidian-bridge

neuromcp-init-wikiは、最小限のwiki/.obsidian/（ページの種類ごとの色グループ、プラグインなし）も初期化します。ただし、存在しない場合に限ります。既存の保管庫の設定は変更されません。詳細はdocs/OBSIDIAN.mdをご覧ください。

MCP の機能

8つのファミリーにまたがる46個のツールがあります。すべてのパラメーターを含む自動生成の完全なリファレンスはdocs/TOOLS.mdにあります（変更のたびに実際の登録内容から再生成され、差異があるとCIで失敗します）。

ファミリー	ツール数	主な機能
コアメモリ	11	store_memory（重複排除＋矛盾検出＋意外性スコアリング）、search_memory（ハイブリッドRRF＋説明メタデータ）、recall_answer（ギャップ分析を含む、引用付きの抽出型回答）、search_all
ナレッジグラフ	6	create_entity、create_relation、query_graph、compute_centrality（PageRank）
エピソード	10	start_episode／end_episode、クラスタリング、memory_timeline
マルチエージェント	9	register_agent、find_expert、レビューキュー、メモリ転送
原文ストア	3	生テキストに対する正確な再検索を行うFTS。要約や削除は行いません
Wiki	3	wiki_ingest、wiki_lint、wiki_briefing
帰属と有用性	3	log_retrieval、cite_memories — 有用性事前分布のループを閉じます
リフレクション	1	generate_reflection

適切な検索ツールの選び方： search_memoryはランキング済みの生メモリを返します。recall_answerは引用付きの抽出型回答を生成します（または正直にnot_in_memoryと返します）。recall_memoryは意味検索を行わない、ID／フィルターによる単純な検索です。search_allは検索対象に原文ストアを加えます。

リソース（13）

URI	説明
memory://stats	全体の統計
memory://recent	直近20件のメモリ
memory://namespaces	件数を含むすべての名前空間
memory://health	サーバーの健全性＋メトリクス
memory://stats/{namespace}	名前空間ごとの統計
memory://recent/{namespace}	名前空間内の最近のメモリ
memory://id/{id}	IDで指定した単一のメモリ
memory://tag/{tag}	タグで指定したメモリ
memory://namespace/{ns}	名前空間内のすべてのメモリ
memory://consolidation/log	最近の統合エントリー
memory://operations	実行中／最近の操作

プロンプト（3）

プロンプト	説明
memory_context_for_task	関連するメモリを検索し、LLMのコンテキストとして整形します
review_memory_candidate	提案されたメモリを類似度の高い重複候補とともに表示します
consolidation_dry_run	適用せずに統合をプレビューします

Wikiナレッジベース

Wikiは、人が読める形にまとめられた知識レイヤーです。セッションログの混沌とした状態を、構造化され相互にリンクされたMarkdownページに置き換えます。

ベクトル検索を増やすのではなく、Wikiを使う理由

従来のRAG	neuromcp Wiki
クエリのたびに回答を再導出します	知識を一度まとめ、時間をかけて洗練させます
チャンク分割によるアーティファクトや検索ノイズが発生します	出典を引用した、人が読みやすいページを利用します
ベクトルDBと埋め込みパイプラインが必要です	プレーンなMarkdownとGitを使います
検索処理がブラックボックスです	監査、編集、移植が可能です
知識が失われます	知識が蓄積されていきます

Wikiページの形式

---
title: My Project
type: project
created: 2026-04-06
updated: 2026-04-06
confidence: high
related: [other-project, oauth-setup]
---

# My Project

Description, stack, auth, deployment details...

使い方

フックをインストールすると、Wikiは自動的に機能します。LLMは次の処理を行います。

1. セッション開始時に index.md を読み込み、どのような知識があるかを把握します
2. 現在のタスクに関連する場合、該当するページを読み込みます
3. 新しいことを学んだときに、ページを更新します
4. Wikiの更新が必要な場合、ツールを8回呼び出すごとに通知を受けます

Wikiを手動で閲覧、編集することもできます。通常のMarkdownファイルにすぎません。

自動統合（任意）

未加工のセッションログが蓄積されたら、Wikiを自動的に最新の状態に保てます。スケジュールされたジョブが未処理のセッションを読み込み、プロジェクトごとに分類し（セッションの内容から $HOME/projects/<name> のパスを検出）、claude CLIを使って適切なWikiページに ## [date] エントリーを合成します。

npx neuromcp-enable-consolidation

インストールされるもの：

• ~/.neuromcp/scripts/consolidate-sessions.py — ワーカー
• ~/.neuromcp/scripts/run-consolidation.sh — しきい値チェック付きの実行スクリプト
• macOS：4時間ごとに実行されるlaunchdエージェント（com.neuromcp.consolidate）
• Linux：手動で追加するcron設定の例を表示します

要件：

• PATH 上に python3 ≥ 3.8 があること
• claude CLI が PATH 上にあること

組み込みのガード機能：

• しきい値：未処理のセッションが5件未満の場合はスキップします
• 出力はフェンス付きMarkdownブロックから抽出されます。謝罪や説明文は拒否されます
• 台帳（~/.neuromcp/consolidation-ledger.json）により、再実行しても結果が重複しません
• 大規模なプロジェクトのバックログは自動的にバッチ処理されます（claude の呼び出し1回あたりのセッション数はデフォルトで15件です。--max-sessions で変更できます）

アンインストール： npx neuromcp-enable-consolidation --uninstall

実行間隔の変更： npx neuromcp-enable-consolidation --interval 7200（2時間ごと）

ハルシネーション対策（eval-loop）。 統合処理の出力はすべて、Wikiに反映する前に2回目のHaiku監査を受けます。生成された要約に、生のセッションから追跡できない事実の主張が含まれている場合、そのチャンクはWikiではなく ~/.neuromcp/review-queue/ に送られます。ハルシネーションによる主張が混入することはありません。

時間的な置き換えに対応した原子的な事実。 要約が承認されると、短く独立した事実にも分解され、valid_from=today を指定した category='fact' の行として保存されます。同じプロジェクト内で新しい事実が既存の事実とJaccard類似している場合、HaikuがNEWによるOLDの置き換えの要否を判断します。置き換える場合、古い行には superseded_by_id と valid_to が設定されます。検索ではデフォルトで現在有効な事実のみ（superseded_by_id IS NULL）が対象となるため、古い結論が再び表示されることはありません。

自動検索＋ハイブリッドインデックス

Wikiにコンテンツを追加したら、UserPromptSubmit フックが関連ページを自動的に提示できるよう、検索可能にします（「LLMがsearchを呼び出すのを覚えていなければならない」という問題がなくなります）。

npx neuromcp-index-wiki              # index wiki pages into memories_fts + memories_vec
npx neuromcp-index-wiki --rebuild    # wipe wiki entries first, then reindex
npx neuromcp-index-wiki --dry-run    # preview what would change
npx neuromcp-index-wiki --no-embed   # FTS-only mode (no embedding provider needed)

npx neuromcp-backfill-embeddings     # embed any memory still missing a vector

インデクサーは各ページを##のセクション見出しで分割し、各セクションを重複排除されたメモリ（source='wiki'、category='wiki'）として保存します。各セクションはFTS5インデックスに書き込まれると同時に、設定済みのプロバイダー（Ollama → OpenAI → ONNX）で埋め込みが生成されるため、ベクトル検索も機能します。

プロンプトの処理時に、neuromcp-auto-retrieve.jsフックがneuromcp-queryを呼び出します。neuromcp-queryはFTS5 BM25とsqlite-vecのコサイン検索を並行して実行し、Reciprocal Rank Fusion（k=60）で順位を統合します。統合後の上位3件は、<neuromcp-recall>コンテキストとして挿入されます。

このフックはneuromcp-init-wikiによって自動的にインストールされ、Claude Codeのsettings.jsonでUserPromptSubmitに登録されます。Wikiを大幅に更新した後は、インデクサーを再実行してください（スケジュール実行も可能で、冪等です）。

調整項目：

環境変数	デフォルト	用途
NEUROMCP_BM25_THRESHOLD	-1.0	より厳格（より負の値）にすると、関連性の低いキーワード一致が減ります
NEUROMCP_QUERY_BIN	自動検出	neuromcp-queryバイナリのパスを上書きします
NEUROMCP_NO_EMBED	0	1に設定すると、FTSのみのインデックス作成を強制します
NEUROMCP_CONTRADICTION_CHECK	1	0に設定すると、Haikuによる新旧情報の判定をスキップします
NEUROMCP_AUDIT_FAIL_OPEN	0	1に設定すると、インフラストラクチャ障害時に統合監査をバイパスします（デフォルトではフェイルクローズです）

既知の上流の問題

memories_vecはDELETE後に容量を回収しません — sqlite-vec #54 / #265。Wikiのセクションを編集して再インデックスすると、古いベクトルの行は削除済みとしてマークされますが、そのストレージは残ります。npx neuromcp-index-wiki --rebuildを実行してベクトルの行を削除・再作成するまで、データベースファイルは単調に増大します。Wikiを頻繁に編集する場合は、数週間ごとに再構築を実行してください。

macOSでは、TTY以外のサブプロセスからclaude CLIのストリーミングを実行すると停止します — 別のプロセス（スケジュールされたジョブなど）からclaude -pを使ったやり取りをスクリプト化する場合は、script -q /dev/nullを介して疑似TTYを割り当ててください。そうしないと、stdoutバッファーがフラッシュされません。必要な箇所では、統合処理の内部でこの問題を回避しています。

メモリガバナンス

名前空間を使って、プロジェクト、エージェント、またはドメインごとにメモリを分離します。

信頼レベル（high、medium、low、unverified）によって検索結果をランク付けし、減衰への耐性を制御します。

論理削除ではメモリに削除済みの印を付けます。30日間は復元できます。

コンテンツハッシュ（SHA-256）によって、書き込み時に重複を排除します。

系譜の追跡では、各メモリのソース、プロジェクトID、エージェントIDを記録します。

設定

すべて環境変数で設定します。デフォルト値はほとんどの環境でそのまま使えます。

変数	デフォルト	説明
NEUROMCP_DB_PATH	~/.neuromcp/memory.db	データベースファイルのパス
NEUROMCP_EMBEDDING_PROVIDER	auto	auto、onnx、ollama、openai
NEUROMCP_DEFAULT_NAMESPACE	default	デフォルトの名前空間
NEUROMCP_AUTO_CONSOLIDATE	false	定期的な統合を有効にします
NEUROMCP_TOMBSTONE_TTL_DAYS	30	完全削除までの日数
NEUROMCP_LOG_LEVEL	info	debug、info、warn、error
NEUROMCP_MODEL_DIR	~/.neuromcp/models	ONNXフォールバックモデルのキャッシュ先
NEUROMCP_DISABLE_MODEL_DOWNLOAD	未設定	1に設定すると、初回実行時の遅延モデルダウンロードを禁止します
NEUROMCP_STRICT_EMBEDDINGS	未設定	1に設定すると、劣化モードで起動する代わりに、インデックスとプロバイダーの不一致時にクラッシュします
NEUROMCP_EMBEDDING_RETRY_ATTEMPTS	3	劣化モードに移行するまでのプロバイダー切り替えの試行回数
NEUROMCP_EMBEDDING_RETRY_BASE_MS	500	最初のバックオフ遅延（試行ごとに倍増）

新機能

全履歴はCHANGELOG.mdをご覧ください。最近の主な変更点：

• v0.29 — あらゆる場面での現在有効性: デフォルトですべての読み取り経路から置き換え済みのメモリを非表示にします（オプトインするには include_superseded / valid_at を指定）。強制指向グラフとタイムラインを備えた組み込みのウェブメモリブラウザー、Obsidian ブリッジと非破壊的な Vault シード、コールドブート時の競合を修正（デーモンがプロセス開始時にポートをバインド）、neuromcp-doctor と neuromcp-connect が設定済みポートでデーモンを検出、埋め込みプロバイダーを切り替えても既存データベースが使用不能にならない（neuromcp-reembed、縮退モード）、Trusted Publishing による npm リリース（トークン不要）、システム自身の矛盾処理によってグラフ概要が汚染されないよう修正。
• v0.28 — neuromcp-init によるワンコマンドセットアップ（クライアントを検出し、バックアップ付きで設定を書き込み）、neuromcp-doctor を実用的なトリアージツールとして再構築、自動生成される docs/TOOLS.md + docs/BENCHMARK.md、クライアント設定の examples/、保存時の名前空間プッシュダウン、エンティティのプレフィックスマージに証拠が必要に。
• v0.27 — セキュリティリリース：wiki_ingest の CWE-22 パストラバーサル修正、デーモンでの MCP 仕様に準拠した Origin 検証、起動競合に安全な neuromcp-connect の Claude Desktop ブリッジ、ランタイムのヘルスチェックフック。
• v0.26 — recall_answer（引用とギャップ分析を含む決定論的な抽出的回答。読み取り経路で LLM を使用しません）、オプションのローカルクロスエンコーダー・リランカー（正直な A/B テストを経て、デフォルトでは無効）、想起品質の正確性を総点検。
• v0.20–0.25 — 共有 HTTP デーモン、セッション分離、批評フック、エンティティ重複排除の正規化、妨害要素ベンチマークの強化。

説明モード

すべての search_memory 結果に explain フィールドが含まれるため、システムが何を記憶しているのか、なぜそれを提示したのかを監査できます。

{
  "explain": {
    "source_trust": { "level": "high", "reason": "Directly provided by user" },
    "temporal_validity": { "currently_valid": true, "superseded_by": null },
    "contradictions": [{ "memory_id": "abc", "content_preview": "...", "resolution": "coexist" }],
    "claims": [{ "subject": "neuromcp", "predicate": "version", "object": "0.26.0" }],
    "confidence": { "retrieval_score": 0.016, "source_trust_score": 1.0, "overall": 0.85 }
  }
}

矛盾の解決は3段階で行われます。グラフに影響する2つの段階では、主張レベルの証拠が必要です。つまり、同じ主語、相互排他的な述語（is、uses、runs など。src/config/predicate-classes.json を参照）、異なる目的語です。置き換え（証拠 + ヒューリスティックスコア > 0.5：古いメモリを無効化）、共存（証拠 + スコアが (0.3, 0.5]：両方を保持し、contradicts グラフエッジでリンク）、フラグ付け（ヒューリスティックな兆候のみ — 数値の差、否定語など。レビュー用に store_memory の結果で報告され、グラフには反映されません）。キーワードヒューリスティクスだけでメモリを無効化したり、矛盾を断定したりすることは決してありません。誤った判定は、後続のすべての LLM にとって幻覚の原因となるからです。

トラブルシューティング

npx neuromcp-doctor check          # human-readable report
npx neuromcp-doctor check --json   # same checks, machine-readable

1回の実行で、Node のバージョン、ネイティブモジュールが実際に読み込み可能か（better-sqlite3、sqlite-vec）、データベースを開けるか、共有デーモンの /health、Ollama に到達できるかと nomic-embed-text がプル済みか、ONNX フォールバックモデルが存在するか、データベースのベクトルインデックスがこのマシンから到達できるプロバイダーと引き続き一致しているかを確認します。終了コード：正常なら 0、縮退状態なら 1（例：Ollama がなく、ONNX フォールバックが有効）、異常なら 2。バグ報告には、まずその出力を添えてください。

「埋め込み次元の不一致」／ベクトル検索が無効

ベクトルインデックスは幅が固定された vec0 テーブルです。ONNX フォールバックでは 384、Ollama の nomic-embed-text では 768 です。プロバイダーが変わると（フォールバックで動作させた後に Ollama をインストールした場合や、Ollama が停止し auto の連鎖処理が ONNX に切り替わった場合）、新しいプロバイダーは古いインデックスに書き込めません。

0.29.3 以降、この問題でサーバーが停止することはありません。次のように動作します。

1. 既存のインデックスに一致するプロバイダーを優先します。
2. 一時的に利用できないプロバイダーを、バックオフを伴って再試行します。
3. それ以外の場合は縮退モードで起動します。全文検索は引き続き利用できますが、ベクトル検索は無効になり、新しいメモリは埋め込みなしで保存され、backfill_embeddings 用のキューに入ります。何も削除されず、インデックスが知らないうちに再構築されることもありません。

neuromcp-doctor check で状態を確認できます。ベクトル検索を復旧するには、次のいずれかを選んでください。

# a) restore the provider that matches the index
ollama serve && ollama pull nomic-embed-text      # 768-dim index
# or force the fallback for a 384-dim index:
export NEUROMCP_EMBEDDING_PROVIDER=onnx

# b) rebuild the index for the provider you want (works on a COPY first)
npx neuromcp-reembed                 # dry run: rebuild a copy, report, discard
npx neuromcp-reembed --keep-copy     # same, but keep the copy to inspect
npx neuromcp-reembed --apply         # swap it in; original kept as *.pre-reembed-<ts>

--apply を実行する前に、すべてのクライアントを停止してください。ロールバックはファイルを元の場所に戻すだけです。

Xcode をインストールしない場合／インストールスクリプトが無効な場合

better-sqlite3 は、インストールスクリプトからビルド済みバイナリを取得します。 npm install --ignore-scripts（または強化された .npmrc、pnpm の ビルド許可リスト）を使用すると、パッケージはインストールされますが、ネイティブバインディングがなく、 何も動作しません。npm 11 のデフォルト設定は ignore-scripts=false なので、通常の インストールで問題ありません：

npm install -g neuromcp                      # normal path, scripts run
npm install -g neuromcp --ignore-scripts=false   # if your .npmrc disables them

スクリプトを無効にしてすでにインストールした場合は、上記の手順で再インストールしてください（グローバルプレフィックスで単に npm rebuild を実行しても、バインディングが確実に生成されるとは限りません）。

約 33 MB の ONNX フォールバックモデルは、postinstall に依存しなくなりました。 初回使用時に ~/.neuromcp/models へ遅延ダウンロードされます（パッケージが root 所有のグローバルプレフィックスにあっても、ユーザーが書き込めます）。 事前に取得するには npx neuromcp-download-model を実行するか、 ダウンロードを完全に禁止するには NEUROMCP_DISABLE_MODEL_DOWNLOAD=1 を設定してください。

比較

機能	neuromcp	Hindsight	Mem0	Letta/MemGPT	agentmemory
LongMemEval R@5（オラクル）	99.8%	—	—	—	—
LongMemEval R@5（1000 件の妨害項目、n=5、Ollama）	100%（暫定、CI [57%, 100%]）	未公開	未公開	未公開	未公開
検索	ハイブリッド（ベクトル + FTS + RRF + グラフ）	ベクトル + 再ランキング	ベクトル	ベクトル	ベクトル
自動記録	決定論的（LLM コストなし）	LLM による抽出	なし	エージェントによる自己編集	あり
説明モード	あり（信頼度、矛盾、主張）	なし	なし	なし	なし
ナレッジグラフ	エンティティ、関係、PageRank	エンティティ + 信念	なし	なし	なし
矛盾の検出	3 段階（置換／共存／フラグ付け）+ グラフエッジ	信念の更新	なし	なし	なし
時間的な有効性	メモリと関係に valid_from/valid_to	あり	なし	なし	なし
Wiki ナレッジベース	コンパイル済み Markdown + Git	なし	なし	階層型ブロック	なし
ローカルファースト	SQLite、クラウド不要	SQLite	クラウド / Postgres	サーバー	ローカル
埋め込み	組み込み ONNX（設定不要）+ Ollama	外部	外部 API	外部	外部
ガバナンス	名前空間、信頼レベル、ソフト削除	名前空間	API キー	エージェント単位	エージェント間
インフラストラクチャ	不要	不要	クラウドアカウント	サーバー	不要
価格	無料（AGPL-3.0）	無料（MIT）	フリーミアム（2,390 万ドル調達）	無料（1,000 万ドル調達）	無料（Apache-2.0）

ライセンス

src/ のエンジンには AGPL-3.0 が適用されます。bin/、templates/、 scripts/、docs/、examples/ には MIT が適用されます（例外規定については LICENSE-EXAMPLES を参照してください）。

ライセンスに関するよくある質問

neuromcp を商用利用できますか？ はい。neuromcp を独自のアプリケーションの一部として、 独自のインフラストラクチャで実行することに制限はありません。AGPL による義務が生じるのは、エンジンのコードを 変更し、さらにそれを配布するか、ネットワークサービスとしてホストする場合のみです。

クローズドソース製品に npm から neuromcp をインストールできますか？ はい。公開済みの バイナリを依存関係として使用しても、AGPL の感染性は発生しません。

neuromcp を SaaS としてホストする場合はどうなりますか？ その場合は AGPL §13 が適用されます。ソースコード（変更内容を含む）を ユーザーに提供する必要があります。これは、エンジンに適用するために選んだ、明示的なフォーク防止条項です。十分な資金を持つ競合他社がコードを取得し、ログインの背後に置いて、 自社製品として提供することを防ぎます。

CLI スクリプトやテンプレートをコピーできますか？ はい。bin/、 templates/、scripts/、docs/、examples/ のすべては AGPL-3.0 または MIT のデュアルライセンスです。派生プロジェクトでは MIT を選択できます。

エンジンに別のライセンス条件が必要ですか？ 商用デュアルライセンスをご利用いただけます。メンテナーにお問い合わせください。