brainllm

---

BrainLLM とは？

LLM は忘れてしまいます。セッションが始まるたびに、あなたが誰なのか、何に取り組んでいるのか、昨日何が決まったのか、先週何がうまくいかなかったのか、すべてがゼロから始まります。BrainLLM はその問題を解決します。

BrainLLM は、LLM に実際に永続するメモリーを与える MCP サーバーです。メモリーは、セルフホストして自分で管理できる、成熟したオープンソースのナレッジベースである TriliumNext Notes に保存されます。モデルは各セッションの開始時に、あなたが誰で、現在何が進行中なのかを読み込み、重要な事実が明らかになるとすぐに長期保存できる形で書き込み、知識を型付きグラフとして結び付け、各セッションの終了時にログ、日記の記録、データベースのバックアップを作成します。次のセッションは、前回の終了地点から正確に再開できます。

これは Bun/TypeScript 製の単一サービスで、依存関係は 2 つ（MCP SDK と Zod）です。Trilium とは公開 ETAPI のみを通じて通信します。メモリーは あなた自身の Trilium インスタンスに保存されるため、確認、編集、移行が可能で、ベンダーのブラックボックスに閉じ込められることはありません。

対象ユーザー

コーディング、リサーチ、個人のナレッジ管理、日々の業務の記録などで、単発の Q&A ツールではなく、長期的な協力者として LLM を使っている方を対象としています。毎回説明し直さなくても、自分が誰なのか、何が進行中なのか、何が決まったのかを協力者に覚えていてほしい方に最適です。小規模なサービスと Trilium インスタンスを 1 つずつセルフホストできる方なら、BrainLLM によって「またモデルがすべて忘れてしまった」という問題を解決できます。特定の製品だけでなく、Claude Desktop、Claude Code、その他 MCP を話すあらゆるものなど、MCP 対応のクライアントで利用できます。

実験からオープンソースへ

BrainLLM は 2026 年 2 月、個人的な実験として始まりました。LLM は、実際のセルフホスト環境のメモリを、自身の記憶として信頼できるほど確実に運用できるのか。人間が整理しなくても、状況を把握し、書き込み、関連付け、セッションを終了できるのか。日々継続して本番環境で使用した結果、答えは変わりませんでした。設計は固まり、障害のパターンを見つけて修正し、プロジェクトは実験段階を終え、共有できるほど効率的で安定したものになったため、オープンソースとして公開されました。今も作者自身のセッションで毎日稼働しています。ここで読んでいるのはデモではなく、実際に使われているのと同じコードです。また、今も一人の日常的な使い方を反映した形になっています。それが具体的に何を意味し、何を変更すべきかについては、環境への適応を参照してください。

中核となる原則

モデルが内容を提供し、サーバーが形式を管理します。

配置、命名、ラベル、重複排除、関連付けの管理、ライフサイクルに応じた経年処理、アーカイブ、日付の付与、HTML のサニタイズ、バックアップ、そして構造そのものは、すべて決定論的なサーバー側のポリシーであり、LLM に委ねることはありません。モデルが親ノートを選ぶことも、ラベルを設定することも、重複を確認することも、日付を付与することもありません。この役割分担によってメモリの信頼性が保たれます。あらゆる保証はプロンプトで要求するのではなく、ツール層で強制されます。

設計の主な特長

