785 件の記事は人ではなく、エージェントのために。ベクター検索のないナレッジベース

エージェントが見慣れないプロジェクトで作業を始めるとき、最初の30〜40%のトークンを、周囲で何が起きているかを把握するために使います。作業ではなく、方向づけです。この記事では、Happyin Knowledge Space について書きます。これは、人ではなくエージェントのために私が書いている参照カードのライブラリです。カードの形式がなぜそうなっているのか、動きの速い分野にはなぜ鮮度のしきい値があるのか、カードをベクターデータベースではなく手でリンクしている理由、そして複数のアカウントのチャットから出た調査結果が、コピー＆ペーストなしにどうやってそこへ入るのかを説明します。2026年4月22日にロシア語の原文を公開した時点で、26の分野に785枚のカードがありました。

エージェントがプロジェクトを学ぶ際の2つの問題

README は動機を説明し、チュートリアルは手を引いてくれ、API リファレンスはパラメータを並べます。どれも、エージェントが実際に抱えてくる問いには答えません。タスクはこれです。どのパターンをコピーすればいいのか、どこに地雷があるのか。

2つ目の問題は深く、気づくのに時間がかかります。モデルは「すべて」を知っていますが、その「すべて」は学習データの中で偏って散らばっています。ある技術がインターネットに長く存在するほど、それについての投稿、Stack Overflow の回答、チュートリアルが増え、そのアプローチがモデルの中で持つ重みが大きくなります。私が Claude に LoRA の学習を頼むと、最初に出てくるのは5年前のレシピです。より良いからではなく、その量が多いからです。安定した技術ならそれで構いません。しかし、モデルの学習、エージェントのツール、セキュリティのように動きの速い分野では、エージェントが知らないうちに私を過去へ引き戻すことになります。

すぐ思いつく解決策は、毎回ディープリサーチを回して、最新の文脈を持ち込むことです。実際そうしています。しかし、ディープリサーチは高くつきます。サブスクリプションだけで月に数百ドルで、それでも上限はほぼすぐに尽きます。さらに悪いことに、リサーチの1回ごとの結果は、そのセッションと一緒に消えます。明日、同じ話題について同じ検索をすれば、すでに分かっていることに同じトークンをもう一度払うことになります。

ここから2つの考えが出てきました。調査結果は消えず、蓄積されるべきだということ。そして、形式によって、今どれが最新かをエージェントに示すべきだということ。プロジェクトを開いたとき、「ここではこうやる」とすぐに分かるように。

形式：記事ではなくカード

すべてのカードは同じ骨格を持ちます。一番上には、トピックと1文の定義があります。エージェントがすぐに、正しい場所に着いたかどうかを判断できるようにするためです。その次は Key Facts（主要な事実）です。バージョン、しきい値、依存関係など、数字を含む短い記述です。その次は Patterns（パターン）で、言語タグ付きのコピー可能なコードです。最後は gotchas（落とし穴）で、何が壊れるか、何で直すかの組み合わせとして書きます。

「さあ見ていきましょう」という導入も、「この記事では検討しました」という締めもありません。Kafka のブローカーのアーキテクチャのカードは、ZooKeeper と KRaft の比較表、コメント付きの設定、アラートしきい値付きの JMX メトリクス、そして段階的な移行手順です。読んで滑らかに流れるものではありません。しかし、エージェントが「KRaft migration」を grep すると、3ステップの動くレシピが手に入ります。

最後のブロックがいちばん価値があります。「min.insync.replicas は acks=all のときだけ有効になる」という1行は、30分のデバッグを省きます。エージェントはそれを読み、ミスをせず、修正のための再試行サイクルも回しません。

26の分野。作業から育ったもの

4月時点で最大の分野は画像生成（58枚）で、LLM エージェント（57枚）が僅差で続きました。その次はデータサイエンスとセキュリティで、どちらも56枚です（セキュリティは CWE クラスの別フォルダから育ちました）。続いて Kafka が43枚、DevOps が38枚、Web フロントエンドが36枚、データエンジニアリングが34枚で、Python、SQL、アーキテクチャ、アルゴリズムの4分野がそれぞれ33枚でした。残りの14の小さな分野は、iOS、Linux CLI、C++、Java Spring、テストと QA、BI、SEO、Rust、Node.js、PHP、LLM メモリ、音声、執筆、Go です。

これは計画ではありません。エージェントと作業するとき、私の時間が実際にどこへ行っているかの地図です。LoRA の学習、C++ プラグインのデバッグ、リサーチです。どの分野も、私にとって何かが壊れた場所のリストを集めていて、そのリストが骨格になりました。

知識は同じ速さでは古くならない

アルゴリズムと数学は安定しています。3年前に書いた償却解析やネットワークフローのカードは、今も正しいままです。拡散モデルの学習、推論の最適化、ComfyUI のノードは数か月ごとに変わり、秋にうまくいったものが春には古くなっています。非常に大きな写真に対するタイル分割された拡散処理は、40メガピクセルの写真で拡散モデルが継ぎ目を描く理由で書きましたが、動きの速いトピックの1つです。

