Retrieve The Forgotten Memory

---

問題

あなたの AI エージェントは、状況が見えていないまま作業しています。

何千ものファイルを grep しても、質問への答えが書かれたドキュメントを見落とし、存在しないモジュールをでっち上げ、前回のセッションで決めたことを忘れてしまいます。プロジェクトが大きくなるほど、状況は悪化します。より賢いモデルを追加しても、改善しませんでした。ボトルネックは知能ではなく、検索だからです。

コードインデクサー（Augment、Sourcegraph、Cursor）が対象にするのはコードだけです。しかし、プロジェクトはコードだけではありません。仕様書、PR、アーキテクチャ上の決定、研究論文、PDF、規制文書、保管庫のメモなど、エージェントが推測をやめるために必要なコンテキストがあります。

これを作った理由

私はフランスの税務に関する記事を書いていました（規制文書は約50ページ、法令条文間の相互参照、判例、行政解釈を含みます）。Claude Code は同じディレクトリをループしながら grep し続け、コンテキストを使い果たし、自信満々に誤った引用を出していました。メモリを増やし、プロンプトを改善し、より賢いモデルを追加しました。どれもうまくいきませんでした。エージェントの推論が悪かったのではなく、2,000 ファイルからなる法令コーパスで適切な段落を 見つけられなかった からです。そこで、モデルをさらに賢くしようとするのをやめて、欠けていたレイヤーを作りました。それが RTFM です。

解決策

RTFM はあらゆるものをインデックス化します。 1 つのコマンド、1 つの SQLite ファイル、そしてエージェントが grep する前にクエリする検索レイヤーです。

pip install rtfm-ai && cd your-project && rtfm init

30 秒で完了します。Claude Code は、インデックス化したナレッジベース（コード も ドキュメント も PDF も、追加したその他すべて）を、全文検索、セマンティック検索、またはハイブリッド検索で検索できるようになります。エージェントはまず 300 トークン分のメタデータを確認し、関連するものだけを展開します。コンテキストを一括で渡すのではなく、段階的に情報を開示します。

無料。ローカルで動作します。API キーもクラウドも不要です。データはあなたの手元に残ります。

使用例

$ rtfm search "authentication flow" --limit 3
[1] src/auth/handlers.py > authenticate_user (p.2)    score 9.12
    src/auth/handlers.py:147  42 lines
[2] docs/architecture/auth.md > SSO flow (p.1)        score 7.84
    docs/architecture/auth.md:1   23 lines
[3] docs/ADR/0007-oauth.md > Decision (p.1)           score 6.90
    docs/ADR/0007-oauth.md:12  18 lines

3 件の結果で約 300 トークンです。エージェントはコンテキストを一括で渡されるのではなく、rtfm_expand(source, target_section) を使って次に読む内容を決め、対話を続けます。

---

クイックスタート

推奨 — Claude Code プラグイン

Claude Code（CLI またはデスクトップ版の Code タブ）で：

/plugin marketplace add roomi-fields/claude-plugins
/plugin install rtfm@roomi-fields

RTFM は roomi-fields/claude-plugins マーケットプレイス経由で配布されています。このマーケットプレイスには、引用に基づく Q&A 用の notebooklm-mcp も含まれています。両方を一度に入手するには：

/plugin install notebooklm@roomi-fields

これで完了です。プラグインは初回使用時に、各プロジェクトを自動で初期化します：

• .rtfm/library.db（単一の SQLite ファイル）を作成します
• 検索手順を CLAUDE.md に挿入します
• MCP ツールの使用許可を事前に付与します（検索のたびにプロンプトが表示されません）
• 初回のプロンプトでプロジェクトをインデックス化し、その後はプロンプトのたびに差分をインデックス化します

pip install は不要です。 純粋な Python で実装されており、Python 3.10 以降が PATH に設定済みであれば、Linux／macOS／Windows／WSL で動作します。プラグインには独自の MCP サーバーが同梱されているため（mcp SDK への依存はありません）、python3／python／py を自動で解決します。

その後、Claude に 「認証フローを探して」 と伝えると、grep ではなく rtfm_search を使って検索します。

オプションの追加機能（セマンティック検索、PDF 解析）

