ragnarok

ragnarok

Claude Code 向けの、Obsidian ボルトを対象としたローカル RAG 検索です。

ragnarok は、コンピューター上にある 1 つ以上の Obsidian ボルトの Markdown ノートをインデックス化します。ローカル MCP サーバーにより、Claude Code はインデックスを検索するツールを利用できます。ノートがコンピューターの外に出ることはありません。埋め込みにはローカルの Ollama モデルを使用し、インデックスは 1 つの SQLite ファイルに保存されます。

機能

• ハイブリッド検索。 各クエリでは、密ベクトル検索（sqlite-vec の埋め込み）とキーワード検索（BM25 を使う SQLite FTS5）を実行します。逆順位融合で 2 つのリストを統合します。順位付けの単位はノートで、最も関連性の高いセクションが使われます。
• 見出しごとのチャンク。 分割処理では、各ノートを見出しの位置で区切り、ごく短いセクションは結合します。
• フロントマターまたはパスからのメタデータ。 各ノートには、ボルト、プロジェクト、領域、タイプ、ステータス、チケットキーが付与されます。まずフロントマターから値を取得します。値がないノートには、設定内のパスルールを適用します。
• プロジェクト検索。 find_projects は、プロンプトでプロジェクト名が指定されていない場合も含め、プロンプトの続きまたは類似のプロジェクトを見つけます。list_project は、プロジェクトのすべてのノートを返します。
• 常に最新。 各ツール呼び出しの前に、ボルトをスキャンして変更されたノートを探し（通常は 100 ms 未満）、埋め込みを生成します。監視プロセスは不要です。
• プライベートノート。 設定したプライベートパスにあるノートもインデックスに含まれますが、サーバーからは返されません。設定で allow_private = true にすると、ユーザーだけが開けるようになります。
• 認証情報の秘匿。 インデックス作成処理と open_note は、平文のパスワード、トークン、キーを [REDACTED] に置き換えます。ボルト内のファイルは変更されません。
• フロントマターの補完。 ragnarok backfill propose は、ボルトで不足しているフロントマターのキーを提案するファイルに書き出します。ragnarok backfill export は、説明が必要な各公開ノートについて、タイトルと冒頭の行を含む JSON ファイルを書き出します（認証情報は削除されます）。Claude は説明を 1 つ以上の JSON ファイルに {path: {"description": "...", "type": "..."}} の形式で書き込みます。ragnarok backfill merge <vault> <file>... は、それらを提案ファイルに反映し、認証情報を削除します。また、25 語を超える説明と、説明のない各行を報告し、デフォルトのタイプを Claude が指定した有効なタイプに置き換えます。提案を確認してから、ragnarok backfill apply を実行すると、ボルトのバックアップアーカイブが作成され、不足しているキーだけが追加されます。
• 評価。 ragnarok eval は、独自の質問セットを使って grep、キーワード検索、密ベクトル検索、ハイブリッド検索を比較します。ragnarok eval agent は、Claude Code エージェントと grep、およびエージェントと MCP ツールを比較します。
• ワンコマンドでセットアップ。 ragnarok init はモデルとインデックスをインストールし、Claude Code プラグインから MCP サーバーが提供されない場合は、Claude Code に登録します。ragnarok doctor はセットアップを確認します。

必要条件

• Homebrew がインストールされた macOS。セットアップでは Ollama に brew services を使用します。
• Ollama：brew install ollama。
• Claude Code。
• uv：brew install uv。uv は Python 3.12 をインストールします。見つからない場合、setup.sh が uv をインストールします。

セットアップ

ragnarok は、PyPI では ragnarok-mcp として、MCP Registry では io.github.freyr/ragnarok として公開されています。

Claude Code プラグインを使う（クローン不要）

Claude Code で実行します。

/plugin marketplace add freyr/ragnarok-bundle
/plugin install ragnarok@ragnarok

次に、ターミナルで実行します。

uvx ragnarok-mcp init

