NeuroStack

お手持ちのMarkdownナレッジベース向けの、ローカル検索レイヤー兼オプティマイザーです。

NeuroStackは.mdファイル（Obsidian、Logseq、Notionのエクスポート、プレーンなMarkdown）のフォルダーを、全文検索、埋め込み、Wikiリンクグラフを備えた1つのSQLiteデータベースにインデックス化します。任意のMCPクライアントから検索やグラフの探索、メモリーの保存ができます。クエリはノートのパスとともにランク付けされた根拠を返し、推論はAIが行うため、待機中にモデルが実行されることはありません。クエリの合間も、NeuroStackはナレッジベースの正確さを保ちます。古くなったノートにフラグを付け、AIとのセッションから決定事項や根本原因を抽出し、繰り返し現れるメモリーを統合して学習内容にまとめ、実証された学習内容をノート化するためのキューに追加します。インデックス作成によってファイルが変更されることはありません。また、オプションのMCP書き込みツールを使えば、クライアントからGitの履歴を通じてノートを編集できます。

Claude、Cursor、Windsurf、Gemini CLI、VS Code、Codex、およびMCPをサポートするその他のクライアントで動作します。

60秒で開始

npm install -g neurostack          # install
neurostack init                    # pick your notes folder, press Enter for the rest
/save                              # in omp or Claude Code, keep what this session learned
neurostack doctor                  # check that everything works

以下の手順では、それぞれの操作と、ほかのAIクライアントの接続方法を説明します。

ノートは自分で管理

NeuroStackはデフォルトで読み取り専用のインデックスレイヤーです。

• インデックス作成、検索、要約、グラフ分析によって、Markdownファイルが変更されることはありません
• インデックスデータはすべて、NeuroStack専用の独立したデータベースに保存されます
• 完全に削除するには、neurostack uninstallを実行します。ノートはそのまま残ります。
• 要約と埋め込みにサードパーティーのLLMプロバイダーを設定しない限り、データがマシンの外に送信されることはありません

VaultがGitリポジトリの場合、オプトインのMCP書き込みツール4つを使って、AIクライアントからノートを作成・編集できます。ツールはvault_write_file、vault_delete_file、vault_read_file、vault_list_filesです。書き込みはすべて、説明的なメッセージとともにGitリモートへコミットしてプッシュされるため、変更はすべてgit logで確認でき、git revertで取り消せます。また、Vaultごとのロックによって処理が直列化されます。無効なフロントマター、Vault外のパス、非表示ディレクトリ（.git、.obsidianなど）への書き込みは拒否されます。neurostack serveと通信する任意のクライアントにこれらのツールが公開されるため、MCPエンドポイントをパブリックインターネット上に設置する場合は、トランスポート側でアクセスを制限してください（認証、トンネル、LAN限定など）。

対象ユーザー

開発者である必要はありません。Markdownでノートを取っている方や、Obsidian、Notion、Bear、RoamからMarkdown形式でノートをエクスポートできる方なら、NeuroStackをお使いいただけます。

3 つのステップで始めましょう

Node.js をインストールしておく必要があります（ほとんどのコンピューターにはすでにインストールされています）。npm パッケージが Python のセットアップを代行します。

ステップ 1．インストール

npm install -g neurostack

ステップ 2．セットアップ（約 2 分かかります）

neurostack init

セットアップウィザードでは、インデックスを作成する Vault フォルダー、実行モード（Lite または Full）、適用する職業パックを選択します。その後、インストールが完了します。omp または Claude Code がインストールされている場合は NeuroStack フックを追加し、/save でセッションから学んだことを保存できるようにします。保存したセッションをメモリに変換する AI もセットアップします。これは要約に使うモデルと同じモデルを使用します。まだ応答するモデルがない場合は、この機能を無効のままにして、その旨をお知らせします。インデックスを適切な状態に保つバックグラウンドタイマーを 1 つインストールします。バックグラウンドジョブに失敗すると、デスクトップ通知が表示されます。各質問で Enter キーを押すと、デフォルト値が選択されます。最後に neurostack doctor を実行し、最初に試すことを表示します。

ステップ 3．AI に接続

Claude Desktop の場合：

neurostack setup-desktop

Claude Code の場合：

claude mcp add neurostack -- neurostack serve

Cursor、Windsurf、Gemini CLI、または VS Code の場合：