コアプラグインには依存関係がありません。より大規模なオプションの追加機能（埋め込みモデル、PDF パーサー）は、プラグインのデータディレクトリ内に分離された venv を作成して、必要に応じてインストールされます。システムの Python を汚さず、PEP 668 の競合も発生しません：

/rtfm:install-embeddings    # FastEmbed ONNX (~85 MB), semantic + hybrid search
/rtfm:install-pdf           # pdftext only (~50 MB), fast text extraction
/rtfm:install-pdf-full      # + marker-pdf + CPU-only torch (~1.5 GB), complex layouts

pdf-full のインストールでは、PyTorch の CPU 専用インデックスを使用するため、CUDA や GPU は不要です。サイズは 5 GB ではなく、約 1.5 GB に抑えられます。

追加機能を有効にするには、インストール後に Claude Code を再起動してください。

手動インストール（Cursor、Codex、Claude Desktop チャット、その他の MCP クライアント）

Claude Code のプラグインシステムを備えていないクライアントの場合：

pip install rtfm-ai
cd /path/to/your-project
rtfm init

次に、MCP クライアントの接続先を rtfm-serve（pip パッケージが公開するエントリ）に設定します。オプションの追加機能は pip install rtfm-ai[embeddings,pdf] でインストールできます。

---

比較

	RTFM	Augment CE	Sourcegraph	Code-Index-MCP	MemPalace
コードのインデックス作成	✅（AST 対応）	✅	✅	✅	浅い（文字単位のチャンク）
ドキュメント、仕様書、Markdown	✅（ヘッダー解析）	部分的	❌	限定的	そのままのチャンク
法務／規制関連	✅（XML、BOFiP）	❌	❌	❌	❌
研究（LaTeX、PDF）	✅	❌	❌	❌	❌
カスタムパーサー	✅（約50行）	❌	❌	❌	❌
ナレッジグラフ	✅（ファイル／コードのリンク）	❌	部分的	❌	エンティティグラフ（人物）
ファイルのバージョン履歴	✅（無制限）	❌	❌	❌	❌（削除して置き換え）
MCP ネイティブ	✅	✅	✅	✅	✅
ローカルで実行	✅	クラウド	エンタープライズ	✅	✅
オープンソース	MIT	❌	部分的	✅	MIT
価格	無料	$20-200/mo	$$$/mo	無料	無料

構造解析、コードレベルのナレッジグラフ、ファイルごとの無制限の履歴を備え、複数分野のコンテンツにインデックスを作成できるオープンソースの選択肢は、RTFM だけです。 これがその独自の領域です。

MemPalace との違いに特化して説明すると、MemPalace は会話向けのエンティティレベルのメモリです（SQLite に保存される「人物／プロジェクト／決定」の3項組と、ChromaDB に保存されるそのままのチャンク）。RTFM は 成果物 向けの検索レイヤーです。形式ごとに解析され、ファイルレベルでリンクされ、時間の経過とともにバージョン管理されます。この2つは競合するのではなく、組み合わせて使えます。

RAG の設計上の選択肢（チャンク化、検索、拡張、統合、鮮度、ストレージ）を詳しく知りたい場合は、RAG の基礎 — 6つの軸 → をご覧ください。

---

セッションをまたいで保持されるメモリ

セッションの間、多くのエージェントは情報を忘れてしまいます。RTFM は、マシン上のすべてのプロジェクトにある Claude Code 独自のメモリファイルにインデックスを作成し、完全なバージョン履歴を保持します。

rtfm memory                    # Manual snapshot
rtfm memory --install-hook     # Auto-snapshot on every SessionEnd