プラグインは uvx ragnarok-mcp serve でサーバーを起動し、各セッションに検索のガイダンスを追加します。ホームフォルダーは ~/.ragnarok です。別のフォルダーを使用するには、~/.claude/settings.json の env とシェルで RAGNAROK_HOME を設定します。

チェックアウトからセットアップ

git clone https://github.com/freyr/ragnarok-bundle.git
cd ragnarok-bundle
./setup.sh                      # installs uv if needed, then runs `ragnarok init`

チェックアウトしたフォルダーがホームフォルダーになります。

init の動作

ragnarok init は6つの手順を実行します。各手順がすでに完了している場合は、その手順をスキップします。

1. config.example.toml から config.toml を作成します。ボルトフォルダーを格納するフォルダーであるボルトのルートを尋ね、各サブフォルダーをボルトとして追加します。
2. Ollama がインストールされていることを確認します。
3. brew services start ollama を使って Ollama をログインサービスとして起動します（事前に確認します）。ターミナルで ollama serve を実行するなど、Ollama が brew services 以外で起動している場合、init はそれを停止してサービスを起動します。
4. 埋め込みモデルをダウンロードします。
5. インデックスを構築します。ノートが1,500件あるボルトでは、Apple Silicon 搭載 Mac で約12分かかります。
6. プラグイン ragnarok が MCP サーバーを提供する場合は、ユーザースコープの登録を削除します（事前に確認します）。そうでない場合は、Claude Code のユーザースコープに MCP サーバー ragnarok を登録します（別の登録を置き換える前に確認します）。

手順6の後に Claude Code を再起動してください。ragnarok doctor は同じ6項目を確認し、問題ごとに修正方法を表示します。

手順5の前に config.toml を確認してください。ボルトではないフォルダーを削除し、プライベートパスを追加します。後から設定を変更した場合は、再起動することなく、次回の ragnarok index または MCP ツール呼び出し時に反映されます。

Claude Code での使用

サーバーは6つのツールを提供します。

ツール	動作
search	ノートを対象としたハイブリッド検索です。フィルター：ボルト、プロジェクト、領域、タイプ、アーカイブ済み。
find_projects	プロンプトに一致するプロジェクトと、各プロジェクトの概要および一致したノートです。
list_project	1つのプロジェクトに属するすべてのノートです。
open_projects	進行中のプロジェクト（デフォルトでは state: in-progress と paused）を、状態ごとにグループ化し、更新日時の新しい順に表示します。
open_note	ノート全体または1つのセクションの本文と、そのリンクおよびバックリンクです。4,000語を超えるノートでは、各セクションの見出しパス、語数、最初の文を含むアウトラインを表示します。
find_by_jira	ABC-123 のようなチケットキーを含むノートです。

プラグインは、プラグインのツール名 mcp__plugin_ragnarok_ragnarok__* を使って、以下のガイダンスを各セッションに自動で追加します。プラグインを使わない場合、Claude Code は必要に応じて MCP ツールを読み込みます。Claude が grep の前に MCP ツールを使うようにするには、たとえば次のような短い指示を ~/.claude/CLAUDE.md ファイルに追加してください。

## Finding notes: ragnarok first

The `ragnarok` MCP server indexes my Obsidian vaults. Use it before Grep or Glob whenever you look for
notes, earlier work or context:

- `find_projects`: the prompt continues or resembles earlier work and names no project. Then call
  `list_project` on the best match (look at the top 3).
- `search`: facts, decisions, how something was done. Filters: vault, project, area, type.
- `open_note`: read a note or one section, with its links and backlinks. A long note gives its outline first; open the section you need by heading.
- `open_projects`: which projects are in progress or paused.
- `find_by_jira`: a ticket key such as `OPS-77`.

The tools are deferred. Load them in one call before the first use:
`ToolSearch` with `select:mcp__ragnarok__search,mcp__ragnarok__find_projects,mcp__ragnarok__list_project,mcp__ragnarok__open_projects,mcp__ragnarok__open_note,mcp__ragnarok__find_by_jira`.