neurostack setup-client cursor      # or: windsurf, gemini, vscode

これで完了です。新しい会話を開き、ノートにある内容について AI に質問してください。

neurostack init --mode lite ~/my-notes --yes    # lite mode
neurostack init --mode full ~/my-notes --yes    # full mode

# PyPI
pipx install neurostack
pip install neurostack        # inside a venv
uv tool install neurostack

# One-line script
curl -fsSL https://raw.githubusercontent.com/raphasouthall/neurostack/main/install.sh | bash

# Lite mode (no ML deps)
curl -fsSL https://raw.githubusercontent.com/raphasouthall/neurostack/main/install.sh | NEUROSTACK_MODE=lite bash

機能

• 深さを段階的に調整できるハイブリッド検索（FTS5 のキーワード検索＋セマンティック検索）により、クライアントはトークン予算に応じてトリプル、要約、またはノート全文を取得できます。
• CLI、MCP、または OpenAI 互換 API を通じて、ノートのパスと抜粋を含む根拠をランキングし、AI が引用して推論できるようにします。
• 古さを検出します。現在の状況に合わない文脈で繰り返し表示されるノートにはフラグが付けられ、以降の結果で順位が下がります。
• セッションの収集。タイマーが Claude Code、Codex、Gemini、omp のトランスクリプトをスキャンし、決定事項、バグ、規約、学習内容を TTL 付きのメモリとして保存します。
• 統合と昇格。繰り返し現れるメモリは学習内容になり、昇格キューにはノート化の準備ができたものが一覧表示されます。
• PageRank、コミュニティ検出、ギャップ分析、ブリッジ分析を備えた Wiki リンクグラフ。
• デフォルトでは読み取り専用です。書き込みツールをオプトインすると、変更のたびに git のリモートへコミットしてプッシュします。

設計

基本理念

1. ファイルはあなたのものです。インデックスは独立したデータベースに保存されるため、削除してもノートには一切影響しません。
2. NeuroStack は根拠を返し、AI がそれをもとに推論します。ツールが質問に答えることはなく、tests/test_no_answering.py がこの仕組みを維持します。
3. メモリーを削除すると、検索対象外のアーカイブに移動します。後から復元することもできます。
4. NeuroStack は、収集した要約など、モデルが書いたテキストから秘密情報をマスキングします。あなたやエージェントが意図的に保存した内容は、一言一句そのまま保存します。
5. ランキングの変更は、まず効果を測定します。neurostack eval の実行中は使用状況に基づく学習が無効になるため、1回の実行が次回の結果を歪めることはありません。

メンタルモデル

NeuroStack は、2つのレイヤーと1つのループで構成されています。

保管庫は、あなたの Markdown ファイルです。NeuroStack はこれを読み込み、チャンクに分割して埋め込みを生成し、各ノートを要約し、事実をトリプルとして抽出して、リンクグラフを構築します。ノートのステータスとタグは NeuroStack 独自の note_metadata テーブルに保存されるため、フロントマターを編集する必要はありません。

メモリーレイヤーには、エージェントが学んだことが格納されます。これらは観察、決定、規約、学び、バグ、コンテキストとして型付けされます。これらの行は NeuroStack に属し、任意のワークスペースと有効期限を設定できます。

オプティマイザーループはタイマーで動作し、この2つをつなぎます。通常、メモリーは AI セッションで始まり、繰り返し現れるようになると学びとなり、既存のノートでカバーされていない場合はノートになります。

アーキテクチャ

flowchart LR
    V[/"Markdown vault<br/>never modified"/] --> IX["index<br/>chunk, embed, summarise,<br/>triples, link graph"]
    IX --> DB[("neurostack.db<br/>SQLite + FTS5")]
    S[/"AI session transcripts"/] --> H["harvest"]
    A["MCP client or CLI"] -->|vault_remember| DB
    H --> DB
    DB --> R["search, tiered, context,<br/>graph, brief"]
    R --> A
    DB --> J["timer jobs<br/>synthesize, promotion,<br/>decay, communities"]
    J --> DB
    J -->|opt-in, git commit| V
    DB --> UI["neurostack ui<br/>read-only dashboard"]

OS のタイマーが1つあり、毎分 neurostack run-due を実行します。このコマンドは、期限が到来した各ジョブを順番に実行します。neurostack serve は stdio または HTTP 経由で33個の MCP ツールを公開し、neurostack api は同じ検索機能を OpenAI 互換 API として提供します。