そのため、分野ごとに固有の鮮度のしきい値があります。安定した分野にはありません。動きの速い分野では、60日より古いカードはレビュー対象になり、1日1回動くフックがそれを「確認と更新」のリストに載せます。これは削除の警告ではありません。トピックがおそらく動いていて、今の事実と照らし合わせて確認が必要だという注意喚起です。古くなったカードは、エージェントを静かに誤らせるのではなく、自分からレビューに上がってきます。

ベクトルではなくリンク

この種のものの当たり前の設計は、ベクターデータベースの上に RAG を載せることです。意味的に近いテキストを素早く見つけ、本番でもよく機能します。私はあえてそれを使いませんでした。理由は3つあります。

ベクターストアは人が読めません。 Markdown なら、テキストエディタで開き、grep し、git で diff し、メールに貼り、印刷して壁に留めることもできます。今日動き、10年後にも特別なツールなしで、どのコンピュータでも動きます。ベクトルストアは、それ自身のクライアントしか理解しないバイナリです。ベンダーを変え、サービスを失い、API を壊せば、データは誰も読めない数字の山になります。私は、道具が変わっても知識が生き残ってほしかったのです。ツールに依存してほしくありませんでした。

ベクトル化はほぼ不可逆です。 埋め込みは損失のある一方向の圧縮です。元のチャンクを隣に保存していなければ、埋め込みのファイルは役に立ちません。読めるテキストを取り戻すのはほぼ不可能だからです。埋め込みの逆変換の研究はありますが、それは非常に短い断片に対して動き、同じ埋め込みモデルが必要で、別途学習したデコーダも必要です。また、1つの埋め込みモデルに縛られます。品質向上のためにモデルを替えれば、古いベクトルは新しい空間では意味を持たないため、すべてを再インデックスしなければなりません。

そして、私にとっていちばん重要なこと：リンクのグラフは、どのトピックが隣接しているかを記録するのであって、どのテキストが似ているかを記録するのではありません。 ベクトルの類似度が見つけるのは、語彙や概念が重なるトピックです。実際の作業で価値あるリンクは、遠く離れたトピック同士をつなぐことが多いのです。私の Kafka のレプリケーションのカードは、メモリプロファイリングのカードにリンクしています。トピックが似ているからではなく、コンシューマーのチューニング中にメモリリークが見つかり、その経験が両者を隣同士にしたからです。埋め込み空間では、「分散キューのレプリケーション」と「Python のメモリプロファイリング」は遠く離れていて、意味検索ではその橋は架かりません。手で書いた wiki リンクなら架かります。今では、Kafka を読むエージェントが、メモリプロファイリングから1ステップの距離にいます。

仕組みは単純です。カードは [[flux-klein-9b-inference]]、[[two-phase-commit]]、[[saga-pattern]] のように、互いを参照します。ビルド時に、Python のフックが各 slug を相対パスに解決します。slug が見つからなければログに警告が出ます。strict モードではビルドが失敗するので、壊れたリンクが公開サイトに届くことはありません。4月時点で、このようなリンクは2,100以上ありました。それがナレッジグラフのすべてです。埋め込みも、ベクターデータベースも、RAG もありません。Markdown と grep だけです。エージェントは分散トランザクションのカードを開き、See Also の下に隣接するトピックを見て、1つをたどって作業を続けます。入り口から動くパターンまで3ステップです。

これは、CLAUDE.md は582行 で説明した、エージェントのメモリにある [[filename]] リンクと同じ考え方です。

サイトはリポジトリのビルド

happyin.space のすべては、オープンなリポジトリの Markdown から作られた静的サイトです。データベースもバックエンドも、隠れた層もありません。ファイル docs/kafka/broker-architecture.md は、ビルド後にページ happyin.space/kafka/broker-architecture/ になります。仕組みはそれだけです。

つまり、誰でもフォークして、約5分でローカルに動かせます。

git clone https://github.com/AnastasiyaW/knowledge-space.git
cd knowledge-space
pip install -r requirements.txt
mkdocs serve        # then open http://localhost:8000

これで、すべてのカード、全文検索、リンクのグラフを備えたローカルコピーができます。そこから、私の分野を消して自分のものを足し、エージェントを公開サイトではなくローカルのビルドに向けることができます。私自身の使い方もそうです。大半の時間はローカルのビルドを開いていて、公開サイトはミラーです。

フルビルドは約5秒で終わりました。古いノートパソコンでも、ワークステーションでも同じ速さです。その下にあるのは、業界が15年使ってきた種類の静的サイトジェネレーターだからです。ローカルのコピーに対して作業するエージェントは、ネットワークの往復やデプロイの待ち時間にトークンを使いません。ビルドして、カードを開いて、レシピを取ります。