• 構造は要求するのではなく、強制されます — すべてのコンテンツ種別には、template() が提供し、書き込み時に保持される標準構造があります。新しいスレッドには目標が必要です。スレッド／日記／セッションの各エントリーは、識別行（どの LLM、どの環境、どのセッション種別か）で始まります。スレッドには resolve() が管理する Resolution がちょうど 1 つ含まれ、重複するセクション見出しは検出されます。また、Last updated のタイムスタンプはサーバーが管理します。
• 最初から完成しているドメイン — ナレッジドメインを作成すると、そのブックと標準の Sources ノート（マーカーの凡例、タイムスタンプ、出典のグループ別リスト、改訂履歴テーブル）が作成されるため、最初の書き込みからすべての主張に出典を記録する場所があります。
• 可視化されたグラフ — graph() は、関係グラフ全体（または任意のノートの周辺）を Mermaid フローチャートとしてレンダリングし、ネイティブな Trilium ノートとして保持します。
• バイトを保持するアーティファクト — テキストは UTF-8 で、バイナリコンテンツはツールのコントラクトでは厳格な標準 base64、通信上では生のバイト列を使用します。バイナリの読み取りでは、置換文字の代わりに明示的な MIME/base64 エンベロープを返します。
• 1 回の呼び出しで当日を把握 — day() は、前回のセッション、その変更ログ、およびそれ以降に変更されたすべての内容を 1 回の呼び出しで提供します。
• 2 種類のスレッド構造 — スレッドは日付付きジャーナル（有効な日ごとに子ノート 1 つ）またはタイトル付きコレクション（項目ごとに維持されるノート 1 つ。アイデア一覧など）です。作成時に shape= で選択します。
• 時点を持たないノート、日付付き記録 — ナレッジ、情報、スレッドの各ブックには状態や履歴を保持しません（ドメインの Current State のみが例外です）。maintain(deep=true) は、入り込んだ日付付きの文章を検出します。ログ以外のすべてのノートにはアイコンが付き、種別に応じて設定され、スイープによって過去のノートにも設定されます。
• 堅牢なバックエンド処理 — すべてのバックエンド呼び出しにはタイムアウトが設定され、冪等な読み取りは再試行されます。通常のコア書き込みは冪等であるか重複を防止しますが、フルモードの生データ上書きは明示的に行います。コンテンツの外科的な編集は、エディター独自の HTML 書き換えにも耐えます。ドメインの名前を変更すると、その内部のすべてに反映され、メンテナンススイープは検出した不整合を修復します。
• 標準でマルチエージェント対応 — 書き込みに分類されるすべてのツールは、プロセス全体で共有される FIFO ロックの後ろで直列化されます。そのため、1 つのホストインスタンスを通じて 2 つのエージェント（対話セッションと自動実行など）が書き込む場合、競合せず、到着順にキューへ入ります。読み取りは完全に並列のままです。日次ログの削除反映処理により、その日の終了後に削除されたノートも痕跡なく消えることはありません。この期間は設定可能（ライフサイクルポリシーの deletionCatchupDays）で、デフォルトは Trilium の 7 日間の保持期間です。
• 文章で尋ね、区切りを指定して分割 — consistency(subject="…") は、正規表現を推測することなく、表現の違いを問わず、ある事実について述べているすべてのノートを見つけます。consistency(pattern, staleAfterDays=N) は、未更新のノート 1 つだけに記載された数値を検出します。何も反対していないためにひそかに古くなっていく数値です。主張ではなく履歴であるセッションと日記は除外します。diff(since="today") は、セッションが変更したすべてのノートを 1 回の呼び出しで確認します。revise(find="Phase 2", within="tr") は、ノート内の数語で指定したテーブル行を編集、挿入、または削除します。read(ids=[…]) は、複数ノートの確認を 1 回の往復にまとめます。各ノートのサイズを先に確認することも、すべてのノートから単一の section= を読むこともできます。また、split(noteId, sections=[…], into="…") は、大きすぎるノートの問題に対する書き込み側の機能です。セクション全体を新しいノートへ移し、元のノートには参照先を残します。情報ノートには #mandate マーカーを付けられるため、スコープを限定したセッションは、すべてのノートの文章を読むことなく、従うべき 1 つのノートを見つけられます。
• 明確に区別できるコネクターの識別情報 — ホストインスタンスは BrainLLM と独自のオリジンを通知し、同一オリジンの PNG/SVG アイコン、明示的なページファビコンリンク、実際の複数サイズ ICO を備えます。標準のマークはコネクター、同意ページ、公開アセットで共有されます。
• 変更をプレビューし、網羅性を測定 — revise(noteId, edits=[…], dryRun=true) は、リビジョン、ラベル、ゲートへの書き込みを行わずに、順次の一致件数と、サニタイズされた変更前後のコンテンツを表示します。リビジョンに失敗した場合、コンテンツの上書きは中止されます。consistency() は読み取り失敗とスキャン範囲を報告します。大文字小文字を区別しない比較により、誤った矛盾を生まずに綴りのバリエーションを保持します。不完全なスキャンでは、存在しないことや全員一致を証明できません。
• レジスターを 1 回の呼び出しで完了 — revise(find, within="tr", mode="remove", closure={thread, body}) はレジスターの行を削除し、その日のエントリー内のスレッドに完了記録を残します。closure={note, table?, row?} は、明示的に選択したレジスターテーブルへ行を移します。移動先のセルはテーブルの形式に一致している必要があります。移動先を先に処理することで復旧可能性を保ちます。また、moves=[{find, row?}] は事前確認と行ごとの進捗表示を伴って複数の完了処理をまとめ、append={table, row} は検索用の基準なしで行を追加します。within= には、読者が目にする形式で行を指定することもできます（"Phase 2 | Claude | Open"）。セルと見出しが一致しないテーブル行は、書き込み時と maintain(deep) によって検出されます。
• 証明できる記録 — セッション、日記エントリー、日付付きスレッドエントリーは追記専用であり、これを検証できるようになりました。各 close() は、その日の記録を前日のダイジェストと連鎖したダイジェストで封印します。maintain(deep) は、封印後に書き換えられた記録を報告します。追記は引き続き可能ですが、履歴の編集は見逃されません。

---

仕組み

ブートストラップ時に、BrainLLM は Trilium 内に 5 つの領域からなるツリーを構築します。ツールが作成するすべてのノートは、サーバーポリシーに従って種類が設定され、ラベルが付けられ、日付が記録され、配置されます。

