llm-wiki

LLM Wiki

ユーザーが自由に選んだファイルシステム上の場所に、LLM がキュレーションするナレッジベースを構築・維持するためのスキルです。Andrej Karpathy が 2026 年 4 月の gist で説明したパターンに従います。個人用の Wiki ひとつに複数のプロジェクトの知識を蓄積することも、ひとつのプロジェクト内に Wiki を分けて作ることもできます。ユーザーが情報源を選び、質問します。LLM が記録や整理を担当します。

このパターンを一段落で説明すると

従来の RAG では、クエリのたびに生のチャンクから知識を再構成するため、何も蓄積されません。LLM Wiki パターンはこれを逆転させます。新しい情報源が追加されると、LLM は一度だけ内容をまとめ、構造化された永続的な Wiki にします。概念を抽出し、エンティティのページを作成し、相互参照を更新し、矛盾にフラグを立てます。その後のクエリでは、生の情報源ではなく、事前に統合された Wiki を読み込みます。知識が積み重なっていきます。情報源の選定と適切な質問はユーザーが担当し、LLM は人間が Wiki を放棄してしまう原因となる要約、リンク付け、一貫性の維持を担います。

このスキルを使う場面

適用される状況は幅広くあります。ユーザーが長期的にテキスト資料を蓄積していて、それらをセッションごとにチャットへ貼り付けるのではなく整理することでメリットが得られる場合はいつでも、このスキルが役立ちます。対象となる資料には、研究論文、記事、トランスクリプト、会議メモ、書籍の章、顧客との通話記録、コードリポジトリ、日記などがあります。単一の情報源（「この論文を取り込んで」）にも、既存の Wiki に対する継続的な操作（「拡散モデルについて Wiki に何と書いてある？」「Wiki の lint を実行して」「何が足りない？」）にも同様に役立ちます。

何よりも先に、対象の Wiki を特定してください。次の順に優先します。ユーザーが指定したパス、最も近いプロジェクトの指示に記載されたパス、グローバルエージェントの指示に記載されたパス、現在のプロジェクト内の wiki/。特定した Wiki の SCHEMA.md を読み込んでください。ここに記載されている既定の設定が上書きされる場合があります。2 つの Wiki を黙って統合してはいけません。Wiki が存在しない場合は、以下のブートストラップ手順を実行してください。

このスキル内のすべての相対パス wiki/ および raw/ は、現在の作業ディレクトリとは限らない、特定した Wiki と生の情報源のルートを指します。

アーキテクチャ：3 つのレイヤーと 3 つの操作

Wiki には 3 つのレイヤーと 3 つの操作があります。この用語を理解してください。このスキルの以降の説明は、これらを前提としています。

3 つのレイヤーとは、生の情報源（ユーザーがキュレーションした資料。記事、論文、PDF、トランスクリプトなど。変更不可で、LLM は読み込みますが変更しません）、Wiki（LLM が生成した Markdown ページのディレクトリ。エンティティのページ、概念のページ、比較、要約など。LLM がこのレイヤー全体を管理します）、そして スキーマ（Wiki のルートにある SCHEMA.md ファイル。この Wiki 固有の規約、つまりページの種類、命名規則、タグの分類体系、取り込みワークフローのカスタマイズなどを記載します。ユーザーとともに進化します）です。

3 つの操作とは、取り込み（新しい情報源が追加されると、LLM がそれを読み、要約ページを作成し、関連するエンティティと概念のページを更新して、ログに追記します）、クエリ（ユーザーが質問すると、LLM がインデックスから Wiki をたどり、関連するページを読み込み、回答を統合します。探索内容を積み重ねられるよう、回答を新しいページとして記録することもよくあります）、そして lint（定期的な健全性チェックです。LLM が矛盾、古くなった主張、孤立したページ、欠落している概念、リンク切れをスキャンします）です。

これらの操作を正式に説明した資料については、references/architecture.md を読んでください。手順を一つずつ確認する場合は、必要に応じて references/ingest-workflow.md、references/query-workflow.md、references/lint-workflow.md を読んでください。

グラフレイヤー（コンパイル済み、オプション）

