Kanji
・クラウド / AIエージェント開発 / フリーランス ・AWS・GCP・自律型AIの現場実務と試行錯誤を発信 ・愛媛出身 / 東京在住 (1993年生) プロフィールの詳細
目次
自律型AIコーディングエージェント（Google Antigravity, Claude Code, Kiro等）を日常的な開発パートナーとして本格運用し始めると、誰もが直面する最大の壁があります。それは、 「セッションが終了するたびに、過去の試行錯誤や設計判断を綺麗さっぱり忘れてしまう」 という問題です。
現在、Claude の MEMORY.md 、Kiro の公式 Memory 機能、Google Antigravity の Brain 領域や /learn 、OpenAI Codex のコンテキスト保持など、各エージェントでも「長期記憶（Long-term Memory）」の実現に向けた機能開発が急速に進んでいます。しかし、企業の複雑な既存コードベースや障害対処のノウハウを、トークンを浪費せずに高精度かつセキュアに扱うには、依然として大きな課題が残されています。
MEMORY.md
/learn
私自身、この課題を解決するために当初はローカルノートツールの定番である Obsidian（Vault）と各種連携プラグインを活用し、エージェントに知識を読み込ませる構成を試していました。しかし、開発を自動化・高度化していくにつれて、GUI依存や検索精度の面でいくつもの限界に直面しました。
そこで今回、AIエージェントの長期記憶基盤（Agent Memory Hub）を根本から見直し、「LanceDB（高速ベクトルDB）＋ SQLite FTS5（キーワード全文検索）＋ 再帰CTE（WikiLinkグラフ探索）＋ ローカルCross-Encoder（リランカー）＋ Markdown SSOT」を組み合わせた自律型ハイブリッドアーキテクチャへと刷新しました。
本記事では、各AIエージェントの長期記憶機能の現状を整理した上で、Obsidian単体連携で直面したリアルな課題と、新構成（Gen 3）の設計思想、アーキテクチャ詳細、そして実際に移行して得られた変化と実測メトリクスを詳しく解説します。
現在主流のコーディングエージェントは非常に賢く、指示を与えれば自律的にコマンドを実行し、ファイルを編集してテストをパスさせることができます。
しかし、エージェントは基本的に セッション単位で独立 しています。そのため、以下のような知見がセッションをまたいで引き継がれません。
これらの知識を毎回プロンプトに長々と書き込むのは非効率であり、貴重なコンテキストウィンドウ（トークン枠）を圧迫します。必要な時に、必要な過去の知見だけをピンポイントで想起できるセッション横断の長期記憶基盤がどうしても必要でした。
とはいえ、「記憶を持たせる」こと自体は各社のコーディングエージェントも既に取り組んでいます。まずは現状のアプローチを整理し、何が不足しているのかを明確にしておきます。
現在、開発の現場で日常的に使われている主要なコーディングエージェントでも、「セッションの壁を超えて記憶を保持する」ための機能開発が急速に進んでいます。
特に注目すべきは、 Claude Code の MEMORY.md （Auto-memory機能） や、 Kiro の公式 Memory 機能 ( kiro.dev/docs/memory/ ) 、そして Google Antigravity の「Brain領域」と「 /learn コマンド」 です。 Antigravity では会話ごとに独立した Brain ディレクトリ（ <appDataDir>/brain/ ）を持ち、実行計画やアーティファクト、詳細な思考ログ（ transcript.jsonl ）を永続化するほか、ユーザーの指摘から教訓を自律学習する /learn コマンドを備えています。また、Claude Code や Kiro もエージェント自身が経験知やプロジェクトルールをファイルに書き溜めて自動参照する機能を公式サポートしています。
kiro.dev/docs/memory/
<appDataDir>/brain/
transcript.jsonl
しかし、実務の大規模開発で知見が数百〜数千件に増えてくると、 「単一の Markdown ファイルに追記してプロンプトに流し込む方式」 や 「セッション単位の Brain 領域を個別に漁る方式」 では以下の壁に直面します。
だからこそ、「人間が普段使いのエディタで普通に追記・修正でき、エージェントが完全なヘッドレス環境からミリ秒でピンポイントに想起できるセキュアなローカル長期記憶基盤（Hybrid GraphRAG）」が必要になったのです。
最初に採用したのは、世界中で愛用されているローカルMarkdownエディタ Obsidian を核とした構成でした。
Obsidian はノート同士を [[WikiLink]] で相互リンクでき、美しいナレッジグラフビューを備えています。Smart Connections や Obsidian Copilot、Local REST API などのコミュニティプラグインを組み合わせることで、エージェントからVault（ノート保管庫）を読み書きさせるアプローチを試みました。
[[WikiLink]]
しかし、実務の自律開発ループに組み込む中で、以下の 4つの決定的な壁 に突き当たりました。
Obsidian 本体および主要な REST API プラグイン（ obsidian-local-rest-api 等）は、基本的に「Desktop only」と明記されており、macOS/Windows上で Obsidian アプリが起動していることを前提としています。 Docker等でVaultディレクトリを直接読み書きする代替実装は一部存在するものの、プラグインの索引・UI連携・Obsidian依存機能を維持したままのヘッドレス運用は極めて困難です。自律エージェントの主戦場であるターミナルCLIやCI/CD環境、Dockerコンテナ、リモートPCなどのGUIを持たない環境ではアプリを常時起動しておくことが難しく、自律的な記憶読み書きパイプラインが途切れてしまいました。
obsidian-local-rest-api
Obsidian のAIプラグインの多くは、ローカルモデル（BGE-micro等）やクラウドAPI（OpenAI等）問わず、Embeddingベースのセマンティック検索（ベクトル検索）に大きく依存しています。 文章全体の意味が近いノートを探すのは得意ですが、ソフトウェア開発で頻出する 「エラーコードや識別子の完全一致」 を保証しません。例えば ERR_CERT_AUTHORITY_INVALID のような特定のエラーコード、ライブラリの正確な型番、 S3 や Go といった2文字の短い固有名詞を検索すると、ベクトル空間の近似によって関係のないノートがヒットしたり、肝心のノウハウを取りこぼす現象が多発しました。
ERR_CERT_AUTHORITY_INVALID
S3
Go
Smart Connections の公式ドキュメントでも「semantic queries do not behave like plain text search（セマンティック検索はプレーンテキスト検索とは異なる挙動をする）」と明記されており、完全一致する文字列が存在していても意味的類似度が低ければ結果に表示されないリスクがあります。エラーコードや製品名などの正確な文字列照合には、BM25 のような Lexical（語彙）検索 とのハイブリッド化が不可欠でした。
Obsidian のナレッジグラフは、人間が視覚的に俯瞰するには最高ですが、低レイテンシで動的な多ホップ探索を行う標準APIは提供されておらず、エージェントがプログラムから再帰的に探索する用途には不向きでした。 Markdown 内の [[リンク]] を自前でパースしてグラフを組めば解決可能ですが、Obsidian 本体の標準機能やプラグインに頼る形では、「ある設計書（ADR）に関連するインシデント事例を1〜2ホップ自動で手繰り寄せてコンテキストに注入する」といったミリ秒単位の動的 GraphRAG は実現できませんでした。
[[リンク]]
多くの Obsidian AI プラグインで採用されている素朴な RAG パイプラインでは、ベクトル検索の上位結果をそのままプロンプトに流し込む設計が一般的です。 文脈の微妙に異なるチャンクが無加工で混入すると、エージェントの推論精度低下（ハルシネーション）を招くだけでなく、貴重なコンテキストウィンドウとトークン費用を浪費してしまいます。不要なノイズを削ぎ落とす Cross-Encoder による再ランク処理 が組み込まれていない点も、実務での課題となりました。
これらの課題を解決するために構築したのが、「正本（SSOT）は Obsidian 互換の Markdown のまま維持し、検索・探索エンジンを完全にヘッドレス化・高速化したハイブリッド構成（Gen 3）」です。
本アーキテクチャの主要コンポーネントとその役割は以下の通りです。
長期記憶の正本（Single Source of Truth）は、独自のバイナリデータベースではなく、Git管理されたプレーンな Markdownファイル群（Vault） に置いています。 各ファイルには YAML Frontmatter（ID, title, tags, category等）と [[WikiLink]] 記法を含めています。これにより、人間は Obsidian や VS Code でいつでも普通にメモを閲覧・編集・リンクでき、Obsidian のグラフビューもそのまま活用できます。
セマンティックな類似度検索には LanceDB を採用しました。
Xenova/multilingual-e5-small
ベクトル検索の弱点を補うため、SQLite の全文検索拡張（FTS5）を並行稼働させています。 trigram トークナイザーを採用することで、日本語の形態素解析漏れや英数字混じりのエラーコード、2文字の略語であっても、完全一致するキーワードを確実に BM25 スコアリングで拾い上げます。
trigram
Markdown 内の [[WikiLink]] をパースして SQLite のリンクテーブルに格納しています。 エージェントが特定のノートを検索した際、SQLite の 再帰 CTE（共通テーブル式） を実行することで、関連するリンク先や被リンク先を 1〜2 ホップ分、わずか数ミリ秒で芋づる式に自動取得できます。
LanceDB（ベクトル）と SQLite（BM25）の検索順位を RRF（Reciprocal Rank Fusion, k = 60 k=60 ）で統合します。 さらに、ローカル軽量 Cross-Encoder モデル（ japanese-reranker-xsmall-v2 、ONNX INT8 最適化）を通すことで、最終的に 本当に価値のある上位3〜5件のチャンクだけを厳選 します。M5 Mac 環境において、全リランク処理は 200ms 以内で完了します。
japanese-reranker-xsmall-v2
ここまでの内容を踏まえ、Obsidian単体構成と新構成（Gen 3）を、アーキテクチャ特性・検索能力・実リソース消費の3軸で比較します。 特にヘッドレス環境への適性とリソース効率の差 が、実務運用上の分岐点になります。
ローカル環境や開発マシン（M5 Mac）上で長期運用するにあたり、リソース効率の差は顕著でした。実機における測定値の内訳は以下の通りです。
常駐メモリの劇的削減（約1/30以下） Obsidian は Chromium/Electron ベースのため、プラグインを導入して常駐させておくだけで 500MB〜1GB 以上のメモリを常に占有します。一方、新構成の FastMCP サーバーはアイドル時の常駐メモリがわずか約16MBです。検索やリランク処理が走る瞬間だけ一時的にメモリを確保し（ピーク時でも約80〜150MB）、完了後は即座に開放されるため、常駐させていることを忘れるほど軽量です。
ディスク容量はDB全体で10MB未満、モデル込みでも約190MB 数千件規模のドキュメントをパースした状態でも、SQLite の全文検索・グラフインデックスはわずか816KB、LanceDB のベクトルデータは8.1MBです。ONNX INT8 最適化を施した Cross-Encoder モデル一式を含めても、ディスクフットプリント全体で約190MBに収まります。
待機時 CPU 負荷はほぼ 0.0% Obsidian のファイル監視（Watcher）やUI描画に伴う微小なCPU消費（0.5〜3%）に対し、新構成は完全なイベント駆動型（stdio/SSE）です。待機中の CPU 使用率はほぼ0.0%を維持し、エージェントからの問い合わせ時のみ、M5 チップの NEON ベクトル演算をフル活用して数十ミリ秒〜180ミリ秒程度で処理を完遂します。バッテリー駆動中のノートPCでも負荷をほとんど感じさせません。
このハイブリッド構成に変更してから数週間運用していますが、エージェントとの協働体験は大きく向上しました。
過去に発生した認証エラーや設定ミス（例: パスキーのタイムアウト設定や特定リージョンの制限）のメモを一度保存しておくだけで、次に類似タスクをエージェントに依頼した際、 「過去のインシデント知見（incident-xxx）を参照し、安全な設定値を適用しました」 と自律的に配慮してくれるようになりました。
ハイブリッド検索と Cross-Encoder の組み合わせにより、エージェントに渡すコンテキストは常に厳選された数件の重要知見のみに絞り込まれます。これにより、プロンプトのトークン消費が抑えられ、LLM の回答速度と精度が向上しました。
エージェント専用の特殊な管理画面を開く必要はありません。人間は普段使いの VS Code や Obsidian で Markdown ノートを書き、Git にコミットするだけです。バックグラウンドで差分検知スクリプト（ sync_vault.py ）が自動でベクトルDBと全文検索インデックスを更新してくれます。
sync_vault.py
定性的な体験向上だけでなく、日々の開発セッションにおける 消費トークン量 と 応答速度（レイテンシ） を実測比較しました。
トークン消費量が 1/15 〜 1/20 に激減 : 従来はナレッジが増えるたびに CLAUDE.md や MEMORY.md のファイルサイズが肥大化し、毎回 20,000 トークン前後がコンテキストを占有していました。新構成では、LanceDB と SQLite で候補を絞り込み、Cross-Encoder で本当に必要な 3〜5 チャンク（約1,200トークン）だけを動的に切り出すため、 1回のセッションあたりのプロンプト消費トークンを 90% 以上削減 できました。API 課金額の節約はもちろん、コンテキスト枯渇による「直前の会話を忘れる」問題も解消しました。
CLAUDE.md
応答速度（Time to First Token）が 3〜5倍 高速化 : 巨大なコンテキストを LLM に読み込ませると、モデルが最初のトークンを出力し始めるまで 4〜7 秒以上の思考待機時間（TTFT）が発生していました。新構成ではプロンプトが軽量化されたことに加え、ローカルのハイブリッド検索＋リランクが わずか 150ms 前後 で完了するため、エージェントが指示を受けてから動き出すまでのレスポンスが 1 秒前後に短縮。思考の引っかかりがなくなり、対話のテンポが劇的に改善しました。
一方で、この構成への移行はゼロコストではありません。LanceDB や SQLite FTS5、ONNX ランタイムのセットアップ、Embeddingモデルのローカル配置、Git post-commit フックの整備など、 初期構築には一定のエンジニアリングコストがかかる 点は考慮しておく必要があります。小規模なチームやプロジェクトでは、まず MEMORY.md のような軽量な方式から始め、知見の蓄積量や検索精度の要求が高まった段階で本構成への移行を検討するのが現実的なステップです。
Obsidian は人間にとって最高のナレッジツールですが、AIエージェントが実務の現場で自律的に活躍するためには、「GUIからの解放」「完全一致と意味検索の両立」「高速なグラフ探索」「ローカルリランク」が不可欠でした。
今回の構成変更を通じて、「Markdown Vault による人間向けの視覚的な知識資産」と、「LanceDB ＋ SQLite によるAIエージェント向けの高速自律インデックス」という、人間とAIの双方が最も心地よく共存できるアーキテクチャを実現することができました。
AIエージェントの記憶管理やナレッジベース構築に悩んでいる方は、ぜひ「Markdown SSOT ＋ ハイブリッド検索」のアプローチを検討してみてください。