同じビルドのステップが、リンクを正直に保ちます。すべての [[slug]] をたどり、対応するカードを見つけて相対パスを書き込みます。見つからなければビルドは失敗します。コミット前にローカルで確認でき、CI も同じチェックを strict モードで実行し、壊れたリンクがあればデプロイをブロックします。4月時点で、2,100以上のリンクがあり、壊れたものは1つもありませんでした。そして、サイトがリポジトリそのものなので、すべてが git に入っています。カードがどう変わったか、どの事実がどのリサーチの後に届いたか、いつ最後に触られたかが見えます。知識の古くなる速さで並べた知識ベースにとって、この履歴は重要です。

調査結果はどうやって入るか

この流れは、私がデータを手で動かすことが一切ないように組まれています。Claude のアカウントを複数持ち、それぞれで複数のチャットを開いていて、どのチャットでもいつでもディープリサーチが始まる可能性があります。新しいモデル、最適化、バグ、何でもです。以前は、結果はチャットが終わるまでしか残りませんでした。今では、そうしたチャットはすべて同じ常設ルールに従います。リサーチが終わったら、結果のコピーを中央の1か所に置くことです。

その場所は、knowledge-space リポジトリに紐づいた Claude Code のプロジェクトです。そこには research/inbox/ フォルダがあり、すべてのアカウントのすべてのチャットから、生のダンプが集まります。コピー＆ペーストはありません。各チャットが最初に読み、リサーチが終わったら従うルールがあるだけです。

次に、2段階目の処理があります。knowledge-space プロジェクトの別のセッションが受信箱を処理します。各生ダンプを読み、具体的な事実と落とし穴を抜き出し、カードの形式に組み直し、その分野にある既存の内容と照らし合わせます。重複がカードを増やすのではなく、既存のカードを充実させるようにするためです。その後、wiki リンクを確認し、ビルドを回し、差分を読んで push します。こうしたセッション1回で、数時間のうちに新規または充実したカードが20〜40枚できることが多いです。

モデルの階層化は、ここから直接出てきます。ここで私はついに Sonnet の使い道を見つけました。私にとって Sonnet は、「単純なことには賢すぎ、面白いことには単純すぎる」の間にあるものでした。しかし、「生のリサーチダンプを読み、事実を抜き出し、カードの形式に組み直し、フォルダ内の隣接カードと比べる」は、まさにそれにふさわしい種類の作業です。機械的ですが、言語を扱います。Sonnet はより大きなモデルと同じくらい上手にテキストを組み直せて、コストもかなり低いので、リサーチのチャットと受信箱の処理はどちらも Sonnet で動かしています。wiki リンクの確認、2枚のカードを統合すべきかの判断、2つの情報源の矛盾の解決は、理解して判断して設計する作業なので、より強いモデルに回しています。コストの差は数倍ですが、品質は落ちません。

結果として流れができます。私は本来の作業をし、途中で別々のチャットでリサーチを回し、私が何も移動したり整形したりせずに、ベースは埋まっていきます。

使う、そして加える

いちばん簡単な使い方は、エージェントを happyin.space/llms.txt に向け、必要に応じてカードを取り込ませることです。それだけで、方向づけに使っていた最初の3分の1のトークンが減ります。

次のレベルは貢献することです。リポジトリには、そのために書かれた2つのファイルがあります。CONTRIBUTING.md は、ページを準備して変更を送るための一般的なガイドです。AGENTS.md は、エージェント向けの指示です。カードの形式、文章の密度、Gotchas に何を書くか、wiki リンクの書き方、新しいカードや修正の pull request の開き方を説明しています。エージェントにガイドと新しいリサーチ結果を渡せば、エージェントがカードを自分で組み立てます。あなたのリサーチはベースに入り、同じものに二度とお金を払わなくてよくなり、他の人もそれに二度とお金を払わずに済みます。README には MIT ライセンスと書かれています。

ベースにリサーチが増えるほど、誰かが同じリサーチをやり直す必要は減ります。より多くの人とエージェントがカードを送るほど、分野をまたぐ予想外の橋が増えます。そして、それこそが価値のあるものです。このサイトのプロジェクトページは happyin.space です。

4月以降の変化

2026年9月の更新。リポジトリの README は、現在 28 の分野にわたる 1,287 本以上の記事と、3,139 件以上の相互参照を報告しています。増加の大半は2種類の新しいページです。projects/ は388ページで、ニュースのパイプラインが追跡するツール、モデル、プロダクトごとに1ページあります。organizations/ は45ページで、企業やラボごとに1ページです。鮮度のルールは、README では4段階のサイクルになりました。安定、年次、6か月ごと、毎月です。画像生成とエージェントのフレームワークは、毎月の区分に入っています。

4月の数字（785枚のカード、26の分野、2,100以上のリンク、60日のしきい値、5秒のビルド）は、公開日の時点で正しく、そのまま残しています。サービスよりプレーンなファイルを選ぶという同じ好みを、同時に動く複数のエージェントのセッションに当てはめた話は、1つのリポジトリで複数の Claude を動かすにあります。