BrainLLM  (#brainLlmRoot)
├── 👤 Master       Biography · Goals · Preferences               (the user — maintained singletons)
├── 🤖 LLM          Responsibilities · Protocols · Self-correction · Diary/  (the assistant's self-model + daily diary)
├── 🗂️ Memory       Sessions/ · Threads/                          (daily session logs + multi-session work)
├── 📚 Knowledge    Master/ · Domains/<domain>/{ Sources, info }  (learned facts beyond/contra training)
└── 💡 Insights     Logs/ · Graph · Claims                         (the brain's record of itself)

ノートの分類	種類	動作
シングルトン	biography、goals、preferences、responsibilities、protocols、selfcorrection（各ドメインの Sources ノートも含む）	維持するノートはそれぞれ 1 つだけです。ノート自体を編集し、現在の状態の事実を保持します
日付付き記録	diary、session、log	暦日ごとに 1 つです。書き込みはすべて、タイムスタンプ付きの追記ブロックとして記録されます。重要なのは時系列です
コレクション	thread、user、information、domain	タイトル付きノートで、スコープ内の正規化されたタイトルに基づいて重複を排除します

セッションでは、次のプロトコルを必ず実行します。start() で状況を把握し（自分が何者か、進行中のスレッド、前回からの変更点）、モデルは作業を進めながら、永続化すべき事実が明らかになった時点で記録します。その後、session() → addendum() → maintain() → remarks() → diary() → close() の順に実行します。close() はログを確定し、日次変更ログを再生成し、データベースのバックアップを開始します。終了前のゲートはコードで強制されます。実際にすべての手順が順番どおりに実行されるまで、close() は拒否されます。「手順を実行しました」と述べるだけでは不十分で、ツール呼び出しが必要です。このゲートはメモリ内に保持されるのではなく、セッションノートに書き込まれて永続化されるため、セッション途中で再起動しても状態が維持され、stdio と HTTP で同じように動作します。何も書き込まなかったセッションは簡易終了となります。整理や走査の対象がないため、close() で必要なのは session()、remarks()、短い diary() だけです。

状況把握は意図的に低コストにしています。start() はシングルトンをセクション見出しとして返します。これにより、脳に何が保存されているかをモデルが把握でき、重要なセクションだけを取得できます。自己モデル全体を毎回のセッションで提供すると、1 行の質問にも 1 日分の作業と同じコストがかかっていました。本当に必要なセッションのために、start(depth="full") も引き続き利用できます。

知識は型付きグラフです。16 種類の関係（extends、contradicts、supports、partOf、supersedes、corrects、…）からなる固定語彙を持ち、connect() またはノート作成時に接続します。explore() でたどり（リンク／バックリンク／近傍／最短経路）、graph() で描画し、maintain(deep) で監査します。maintain(deep) は重複したエッジを修復し、ノートアプリケーションが通常は調べようとしない問題にもフラグを立てます。たとえば、孤立したノート、古くなった内容、重複したタイトル、ノート内の構造のずれ、読み取り上限を超えた本文、ラベルだけ付けられて本文が書かれていないスタブ、タイトルに日付が含まれているノート（タイトルによる重複排除が機能しなくなります）、統合を検討すべきほど大きくなったスレッド、検証テーブルが未記入の Sources ノート、二重にエスケープされたマークアップを含む本文などです。ほとんどの情報は本文を読み取らずにサーバー側でノートのプロパティから計算されるため、レポートが途中で切れることなく全件を網羅します。検出結果は確認済みとして記録（maintain(ack=[…])）できます。正しいと判断したフラグは、そのノートの内容が実際に変わるまで表示されなくなります。実行のたびに再表示され、そのたびに正しく無視する警告は、リストを流し読みする習慣につながります。

---

クイックスタート

前提条件

• Bun v1.0+
• 稼働中の TriliumNext インスタンス（デスクトップアプリまたはサーバー）

1. インストールとビルド

git clone https://github.com/miisodev/BrainLLM
cd BrainLLM
bun install
bun run build

2. ETAPI トークンを取得する

この手順は省略できます。 TRILIUM_ETAPI_TOKEN の代わりに TRILIUM_PASSWORD を設定すると、BrainLLM は初回起動時にトークンを自動生成し、brainllm.json の隣にキャッシュします。再起動時には新しいトークンを毎回作成せず、キャッシュされたトークンを再利用します。セットアップコマンドを実行するターミナルがないコンテナへのデプロイでは、この方法が最も簡単です。

明示的に作成する場合は、init に生成させます。

TRILIUM_BASE_URL=http://localhost:8080 TRILIUM_PASSWORD=your-trilium-password bun run init

トークンは brainllm.json の隣に、所有者のみがアクセスできる権限でキャッシュされ、シークレットは出力されません。コピーが明示的に必要な場合は、bun run init -- --show-token を実行してください。CLI は冪等で、重複したツリーを作成せず、既存の #brainLlmRoot を引き継ぎます。または、Trilium で手動作成することもできます：Options → ETAPI → Create token。

3. MCP クライアントを設定する

Claude Desktop の場合は、claude_desktop_config.json に追加します（リモートを含む完全な例は config.example.json を参照してください）。

プラットフォーム	パス
Windows	%APPDATA%\Claude\claude_desktop_config.json
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "BrainLLM": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/BrainLLM/dist/index.js"],
      "env": {
        "TRILIUM_BASE_URL": "http://localhost:8080",
        "TRILIUM_ETAPI_TOKEN": "your-etapi-token-here"
      }
    }
  }
}