データモデル

メモリーの行には、内容、タグ、種類、ワークスペース、ソースエージェント、埋め込み、有効期限が保存されます。また、埋め込み生成機能が停止していた場合は embed_pending も記録されるため、後から neurostack backfill で埋め込みを生成できます。さらに、編集と統合のために revision_count と merged_from も記録されます。2つ目のデータベースである sessions.db は、生のセッショントランスクリプトをインデックス化し、neurostack sessions search で検索できるようにします。

書き込みの仕組み

1. 意図的な保存。 vault_remember と neurostack memories add は、書かれたとおりにテキストを保存し、1 回だけ埋め込みを生成してから、類似度が 0.85 を超える近似重複があれば報告しますが、保存は拒否しません。埋め込みに失敗した場合でも行は保存され、バックフィルが必要としてフラグが付けられます。
2. 収集。 インデックス LLM が各セッションのメッセージを読み、決定事項、根本原因、ルール、事実を保持します。2 回目の処理ではセッション全体を読み、session-verdict タグを付けた最終的な結論を最大 3 件保存します。その後、判定モデルが各メモリの種類を選びます。収集では秘密情報を伏せ、稼働中のメモリとの類似度が 0.88 を超えるものを除外し、各セッションで何件のメッセージを読んだかを記録します。
3. 統合。 7 日以上前の観察事項のうち、類似度 0.75 以上でクラスタ化されたもの（アンカー 1 件とその他 3 件以上）は、1 件の学習内容にまとめられます。元の項目は残し、superseded_by:<id> タグが付けられます。
4. 削除。 忘却、マージで採用されなかった側、有効期限切れ、プルーニングはすべて、理由とタイムスタンプとともに行を memories_archive にコピーしてから、稼働中のテーブルから削除する共通のヘルパーを通じて行われます。検索は実行前に有効期限を確認するため、期限切れのメモリが表示されることはありません。
5. Vault への書き込み。 オプトイン方式のツール（vault_write_file、vault_delete_file）と昇格ジョブのみが Vault にアクセスし、いずれも git にコミットしてプッシュします。

読み取りの仕組み

1. ハイブリッド検索。 NeuroStack はキーワード検索と埋め込み検索を個別に実行し、それぞれから上位 50 個のチャンクを取得して、逆順位（k = 60）で 2 つのリストをマージします。片方の検索でしか見つからなかったチャンクも、ほかの結果と競合します。その後、収束ボーナス、呼び出し元のコンテキストに対する 1.4 倍のブースト、使用頻度と共起による加点を加え、古いとフラグが付いたノートの順位を下げます。
2. 多様性。 結果にはノートごとに 1 つのチャンクのみが含まれ、類似したノート同士は互いに抑制されるため、長いノート 1 つで結果リストが埋まることはありません。
3. 段階的な詳細度。 クライアントはトリプル（約 15 トークン）、要約（約 75 トークン）、または完全なノート（約 300 トークン）を要求できます。または、より軽量な段階で不足した場合にのみ auto で詳細度を上げることもできます。
4. コンテキストの組み立て。 vault_context はトークン予算をメモリに 40%、トリプルに 20%、要約に 30%、セッションに 10% 割り当てるため、特定の情報源がほかを圧迫することはありません。
5. 厳格な上限。 どの検索でも返される結果は最大 top_k 件です。rerank=True を渡さない限り、LLM を呼び出す検索経路はありません（下記参照）。

任意の再ランキング。 vault_search(rerank=True) は判定モデルに各ノート全体の結果をクエリに照らして採点させ、判定モデルの順位で返します。実際の検索クリック 76 件では、MRR が 0.503 から 0.652 に、上位 1 件の的中率が 34% から 49% に、上位 3 件の的中率が 57% から 75% に向上しました（対応のある置換検定 p=0.004）。検索 1 回あたりのコストは約 $0.0004 で、約 0.4 秒追加されます。depth="full" または reference_only=True で動作し、それ以外の詳細度ではエラーになります。判定モデルが失敗した場合は、通常の順位が返されます。

使用頻度が高いノートほど、再び見つけやすくなります。使用頻度によって、ノートが真実だと判定されることはありません。

既知の制限事項

