obsidian-knowledge-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

コマンド

npm run build                                   # tsc
npm test                                        # tsc してから dist/test/*.test.js を node --test で実行
node --test dist/test/chunker.test.js           # 単一ファイル (先に npm run build が必要)
node --test --test-name-pattern "containment" dist/test/*.test.js   # 単一テスト

npm run check                                   # Biome の lint + format 検査 (書き込みなし)
npm run check:fix                               # 検査して安全な自動修正を適用
npm run format                                  # format のみ適用
npm run lint                                    # lint のみ

テストは src/ ではなく dist/ のビルド出力を実行する。npm test は毎回 tsc を挟むが、node --test を直接叩くときはビルドが古いままにならないよう注意する。

lint / format は Biome (biome.json) に集約している。vcs.useIgnoreFile を有効にしてあるので対象範囲は .gitignore に従う (dist/ と node_modules/ は自動で外れる)。check:fix で消えない指摘には --unsafe でしか直せないものが混ざる。当てるなら npx biome check --write --unsafe の後に必ず npm test まで通すこと。

動作確認とデータ投入には VAULT_ROOT / KNOWLEDGE_DIR と起動済みの ollama が要る (環境変数の一覧は README.md)。

VAULT_ROOT=/path/to/vault KNOWLEDGE_DIR=knowledge npm run dev-search -- "クエリ" --top-k 5
VAULT_ROOT=/path/to/vault KNOWLEDGE_DIR=knowledge npm run eval

アーキテクチャ

エントリポイントは 3 つ (src/index.ts の MCP サーバー、src/dev-search.ts の CLI、eval/run-eval.ts) あるが、いずれも src/search.ts の searchKnowledge() を共有する。検索ロジックを変えるときはこの 1 箇所を見ればよい。

searchKnowledge() は冒頭で必ず syncIndex() を呼ぶ。これが「検索した瞬間に必ず最新」を担保する設計の中核であり、インデックス更新は独立したバックグラウンド処理ではなく検索パスに埋め込まれている。同期は mtime/size の突合なので、変化が無ければ stat のコストしかかからない。

データの流れは chunker.ts (markdown → チャンク + frontmatter) → ollama.ts (チャンク → embedding) → store.ts (sqlite へ投入) の一方向。indexer.ts がこの 3 つを束ねてファイル走査と差分検知を担う。

変更時に壊しやすい結合

embedding 次元 — ollama.ts の EMBEDDING_DIM (1024) が store.ts の vec0 テーブル定義に文字列展開されている。EMBED_MODEL を次元の違うモデルへ変えるなら、この定数と既存 DB の両方を作り直す必要がある。次元不一致は投入時ではなく embedBatch() の検証で先に落ちる。