ページには、フロントマターに型付きの graph: メタデータを含めることができます。同梱の抽出ツールは、すべてのページをコンパイルして wiki/graph/ に出力します：nodes.jsonl、edges.jsonl、graph.sqlite、graph.graphml。Markdown が正規の情報源であり、グラフは再生成可能なインデックスです。graph: のないページも、type／kind から導出されたノードとして表示され、本文中のウィキリンクから信頼度の低い mentions エッジが作成されます。型付きの意味的エッジ（例：founded、proposed、depends_on）には、明示的な出典と証拠となる引用が必要です。学習データから推測したエッジを出力してはなりません。

グラフレイヤーの規約（述語の語彙、ノード ID の形式、必須フィールド）は wiki/graph/ontology.yaml に記載されています。完全なリファレンスは references/graph-workflow.md です。重要な取り込みの後に、同梱のスクリプトを実行してください：

uv run --script scripts/wiki_graph_lint.py wiki/      # check ontology + evidence + alias collisions
uv run --script scripts/wiki_graph_extract.py wiki/   # rebuild nodes.jsonl, edges.jsonl, graph.sqlite, graph.graphml
python scripts/wiki_graph_query.py wiki/ neighbors --node product:konvy

wiki/graph/ontology.yaml が存在しない場合、そのウィキはグラフ導入前のものです。グラフの手順は何もせず、捏造して作成しないでください。

ストレージの範囲と構成

ウィキのストレージ範囲は、スキルのインストール範囲とは独立しています。スキルをグローバルにインストールすると、複数のプロジェクトで利用できるようになりますが、グローバルウィキが作成または選択されるわけではありません。

次のいずれかの構成を使用します：

• 個人用グローバルウィキ： ~/wiki/ のような安定したルートと、~/wiki/raw/ のような生ソースの保存先を使用します。エージェントのグローバル指示で、ユーザーレベルのそのパスを指定します。これにより、どのプロジェクトの作業内容も、意図的に一つの蓄積型ナレッジベースへ取り込めます。
• プロジェクトウィキ： wiki/ と raw/ をプロジェクト内に置き、そのプロジェクトのエージェントメモリーファイルから参照します。リポジトリ単位で知識を分離またはバージョン管理する必要がある場合に使用します。

グローバルウィキがプロジェクトを自動的に巡回したり、取り込んだりすることはありません。ユーザーから取り込みを依頼された場合、またはグローバル指示で知見の保存が求められている場合は、プロジェクトのソースと、長期的に価値のある知見を追加します。

プロジェクト内でのデフォルト構成は次のとおりです：

<project-root>/
├── wiki/
│   ├── SCHEMA.md              ← conventions, the "config file" — read this FIRST
│   ├── index.md               ← entry point: catalog of all pages with one-line summaries
│   ├── log.md                 ← append-only chronological log of ingests/queries/lints
│   ├── indexes/               ← (appears once index.md shards) per-category indexes
│   ├── entities/              ← pages about specific things (people, products, papers, places)
│   ├── concepts/              ← pages about ideas, methods, frameworks
│   ├── sources/               ← per-source summary pages (one per ingested source)
│   └── synthesis/             ← cross-cutting analyses, comparisons, query results filed back
├── raw/                       ← the user's source material (PDFs, .md clippings, images)
│   └── assets/                ← downloaded images referenced by raw clippings
└── ...

この構成はデフォルトであり、必須ではありません。グローバルウィキでは raw/ をウィキのルート内に配置できます。また、どちらの範囲でも kb/、notes/、vault/ など別の名前を使用できます。SCHEMA.md に従ってください。

スケーラビリティを保つための指針

LLM Wiki パターンで最も大きな失敗につながるのは、Wiki 自体がコンテキストのボトルネックになることです。単純な実装では数百ページほどで破綻します。LLM がクエリごとに読み込むページが多くなりすぎるか、関連するページを見落として幻覚を始めるためです。このスキルの設計は、ほぼ全面的にこの失敗を避けることを目的としています。以下の原則は必ず守ってください。これらを無視すると、規模の拡大に伴ってパターンは破綻します。

ページの原子性。 Wiki の各ページは1つの概念を扱い、小さく保ちます。目安は400行または約2,000語、上限は800行です。ページがこれを超える場合は分割します。下位概念を独立したページに切り出し、親ページからリンクしてください。1ページだけでコンテキストウィンドウの30％を占めるのは、設計上の問題です。