If the tools are absent (for example on a computer without ragnarok), fall back to Grep and say so.
Results can be unrelated: read the text before you rely on it, and cite note paths. Private notes are
refused by design; do not work around the refusal with Read or Grep.

ボルトに合わせた調整

docs/vault-requirements.md では、ragnarok を最大限活用するために必要なボルトの構成（見出し、プロジェクトフォルダー、SUMMARY.md、フロントマター、プライベートフォルダー）について説明しています。

デフォルトのパスルールでは、<vault>/<area>/<project>/note.md の形式を想定しています。ボルトの構成が異なる場合は、リポジトリのスキル .claude/skills/adapt-vault/ が、Claude Code による変更をガイドします。チェックアウトしたリポジトリで Claude Code を開き、ragnarok をボルトに合わせて調整するよう依頼してください。このスキルは次の処理を行います。

1. 各ボルトで ragnarok survey を実行します。
2. ほかの変更を行う前、また新しいボルトを vaults に追加する前に、プライベートフォルダーについてユーザーと合意します。
3. ragnarok inspect で確認しながら、パスルールを config.toml に書き込みます。
4. ユーザーの同意を得たうえでフロントマターの一括補完を実行し、apply の前にユーザーによる確認を行います。
5. ノートから小規模な評価セットを作成し、ragnarok eval mechanical を実行します。
6. ユーザーに確認してから、上記のガイダンスを ~/.claude/CLAUDE.md に追加します。

変更するのは config.toml のみで、フロントマターのキーを追加します。ノートやフォルダーを移動、名前変更、削除することはありません。

設定

config.toml はホームフォルダーにあります。このファイル内の相対パスは、ホームフォルダーを基準とします。 各キーの説明は config.example.toml にあります。特に重要なキーは次のとおりです。

キー	内容
root, vaults	ボルトを格納するフォルダーと、インデックスを作成するボルトのフォルダーです。
[vault_paths]	root の外にあるボルトのフォルダーです。たとえば、kb = "~/code/kb" のように指定します。ノートキーは <vault>/<path> のままです。
private_patterns	"Notes/Journal/**" のような、非公開ノートのグロブパターンです。
model, dimension	Ollama の埋め込みモデルと、そのベクトルサイズです。モデルのネイティブ次元より小さい次元を指定すると、短いベクトルになります（Ollama の dimensions）。変更後は ragnarok index --rebuild が必要です。
query_prefix, doc_template	モデルプロファイルのクエリプレフィックスとドキュメントテンプレートを上書きします。テンプレート内の {title} は、ノートのタイトルと見出しのパスです。プロファイルは embeddinggemma-2:270m（および -bf16-text）、qwen3-embedding:0.6b と :4b、snowflake-arctic-embed2、bge-m3 に対応しています。その他のモデルには、embeddinggemma-2:270m のプレフィックスが使われます。旧キーの doc_prefix も doc_template として引き続き使えます。変更後は ragnarok index --rebuild が必要です。
keep_alive	呼び出し後に Ollama が埋め込みモデルをメモリに保持する時間です。秒数を表す整数、-1（デフォルト。ロードしたままにします）、または "30m" のような期間を指定します。変更後に再構築は必要ありません。
min_words, max_words	分割処理のチャンクサイズの上限と下限です。分割処理では、チャンクをモデルプロファイルのトークン上限（トークンあたり4文字）に合わせて分割します。また、長すぎるとして Ollama が拒否するテキストは2つに分けて埋め込みます。Ollama がテキストを切り詰めることはありません。変更後は ragnarok index --rebuild が必要です。
chunk_prefix	none（デフォルト）または description を指定します。description を指定すると、各本文チャンクのテキストの前にノートの説明が追加され、モデルに送信されます。保存済みのテキストとキーワードインデックスは変わりません。変更後は ragnarok index --rebuild が必要です。
note_rank	ノート内のチャンクからランクを決める方法です。maxp（デフォルト。最も良いチャンク）、topk_sum（密ベクトルリストとキーワードリストそれぞれで、ノート内の上位3チャンクのスコアを合計）、または note_vector（3つ目のリストとして、各ノートのチャンクベクトルの平均も使用）を指定します。変更後は新しいインデックスが必要です。
[variants.<name>]	ベンチマーク用です。バリアントは model、dimension、query_prefix、doc_template、min_words、max_words、chunk_prefix、note_rank を上書きします。
[corpora.<name>]	ベンチマーク用です。バリアントがインデックスを作成する root と vaults のリストを指定します。
project_markers	次のいずれかのファイルがあるフォルダーをプロジェクトフォルダーとして扱います（デフォルトは DRIVERS.md、SUMMARY.md）。
jira_prefixes	find_by_jira が認識するチケットのプレフィックスです。
[vault_rules.<vault>]	1つのボルトのパスルールです。どのフォルダーをエリアとプロジェクトにするかを指定します。