• 収集されたメモリには、まだワークスペースが記録されないため、ワークスペース単位の検索では見つかりません。
• 収集されたメモリは、元になったセッションやメッセージにリンクされません。
• 重複チェックが稼働中のメモリのみを参照するため、後のセッションで同じ内容が述べられると、忘れたメモリが再び追加されることがあります。
• メモリを編集するとテキストが置き換えられ、変更があったことを示すのは revision_count のみです。

外部サービス

ライトモードでは、以下のサービスは不要です。以下の設定はすべて任意で、~/.config/neurostack/config.toml に記述できます。それぞれに対応する NEUROSTACK_* 環境変数もあります。サービスが利用できない場合、それを必要とする機能は無効になり、ほかの機能は引き続き動作します。

ノートのテキストを参照するのは、埋め込みモデルとインデックス用 LLM だけです。判定モデルが参照するのは、クエリ、メモリー、およびランク付けやチェックの対象となるノートです。すべてのデータをマシン上に保つには、すべての URL を localhost に設定してください。

他との違い

NeuroStack は Obsidian、Notion、その他のノートアプリの代替ではありません。現在お使いのツールの上に追加し、それらにない機能を提供します。

古い情報の検出は、ほかのツールにない機能です。非推奨の API や、より新しい論文に置き換えられた論文のように、ノートが適合しなくなったコンテキストに繰り返し表示されると、NeuroStack はそのノートにフラグを付け、以降の検索結果で順位を下げます。

職業別パック

neurostack init を実行すると、職業別パックを選択します。それぞれのパックは、実際の職業でのノートの使い方に合わせたテンプレート、フォルダー構成、AI 向けガイダンスを NeuroStack に設定します。

ノートを失うことなく、既存の保管庫にパックを適用できます。

neurostack scaffold researcher ~/my-notes    # or: writer, student, developer, devops, data-scientist

既存の Markdown ディレクトリをインポートすることもできます。

neurostack onboard ~/my-notes

検索の仕組み

多くのメモリツールは、AI に大量のテキストを渡し、関連する情報を判断させます。NeuroStack は段階的に検索します。質問に答えるために必要な、最も低コストの検索から始め、必要な場合にのみ段階を上げます。

単純な事実に関する質問は、約 15 トークンで解決します。詳細な調査では、完全なコンテキストを取得します。AI は、重要なところに注意の予算を使います。

AI が決定を記憶します

セッションをまたいで、AI は観察事項、決定事項、規約、学び、バグなどの型付きメモリを保存し、取得できます。新しいセッションを開始すると、これらのメモリが自動的に表示されます。

「認証はステートレスにすることにしました。」 「論文の枠組みは、統合から補完的な学習システムへと変わりました。」 「第 7 章の改訂で、Elena の姓が Vasquez から Reyes に変わりました。」

これは単なるノートではありません。AI が、あなたと一緒に決めたこととして記憶する内容です。/clear の後も残ります。ターミナルを閉じても残ります。マシンを切り替えても残ります。

neurostack memories add "revised thesis framing to CLS, not just consolidation" --type decision --tags "thesis,neuroscience"
neurostack memories search "thesis direction"

AI セッションから学習します

NeuroStack はタイマーで過去の AI との会話をスキャンし、決定事項、観察事項、学びを抽出して、メモリとして保存します。自分で書き留める必要はありません。

neurostack harvest --sessions 5          # extract insights from last 5 sessions
neurostack schedule install              # one timer runs due jobs every minute

Claude Code、VS Code、Codex CLI、Aider、Gemini CLI のセッション形式に対応しています。

常に最新の状態を保ちます

保管庫の内容は変化します。NeuroStack はそれを監視します。

neurostack watch     # auto-index on vault changes

インデックスは執筆に合わせて更新され、古くなった情報の検出も継続的に実行されるため、手作業で管理する必要はありません。

スケジュール

NeuroStack は、1 つの OS タイマーからバックグラウンドジョブを実行します。タイマーは 1 分に 1 回 neurostack run-due を呼び出し、run-due は実行時刻になったジョブを判定して、1 つずつ実行します。neurostack init を実行すると、タイマーがインストールされます。インストール時に、各日次ジョブは実行済みとして記録されるため、すべてのジョブが一斉に実行されるのではなく、次のスケジュール時刻から開始されます。以下のコマンドを使うと、手動でタイマーを管理できます。