Claude Code の場合、同じサーバーブロックを .mcp.json で使用できます。カスタム Bun コマンドに対応したホスト向けに、スキーマに準拠した MCPB マニフェスト（manifest.json）が含まれています。ただし、BrainLLM には引き続き Bun が必要で、このリポジトリではワンクリックで使える .mcpb 成果物はまだ公開されていません。

4. 脳を初期化する

クライアントを再起動し、Claude に bootstrap を実行するよう依頼してください。これにより、5 領域のツリー（各領域には目的が刻まれています）が構築され、brainllm.json が書き込まれ、すぐに使用できる状態になります。CLI から実行することもできます。

TRILIUM_BASE_URL=http://localhost:8080 TRILIUM_ETAPI_TOKEN=your-token bun run init

5. モデルに操作方法を教える

運用スキルをインストールします。これは、BrainLLM を書類整理棚ではなく、自分自身の思考として扱うよう Claude に教えるドキュメントです。

# Claude Code / Cowork skills directory (macOS/Linux)
cp -r skills/brainllm ~/.claude/skills/brainllm

# Windows PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.agents\skills" | Out-Null
Copy-Item skills\brainllm "$env:USERPROFILE\.agents\skills\brainllm" -Recurse -Force

その後、セッションを開始します。モデルは start() を呼び出して状況を把握し、以降はネイティブに脳を操作します。

---

ツールの概要

すべてのツールの戻り値は構造化 JSON です。ユーザー入力の誤りは情報提供用のエラー（{error, detail, hint}）を返し、モデルが内容を読み取って自ら修正できます。すべての読み取り／書き込み／検索ツールには無料の relations スニペットが含まれ、すべての書き込みは再試行しても安全です。

ツールの名前の由来

名前は、スタイル上の好みではなく、読みやすさを高めるための工夫です。 ほとんどの MCP クライアントでは、各ツール呼び出しが実行されるたびに、その名前が表示されます。BrainLLM のツール名には、メモリに対して何が行われているかを表す、平易な英語の動詞が使われています。remember、recall、revise、resolve、forget、connect、maintain といった名前なので、スキーマを知っていたり、Trilium を開いて確認したりしなくても、呼び出しログからモデルが脳内で何をしているのかがわかります。

多くのサーバーが採用している別の方法では、ツールに基盤となる API の名前を付けます。たとえば、create_note、patch_note、update_attribute です。これでは、ある行が変更されたことはわかります。しかし、モデルが意思決定を記録したのか、以前信じていたことを訂正したのか、作業項目を完了させたのかはわかりません。実際に目にしたいのは、そうした内容です。

このように見ると、セッションの内容はひと目でわかります。

表示される内容	意味
start → day	状況の把握：あなたが誰なのか、何が未完了なのか、前回から何が変わったのかを読み込む
remember · diary	何かを書き留めること。永続的な事実、またはモデル自身の日々の記録
recall · domain · outline	学習データから回答するのではなく、回答する前に何かを調べる
revise · resolve · forget	すでに存在するものを変更、完了、またはアーカイブする
connect · graph	気付いた2つの事柄の関係をつなぐ
maintain · addendum	整理作業：古くなった情報や構造上のずれを処理し、保留中の編集を反映する
remarks → close	締めくくり：振り返りを行い、その後セッションログを確定する

表面が拡大してもわかりやすさを保つため、3つの規則を設けています。

• アクションには動詞、対象には名詞を使います。 remember は書き込み、knowledge は読み取りを行います。ツール名が名詞の場合、読み取り専用です。
• <surface> と <surface>_recall の組み合わせ。 名前だけのツールは対象をすべて読み込み、_recall 接尾辞付きのツールは概要を確認します。memory ではなく memory_recall と表示されていれば、モデルが負荷の低い読み取りを選んだことがわかります。
• 破壊的な動作には、それとわかる動詞を使います。 forget、detach、delete_* は、決して穏当な表現には置き換えません。そのため、取り消せない呼び出しが通常の呼び出しに見せかけられることはありません。

フルモードのツールは、意図的にこの規則に従わず、create_note、patch_note、delete_attribute のような Trilium の生のプリミティブにちなんで命名されています。これは、ガードのない生の操作が、脳を考慮した操作とはログ上で明確に区別できるようにするためです。

ツールの権限

すべてのツールは、読み取り、書き込み、破棄のいずれを行うかを宣言します。そのため、クライアント側でツールを分類でき、呼び出しごとではなくグループごとに権限を付与できます。また、すべてのツールには、人が読んでわかるタイトル（「ノートを編集」「脳を検索」など）が付いており、権限の確認画面やディレクトリ一覧に表示されます。現在のフルモードの内訳は読み取り専用 34 · 書き込み 31 · 破壊的 13です（コアモードは読み取り専用 23 · 書き込み 17 · 破壊的 5）。revise、label、connect は、既存の内容を上書きまたは削除する可能性があるため、破壊的操作に分類されます。これにより、読み取りは無人で実行できる一方、脳に変更を加える操作では引き続き確認が求められます。