• プロジェクト横断インデックス — ~/.rtfm/memory.db にある1つのDBで、マシン上のすべての ~/.claude/projects/*/memory/ ディレクトリを参照できます。rtfm_search("OAuth auth decisions") を実行すると、18個すべてのプロジェクトから結果が得られます。
• 無制限のバージョン履歴 — メモリファイルへの変更はすべてスナップショットとして保存されます（削除されません）。rtfm_history <slug> を実行すると、変更の全履歴を確認できます。
• SessionEnd 時に自動でスナップショットを作成 — 1つのコマンドで、グローバルな Claude Code フックをインストールできます。セッションを終了するたびに、新しいスナップショットが保存されます。
• そのままではなく、厳選された内容 — RTFM は、セッション中にエージェント自身がすでに選び抜いたメモ（小規模で構造化され、情報密度の高いもの）にインデックスを作成します。これは、ChromaDB 内の会話トランスクリプト全体（大規模でノイズが多く、積極的なセマンティックフィルタリングが必要）にインデックスを作成する MemPalace とは異なる考え方です。

---

Obsidian ボルトモード

RTFM は、Karpathy LLM Wiki パターンの検索レイヤーです。Karpathy 自身もこう書いています。「小規模ならインデックスファイルで十分ですが、Wiki が大きくなるにつれて、適切な検索が必要になります。」 これがその適切な検索です。

cd /path/to/your-obsidian-vault
rtfm vault

• .obsidian/ を検出し、フォルダーからコーパスへのマッピングを提案します
• Obsidian のルールに従って [[wikilinks]] を解決し、グラフのエッジとして保存します
• Obsidian ネイティブのナビゲーション（インデックス、Mermaid によるグラフ、ハブ、孤立ノート、Dataview のフロントマター）を備えた _rtfm/ を生成します
• 1,700 ノートの研究用ボルトでテスト済みです

_rtfm/
├── index.md      # Hub: corpus list, top connected documents
├── graph.md      # Hub documents, orphans, broken links, Mermaid
├── recent.md     # Recently modified files
└── corpus/       # Per-corpus indexes

Wiki を書くのは引き続き LLM です。RTFM は、index.md では規模に対応できない検索を担います。

Obsidian ガイド全文 →

---

NotebookLM との統合

RTFM は notebooklm-mcp と自然に連携します。NotebookLM はノートブックごとに 1 日 50 回までしかクエリできませんが、RTFM は回答をローカルにインデックス化してその上限を取り除きます。1 回質問すれば、オフラインでミリ秒単位の検索をいつまでも利用できます。

notebooklm-mcp の /batch-to-vault エンドポイントは、引用元に裏付けられた Q&A を {slug}.md（フロントマター付き Markdown）と {slug}.json（構造化された nblm-answer-v1 サイドカー）として書き込みます。どちらも確実に共存します。統合方法は 2 通りあり、どちらもすぐに利用できます。

• 方法 A — Markdown（設定不要）：ボルトを RTFM に追加して、rtfm sync を実行します。デフォルトの Markdown パーサーが、各回答を質問／回答／引用ごとのチャンクに自動で分割します。マッピングもスキーマもコードも不要です。
• 方法 B — JSON サイドカー（型付きメタデータ）：nblm-answer.yaml マッピングを .rtfm/mappings/ に追加します。各 .json 回答ファイルから、SQL でクエリできる notebook_id、source_name、citation_marker を含む型付きチャンクと、回答とソース間の cites エッジ候補が生成されます。

構造化された引用フィールドでの絞り込みやグラフ化が特に必要な場合を除き、方法 A を使用してください。

NotebookLM のレシピ全文 →

---

測定結果

2 種類のベンチマークを実施しました。実態は単純ではありません。検索が最も役立つのは、実際に解決可能で、エージェントが「情報を探す」ことに時間を費やしているタスクです。

文書中心のタスク：フランス税法に関する記事の作成（B10）

法令、判例、行政解釈のコーパスをもとに、約 50 ページの規制対象記事を執筆します。同じエージェント（Claude Code + Sonnet 4）、同じプロンプトを使い、8 つの構成をテストしました。

構成	所要時間	コスト	トークン
ベースライン（RTFM なし）	8m 16s	$22.61	8.21 M
RTFM あり（FTS デフォルト）	6m 58s	$11.14	3.22 M

Δ：コスト −51 %、トークン −61 %、所要時間 −16 % — 事実の正確性も向上しました。 これは RTFM が想定して作られたユースケースです。grep では適切な段落を見つけにくい、大規模で複数の領域にまたがるコーパスを検索します。

コードタスク：FeatureBench（LiberCoders データセット）

11 個のタスク、規模の異なる 3 つのリポジトリ、4 つの条件（A = ファイルパスを含む標準プロンプト、B = パスなしでの探索、C = RTFM FTS、D = RTFM ハイブリッド）、各 3 回実行。

リポジトリ	サイズ	RTFM が役立つ場面
metaflow	620 ファイル	すべて解決可能 — RTFM に測定可能な改善効果はありません
astropy	1,119 ファイル	すべての条件で F2P の合格率は 25–30 %。完全に解決した条件はありません
mlflow	8,255 ファイル	すべての条件で F2P の合格率は 0–5 %。完全に解決した条件はありません

規模を絞った単一の実行（metaflow の test_stub_generator）では、RTFM によってエージェントの所要時間がパスなしのベースラインと比べて −37 % 短縮されました。より大規模なリポジトリでは、検索方法にかかわらず、タスク自体が難しすぎたため、Sonnet 4 は 20 分のタイムアウト内に解決できませんでした。

正直な注意点

• モデルは1つ（Sonnet 4）、エージェントは1つ（Claude Code）です。統計的に確実とは言えません。
• 小規模なリポジトリ（ファイル数が1,000未満）なら、grep で十分であり、RTFM はオーバーヘッドになります。
• FeatureBench が測定するのはコードの変更であり、情報検索ではありません。検索ツールの評価には適さないベンチマークですが、現時点で存在するベンチマークがこれしかないため、これを使って評価しています。より適したベンチマーク（RepoQA、SWE-QA、LocAgent）は今後のロードマップに含まれています。

ここから分かること

ボトルネックが**「2,000ファイルのコーパスから適切な段落を見つけること」**の場合、RTFM は測定可能な成果を上げます。解決不可能なタスクを魔法のように解決可能にするわけではありません。モデルが作業を行う必要があることに変わりはなく、RTFM はその作業に適したコンテキストを確実に得られるようにするだけです。

---

対象ユーザー

RTFM は、プロジェクトにコード以外のものも含まれる場合に役立ちます。

• LegalTech — コード＋税法＋規制仕様。Legifrance XML と BOFiP のパーサーが付属します。
• 研究 — コード＋LaTeX 論文＋データセット。LaTeX と PDF のパーサーが付属します。
• FinTech — コード＋金融規制＋XBRL レポート。50行のコードで XBRL パーサーを作成できます。
• HealthTech — コード＋医療記録（HL7/FHIR）＋臨床ガイドライン。
• 大規模プロジェクトに取り組む個人開発者 — セッションのたびにエージェントが同じ8,000個のファイルを grep するのを眺めるのは、もうやめましょう。
• Obsidian / PKM ユーザー — 保管庫を AI で実際に検索できるようにします。
• 規制対象のあらゆる業界 — プロジェクトにコードと専門分野の文書が混在しているなら、RTFM が役立ちます。

---

全機能一覧

検索と取得

• FTS5 全文検索 — 即座に使え、設定不要で、インストール後すぐに動作します
• セマンティック検索 — 埋め込み表現に対応（任意。FastEmbed/ONNX を使用し、GPU は不要です）
• ハイブリッドモード — 両方を組み合わせ、関連度スコアで順位付けします
• メタデータ優先 — 結果としてファイルパスとスコア（約300トークン）を返し、コンテンツ全体は返しません
• 段階的な情報開示 — エージェントは実際に必要なチャンクだけを展開します
• ナレッジグラフ — wikilink と Python の import をグラフのエッジとして解決し、ハブ検出と中心性による順位付けを行います

複数形式のインデックス作成

• 24種類の組み込みパーサー — Markdown、Python（AST）、LaTeX、YAML、JSON、TOML、Shell、PDF、XML、HTML、SQLite、Jupyter、CSV/TSV、XLSX、EPUB、MOBI/AZW、FB2、DJVU、DOCX、ODT、RTF、MIDI、音声タグ（MP3/FLAC/OGG/M4A/WAV/AIFF…）、プレーンテキスト
• 拡張可能 — Python のコード約50行で任意の形式に対応できます
• 自動同期フック — プロンプトのたびにインデックスが最新の状態に保たれ、手動作業は不要です
• 増分処理 — 変更されたものだけを再インデックスします

統合

• Claude Code ネイティブプラグイン — /plugin install rtfm@roomi-fields/rtfm。プロジェクトごとに自動初期化します
• Pure-Python MCP サーバー — 外部依存関係は0個で、mcp SDK、pydantic、ネイティブバイナリは不要です
• クロスプラットフォーム — Linux、macOS、Windows、WSL に対応（PATH 上の Python ≥ 3.10 のみ必要です）
• 14個の MCP ツール — 検索、コンテキスト、展開、グラフ、履歴、同期、タグなど
• 手動インストールの代替手段 — Cursor、Codex、Claude Desktop のチャット、その他あらゆる MCP クライアントでは pip install rtfm-ai を使用します
• CLI ＋ Python API — パイプラインからスクリプトで実行できます
• 非侵襲的 — コードに手を加えず、エディターも置き換えません

---

パーサーのアーキテクチャ

まだ対応していない形式をインデックス化する必要がありますか？約50行のコードでパーサーを作成できます。

from rtfm.parsers.base import BaseParser, ParserRegistry
from rtfm.core.models import Chunk
import json
from uuid import uuid4

@ParserRegistry.register
class FHIRParser(BaseParser):
    """Parse HL7 FHIR medical records."""
    extensions = ['.fhir.json']
    name = "fhir"

    def parse(self, path, metadata=None):
        data = json.loads(path.read_text())
        for entry in data.get('entry', []):
            resource = entry.get('resource', {})
            yield Chunk(
                id=resource.get('id', str(uuid4())),
                content=json.dumps(resource, indent=2),
                book_title=f"FHIR {resource.get('resourceType', 'Unknown')}",
                book_slug=resource.get('id', 'unknown'),
                page_start=1,
                page_end=1,
            )

プロジェクトに配置して Claude Code を再起動すれば、医療用 AI エージェントが FHIR レコードを理解できるようになります。

JSON 統合の2つのレベル

JSON ベースの形式には、Python を使わずに利用できる、もう1つの拡張方法があります。

レベル	作業内容	得られるもの
1. 汎用	何もしません。ファイルをインデックス化するだけです。	トップレベルの各キーがチャンクになります。値を全文検索できます。
2. マッピング	.rtfm/mappings/ に YAML マッピングを配置します（約30行）。	宣言済みメタデータ、カスタムタイトル、配列からの foreach 抽出、エッジ候補を含む、型付きチャンクを得られます。生成元のプロジェクト（NotebookLM、Linear、Notion、OpenAPI など）がマッピングを提供するため、RTFM は汎用性を保てます。

詳しくはJSON スキーママッピングを参照してください。また、具体的な手順についてはRTFM × NotebookLMを参照してください。

組み込みパーサー

パーサー	拡張子	方式
Markdown	.md	ヘッダーで分割し、YAML フロントマターを抽出します
Python	.py	AST ベース：各クラス／関数を 1 つのチャンクにします
LaTeX	.tex	\section、\chapter などで分割します
YAML	.yaml、.yml	最上位のキーで分割します
JSON	.json	最上位のキーまたは配列要素で分割します
TOML	.toml	最上位のテーブル。depends_on エッジを出力します（PEP 621、Cargo、Poetry）
Shell	.sh、.bash、.zsh	関数を考慮してチャンク化します
PDF	.pdf	ページ単位（pip install rtfm-ai[pdf]）
Legifrance XML	.xml	フランスの法典（LEGI 形式）
BOFiP HTML	.html	フランスの税務ドクトリン
SQLite	.sqlite、.sqlite3、.db	テーブルごとのスキーマ＋サンプル行。FK エッジ（読み取り専用）
Jupyter	.ipynb	Markdown の見出しごとにセルをグループ化し、出力を除外します
CSV / TSV	.csv、.tsv	ヘッダー＋サンプル行＋軽量な型推論
XLSX	.xlsx	シートごとのスキーマ＋サンプル（pip install rtfm-ai[xlsx]）
プレーンテキスト	.js、.ts、.rs、.go、...	行の境界でチャンク化（約 500 文字）

---

MCP ツール

ツール	機能
rtfm_search	インデックスを検索します（FTS、セマンティック、またはハイブリッド）
rtfm_context	対象に関連するコンテキストを取得します（メタデータのみ）
rtfm_expand	ソース内のすべてのチャンクを完全な内容とともに表示します
rtfm_discover	プロジェクト構造を高速スキャンします（約 1 秒、インデックス作成不要）
rtfm_books	インデックス化されたドキュメントを一覧表示します
rtfm_stats	ライブラリの統計情報
rtfm_sync	ディレクトリを同期します（増分）
rtfm_ingest	単一ファイルを取り込みます
rtfm_tags	すべてのタグを一覧表示します
rtfm_tag_chunks	特定のチャンクにタグを追加します
rtfm_remove	インデックスからファイルを削除します
rtfm_graph	ソースの依存関係グラフを表示します（インポート、リンク）
rtfm_history	ファイルのバージョン履歴とメモリスナップショット
rtfm_coverage	ディスク上の内容に対してインデックスが保持している内容を表示します

---

CLI リファレンス

# Search
rtfm search "authentication flow"
rtfm search "article 39" --corpus cgi --limit 5

# Sync
rtfm sync                              # All registered sources
rtfm sync /path/to/docs --corpus docs  # Specific directory
rtfm sync . --force                    # Force re-index

# Source management
rtfm add /path/to/docs --corpus docs --extensions md,pdf
rtfm sources

# Obsidian vault
rtfm vault                             # Initialize for cwd vault
rtfm vault /path/to/vault              # Specific vault
rtfm vault --regenerate                # Regenerate _rtfm/ files

# Cross-project Claude memory
rtfm memory                            # Manual snapshot
rtfm memory --install-hook             # Auto-snapshot on SessionEnd

# Status & info
rtfm status
rtfm books
rtfm tags
rtfm history path/to/file.md           # Memory version history

# Semantic search
rtfm embed                             # Generate embeddings (one-time)
rtfm semantic-search "tax deductions" --hybrid

# MCP server
rtfm serve

---

Python API

from rtfm import Library

lib = Library("my_library.db")

# Index
stats = lib.ingest("documents/article.md", corpus="docs")
result = lib.sync(".", corpus="my-project")  # SyncResult(+3 ~1 -0 =42)

# Search
results = lib.search("depreciation", limit=10, corpus="cgi")
results = lib.hybrid_search("amortissement fiscal", limit=10)

# Export for LLM
prompt_context = results.to_prompt(max_chars=8000)

lib.close()

---

RTFM の位置づけ

RTFM はタスクマネージャーではありません。エージェントフレームワークでもありません。すでに使用しているものの下で、エージェントが必要とするナレッジレイヤーです。

┌─────────────────────────────────┐
│  GSD / Taskmaster / Claude Flow │  ← Orchestration
├─────────────────────────────────┤
│              RTFM               │  ← Knowledge (you are here)
├─────────────────────────────────┤
│          Claude Code            │  ← Execution
└─────────────────────────────────┘

RTFM がなければ、オーケストレーターは幻覚を起こすエージェントを動かします。RTFM があれば、エージェントは何を土台に構築しているのかを把握できます。

---

貢献

パーサーの追加は、最も簡単で、最も大きな効果がある貢献方法です。CONTRIBUTING.md をご覧ください。

バグを見つけましたか？アイデアがありますか？issue を作成してください。

謝辞

@AVeryTastyRaspberry は、RTFMをネイティブのWindowsで動作するようにしてくださいました。RTFMはLinux上で開発されており、そこで実行すると、引数を解析する前にCLIがインポート時に終了し、どのコマンドも動作しませんでした。報告（#8）で問題の行が特定され、その後、実際のWindows 11マシンで行われたテストでは、RTFM自身の主張ではなく tasklist と照らし合わせて確認した結果、その箇所に起因する5つの不具合がさらに見つかり、それぞれの修正が確認されました。続く #9 では、繰り返し表示されるコンソールウィンドウの原因が追跡されました。このプラットフォームは、このプロジェクトだけでは対応できなかったものです。

ライセンス

MIT — 自由に使い、フォークし、拡張し、公開してください。

作者

Romain Peyrichou — @roomi-fields

---