ノートのメタデータ

ragnarok は次のフロントマターキーを読み取ります。いずれも省略できます。

---
project: heating-upgrade     # the project slug; default: from the path rules
area: home                   # a wide subject; default: from the path rules
type: plan                   # drivers, summary, research, spec, plan, brainstorm, review, decision,
                             # guide, reference, meeting, log, template or note
status: active               # active or archived; a note in an _archive folder, or in a project
                             # whose SUMMARY.md has state: superseded or abandoned, is archived; state: done is current
description: One sentence about the note, which improves find_projects.
jira: [ABC-123]              # ticket keys, in addition to the keys in the text
---

フロントマターがない場合、パスルールからメタデータが決まります。デフォルトのルールは、 <vault>/<area>/<project>/note.md という構成のボルトで機能します。異なる構成の場合は、[vault_rules.<vault>] テーブルを追加してください。ノートのメタデータを確認するには、 ragnarok inspect <note path> を使います。

コマンド

コマンド	内容
ragnarok init	このコンピューターをセットアップします（「セットアップ」を参照）。
ragnarok doctor	セットアップを確認します。
ragnarok index [--rebuild]	インデックス内のノートを追加、変更、削除します。パスルール、プライベートパス、マーカーを変更した後は、新しい埋め込みを作成せずに、すべてのノートのメタデータを再生成します。.md マーカーファイルを追加または削除した場合は、そのファイルがあるフォルダー内のノートに対して同じ処理を行います。--rebuild が必要なのは、model、dimension、min_words、max_words を変更した場合のみです。埋め込みキャッシュは保持されるため、キャッシュにないチャンクテキストのみを埋め込みます。
ragnarok status	インデックスのサイズと状態を表示します。
ragnarok search "<query>"	ターミナルから検索します。
ragnarok inspect <path>...	ノートのメタデータを表示します。
ragnarok chunks <path>... | --stats	ノートのチャンク、または合計を表示します。
ragnarok serve	MCP サーバーを stdio で実行します。Claude Code が起動します。
ragnarok backfill propose|export|merge|apply <vault> [file...]	不足しているフロントマターキーを提案し、説明を追加して適用します。順序は propose、export、Claude が説明を作成、merge <vault> <file>...、提案内容を確認、apply です。
ragnarok survey <vault> [--json]	Vault フォルダーのフォルダー、フロントマターキー、マーカーファイル、名前のパターン、チケットのプレフィックスを出力します。[vault_rules.<vault>] を記述する前に実行してください。ノートのテキストは出力しません。
ragnarok eval mechanical|pool|agent	data/eval/sets/ の質問セットを評価します。
ragnarok bench index --variant <name> --corpus <name>	data/variants/<variant>/<corpus>/index.db にあるコーパス上で、バリアントのインデックスを作成または更新します。埋め込みキャッシュを共有するため、デフォルトの埋め込み設定を使うバリアントでは再度の埋め込みは発生しません。バリアントに別の設定で作成されたインデックスは拒否します。
ragnarok bench run --set <file> --variant <name>	セット内の各質問を、セットのコーパス上にあるバリアントのインデックスで MCP 検索にかけます（limit は 20、変更スキャンあり、フィルターなし）。各質問について、期待される各ノートの順位、スキャン時間、検索時間、質問と正解ノートのキーワードの重複度、および正解ノートの BM25 順位を data/bench/<set hash>-<variant hash>.json に書き込みます。最初に上限なしでバリアントのインデックスを最新の状態にします。期待されるパスがインデックスにない場合、またはプライベートな場合はセットを拒否し、該当する各パスとその理由を列挙して、質問を実行しません。
ragnarok bench compare --set <file> <A> <B> [<B2>...] [--margin 0.05]	各バリアントの recall@5 と MRR を層別および領域別に示し、クラスター・ブートストラップ（サンプル数 10,000、固定シード）による B − A の差と 95% 区間を示します。B が複数ある場合、区間の水準は Holm 補正に従います。不一致の質問の割合と、診断情報を含む変更された各質問を列挙します。最後に、各 B について判定行を 1 行出力します（セット形式を参照）。
ragnarok bench convert <draft set> --out <file> --name <name> --kind synthetic|real --corpus <name>	ragnarok eval のドラフトセットをセット形式に変換します。層には元の type を、クラスターには最初の期待パスを使用し、領域は最初の期待ノートのメタデータルールから取得します（ノートがない場合は unknown）。期待パスがない質問や、期待パスがフォルダーである質問は変換せず、それぞれを列挙します。