分類は、登録箇所に分散させず、レビュー可能な単一のテーブル（src/annotations.ts）で管理しています。また、デフォルトでは意図的に安全性よりも危険性を優先します。テーブルにないツールは読み取りではなく書き込みとして扱われ、起動時にその旨が示されます。読み取りに見えて実際にはそうではないため、知っておくべきツールが3つあります。start() は今日のダイアリーとセッションのスタブを作成し、session() はメンテナンス処理を実行し、graph() はレンダリング済みのグラフノートを書き込みます。

Core — 汎用動詞（35）

グループ	ツール
セッションのライフサイクル	start · day · session · remarks · close · backup · health
書き込み	remember · diary · revise · split · resolve · withdraw · recover
読み取りと検索	read · recall · domain · brain · assembly · outline · inspect · diff · template · consistency
グラフ	connect · explore · graph
添付ファイルとラベル	attach · detach · label
メンテナンスとシステム	addendum · maintain · claim · forget · bootstrap

Core — 表層読み取り（10、デュアルモード）

master/master_recall · llm/llm_recall · memory/memory_recall · knowledge/knowledge_recall · insights/insights_recall — 各表層を全文読み取るか、コンパクトなスタブで概略を確認できます。

フルモード（BRAINLLM_MODE=full、+33）

生のETAPIを使用し、Triliumのプリミティブ（ノート、属性、ブランチ、リビジョン、添付ファイル、カレンダー、システム）ごとに1つのツールを提供します。Brainに依存せず、ガードもありません。Coreでは表現できないケース（正確な生クエリ、コード／キャンバス／mermaidノート、ブランチの外科的編集、リビジョンの復旧）に対応するフォールバックです。

運用に関する完全なリファレンスはskills/brainllm/SKILL.mdにあり、トピック別の詳細解説はskills/brainllm/references/にあります。さらに、アーキテクチャリファレンスでは、BrainLLMの構築方法とその理由を説明しています。すべてのモジュール、各ツールの動作、sweepの内部処理、冪等性マトリックスを網羅しており、このリポジトリでは公開せず、各リリースに合わせて最新の状態に保たれます。入手方法についてはプロジェクトを支援するをご覧ください。

---

デプロイ

トランスポートモード

モード	用途	選択方法
stdio	ローカル — Claude Desktop／Claude CodeがBrainLLMを子プロセスとして起動します	PORTが未設定（デフォルト）
HTTPコネクター	リモート — クライアントがネットワーク経由でBrainLLMに接続します	PORTを設定（Railwayが注入）

HTTPコネクターは、/mcpにストリーミング可能なHTTP MCPエンドポイントを提供します（mcp-session-idごとに1セッション、DELETEで終了、ブラウザクライアント向けにmcp-session-idを公開するCORS対応）。また、ストリーミングHTTPより前のクライアント（古いCursorビルド、Continue、Python-SDKクライアント）向けに、POST /messagesを備えたレガシーSSEエンドポイント/sseと、GET /healthも提供します。サーバーのルートでは通常のブラウザーのGETリクエストにプレーンなページを返します。また、一部のホスト型Claudeコネクターのバージョンではトークン取得後のMCPパスがオリジンのルートに正規化されるため、/に送信されたMCP形式のリクエストも互換性エイリアスとして受け付けます。サーバー自体はプレーンHTTPを使用します。TLSはその手前で終端する必要があります（Railwayではエッジで自動的に処理されます。素のVPSや独自のDockerホストでは、Caddy、nginx、Cloudflare Tunnelなどのリバースプロキシの背後に配置してください）。HTTPモードは、MCP_AUTH_TOKENまたはBRAINLLM_OWNER_PASSWORDが設定されていない場合、接続を拒否するようになりました。BRAINLLM_ALLOW_UNAUTHENTICATED_HTTP=trueは、隔離された信頼済みネットワークでのみ使用する明示的な回避策です。CORSのデフォルトは*のため、外部から到達可能なデプロイ環境には、実際に機能する認証ゲートが必要です。アイドル状態のセッションは1時間後に破棄されます。MCPリクエストの本文サイズ上限は、サーバーとSDKトランスポートの両方で50 MiBです。どちらのトランスポートも同じ認証ゲートを経由します。

Docker／Railway

同梱のDockerfileは、HTTPコネクターをビルドして実行します（2段階構成、ダイジェスト固定のoven/bunを使用し、entrypoint.sh経由で権限を降格）。Railwayでは、PORTが自動的に注入されます。サービス変数としてMCP_AUTH_TOKEN、TRILIUM_BASE_URL、TRILIUM_ETAPI_TOKEN、BRAINLLM_TZを設定してデプロイし、ベアラートークンを指定してクライアントをhttps://<app>.up.railway.app/mcpに接続してください。他の環境（VPS、独自のDockerホスト）へのデプロイも同様です。コンテナに必要なのは同じ環境変数と、前述のトランスポートの説明にあるTLS終端プロキシだけです。

ブランディング

HTTP モードでは、BrainLLM が独自のアイコン（/icon.png、/icon.svg、各サイズのバリエーション、/favicon.ico）を配信し、タイトル、1 行の説明、ウェブサイトとともに MCP ハンドシェイクで通知します。これにより、クライアントはコネクター一覧やツール呼び出しの横に BrainLLM のマークを表示できます。ハンドシェイクには、5 つの領域とセッションの形式を説明する短いサーバー指示も含まれます。名前、タグライン、説明、マークの形状といったブランドに関する情報はすべて src/brand.ts で一元的に定義され、ユニットテストによって package.json、manifest.json、server.json の説明が同じ内容に保たれています。