インデックスを起点にしたナビゲーション。 クエリに回答する際、Wiki を無差別に grep または glob してはいけません。まず必ず index.md（または indexes/ 内の該当する分割インデックス）を読み、候補となるページを特定してから、それらだけを詳しく確認します。インデックスは読み込みコストが低くなるよう設計されています。本文は含めず、ページごとに1行だけです。これがパターン全体をスケーラブルにするキャッシュです。

インデックスの分割。 index.md が約300行を超えるか、Wiki が約150ページを超えたら、インデックスを分割します。カテゴリ別の項目を indexes/<category>.md ファイル（例：indexes/entities.md、indexes/concepts.md、indexes/sources.md、またはさらに細分化したドメイン別インデックス）に移し、トップレベルの index.md をそれらの一覧にします。これによりインデックスを読む手順は2段階になりますが、各段階の規模は上限内に収まります。

すべてのページに YAML フロントマターを付ける。 Wiki の各ページの冒頭には、最低限 type、tags、sources、updated を含むフロントマターを記述します。同梱の wiki_search.py スクリプトは、ページ本文を読み込まずにこれらの項目で絞り込めます。references/page-conventions.md を参照してください。

全面的な書き換えではなく、必要箇所だけを編集する。 ページを更新するとき（たとえば、新たに取り込んだソースで既存エンティティが言及されたため相互参照を追加するとき）は、str_replace を使い、該当箇所だけを変更します。ページ全体を書き換えると時間とトークンを浪費し、既存の細かなニュアンスを失うおそれがあります。

grep によるバックリンクの特定。 特定のエンティティを参照するページをすべて見つけるには、ページを読んで言及を探すのではなく、grep -rl "\[\[entity-name\]\]" wiki/ を実行します。同梱のスクリプトを使えば簡単に実行できます。

ソースの分割取り込み。 大きな生ソース（長い PDF、書籍の章、長時間の書き起こし）は、取り込み時に全体を読み込まず、分割して読みます。取り込みワークフローがこの処理を行います。references/ingest-workflow.md を参照してください。

大規模な Wiki では検索スクリプトを使う。 Wiki が約300ページを超えると、インデックスを単純に参照するだけでは、あいまいなクエリに適したページを見つけられない場合があります。セクション単位のハイブリッド検索には、任意のフロントマターによる絞り込みと、構造化された --json の根拠行を利用できる scripts/wiki_search.py を使います。デフォルトでは、ローカルの BAAI/bge-small-en-v1.5 FastEmbed モデルを実行し、生成したベクトルを sqlite-vec 経由で wiki/.wiki-cache/embeddings.sqlite に保存し、意味検索と BM25 の順位を RRF で統合します。初期化とアップグレードでは uv 経由で scripts/setup_wiki.py を実行します。固定バージョンの FastEmbed、sqlite-vec、PyYAML をインストールし、モデルをキャッシュして、セットアップ完了と報告する前にすべてのセクションを同期します。Wiki やクエリのテキストがマシンの外部に送信されることはありません。依存関係なしで BM25 を使う場合は、python scripts/wiki_search.py "query" --no-embed を実行して PEP 723 の依存関係解決を回避してください。

しきい値や移行手順を含むスケーリングの完全な手引きについては、references/scaling-playbook.md を参照してください。

新しい Wiki の初期化

ユーザーに、個人用のグローバル Wiki とプロジェクト Wiki のどちらを希望するか尋ねます。その後、選択したベースディレクトリに対してブートストラップスクリプトを実行します。

# Project wiki: <project-root>/wiki and <project-root>/raw
python scripts/init_wiki.py <project-root> [--wiki-dir wiki] [--raw-dir raw]

# Personal global wiki: ~/wiki with raw sources at ~/wiki/raw
python scripts/init_wiki.py <home-directory> --wiki-dir wiki --raw-dir wiki/raw

これによりディレクトリ構造が作成され、SCHEMA.md、index.md、log.md のテンプレートが配置された後、必須のローカルランタイムセットアップが実行されます。セットアップでは、uv を通じて固定された依存関係をインストールし、存在しない場合は BAAI/bge-small-en-v1.5 をダウンロードして、解析キャッシュを構築し、現在のすべてのセクションを埋め込みます。セットアップで "status": "ready" が出力されない限り、初期化やアップグレードが完了したものとして扱わないでください。