セット形式

セットは1つの JSON ファイルです。

{
  "name": "pilot", "kind": "real", "version": 2, "corpus": "real", "hash": "<SHA-256 of the questions>",
  "questions": [
    {"id": "q01", "question": "What is a field stop?", "expected": ["Private/Astro/Field Stop.md"],
     "stratum": "lookup", "area": "astro", "cluster": "Private/Astro/Field Stop.md", "notes": "optional"}
  ]
}

• kind は synthetic または real です。corpus は設定のテーブル [corpora.<name>] です。
• hash は、questions リストをキー順に並べ、空白なしの JSON として表したものの SHA-256 です。ハッシュが一致しないセットはベンチマークで拒否されます。
• expected には1つ以上のノートパスを指定します。継続質問には、対象プロジェクトの SUMMARY.md を指定します。
• cluster はメインの正解ノートへのパスです。ブートストラップでは質問ではなく、クラスターを抽出します。
• recall@5 は、期待されるノートがすべて上位5件に含まれる場合は1、それ以外は0です。MRR は最初に見つかった期待ノートの順位を使用します。上位20件に期待されるノートがない場合は0です。

bench compare の判定は次のとおりです。

• 合成セットの場合、recall@5 または MRR について、Holm 補正後の信頼区間で B − A の下限が0を上回り、もう一方の指標の差の点推定値が0未満ではなく、検索時間の p95（スキャンを含む）が500 ms未満であれば、B の勝利と判定します。レポートには、各ボルトにおける差の符号も表示されます。
• 実データセットでは勝敗を判定しません。B が悪化していないことを確認します。recall@5 と MRR について、B − A の信頼区間の下限が −margin を上回る必要があります。p95 時間も確認します。

各コマンドは uvx ragnarok-mcp を使って実行します。たとえば uvx ragnarok-mcp search "boiler" のように実行するか、チェックアウト内で uv run を使用してください。

ファイルの場所

すべてホームフォルダーにあります。RAGNAROK_HOME が設定されていればその場所、そうでなければチェックアウト、さらにそれもなければ ~/.ragnarok が使われます。チェックアウト内では、git は config.toml、data/、logs/ を無視します。