この 2 つはどちらも欠かせません。仕様ではクライアントに対し、アイコン URI がサーバーと同じオリジンにあることを確認するよう求めているため、それ以外の場所でホストされたアイコンは通知なしに無視されます。また、ファビコンを配信しないホストでは、クライアントは 登録可能ドメイン のファビコンにフォールバックします。brain.yourdomain.com の BrainLLM には yourdomain.com のサイトロゴが表示されます。意図的に見えてしまうため、何も表示されないよりも悪い結果です。

独自のアートワークを使うには、public/BrainLLM.svg を置き換えて bun run icons を実行します。ベクター画像が、サーバーで配信する各サイズにラスタライズされます。生成結果をコミットしてください。Docker イメージは public/ をコピーし、実行時に画像処理ツールチェーンを必要としません。

リモートクライアントの接続（OAuth）

Claude Code と mcp-remote は MCP_AUTH_TOKEN をヘッダーとして送信するため、ほかに必要な設定はありません。**ホスト型の Claude サービスである claude.ai、Claude mobile、Cowork は対応していません。**カスタムコネクターの UI では OAuth を使うか、何も使わないかの二択で、ベアラートークン用のフィールドはありません。そのため BrainLLM には独自の OAuth 2.1 認可サーバーが組み込まれています。両方の登録方式に対応しているため、OAuth 対応クライアントならどれでも使えます。

• Client ID Metadata Documents（CIMD） — MCP 2025-11-25 仕様で採用された、登録不要の方式です。Claude が選択するのはこちらです。
• Dynamic Client Registration（RFC 7591） — CIMD に対応していないクライアント向けです。opencode（MCP TS SDK ≤1.29）が該当します。registration_endpoint がないと、認証を一切行いません。

次の変数を設定すると有効になります。

BRAINLLM_OWNER_PASSWORD=<a strong password you choose>

このパスワードは、同意画面で入力するものです。設定しない場合、OAuth エンドポイントはすべて無効になり、それ以外の動作は変わりません。

Claude で Settings → Connectors → Add custom connector を選択し、https://<your-host>/mcp を入力します。OAuth クライアントの各フィールドは空欄のままにしてください。CIMD ではクライアント ID もシークレットも不要です。Claude は 401 の応答から必要な情報をすべて取得し、同意画面で一度承認すれば、接続状態が維持されます。

有効になる機能は次のとおりです。

エンドポイント	用途
/.well-known/oauth-protected-resource（および /mcp 版）	RFC 9728 — 認可サーバーを指定します
/.well-known/oauth-authorization-server（および /mcp 版）	RFC 8414 — CIMD、DCR、PKCE S256 への対応を通知します
/authorize	クライアント（CIMD ドキュメントまたは登録済み ID）を検証し、同意画面を表示します
/token	PKCE で検証したコード交換を行い、ローテーションされるリフレッシュトークンは SHA-256 ハッシュのみを保存します
/register	RFC 7591 の動的クライアント登録 — opencode など、DCR のみをサポートするクライアントの接続に使います

同意画面には、接続を要求しているクライアントと、リダイレクト先のアドレスが表示されます。そのアドレスが使用中のコンピューター自身（Claude Code が使うループバックリダイレクト）の場合は警告も表示されます。MCP トラフィックには、ベアラートークンごとにレート制限が適用されます。また、IP アドレスごとの制限はより緩やかに設定されているため、同じ外向き接続範囲を共有するクライアント（Claude のホスト型トラフィックはすべて該当します）が、互いの利用枠を使い切ることはありません。

両方の認証情報を同時に使用できます。同じ brain に対し、Claude Code の静的トークンと claude.ai の OAuth トークンを使えます。アクセストークンは、サーバーのリソース URI にひも付けられた署名済み JWT です。そのため、別の MCP サーバー向けに発行されたトークンは拒否されます。署名シークレットとリフレッシュトークンは brainllm.json の隣に保存されます。コンテナにデプロイする場合は、BRAINLLM_CONFIG をボリューム上に配置してください。そうしないと、再デプロイのたびにすべてのトークンが無効になります。

再デプロイ後も設定を保持するには、BrainLLM サービス（Trilium サービスではありません）にボリュームをマウントし、BRAINLLM_CONFIG にその中のファイルパスを設定します。

railway volume -p <project-id> -s <brainllm-service-id> -e production add --mount-path /vol
railway variables set BRAINLLM_CONFIG=/vol/brainllm.json

ボリュームを使わない場合は、BRAINLLM_CONFIG を設定せずにおきます。自動検出により、コールドスタートのたびに Trilium の #brainLlmRoot マーカーから brain が再検出されます（約 1 秒）。

設定リファレンス

