Skip to content
Projects

kimushun1101/mikke has 49 GitHub stars and 1 forks. Star changes are not measured yet. Last checked 2026-11-15 23:35 UTC. Last push 2026-11-11.

How these counts are measured

Measured star growth

in 24h
Update delayed
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

日本語 Markdown ノートのローカル検索 CLI 👀 — BM25 全文検索 (SQLite FTS5) + optional なローカル semantic/hybrid。単一バイナリ・外部 API 不使用、AI コーディングエージェント向け。

Productivity

README.md

Original

mikke

日本語 Markdown ノートのためのローカル検索 CLI。「みっけ👀」

Markdown ノートの入ったフォルダ (YAML frontmatter + wikilink、Obsidian 互換) を対象に、BM25 全文検索・タグ/タイトル検索・semantic 検索を単一バイナリで提供する。Claude Code / Codex CLI / Cursor 等の AI コーディングエージェントに、人のノート資産を検索させることを主眼に設計している (人間が直接叩いてもよい)。

  • 日本語対応の BM25 全文検索 — SQLite FTS5 (trigram tokenizer)。形態素解析なしで日本語・英語混在ノートを検索できる
  • 即起動・依存ゼロ — 単一バイナリ。エージェントが 1 セッションに何十回叩いても待ちがない
  • semantic / hybrid 検索 (optional, --features semantic) — ローカル embedding + RRF 融合。外部 API 不使用でノートが外に出ない
  • graceful degradation — 埋め込みが無い環境では自動的に BM25 のみで動く
  • フォルダごとに独立・git 不要 — 対象はただのフォルダでよく、git repo である必要はない。index はルート直下 .mikke/ に生成 (git 管理下なら gitignore する)。設定はルートの mikke.toml 1 枚 (全キー省略可、隠したい場合は .mikke.toml)。ノートフォルダを別のノートフォルダの下に置いた場合、親からの走査はネストされた側の [scan] 設定を尊重する
  • health チェック — frontmatter 破損・タグ/要約欠落などを設定駆動で検査 (CI 向け index --check あり)。md レポートは決定的に生成され「変化した時だけ commit」運用ができる

設計思想と運用フローは docs/concept.md、挙動の正確な仕様は docs/SPEC.md、開発の経緯や実装の仕組みは Zenn 記事 で解説している。

インストール

Linux (x86_64) / macOS (Apple Silicon):

curl -fsSL https://raw.githubusercontent.com/kimushun1101/mikke/main/install.sh | sh

Windows (x86_64) は PowerShell で:

irm https://raw.githubusercontent.com/kimushun1101/mikke/main/install.ps1 | iex

配置先は両 OS とも ~/.local/bin (Windows は %USERPROFILE%\.local\bin)。Linux / macOS は PATH に無ければ追加方法を案内するだけだが、Windows は配置先をユーザー PATH に自動追加する (変更したくなければ実行前に $env:MIKKE_NO_MODIFY_PATH = "1")。

cargo でビルドして入れる場合 (既定はスクリプトと違い BM25 のみ):

cargo install --git https://github.com/kimushun1101/mikke --locked

既定で semantic 検索入りの full 版が入る (cargo install のみ BM25 のみが既定)。スクリプトは配置後に installed: (配置したファイル) と、PATH 上で mikke が見つかれば active: (実際に起動するもの) を示し、別の実体 (cargo 版など) が先に見つかれば警告する。slim 版の指定・環境変数によるオプション・PATH の扱い・cargo 版との併存・Releases からの手動取得・トラブルシューティングは docs/install.md。

使い方

cd <ノートフォルダ>
touch mikke.toml          # 初回のみ。ルートの目印
mikke index               # index 生成 (初回は検索時に自動生成される)
mikke find 検索 語        # 全文検索 (BM25 順)
mikke find 言い換え 表記ゆれ --any # いずれかを含むノートを検索 (OR。既定は AND)
mikke find 検索 語 --snippet # 当たった行を行番号付きで最大 3 行表示
mikke find 検索 --top 5   # 件数を絞る (find / tag / title)
mikke tag タグ名         # タグ検索
mikke title キーワード     # タイトル検索
mikke recent 10           # 最近のノート
mikke list-tags           # タグ一覧
mikke links ノート         # 発リンク (wikilink 先をノートへ解決して表示)
mikke backlinks ノート     # 被リンク (このノートを指すノートの一覧)
mikke health              # 健全性チェック
mikke embed               # 埋め込み生成 (semantic feature 必須)
mikke semantic クエリ      # 意味検索
mikke hybrid クエリ        # BM25 + semantic の RRF 融合
mikke hybrid 言い換え 表記ゆれ --any # BM25 側を OR 検索

検索系コマンド (find / tag / title / semantic / hybrid / recent) と list-tags は --json で JSON Lines (1 行目メタ行 + 1 件 1 行) を stdout に出力する。jq やスクリプトから安全にパースでき、exit code は変わらない。スキーマは docs/SPEC.md の「出力フォーマット」。

find と hybrid の複数語は既定で全語を含むノートに絞る (AND)。言い換え・表記ゆれを並べて、いずれかを含むノートを 1 回で引くには --any (OR) を使う。hybrid --any では BM25 ストリームだけが OR になり、semantic には原文クエリを渡す。