ブートストラップを実行する前に、references/retrieval-setup.md にある一連の質問を使って、パス、モデルキャッシュの場所、グラフの使用、エージェントメモリとの統合を確認します。API キーやプロバイダーへの同意を求めないでください。リモートの埋め込み処理はありません。--no-embed は、後で検索する際の決定論的な語彙検索への切り替え手段であり、必須セットアップを省略する方法ではありません。

次に、今後のセッションで Wiki を見つけられるよう、Wiki をエージェントメモリに接続することを提案します。個人用のグローバル Wiki では、ユーザーレベルの安定したパスを含むグローバル指示を使います。プロジェクト Wiki では、相対パスを含むプロジェクトのメモリファイルを使います。ファイル名はエージェントによって異なります。Claude Code では CLAUDE.md、Codex / Cursor / OpenCode / Pi / OpenClaw では AGENTS.md、Gemini CLI では GEMINI.md です。ワークフロー全体と 2 種類の記述例は references/agent-memory-integration.md にあります。ユーザーの承認なしにメモリファイルへ書き込んではいけません。

取り込みワークフロー（概要）

ワークフロー全体は references/ingest-workflow.md にあります。以下はその概要です。新しいソースが届いたら、まずソース自体を raw/ にそのまま書き込みます（ウェブ記事の場合は Markdown 形式を使います）。次にソースを読み込み、大きい場合は分割して読み、ソースのスラッグを名前にした単一のソース要約ページを wiki/sources/ に作成します。フロントマターをすべて記入し、raw ファイルへの引用を含めます。その後、このソースがどの既存のエンティティページや概念ページに関係するかを特定し、それぞれについて str_replace を使って該当セクションだけを更新します。書き換えは行いません。ソースが新たに紹介するエンティティや概念を特定し、そのページを新規作成して、関連する既存ページからリンクし、孤立しないようにします。新しいページを index.md（または該当するシャード）に追加します。log.md に、日付、操作の種類、ソースのタイトルを含む 1 行を追記します。最後に、要点についてユーザーと話し合います。何が意外だったか、何をさらに調べる価値があるかを確認し、その話し合いを統合ページとして記録することを提案します。

クエリワークフロー（概要）

詳細は references/query-workflow.md にあります。Wiki に対するクエリに回答するには、まず index.md（または該当するシャード）を読みます。1 行の要約から候補ページを特定し、それらのページ（および関連性がありそうなバックリンク）を読みます。使用したページを [[wikilink]] 形式で引用しながら回答をまとめ、今後のクエリにも役立つよう、まとめた回答を synthesis/ に保存することを提案します。インデックスから適切な候補が見つからない場合は、順位付けされたローカルのハイブリッド検索を実行するため、uv run --script <skill-root>/scripts/wiki_search.py "query terms" --wiki <absolute-wiki-root> を実行します。依存関係なしで語彙 BM25 を使う場合に限り、--no-embed を追加します。インストール済みのスキルパスと対象 Wiki のパスは、明示してください。Wiki にそのトピックの情報が十分にない場合は、作り話で補わず、その旨を明確に伝え、取り込み候補として提示します。

lint ワークフロー（概要）

完全版は references/lint-workflow.md にあります。Lint は、すべての操作のたびではなく、一定の間隔（N 回の取り込み後、または毎週など）で実行するのが最適です。付属の python scripts/wiki_lint.py を使うと、孤立したページ、壊れた [[wikilinks]]、サイズが大きすぎるページ、欠落または不正な形式のフロントマター、古い updated 日付など、構造上の問題を自動的に検出できます。その後、LLM が必要なセマンティックチェックでは、最近更新されたページを読み、古い主張との矛盾がないかを確認し、言及されているものの専用ページがない概念を特定し、ウェブ検索や新しいソースを通じてユーザーが補いたい可能性のある不足点を提案します。Lint の検出結果は、確定済みの変更ではなく、ユーザーが承認するための編集案として必ず提示してください。wiki はユーザーのものであり、黙って書き換えると信頼が損なわれます。