neurostack schedule install   # install or overwrite the timer
neurostack schedule status    # show whether the timer is active
neurostack schedule remove    # remove the timer

schedule install は、お使いの OS に標準で付属するスケジューラーを使用します。

タイマーは、インストール時に PATH 上で見つかった neurostack 実行ファイルを呼び出すため、NeuroStack の移動後または再インストール後に、もう一度 schedule install を実行してください。3 つのサブコマンドはいずれも --json を受け付けます。

systemd ユーザータイマーは、ログインセッション中にのみ実行されます。ヘッドレス Linux サーバー上で実行する場合、または NeuroStack を root として実行する場合は、ログアウト後もタイマーが動作し続けるように、そのユーザーの lingering を有効にしてください。

sudo loginctl enable-linger <user>

neurostack doctor を実行すると、各ジョブが最後に実行された時刻を確認できます。

ラップトップとサーバー間のチェックポイント

ラップトップで /save を実行すると、セッションのトランスクリプトがサーバーのキューにアップロードされます。サーバーの checkpoint-worker ジョブは 1 分以内にそれをメモリに変換し、harvest-worker は harvest-scan が 30 分ごとにアップロードするトランスクリプトにも同じ処理を行います。各ホストは、それぞれのファイルを読み込みます。

ラップトップでは、~/.config/neurostack/client.toml でサーバーを指定します。checkpoint_command を設定すると、harvest-scan が有効になり、手動で開始する hook checkpoint --run も提供されます。

url = "http://my-server:8001/mcp"
checkpoint_command = "claude -p --model haiku"

フックは、セッションの概要とプロンプトごとのコンテキストを取得するために最大 context_timeout_s（15 秒）、各ツール呼び出しで最大 timeout_s（5 秒）待機するため、サーバーが停止していてもツール呼び出しが滞ることはありません。

サーバーでは、~/.config/neurostack/config.toml に、ワーカーが各チェックポイントのプロンプトをパイプで渡すコマンドを設定します。標準入力からプロンプトを読み取り、モデルの応答を出力するコマンドであれば使用できるため、OpenAI 互換エンドポイントやローカルプロキシを呼び出すこともできます。

checkpoint_command = '''jq -Rs '{model: "qwen/qwen3-30b-a3b", messages: [{role: "user", content: .}]}' \
  | curl -s https://openrouter.ai/api/v1/chat/completions \
      -H "Authorization: Bearer $OPENROUTER_API_KEY" -H "Content-Type: application/json" -d @- \
  | jq -r '.choices[0].message.content' '''
checkpoint_timeout_s = 300     # per checkpoint
checkpoint_max_messages = 40   # largest window one checkpoint summarizes, 0 for no cap

NEUROSTACK_CHECKPOINT_COMMAND、NEUROSTACK_CHECKPOINT_TIMEOUT_S、NEUROSTACK_CHECKPOINT_MAX_MESSAGES を設定すると、それぞれの値を上書きできます。config.toml に checkpoint_command が設定されていない場合、neurostack jobs は両方のワーカーがオフであることと、その理由を表示します。

ダッシュボード

neurostack ui は、http://127.0.0.1:8765 で読み取り専用のダッシュボードを提供します。6 つのページが表示されます。Overview には、インデックスのカバー率、コミュニティ、最近のノート、メモリー数が表示されます。Automations には、スケジュールされたすべてのジョブが、直近の実行、次回の実行、過去 14 回分の実行履歴とともに表示され、ジョブをクリックするとその実行履歴を確認できます。Graph には、PageRank 上位のノートが描画され、ノードをクリックすると概要とリンクが開きます。Memories には、タイプ別のタブと検索機能とともにメモリーが表示されます。Search では、vault_search ツールと vault_memories ツールが受け取るすべてのオプションを指定して、ノートとメモリーを検索できます。ノートの場合は、mode、depth、result count、workspace、context boost、max tokens、judge rerank、reference-only、メモリーの場合は、type、workspace、count を指定できます。ここで検索するとクエリが埋め込まれるため、埋め込みモデルが必要です。また、ノートの使用回数にはカウントされません。各ノートの検索結果には「Best result」ボタンがあり、検索とノートをラベルとして保存します。Tuning では、こうしたラベルとフィードバックループが推定したラベルを使って重みを調整します。半分のデータで調整し、残り半分でスコアを評価します。Apply を実行すると、未使用の半分でより上位にランク付けできた場合に限り、最適な重みがすべての検索で使われます。Revert すると config.toml の設定に戻ります。ダッシュボードで書き込みが発生するのは、適用とラベル付けだけです。