find --snippet は各ヒットについて、検索語が当たった本文の行を行番号付きで最大 3 行表示する (多くの検索語を含む行を優先する)。全角・半角と大文字・小文字は find と同様に吸収するため、grep で再検索せずに開くノートを絞れる。--json と併用すると hit 行に matches 配列が加わる。

ルートは --root PATH 明示指定 → 環境変数 MIKKE_ROOT → cwd からの mikke.toml (設定を隠したい場合は .mikke.toml) 上方探索の順で決める。git 管理の有無によらず、mikke.toml (または .mikke.toml) を置くか --root / MIKKE_ROOT を指定したフォルダが対象になる。どれでも決まらなければ exit 2 で終わる。

設定 (mikke.toml)

ノートフォルダのルートに置く。全キー省略可で、空ファイルでもルートマーカーとして機能する。

# mikke 設定 — https://github.com/kimushun1101/mikke
[semantic]
enabled = true   # semantic / hybrid の意味検索を使う場合のみ (既定 false。mikke embed の前提)

走査から外す exclude_dirs / exclude_files は名前の完全一致で、どの深さにも効く。パスや glob は効かない。root 相対のパスで 1 か所だけ外すには exclude_paths (例: exclude_paths = ["state"])、.gitignore に従うには respect_gitignore = true を使う (既定では .gitignore を見ない)。. で始まるディレクトリや .md ファイルも、それだけを理由には除外せず走査する。ディレクトリで既定で外すのは exclude_dirs の既定名と、常時除外の .git / .mikke だけであり、ツールが作る .trash や .history などは exclude_paths または exclude_dirs で外す。未知のキーや効かない値は stderr に警告し、型の違いはエラー (exit 2) にする。

全キーの注釈付きサンプルは docs/SPEC.md の「設定スキーマ」を参照。

semantic / hybrid 検索

--features semantic 付きビルドで、ローカル embedding (candle 製・純 Rust) による意味検索が使える。外部 API は使わずノートは外に出ない。

mikke embed                # 埋め込みを生成 (2 回目以降は変更ノートのみ差分更新)
mikke embed --force        # 全件再構築
mikke semantic あの摩擦補償っぽいやつ   # 意味検索 (言い換え・表記ゆれ・日英混在に強い)
mikke hybrid 発振 対策      # BM25 と semantic の RRF 融合
  • モデルは既定で intfloat/multilingual-e5-small (mikke.toml の [semantic] model で変更可。BERT 系アーキテクチャのみ対応)
  • 長いノートは token 数で overlap 付きの窓に分けて埋め込み、semantic では全窓の最大類似度をそのノートの score にする。結果は従来どおりノート単位
  • 初回の embed/semantic 実行時にモデルを Hugging Face から自動ダウンロードする (約 470MB)。cache は HF_HUB_CACHE → $HF_HOME/hub → $XDG_CACHE_HOME/huggingface/hub → 既定の ~/.cache/huggingface/hub の優先順
  • オフライン / 社内網: 上記の cache へ取得済みの models--intfloat--multilingual-e5-small/ をそのままコピーすれば動く。Hugging Face のミラーを使う場合は HF_ENDPOINT で指定できる
  • 差分検出はファイル内容の SHA-256。計算結果は途中でも一定の窓数ごとに (ノートの切れ目で) 保存され、中断後の mikke embed は保存済みノートの全窓を再利用して続きから再開する。モデルや prefix を変えた場合は自動で全再構築する
  • chunk 保存形式の導入前に作った埋め込みは互換性がないため、更新後の初回 mikke embed で全件を自動的に作り直す

AI エージェントから使う

mikke は AI コーディングエージェントにノート資産を検索させる用途を主眼にしている。組み込みは 2 段階:

  1. 指示書にスニペットを貼る — examples/agents/mikke.md を、ノートフォルダの CLAUDE.md / AGENTS.md など使っているツールが読む指示書にそのまま貼る。ツール非依存の検索手順 (root 解決から検証まで) で、どのエージェント CLI でも使える。

  2. 再利用可能な手順書として組み込む — ツールが手順書の仕組みを持つ場合 (例: Claude Code の skill) は、examples/skills/mikke/SKILL.md を土台にできる。起動条件・find のクエリセマンティクス (語ごと quote の AND 連結)・0 件時のフォールバック手順 (find → hybrid → Grep) まで含む実戦形の例なので、自分の運用・ツールに合わせて調整して使う (Claude Code ならノートフォルダの .claude/skills/mikke/SKILL.md にコピー)。

検索系コマンド (find / tag / title / semantic / hybrid) は grep の慣習で 1 件以上ヒット = exit 0 / 0 件 = exit 1 / エラー = exit 2 を返すため、0 件時のフォールバック判定は出力文言でなく exit code で書ける (if mikke find ...; then や mikke find ... || mikke hybrid ...)。詳細は docs/SPEC.md の「exit code」。

開発

cargo build            # BM25 のみ
cargo test             # golden 統合テスト (tests/golden/ の期待出力と厳密比較)
cargo test --features semantic                # semantic 込み (モデル不要のテストまで)
cargo test --features semantic -- --ignored   # embed/semantic/hybrid e2e (要 モデル cache かネットワーク)

システムに C コンパイラ (cc) が必要 (rusqlite の bundled SQLite ビルド用)。

CLI 表面・設定キー・出力の意味は安定インターフェース (docs/SPEC.md が正本)。挙動を変える時は仕様と tests/golden/ を意図して同時に更新する。