注意すべき失敗パターン

gist をめぐるコミュニティの議論では、内面化しておくべき失敗パターンがいくつか明らかになりました。このパターンがうまくいかなくなる原因でもあるため、積極的に避けられるよう確認してください。

1 つ目は気づかれない改変です。あるソースを誤読した内容が、権威あるように見える wiki ページになり、そのページが後続のソースの解釈に影響して、誤りが目に見えないまま積み重なります。対策：wiki のすべての主張に、元ファイルを指す sources: フロントマター項目を含め、ソースの場所を特定できない主張があれば lint で報告します。取り込み中に確信が持てない場合は、断定するのではなく、wiki の本文で慎重な表現を使います（「ソースでは X と主張されていますが、他のソースではまだ裏付けられていません」など）。

2 つ目はwiki が自らの出力を読み込むことによる乖離です。LLM が以前の wiki ページを事実として扱い始め、元のソースとの照合をやめてしまいます。対策：取り込み中に既存のページを更新する場合は、新しい主張を統合する前に、既存の主張に関連する元のソースを読み直します。ソースに何が書かれていたかについて、wiki の記述を鵜呑みにしないでください。

3 つ目はメンテナンスの負担増です。gist のコメントで、批評家は、wiki が大きくなるにつれて LLM の出力にますます多くの監督が必要になり、LLM-Wiki は人間の作業を減らすどころか増やす可能性があると指摘しました。その対策は、前述のスケーラビリティに関する規律（分割されたインデックス、アトミックなページ、フロントマター、lint スクリプト）に加え、定期的な lint の実行です。lint の報告件数がユーザーの確認可能な量を超え始めたら、wiki は現在の規約では対応しきれなくなっているため、スキーマを見直す必要があります。

4 つ目は不適切な用途への範囲拡大です。このパターンは、テキスト形式の調査情報を蓄積する用途では力を発揮しますが、実際のデータベースのほうが適している、組織図、財務台帳、構造化データセットなどの、高度にリレーショナルなデータでは効果が低下します。ユーザーの分野が本質的にリレーショナルな場合は、その旨を伝え、Markdown で不適切な用途に対応させるのではなく、より適したツールを提案してください。

参照ファイル

詳細な手順の原本です。該当する操作を行う際に読み、事前には読まないでください。

• references/architecture.md — 3 つのレイヤーと 3 つの操作を、ページ形式の例や各設計判断の理由とともに詳しく説明します
• references/ingest-workflow.md — 大きなソースを分割して読み込む手順や、ページタイプごとのテンプレートを含む、段階的な取り込み手順です
• references/query-workflow.md — インデックス → ページ → バックリンクの移動パターン、検索スクリプトに切り替えるタイミング、回答を統合ページとして記録する方法です
• references/lint-workflow.md — 確認項目、調査結果の提示方法、実施頻度について説明します
• references/page-conventions.md — フロントマタースキーマ、ページ名、リンク構文、ページタイプの定義、サイズ規則です
• references/scaling-playbook.md — インデックスを分割するしきい値、検索スクリプトを導入するタイミング、Wiki が現在の規約では対応しきれなくなったことを示す兆候について説明します
• references/agent-memory-integration.md — 全体またはプロジェクトの Wiki をエージェントの指示に組み込む方法を、節のバリエーションと初期設定用の会話スクリプトとともに説明します
• references/retrieval-setup.md — 必須の初期設定／アップグレード設定について説明します。パス、モデルキャッシュ、バージョン固定されたローカル依存関係、コーパス全体のベクトル同期、準備状況の確認、機密情報を含まない SCHEMA.md の状態が含まれます
• references/graph-workflow.md — オプションのグラフレイヤーについて説明します。オントロジー、フロントマタースキーマ、型付きエッジと通常の Wiki リンクを使い分けるタイミング、抽出／Lint／クエリの流れが含まれます

同梱スクリプト

スクリプトは意図的に最小限の機能に絞っています。呼び出しのたびに LLM が同じヘルパーを作り直さないようにするためのものです。それぞれの説明は、各スクリプトの --help 出力とファイルの冒頭に記載されています。