変数	必須	目的
TRILIUM_BASE_URL	✅	TriliumNext インスタンスの URL（ローカル、または HTTPS リバースプロキシ／トンネルの URL）
TRILIUM_ETAPI_TOKEN	◐	ETAPI ベアラートークン。TRILIUM_PASSWORD が設定されていない場合は必須です
TRILIUM_PASSWORD	◐	トークンの代替手段です。BrainLLM は初回起動時にトークンを発行し、brainllm.json と同じ場所にキャッシュして、再起動後も再利用します。bun run init でも使用されます
BRAINLLM_MODE	—	core（デフォルト）または full（ETAPI の生の機能を追加）
BRAINLLM_TZ	—	ホスティング環境へのデプロイ時に日付を あなたの 日付で記録するための IANA タイムゾーン（例：Africa/Johannesburg）。未設定の場合はホストの時計を使用します
BRAINLLM_DELETION_CATCHUP_DAYS	—	Trilium が削除済みノートを保持する日数（Options → Other → "Erase notes after"）。削除はこの期間内のものだけ報告されます。また、ETAPI からこの設定を読み取ることはできません。デフォルトは Trilium 自体のデフォルトと同じ 7 です。policy.deletionCatchupDays を上書きします
PORT	—	設定されていると HTTP コネクターモードに切り替わります
MCP_AUTH_TOKEN	—	/mcp で受け付ける固定ベアラートークン。Claude Code と mcp-remote が送信します
BRAINLLM_OWNER_PASSWORD	—	OAuth 2.1／CIMD エンドポイントを有効にします。claude.ai では必須です。同意画面で入力するパスワードです
BRAINLLM_OAUTH_SECRET	—	省略可能な 32 文字以上のデプロイ署名シークレットです。変更すると古い OAuth トークンが無効になります
BRAINLLM_ALLOW_UNAUTHENTICATED_HTTP	false	HTTP 認証情報が設定されていない場合に、信頼できるネットワーク内に限って認証なしを許可する明示的な回避策です。公開インターフェースでは絶対に使用しないでください
BRAINLLM_TRUST_PROXY	false	信頼できるリバースプロキシが x-forwarded-host／x-forwarded-proto を設定する場合に限り、OAuth ディスカバリーでこれらを信頼します。BRAINLLM_PUBLIC_URL の使用を推奨します
BRAINLLM_PUBLIC_URL	—	プロキシが Host を書き換える場合に、導出される公開オリジンを上書きします。クライアントに入力する URL と完全に一致する必要があります
BRAINLLM_CONFIG	—	永続ボリュームへのデプロイで使用する brainllm.json の絶対ファイルパス

ライフサイクルのタイミングは brainllm.json に設定されています。必要に応じて調整してください。

"policy": { "dormantAfterDays": 21, "archiveDormantAfterDays": 45, "staleAfterDays": 7 }

スレッドはこのタイムラインに沿って active → dormant → archived-in-place と移行します。経過時間によって削除されることはなく、recover()／withdraw() でいつでも復元できます。

---

環境に合わせた調整

このリポジトリには、作者の環境固有の値がいくつか含まれています。秘密情報ではありませんが、クローンまたはフォークする場合は内容を確認し、自分の値に置き換えてください。

項目	場所	自分用に設定する内容
タイムゾーン	.env の BRAINLLM_TZ	自分の IANA タイムゾーン。ホストの時計を使う場合は未設定にします
削除済みノートの保持期間	.env の BRAINLLM_DELETION_CATCHUP_DAYS	Trilium が削除済みノートを保持する期間が 7 日以外の場合に限り設定します
設定ファイルのパス	BRAINLLM_CONFIG 環境変数	永続ボリュームへのデプロイ時にのみ必要です（上記参照）
バンドルのパス	MCP クライアントの設定	お使いのマシン上にある dist/index.js の実際の絶対パス
作者・リポジトリ・支援	package.json、.github/FUNDING.yml、上記のバッジ	フォークする場合は自分の情報に置き換えてください。支援リンクは元の作者を支援します

---

アーキテクチャ

index.ts ─→ tools.ts ─┬→ trilium.ts     ETAPI client: bounded/retrying I/O, graph traversal
                      ├→ router.ts      placement policy: kind → parent, label plans, domains
                      ├→ templates.ts   canonical structures per kind + the template-tool rules
                      ├→ normalize.ts   titles, slugs, markdown→HTML, sanitization, surgery
                      ├→ lifecycle.ts   protection, sweep, aging, the start digest
                      ├→ journal.ts     daily Insights log generation (regenerate-in-place)
                      ├→ time.ts        timezone-correct now/today (BRAINLLM_TZ)
                       ├→ rate-limit.ts  bounded public HTTP budgets
                       ├→ brand.ts       name, description, mark, icons, server instructions
                       ├→ cap.ts         the 140k-character result cap
                       ├→ diffing.ts     block and table-cell diffs
                       ├→ network-security.ts CIMD public-network and redirect checks
                      ├→ bootstrap.ts   five-area tree builder
                      └→ tools-*.ts     per-area surface reads · full-mode raw ETAPI