パス	内容
config.toml	このコンピューターの設定です。
data/index.db	SQLite インデックスです。これと data/embed-cache.db を別のコンピューターにコピーすると、最初のインデックス作成を省略できます。
data/embed-cache.db	すべてのインデックスファイルで共有される埋め込みキャッシュです。キーはモデル、次元、ドキュメントテンプレート、テキストハッシュです。
data/variants/<variant>/<corpus>/index.db	コーパスに対するベンチマーク用バリアントのインデックスです。MCP サーバーがこれを使用することはありません。
data/bench/	bench run の結果です。セットとバリアント設定ごとに1つのファイルが作成されます。
data/backups/	backfill apply が書き込み前に作成するボルトのアーカイブです。
data/proposals/	backfill propose と backfill export の出力です。
data/eval/	質問セット（sets/）、評価結果、エージェント評価のミラーです。
logs/server.log	MCP サーバーのログです。ツール呼び出しごとに時刻とともに1行記録されます。

Ollama はモデルを ~/.ollama に保存します。

リポジトリの構成

このリポジトリには、MCP サーバーと Claude Code プラグインマーケットプレイス ragnarok が含まれます。

src/ragnarok/  tests/             the MCP server, the PyPI package ragnarok-mcp
pyproject.toml  server.json       the package and the MCP Registry entry
CHANGELOG.md                      the changelog of the server
.claude-plugin/marketplace.json   the marketplace "ragnarok": lists each plugin and its folder
plugins/<name>/                   one folder for each plugin, with .claude-plugin/plugin.json
plugins/CHANGELOG.md              the changelog of the plugins
templates/plugin/                 the skeleton for a new plugin
scripts/                          the version bump and the validation of the plugins

サーバーとプラグインは、それぞれ別のバージョンとタグを使用します。server-vX.Y.Z と plugin-vX.Y.Z です。

開発

サーバー

uv run pytest
uv run ruff check . && uv run ruff format --check .

プラグイン

1回のセッションでフォルダーからプラグインを読み込みます。

claude --plugin-dir plugins/<name>

または、チェックアウトをローカルマーケットプレイスとして追加します。すると /reload-plugins により、新しいバージョンを作成せずに編集内容を読み込めます。

claude plugin marketplace add <path of the checkout>

プラグインを追加するには、templates/plugin/ を plugins/<name>/ にコピーし、PLUGIN_NAME と ONE_LINE_DESCRIPTION を置き換えて、.claude-plugin/marketplace.json にエントリを追加します。scripts/validate-plugins.sh ですべてのプラグインを検証できます。プラグインの version を手動で変更しないでください。

サーバーのリリース

1. pyproject.toml と server.json の両方の version フィールドにバージョンを設定し、CHANGELOG.md にセクションを追加します。
2. マージ後、タグをプッシュします。git tag server-v1.2.3 && git push origin server-v1.2.3。
3. ワークフロー publish.yml は3つのバージョンがタグと一致することを確認し、テストを実行して、信頼されたパブリッシングを使ってパッケージを PyPI に公開した後、server.json を MCP Registry に公開します。

タグ v1.0.0 から v2.1.0 までは、プラグインがこのリポジトリに移動する前のサーバーリリースです。

プラグインのリリース

すべてのプラグインとマーケットプレイスで、同じバージョンを使用します。plugins/ または .claude-plugin/ に変更を加える main へのプッシュごとに、plugins-release.yml が実行されます。最後の plugin-v タグ以降のコミットメッセージを確認し、 コミットメッセージ内のマーカーによってリリースが決まります。

マーカー	リリース	例
[major]	1.4.2 → 2.0.0	Rename the search skill [major]
[minor]	1.4.2 → 1.5.0	Add the setup command [minor]
[patch]	1.4.2 → 1.4.3	Fix the hook matcher [patch]
なし、または [none]	リリースなし	Edit the README

マーカーはプラグインを変更するコミットにのみ付けてください。ワークフローは最後のプラグインタグ以降のすべてのコミットメッセージを読み取ります。マーカーが見つかると、ワークフローは plugins-ci.yml を実行し、.claude-plugin/marketplace.json と各 plugin.json に新しいバージョンを設定し、 git-cliff（cliff.toml）を使って plugins/CHANGELOG.md にセクションを追加し、 コミットを作成して、plugin-vX.Y.Z タグを付け、GitHub リリースを公開します。

ライセンス

MIT。詳細は LICENSE を参照してください。