• scripts/init_wiki.py — Wiki の初期設定またはアップグレードを行い、実行環境とインデックスの設定が検証済みであることを必須とします
• scripts/setup_wiki.py — uv を使ってバージョン固定された FastEmbed／sqlite-vec／PyYAML をインストールし、ローカルモデルをキャッシュして、解析インデックスとベクトルインデックスを同期します
• scripts/wiki_search.py — JSON 形式の根拠、フィルター、増分キャッシュ、依存関係不要の字句検索フォールバックを備えた、セクション単位のローカルハイブリッド検索です
• scripts/wiki_lint.py — 構造の健全性チェック（孤立ページ、リンク切れ、サイズ超過のページ、フロントマターの検証、日付の古さ）です
• scripts/wiki_stats.py — Wiki の規模、タイプ別のページ数、リンク密度をすばやく要約します。インデックスを分割するタイミングの判断に役立ちます
• scripts/wiki_graph_extract.py — バージョン固定された PyYAML を使い、グラフのメタデータと Wiki リンクを JSONL、SQLite、GraphML にまとめます
• scripts/wiki_graph_lint.py — バージョン固定された PyYAML を使い、型付きエッジがオントロジーに準拠しているか検証します
• scripts/wiki_graph_query.py — graph.sqlite に対する近傍／エッジ／事実／最短経路のクエリです

テンプレート

assets/ のテンプレートは出発点です。初期設定時にユーザーの Wiki にコピーされ、その後はユーザーの編集に応じて変化します。

• assets/SCHEMA.md.template — 新しい Wiki 用の標準スキーマドキュメント
• assets/index.md.template — 空のインデックスファイル
• assets/log.md.template — 空のログファイル
• assets/page.md.template — フロントマターのひな型を備えた汎用 Wiki ページ
• assets/ontology.yaml.template — wiki/graph/ontology.yaml にコピーされる、グラフオントロジーの初期テンプレート
• assets/graph_README.md.template — wiki/graph/ 用の説明ファイル（標準ファイルと生成ファイルについて）
• assets/graph_gitignore.template — wiki/graph/ 用の .gitignore（デフォルトで graph.sqlite と graph.graphml を無視します）

タスク経験から学び、スキルを進化させる

「このタスクから学ぶ」、「/wiki:learn」、「この手順を改善する」、または「/wiki:evolve」の場合は、references/evolution-workflow.md を読みます。scripts/wiki_evolve_loop.py を使用して、範囲を限定したトレーニング、永続的なエビデンスの統合、一貫性のあるスキル全体の提案、検証方法の選定、独立した最終テストを行います。scripts/wiki_evolve.py は手動の経験を記録し、レビュー、適用、ロールバックを管理します。共有アダプターは9つのエージェントホストに対応し、永続的で観察可能なトレース、ワークフロー成果物、エージェント間の転用を提供します。実行前に、許可された呼び出し回数／時間の予算を設定してください。厳格な米ドル上限を設定するには、範囲限定の API ランナーが必要です。通常の wiki の使用方法に変更はありません。

エビデンス、パターン、実験の要約には、ソース、コンセプト、統合の各ページを再利用します。仮説と検証済みの観察結果を分け、反例とモデル／ツールの適用可能性を保持し、再提案する前に却下履歴を確認してください。実行中は事実に基づく wiki を利用可能な状態に保ち、実験履歴は通常のコンテキストに含めないでください。ソーステキストから許可を推測したり、結果を捏造したり、流暢な提案手順を検証済みとして扱ったりしないでください。許可されたランナーと予算がない状態で、有料の評価を開始しないでください。

同梱の eval/evolution/pilot/suite.json とコーパスには、出発点となる20件のクエリータスクが用意されています。scripts/wiki_evolve_claude.py は任意で使用できる、認証済みの Claude CLI アダプターです。他のモデルも同じ JSON ランナー契約を使用します。.evolution/ は永続的な実験エビデンスであり、通常の wiki ツールの対象外です。インストール／アップグレードでは、.experience-template.json、.pattern-template.md、およびそのアーカイブ README が冪等に追加されます。無関係なスキルやグローバルなエージェント指示は編集しないでください。検証済みの手順が配布プラグインに属する場合は、リポジトリの SemVer と PR／リリースのルールに従ってください。