主な特性：ツールの結果は 140,000 文字を超えません（それを超える結果は、より範囲を絞った読み取り方法を示す注記を付けて切り詰められます）。すべての書き込みは Trilium／CKEditor 5 との互換性を保つようサニタイズされ、変更内容は sanitized[] として報告されます。通常のコンテンツ変更の前にリビジョンスナップショットが作成されます。すべてのリクエストにはユーザーのローカル時刻が含まれ、Trilium が正しい日付で記録します。コアの書き込みは冪等、または重複が防止されます。一方、フルモードでの生の上書きは明示的に行われます。

開発

bun run dev    # hot-reload dev server
bun run build  # bundle to dist/index.js
bun run test:unit   # all unit tests (Bun discovery; works on Windows and CI)
bun run test:http   # local auth/header smoke (no Trilium required)
BRAINLLM_LIVE_TOKEN=... bun run test:live   # read-only smoke against a deployed server, over real MCP
bun run test        # integration tests (requires a live Trilium instance)
bun run validate:manifest # MCPB schema/icon validation
bun run init   # CLI bootstrap

リポジトリの構成：実行時のソースコードは src/、運用スキルは skills/brainllm/、開発者向けスクリプトは scripts/、スキーマに準拠した MCPB マニフェストは manifest.json、コンテナーのビルド定義は Dockerfile にあります。

コントリビューション

バグ報告、修正、ドキュメント、アイデアなど、あらゆるコントリビューションを歓迎します。

大切にしていること

BrainLLM は、ある個人が日常的に使うツールとして始まったため、コードやドキュメントの一部には、今もその人の前提が残っています（「環境に合わせる」を参照）。特に大切にしているのは、そうした前提を超えて一般化するための貢献です。

価値	PR での具体例
汎用性	あるワークフロー向けに組み込まれた前提を、あらゆる脳のコンテンツや慣習に当てはまるものに置き換えること
ユーザー横断性	src/ 内のどの部分も、特定の人の事業、スケジュール、語彙を前提にしてはいけません。そうした情報は、ツール層ではなく、モデルが書き込む コンテンツ に属します
デバイス横断性	Windows/macOS/Linux、ローカル stdio とリモート HTTP、ノート PC と Railway コンテナで同じように動作すること
トークン効率	応答を小さくし、往復回数を減らし、読み取りコストを抑えること。たとえば、単純な yes/no の確認には inspect(content=true) ではなく、順位付けされたスニペットを返す recall() を使います。これは一度きりの最適化ではなく、継続的な設計方針です
レイテンシ	上限を設けて再試行する I/O、順次読み取りではなく並列読み取り、セッション開始やツール呼び出しを不必要に遅くする要素をなくすこと

貢献方法

1. 大きな変更は、まず issue を作成してください。再現手順を添えたバグ報告や、ユースケースを明記した提案を歓迎します。
2. フォークしてブランチを作成し、変更範囲を絞って、既存のコードスタイルに合わせてください。
3. bun run build がエラーなく通り、ユニットテストがすべて成功する状態を保ってください（bun run test:unit — CI では push と PR のたびに同じチェックを実行します）。新しい normalize／ライフサイクルロジックにはテストを追加してください。
4. Conventional Commits を使用してください（fix:、feat:、docs:、refactor:）。
5. 変更が影響するドキュメントを更新してください — README.md、skills/brainllm/ 内のスキルパッケージ、該当する場合は config.example.json／.env.example。スキルも製品の一部です。スキルを更新せずにツールだけを変更しても、変更は半分にすぎません。

どこから始めればよいか分からない場合は、good first issue ラベル付きの issue、ドキュメントの不足箇所、トラブルシューティングのリファレンスなどから始めるとよいでしょう。

セキュリティ

脆弱性の疑いがある場合は、公開 issue で報告しないでください。SECURITY.md に記載された非公開の報告手順に従ってください。報告には ETAPI トークン、OAuth 認証情報、非公開の脳のコンテンツを絶対に含めないでください。

プライバシーとサポート

BrainLLM は何も収集しません。分析データも、テレメトリーも、アカウントもありません。メモはお使いの Trilium に保存され、サインイン記録はご自身のサーバーに保存されます。プライバシーポリシー全文では、何がどこに保存されるかを説明しています。サポートが必要な場合は、GitHub issueを作成するか、[email protected] までメールでご連絡ください。

---

プロジェクトを支援する

BrainLLM は一人で開発・保守しています。お役に立っている場合、スポンサー支援は継続的な開発に直接役立ちます。

スポンサーは、Blueprint のコピーをリクエストできます。これは、ソースコード全体の分析から生成された完全な内部アーキテクチャリファレンスです（すべてのモジュール、各ツールの正確な動作とシグネチャ、sweep と冪等性の内部処理を網羅）。このリポジトリでは公開していません。希望する場合は GitHub Sponsors 経由でメッセージをお送りください。

リポジトリにスターを付けること、バグを報告すること、プロジェクトを広めることも支援になります。

ライセンス

MIT © Kevin Miiso Novo

クレジット

• TriliumNext Notes — このサーバーのバックエンドを支える、オープンソースでセルフホスト可能なナレッジベースです。TriliumNext チームの取り組みがなければ、BrainLLM は存在しませんでした。
• Model Context Protocol — 1 つのメモリをすべての MCP 対応クライアントで利用できるようにするオープン標準です。