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.
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 コーディングエージェント向け。
ProductivityREADME.md
Originalmikke
日本語 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.toml1 枚 (全キー省略可、隠したい場合は.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 段階:
指示書にスニペットを貼る — examples/agents/mikke.md を、ノートフォルダの
CLAUDE.md/AGENTS.mdなど使っているツールが読む指示書にそのまま貼る。ツール非依存の検索手順 (root 解決から検証まで) で、どのエージェント CLI でも使える。再利用可能な手順書として組み込む — ツールが手順書の仕組みを持つ場合 (例: 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/ を意図して同時に更新する。