追加のインストールは不要で、モデル呼び出しも行いません。ポートを変更するには --port を、ブラウザーを開くには --open を指定します。localhost 以外のアドレスで使う場合は、まず neurostack ui user add NAME でログインユーザーを作成してください。このコマンドでは 8 文字以上のパスワードを求められます（--password-stdin を指定すると、パイプから読み取ります）。ページにサインインフォームが表示され、セッションは 30 日間有効です。neurostack ui user list でユーザーを確認でき、neurostack ui user remove NAME でユーザーを削除して、そのセッションを終了できます。

日々の作業で変わること

Vault の保存方法

~/your-vault/                           # your Markdown files (not modified by indexing; AI clients can edit via opt-in MCP write tools)
~/.config/neurostack/config.toml        # configuration
~/.local/share/neurostack/
    neurostack.db                       # SQLite + FTS5 knowledge graph
    sessions.db                         # session transcript index

NeuroStack は Vault を読み取ります。デフォルトでは何も書き戻さず、すべてのインデックスデータは独自の SQLite データベースに保存されます。オプトインの MCP 書き込みツール（vault_write_file / vault_delete_file）だけは例外です。これらは Vault 内の .md ファイルを作成または編集し、変更をその場で git リモートにコミットしてプッシュします。

メモリーの書き戻し（オプトイン）

メモリーはデフォルトで SQLite に保存されるため、Obsidian からは見えず、データベースが失われると消えてしまいます。書き戻しを有効にすると、条件を満たすメモリーが自分で管理する Markdown ファイルとして永続化されます。

[writeback]
enabled = true                 # opt-in; default false
path = ".neurostack"           # quarantine dir, relative to vault_root
include_observations = false   # also write the noisier observation/context types

• ファイルは {vault_root}/.neurostack/memories/<type>/<YYYY-MM>/<uuid>.md 以下に保存されます。NeuroStack が書き込むのはこのディレクトリだけなので、自分のノートには手を加えません。
• 永続的（TTL なし）な decision / convention / learning / bug メモリーだけが書き込まれます。一時的（TTL あり）なメモリーは書き込まれません。
• データベースが信頼できる唯一の情報源であり、ファイルは読み取り可能なエクスポートです。vault_remember / vault_update_memory / vault_forget / vault_merge を使うと、ファイルも自動的に同期されます。
• このディレクトリには独自の .gitignore があるため、オプトインするまではメモリーが git に含まれません（バージョン管理するには、このファイルを削除してください）。NeuroStack が代わりにコミットすることはありません。
• neurostack migrate write-back [--dry-run] は既存のメモリーをエクスポートします。neurostack sync はファイルと DB を照合して整合させます（競合した場合は DB が優先されます）。

# Setup
neurostack init                          # one-command setup: deps, vault, index
neurostack init --mode full ~/brain      # non-interactive full mode
neurostack onboard ~/my-notes            # import existing Markdown notes
neurostack scaffold researcher           # apply a profession pack
neurostack scaffold --list               # see all packs
neurostack update                        # pull latest source + re-sync deps
neurostack uninstall                     # complete removal

# Search & retrieval
neurostack search "query"                # hybrid search
neurostack tiered "query"                # tiered: triples -> summaries -> full
neurostack triples "query"               # knowledge graph triples
neurostack summary "note.md"             # AI-generated note summary
neurostack related "note.md"             # semantically similar notes
neurostack graph "note.md"               # wiki-link neighborhood
neurostack communities query "topic"     # GraphRAG across topic clusters
neurostack context "task" --budget 2000  # task-scoped context recovery
neurostack brief                         # session briefing

# Maintenance
neurostack index                         # build/rebuild knowledge graph
neurostack watch                         # auto-index on vault changes
neurostack decay                         # excitability report
neurostack prediction-errors             # stale note detection
neurostack backfill [summaries|triples|all]
neurostack communities build             # rebuild topic clusters
neurostack reembed-chunks                # re-embed all chunks
neurostack export --include triples -o dump.json  # dump index data as JSON

# Memories
neurostack memories add "text" --type observation
neurostack memories search "query"
neurostack memories list
neurostack memories update <id> --content "revised"
neurostack memories merge <target> <source>
neurostack memories forget <id>
neurostack memories prune --expired

# Sessions
neurostack harvest --sessions 5          # extract session insights
neurostack sessions search "query"       # search transcripts

# Scheduled jobs: one OS timer (systemd, launchd, or Task Scheduler) runs `neurostack run-due`
neurostack schedule install              # install or overwrite the timer
neurostack schedule status               # is the timer active?
neurostack schedule remove
neurostack run-due                       # what the timer calls: run each due job once
neurostack jobs                          # schedule, last run, and next due per job

# Harness hooks (session brief, auto-RAG, trigger memories, checkpoints)
neurostack hooks install --harness claude   # or: omp
neurostack hooks status

# Trigger memories: did the warnings change anything?
neurostack triggers stats                # fired, followed, ignored per memory (30d)
neurostack triggers stats --days 7

# Checkpoint: manual only — a harness never fires one on its own (issue #176).
# `/save` (both harnesses) queues a request instead of running one directly:
neurostack hook enqueue --harness claude    # or: omp — uploads the transcript to the server's queue
neurostack hook checkpoint --run --session <id>  # run one checkpoint by hand on this host
neurostack hook checkpoint --save               # a model's JSON reply on stdin

# Client setup
neurostack setup-client cursor           # or: windsurf, gemini, vscode, claude-code
neurostack setup-client --list
neurostack setup-desktop                 # Claude Desktop

# Diagnostics
neurostack stats                         # index health
neurostack doctor                        # validate all subsystems
neurostack demo                          # interactive demo with sample vault

よくある質問

ボルトのファイルは変更されますか？ デフォルトでは変更されません。インデックス作成、検索、要約、およびすべての読み取りツールはファイルに変更を加えません。すべてのインデックスデータは NeuroStack 独自の SQLite データベースに保存されます。オプトインで使用できる 4 つの MCP 書き込みツール（vault_write_file、vault_delete_file、vault_read_file、vault_list_files）を使うと、AI クライアントからノートを作成・編集できます。すべての書き込みはコミットされ、git リモートにプッシュされるため、変更の追跡や取り消しが可能です。ボルトが git リポジトリでない場合、ファイルはディスクに書き込まれますが、コミットの手順はスキップされます。これとは別に、オプトインのメモリ書き戻しでは、メモリを Markdown として保存しますが、保存先は自分のノートとは別の隔離された .neurostack/ ディレクトリ内に限られます。

GPU は必要ですか？ いいえ。Lite モードには ML の依存関係がありません。Full モードは CPU で動作しますが、GPU がないと要約に時間がかかります。

Python の知識は必要ですか？ いいえ。npm パッケージがすべて処理します。仮想環境を操作する必要はありません。

どのくらいの規模のボルトに対応できますか？ 約 5,000 件のノートでテスト済みです。FTS5 検索は、どの規模でも高速に動作します。

AI クライアントなしでも使えますか？ はい。CLI は単独で動作し、任意の LLM にパイプで接続できます。

ボルトのプライバシーは保護されますか？ はい。ローカルの Ollama の代わりに、Full モードをサードパーティの LLM プロバイダーに接続しない限り、データが端末の外に出ることはありません。その場合、インデックス化するテキストは、そのプロバイダー独自のポリシーに基づいてプロバイダーに送信されます。

どの AI クライアントで使えますか？ Claude Code、Claude Desktop、Cursor、Windsurf、Gemini CLI、VS Code、Codex、および MCP に対応するその他すべてのクライアントで使えます。

要件

• Linux、macOS、または Windows
• Lite モード： Node.js と Python 3.11 以降。GPU と Ollama は不要です。
• Full モード： nomic-embed-text と要約モデルを備えた Ollama。GPU または 6 コア以上の CPU を推奨します。

はじめに

npm install -g neurostack
neurostack init

neurostack init を実行すると、ティアの選択、依存関係のインストール、ボルトのインデックス作成、MCP クライアントの設定が行われます。

• コントリビューション： CONTRIBUTING.md
• GitHub： github.com/raphasouthall/neurostack
• スポンサー： GitHub Sponsors | Buy me a coffee

Apache-2.0。詳細は LICENSE を参照してください。GPL の依存関係はありません。