Samong

Samong 🧠

すでにリポジトリにあるメモを活用する、ローカルファーストのナレッジベース

一度解決してメモに残した問題も、半年後には、そのメモがリポジトリにあるのに見つけられません。Samong にプロジェクトのルートを指定すると、コミット対象にする .md ファイルを検索・リンクできるようになり、普段使っている AI ツールからも読み取れるようになります。プレーンな Markdown で、Obsidian と互換性があり（[[wikilink]] / [[wikilink|alias]]）、アカウント不要、クラウド不要、バイナリは 1 つです。

Samong を選ぶ理由

• 📁 ノートは、コミット対象にする .md ファイルです。 特別なメモ用フォルダーではなく、リポジトリを指定します。.gitignore を尊重し、依存関係のディレクトリは常に除外するため、プロジェクトのルートを指定すれば node_modules を取り込まずに ADR、運用手順書、設計ドキュメントをインデックス化できます。また、samong doctor で何が対象になり、何が対象にならなかったかを正確に確認できます。
• 🤖 ノートがエージェントの記憶になります。 samong-mcp は MCP に対応しているため、Claude Code と Claude Desktop から、あなたと同じナレッジベースを検索、読み取り、編集できます。セッションのたびにコンテキストを貼り付け直す必要はありません（セットアップ）。
• 🗺 グラフは目新しさのためのタブではなく、ワークスペースです。 ボールトが形を成し、入力すると一致しない要素がすべて薄く表示されるため、クエリがそのまま場所になります。
• 🔎 ノートはタイトルではなくパスで識別します。 1 つのリポジトリに README.md という名前のファイルが 20 個あっても、タイトルでは区別できません。タイトルをキーにしたインデックスでは、それらが気付かれないまま統合されてしまいます。そのため、検索結果、API、MCP ツールのすべてで実際のパスを扱います。
• 📚 コミットしないドキュメントからも学べます。 .gitignore が答えるのは「何を配布するか」です。ナレッジベースが答えるべきなのは「何から学ぶか」です。scope.include を使うと、依存関係に含まれるドキュメントを読み取り専用の参考ノートとして取り込めます。プロジェクトは 1 つ、頭脳も 1 つで、別のボールトは不要です。
• 🔗 ボールトごとにリポジトリは 1 つですが、すべてのボールトをまたいでリンクできます。 [[other-vault/note]] は登録済みのすべてのボールトを横断して解決され、バックリンクも逆方向に反映されます。ボールト間でインデックスを同期する必要はありません。
• 🧭 関連性 と つながりの両方で順位付けします。 単語だけでは 2 つのノートを区別できない場合、ほかのノートから多く参照されている方が先に表示されます。加点は最大 25% に制限されるため、人気のノートが、明らかによりよく一致するノートを追い越すことはありません。
• 🧠 セマンティック検索にも対応し、任意でローカルに実行できます。 --features semantic を指定してビルドし、samong embed を実行すると、単語だけでなく意味も使って順位付けできます。多言語モデルはマシンの外にデータを送信しません。意図的にデフォルトでは無効にしています。詳細は後述します。
• ⚡ 高速で、あなたのものです。 リンクグラフには redb、検索には tantivy を使用し、変更されたファイルだけを処理してインデックスを増分更新します。すべてのインデックスは <vault>/.brain/ に保存され、いつでも .md ファイルから再構築できます。ロックインされる要素はありません。

インストール

手間が少ない順に、4 つの方法があります。

1. パッケージマネージャー

macOS と Linux — waanvar/homebrew-samong：

brew tap waanvar/samong
brew install samong

Windows — waanvar/scoop-samong：

scoop bucket add samong https://github.com/waanvar/scoop-samong
scoop install samong

winget への登録が受理されると、winget は Windows に標準搭載されているため、事前の追加作業なしで winget install Waanvar.Samong を実行できるようになります。マニフェストは packaging/winget/ にあり、CI はプッシュのたびにそこからインストールします。また、リリースごとに Microsoft へのプルリクエストが自動的に作成されます。あとは Microsoft に受理してもらうだけです。 Windows をお使いで、後述の SmartScreen 警告を避けたい場合は、このセクションをご覧ください。ダウンロードリンクではありません。

Arch Linux — パッケージの登録後は paru -S samong-bin でインストールできます。それまでは packaging/aur/ でビルドできます：cd packaging/aur && makepkg -si。

Gatekeeper のプロンプトも SmartScreen の警告もありません。 どちらの方法もアーカイブを自動で取得し、公開されている SHA-256 と照合して検証します。ブラウザー経由でダウンロードされないため、macOS が通常付与する com.apple.quarantine 属性が付かず、Windows にも評価対象となるダウンロードのレピュテーション情報がありません。各タップの CI は実際のランナーにインストールし、このことを前提ではなく実際に検証します。

2. Rust がすでにインストールされている場合

cargo install samong

Web UI を内包した 4 つのバイナリをすべてビルドします。Rust 1.88 以降が必要です。ローカルでコンパイルする場合も、どちらの OS にも問題視されるダウンロードはありません。

3. ダウンロードしてダブルクリック

ダウンロードして展開し、ダブルクリックします：

Windows	Open Samong.exe
macOS	Samong.app
Linux	samong-app（メニューに追加するには、samong.desktop を ~/.local/share/applications/ にコピーします）

ターミナルも設定もアカウントも不要です。初回起動時に Documents/Samong に 2 つのノートを含む保管庫を作成し、インデックスを作成してブラウザーを開きます。その後はすべて、ご自身の Markdown ファイルのフォルダーで管理します。

右上の ⏻ ボタンで停止できます。サーバーはブラウザーのタブを閉じても動作し続けるため、タブを閉じるだけでは終了しません。

すでにどこかにノートがありますか？ 保管庫メニューの + Add vault… を使い、そのフォルダーを指定してください。ファイルの移動や変換は行われません。

ダブルクリックで起動するプログラムには引数がないため、例外的な状況に対応する環境変数が 2 つあります。3117〜3128 番ポートがすべて常時稼働する別のプログラムに使われている場合は SAMONG_PORT、ブラウザーを開かずに起動する場合は SAMONG_NO_OPEN=1 を使います。ランチャーの起動に失敗すると、~/.config/samong/launcher.log にログを書き込み、そのファイルを開きます。

4. バイナリをダウンロードして自分で実行

Releases からいずれかを取得し、展開して実行します。常に最新リリースを指す直接リンク： Linux · Linux ARM · Windows · macOS Apple Silicon · macOS Intel。Rust も Node も不要です — Web UI はすでにバイナリに含まれています。5 つのプラットフォームに対応しています：x86_64-linux、aarch64-linux（Raspberry Pi、ARM サーバー、Asahi）、x86_64-windows、aarch64-macos（Apple Silicon）、x86_64-macos（Intel）。 Windows on ARM 用のアーカイブはまだありません。

ダウンロードしたファイルを、同じ場所に公開されている .sha256 と照合して検証します：

sha256sum -c samong-x86_64-linux.tar.gz.sha256

⚠️ ダウンロードしたバイナリにはコード署名がありません

これは上記のオプション 3 と 4、つまりブラウザー経由で入手するものに当てはまります。 パッケージマネージャーと cargo install には影響ありません。どちらも、OS が警戒するようなダウンロードファイルを残さないためです。

Samong にはコード署名証明書がないため、OS の動作に影響します。

macOS — Gatekeeper は警告を表示するだけではなく、開くことを 拒否します。Samong.app を右クリックして 開く を選択する（初回に限り確認が求められます）か、フラグを解除してください。

xattr -dr com.apple.quarantine Samong.app samong samong-server samong-mcp

Windows — SmartScreen は警告を表示し、発行元を不明として示します。詳細情報 → 実行 を選択してください。実行ファイルには埋め込みアイコンとバージョン情報が含まれているため、ダイアログには単なるファイル名ではなく Samong と表示されますが、証明書がなければここまでです。

どちらも、有料の証明書を持たないオープンソースプロジェクトでは起こることです。ファイルに問題があるという意味ではありませんが、上記のチェックサムを確認し、公式の Releases ページからのみダウンロードしてください。

証明書を購入しても、Windows の警告は消えません。そうなると思える表示なので、ここで説明しておきます。証明書によって「発行元不明」が名前に置き換わるだけです。警告自体は SmartScreen の 評判 に基づいており、2024 年以降は EV 証明書でも即座に評判が得られるわけではありません。また、評判は証明書の拇印にも結び付いているため、証明書を更新するとリセットされます。2026 年 2 月に施行された規則では、更新間隔は最長でも 459 日です。

オプション 1 なら、今日から無料でこれらすべてを回避できます。Scoop、Homebrew、winget はアーカイブを独自に取得して検証するため、どちらの OS でもブラウザーからのダウンロードを評価する必要がありません。

またはソースからビルドする

Rust（stable）と Node.js 20 以降が必要です（Node が必要なのは Web UI を使う場合のみです。Web UI はビルド時にバイナリに埋め込まれます。Node がない場合は CLI + API を利用できます）。

git clone https://github.com/waanvar/samong.git
cd samong
cd web && npm install && npm run build   # build the web UI first (it gets embedded)
cd .. && cargo install --path .          # installs samong / samong-server / samong-mcp

順序が重要です：cargo build／cargo install の前に Web UI をビルドしてください。samong-server は Web UI をバイナリに埋め込むため、UI フォルダーを別途用意する必要のない単一ファイルとして配布されます。（インストールせずにビルドするには、cargo build --release を使用してください。バイナリは target/release/ に出力されます。）

後で samong update を実行すると、最新バージョンに更新できます（下記の 更新 を参照）。

クイックスタート

mkdir my-vault && cd my-vault
samong new "My First Note"         # create + index
samong vault add my-vault .        # register in ~/.config/samong
samong-server start               # opens http://127.0.0.1:3117 in your browser

samong-server start は埋め込み済みの Web UI を提供し、ブラウザーを開きます。UI ファイルを別途用意する必要はありません。--port 8080 でポートを変更し、--no-open でブラウザーを開かないようにできます（従来の samong-server --port 8080 形式も引き続き使用できます）。

CLI コマンド

コマンド	内容
samong new <title>	ノートを作成し、インデックスに登録します
samong edit <title>	$EDITOR で開き、閉じたときに再インデックスします
samong rename <old> <new>	名前を変更し、そのノートを参照するすべての [[wikilink]] を書き換えます
samong delete <title>	削除し、リンク切れのバックリンクについて警告します
samong links <title> [--all-vaults]	順方向リンクとバックリンク（他の Vault からのリンクを含む）
samong orphans / samong broken	リンクされていないノート／存在しないノートへのリンク
samong search <q> [--vault <name>|--all-vaults] [--limit N] [--explain]	全文検索です。--explain は各検索結果の順位付けの根拠を表示します
samong graph [--all-vaults]	リンクグラフのエッジ
samong list	すべてのノートのキーを1行ずつ表示します。これは answers、リンク、MCP サーバーが使用する識別情報です
samong reindex [--full]	インデックスを同期します（変更されたファイルのみ／すべて）
samong embed [--reference]	セマンティック検索用にノートを埋め込みます（--features semantic が必要です）
samong pack <dir> [--include-reference]	公開可能な Vault の内容を外部にコピーします。ノートとマニフェストが対象で、インデックスは含まれません
samong watch	Vault を監視し、インデックスを最新の状態に保ちます
samong vault add/list/remove	中央レジストリを管理します
samong vault install <git-url>	他のユーザーの Vault を読み取り専用の参照ノートとしてインストールします
samong vault update [name]	インストール済みの Vault の最新コンテンツを取得します
samong vault verify [name] [--require-signature]	インストール済みの Vault が公開者の公開内容と一致するか確認します
samong doctor	ノートとして扱われるもの、スキップされたもの、曖昧なタイトルを報告します
samong eval <questions.toml> [--at N] [--vault <name>]	実際の質問を使って検索を評価します。hit@k、MRR、回答不能な質問に回答してしまう頻度を測定します（ドキュメント）
samong update [--check]	最新の GitHub リリースに更新します（--check は確認のみ）
samong-app	ダブルクリックで起動するランチャーです。Vault を検出または作成し、サーバーを起動してブラウザーを開きます

ノートとして扱われるもの（Vault の対象範囲）

ルールは1つです。ノートとは、コミットする .md ファイルです。 プロジェクトのルートをそのまま samong vault add に指定できます。設定は不要です。Samong は以下のように処理します。

• .gitignore を尊重するため、node_modules/、dist/、target/ はインデックスに登録されません
• .gitignore の対象でない場合も、依存関係のディレクトリは常にスキップします （node_modules、vendor、site-packages、__pycache__、Pods、bower_components）
• すべてのドットディレクトリ（.git、.obsidian、.brain）をスキップします

samong doctor で、これらの対象を確認できます。

samong doctor
# vault: /home/me/myproject
# gitignore: respected
# 4 note(s) in scope
# skipped 90 .md file(s) not tracked as notes (web 90)

調整するには、Vault のルートに samong.toml を追加します。コミットしてください。そうすれば、すべてのマシンと中央サーバーで同じルールが読み込まれます。すべてのフィールドは省略可能です。

[vault]
name = "myproject"        # the name used in [[myproject/note]] links

[scope]
notes_dir = "docs"        # only scan this subtree (default ".")
exclude = ["archive/**"]  # extra rules, gitignore syntax
include = []              # directories to index anyway (see below)
follow_gitignore = true   # turn off to index gitignored files too
max_depth = 0             # 0 = unlimited

リポジトリ内のノートが gitignore の対象になっている場合は、.samongignore で対象に戻せます。否定パターンも含め、gitignore と同じ構文です。

!notes/
drafts/

コミットしないドキュメントから学ぶ（scope.include）

.gitignore が答えるのは、**「何を配布するか？」です。ナレッジベースが答えるべきなのは、「何から学ぶか？」**であり、同じ問いではありません。最もわかりやすい例は、依存関係の中に同梱されているドキュメントです。Next.js では、node_modules に400個以上の Markdown ファイルが含まれています。

[scope]
include = ["node_modules/next/dist/docs"]

これらは参照ノートになります。同じ保管庫、同じインデックスなので、自分のノートからの [[installation]] も解決されます。プロジェクトは1つ、知識の拠点も1つです。保管庫をもう1つ用意する必要はありません。

.samongignore に !node_modules/... を指定しても、これはできません。依存関係のディレクトリは、ウォーカーが中を調べる前に除外されるため、否定パターンに一致するものがありません。また、gitignore では、親ディレクトリが除外されているパスを再度含めることはできません。適切な手段は scope.include です。

知っておくべきことが2つあります。

1. 参照ノートはマシンごとに異なります。 samong.toml は Git で共有されますが、node_modules は共有されません。依存関係をインストールしていないマシンや、Git の履歴しか保持していないサーバーでは、参照ノートは見つかりません。これはエラーではありません。Samong はそれらをスキップして警告を1行表示し、samong doctor では存在するルートが報告されます。
2. 参照ノートは読み取り専用です。 save_note／PUT／delete／rename では変更できません。ファイルは依存関係に属しており、編集しても次回のインストール時に消去されるためです。これはエージェントにとって特に重要です。save_note("installation") で、フレームワーク独自のドキュメントページを上書きしてはいけません。

exclude はメインスキャンにのみ適用されます。include ルートの一部を除外するには、include により範囲の狭いディレクトリを指定してください。

意図的に無視されるもの：グローバル gitignore（~/.config/git/ignore）、.git/info/exclude、保管庫より上の階層にある .gitignore ファイルです。これらはマシンごとに異なるため、反映すると、同じリポジトリのインデックスが2台のノートパソコンで異なる状態になります。

他の人が公開した保管庫をインストールする

保管庫を他の人に渡すことができます。samong pack は公開可能な部分（ノートとマニフェストのみで、インデックスは含みません）をコピーし、受け取った人はその結果を Git から直接インストールします。

samong vault install https://github.com/someone/sre-handbook.git

これにより、vendor/sre-handbook にクローンが作成され、scope.include に追加され、自分の .gitignore にも追加されたうえで、インデックスが再作成されます。上記のルールに従い、ノートは参照ノートとして配置されます。同じグラフ、同じ検索機能を使えるので、自分のノートからの [[Runbook]] も参照ノートへ解決されます。また、編集しても次回の samong vault update で消去されるため、読み取り専用です。

理由を添えた .gitignore の行は、自動で追加されます。

# installed vaults (samong vault install)
# Someone else's notes. Committing them here would redistribute
# content that is not yours to redistribute.
/vendor/sre-handbook/

検索結果には、出どころが表示されます。 インストールした保管庫からの検索結果には、CLI、ウェブ UI、API、MCP ツールのいずれでも、その保管庫の名前とライセンスが表示されます。

vendor/sre-handbook/Runbook.md: When the queue backs up, drain it before …
  ↳ from SRE Handbook · CC-BY-4.0

守るべき瞬間は、検索するときではありません。誰かが検索結果の段落を自分の成果物にコピーした後、その出どころを記録するものが何もなくなるときです。ライセンスが明記されていない保管庫には、空欄ではなく licence not stated と表示されます。これは情報の欠落ではなく、明確な回答です。

Vault が発行元のものであることを証明する（samong vault verify）

不足しているのは整合性ではありません。インストール済みの Vault は Git のチェックアウトであり、すべてのバイトはすでにコミットハッシュで保護されています。コンテンツの隣に SHA256SUMS を置いても、その事実を言い換えるだけで、しかもより弱い形になります。ノートを変更できる人は、その隣にあるチェックサムファイルも変更できるからです。

不足しているのは、署名によって示される真正性です。発行元はリリースタグではなくコミットに署名する必要があります。samong vault update はブランチを追跡するため、利用者はタグ間のコミットを取得します。タグの署名では、取得したばかりのコミットについて何も証明できません。

git config commit.gpgsign true

利用者は SSH がホストキーをピン留めするのと同じように、インストール時にそのキーをピン留めします。最初に URL を教えた相手が最初の時点での信頼元となり、それ以降の更新はすべてそのキーに照らして検証されます。

samong vault verify                       # who signed each one, and has anything changed
samong vault verify --require-signature   # fail on unproven, not only on wrong

• 別のキーで署名された更新、または突然署名されなくなった更新は、マージ前に拒否されるため、作業ツリーにもインデックスにも反映されません。（署名を取りやめるのはピン留めに対する最も簡単な攻撃なので、キーの変更として扱われます。）正当なキー変更は、次のコマンドで明示的に受け入れてください。 git -C vendor/<name> config --unset samong.signer
• 未追跡ファイルを含め、ローカルの変更が報告されます。 インストール済みの Vault に紛れ込んだ .md ファイルもインデックスに登録され、発行元のコンテンツとして検索結果に表示されてしまいます。
• 署名されていない Vault はデフォルトで受け入れられます。 現在、世界中のほとんどの Vault は署名されておらず、常に失敗するチェックは誰も実行しません。必要だと判断した場合は、--require-signature を使用できます。

何が誰によって発行されたかを、チェックアウトの外部に保存することはありません。クローン自体が来歴を示すものであり、別の場所に記録を保管しても、チェックアウトとの食い違いが生じるだけです。

更新

samong update は最新の GitHub リリースをダウンロードし、3 つのバイナリ（samong / samong-server / samong-mcp）すべてを、埋め込み Web UI も含めてその場で置き換えます。samong update --check はインストールせずに新しいバージョンがあるかを報告し、samong-server start は更新が利用可能な場合に 1 行の通知を表示します（ベストエフォートで動作し、処理をブロックせず、オフラインでも失敗しません）。

先に GitHub リリースを公開する必要があります （git tag v0.1.0 && git push origin v0.1.0 を実行すると、3 つの OS すべてのバイナリをビルドするワークフローが起動します）。これを行うまで、samong update で更新を取得することはできません。

セマンティック検索（任意）

字句検索で見つかるのは、入力した単語を使っているノートだけです。自分が書いた言葉を思い出せないと、何も見つかりません。セマンティック検索は意味を比較することでこれを解決します。デフォルトではオフですが、これは見落としではなく、意図的な判断です。

cargo install --path . --features semantic
samong embed              # your notes; run it again after you write a lot
samong embed --reference  # also the vendored docs from scope.include (slow)
samong search "how do we stop repeated requests"

必要となるコスト。 この機能では ONNX Runtime を導入し、初回の embed 実行時に Hugging Face から intfloat/multilingual-e5-small を ~/.config/samong/models にダウンロードします。実測値でディスク上の容量は 465 MB です。推定ではなく、470 MB の float32 ONNX グラフと 17 MB のトークナイザーを合わせた容量です。ノートやクエリがマシンの外に出ることはなく、ダウンロード後にネットワーク接続は必要ありません。しかし、「単一のバイナリで、取得するものは何もない」という状態ではなくなります。そして、その約束こそがクラウドツールではなくこのツールを選ぶ理由です。ですから、こちらから押しつけるのではなく、利用するかどうかはあなたが選べるようにしています。

プログラムの処理の中で、埋め込みの生成が最も時間のかかる処理です。実測では、主にベンダー提供の Next.js ドキュメントで構成された 430 件のノートの処理に、ノート PC の CPU で 11 分 25 秒かかりました。参照ノートを明示的に指定しない限り除外するのも、このためです。処理時間の 95％を参照ノートが占めていました。

検索では、ボルトごとではなく、プロセスごとに一度モデルを読み込みます。 その結果、セマンティック検索を一度実行したプロセスでは、モデルが常駐します。CLI の場合はコマンドの実行時間、samong-server と samong-mcp の場合はプロセスが動作している間です。このトレードオフは意図的なものです。代わりに検索のたび、すべてのボルトでモデルを再読み込みする方法もありました。

モデルを多言語対応にしたのは意図的です。 multilingual-e5-small は 100 以上の言語に対応しており、何も設定しなければこれが使われます。主張しているのはそれだけです。最も近いプロジェクトである Basic Memory は、デフォルトで英語専用モデルの bge-small-en-v1.5 を使用するため、セマンティック検索ではタイ語のノートを最初から認識できません。ただし、モデルは設定項目（semantic_embedding_model。E5 のようなモデルで必要となるクエリ／ドキュメントのプレフィックス設定と併せて指定します）なので、変更方法を知っている人なら変更できます。違いはデフォルトにあり、上限にあるのではありません。どちらのモデルがタイ語をより適切に順位付けするかは、まだ測定されていません。同じボルトを両方で検索した人はおらず、実施されるまでは、どちらも断言すべきではありません。（2026 年 9 月に Basic Memory と照合。デフォルト設定は変更される場合があります。）

順位付けの変更を評価する方法。 samong eval questions.toml は、実際に寄せられた質問と、それに答えるノートを組み合わせて検索を評価し、hit@k、MRR、そしてボルトでは答えられない質問に誤って回答してしまう頻度を報告します。類似度の下限をまだ設定していないのは、この最後の数値を実際のボルトで測定する必要があるからです。推測ではなく、ここで測定します。samong eval --floors 0.75,0.80,0.85,0.90 questions.toml は、候補となる下限ごとにセットを一度評価し、それぞれの行を出力します。最初の行は none です。これにより、3 つの数値を比較できます。hit@1 を向上させる一方で、誤って回答する頻度も上げる下限では、検索がより自信を持って誤るようになっただけです。 docs/EVAL.md では、ファイル形式、信頼に値する質問セットの条件、比較結果の読み方について説明しています。

2 種類の順位を組み合わせる方法。 スコアの加重和ではなく、逆順位融合（Reciprocal Rank Fusion）を使います。BM25 には上限がなく、コサイン類似度は −1 から 1 の範囲なので、生の数値を混ぜるにはボルトごとに変動する調整が必要です。順位を融合する方法なら、調整は必要ありません。両方で上位に入ったノートは有利になり、片方だけで 1 位になったノートも順位に残ります。

長いドキュメントでも冒頭ではなく関連するセクションが照合されるよう、ノートを段落の区切りで分割し、約 900 文字のチャンクにします。各ノートのスコアには、最もスコアの高いチャンクを使います。ベクトルは <vault>/.brain/vectors.redb に保存され、再インデックス処理と同じコンテンツハッシュが記録されるため、変更のないノートは再埋め込みされません。このファイルを削除すれば、ボルトは元の状態に戻ります。

samong doctor はベクトルがあるノートの数を報告するため、「セマンティック検索が役に立たなかった」のか、「何も埋め込まれていない」のかを区別できます。

Web UI

Obsidian のクローンではなく、独自のデザインです。UI 全体が samong-server バイナリに組み込まれており（rust-embed）、単一のファイルとして 提供され、すぐに動作します。フォントも同梱されているため、オフラインでも使えます。

• グラフがワークスペースです。レイアウトには d3-force を使い、キャンバスに描画するため、 数百件のノートがある vault でも快適に使えます。ノードのサイズはリンク数、 色は vault を表します。
• 検索が入口です。Ctrl+K でフレーム内の検索欄にフォーカスします。開くパレットは ありません。入力すると、一致しないノードがすべて薄く表示されるため、検索語が場所になります。 Esc でマップ全体に戻ります。
• ノードを選択すると、グラフの横にノートが開きます。リンクはチップとして表示され、 リンク先が解決されるかどうかも分かります。全画面表示で読む場合も、マップ上の状態として開きます。
• [[ と入力すると、vault をまたいだノートの自動補完が表示されます。wikilink をクリックすると リンク先に移動します（存在しないノートはその場で作成されます）。
• 英語またはタイ語に対応しており、?lang=、保存済みの選択、またはブラウザーの言語設定に 基づいて選ばれます。ヘッダーから切り替えることもできます。デフォルトは英語です。
• ダーク／ライトテーマ、自動保存、WebSocket によるリアルタイム更新に対応しています。Obsidian や 任意のエディターでファイルを編集すると、ページが自動的に更新されます。
• Vault の健全性では、インデックス化された内容とスキップされた内容が報告されます。 90 件あるはずのノートが 4 件しかない場合も、謎ではなく目に見える情報として確認できます。

UI の開発：cd web && npm run dev（Vite が samong-server のポート 3117 にプロキシします）。

API（samong-server）

127.0.0.1 のみでバインドします（ローカル優先、認証なし）。

エンドポイント	目的
GET /api/vaults	登録済み vault
POST /api/vaults	vault を登録します（{name, path}）。ターミナルは不要です
GET /api/vaults/{vault}/notes	vault 内のノート：{key, title, reference}
GET /api/vaults/{vault}/doctor	samong doctor と同じ範囲のレポート
GET/PUT/DELETE /api/notes/{vault}/{path}	path を指定して Markdown を読み取り／書き込み／削除します
GET /api/links/{vault}/{path}	順方向リンク＋バックリンク＋vault 間リンク
GET /api/search?q=&vault=&limit=	検索（すべての vault を検索する場合は vault を省略）。結果にはファイルの path が含まれます
GET /api/graph?vault=	ノード＋エッジを JSON で返します
WS /ws	.md ファイルが変更されたときのイベント

AI エージェント（samong-mcp）

samong-mcp は stdio 経由の MCP サーバーです。エージェントは次のツールを利用できます。 search_notes、read_note、save_note、get_links、 list_notes、list_vaults。意図的に削除ツールは用意していません。知識の消去は 人間が行う操作として残しています。

エージェントは、読み取っていないノートを上書きできません。 削除ツールを用意しないだけでは 不十分でした。save_note はファイル全体を書き込むため、ノートを読んでいないエージェントが その内容をすべて 1 つの段落で置き換え、「保存しました」と報告する可能性があります。 これは、より親しみやすい名前で呼ばれた削除です。そのため、read_note は編集可能なノートの 上に [samong base_hash=…] という行を返し、ノートを上書きするにはそのハッシュを渡す必要があります。 古くなったハッシュ、ハッシュがない場合、またはその後削除されたノートのハッシュは、いずれも 拒否され、ファイルには手を加えません。まだ存在しないノートの作成にはハッシュは不要です。 Web UI の PUT にはこのような事前条件はありません。そこでエディターを操作するのは ノートを見ている人だからです。ただし、どちらの画面からの書き込みでも、すべてディスクに アトミックに保存されるため、保存が中断されてもノートが途中で切れた状態になることはありません。

// .mcp.json in your repo
{ "mcpServers": { "samong": { "command": "samong-mcp" } } }

各アシスタントへの接続

MCP はモデルの機能ではなく、クライアントの機能です。 問うべきなのは「Gemini は MCP を使えるか」ではなく、「Gemini とやり取りするために使っているプログラムは MCP を使えるか」です。同じモデルでも、実行する環境によって接続できる場合とできない場合があります。

samong-mcp はお使いのマシン上で stdio 経由で動作するため、同じマシン上にある任意のクライアントで利用できます。ブラウザーのみで動作するアシスタントからはアクセスできません。 Web 版の ChatGPT、Web 版の Gemini、X の Grok はいずれも他者のサーバー上で動作し、それらのコネクター機能は公開 URL 上の MCP サーバーを必要とします。これは Samong の目的とは正反対です。

クライアント	モデル	追加方法	設定ファイル
Claude Code	Claude	claude mcp add --scope user samong -- samong-mcp	.mcp.json
Claude Desktop	Claude	リリースページから .mcpb をインストールします	claude_desktop_config.json
Codex CLI / ChatGPT desktop	GPT	codex mcp add samong -- samong-mcp	~/.codex/config.toml
Gemini CLI	Gemini	gemini mcp add samong samong-mcp	~/.gemini/settings.json
Qwen Code	Qwen	qwen mcp add samong samong-mcp	~/.qwen/settings.json
Kimi Code CLI	Kimi	kimi mcp add samong -- samong-mcp	kimi mcp による管理
Grok Build	Grok	grok mcp add samong -- samong-mcp	~/.grok/config.toml
GLM (Z.ai)	GLM	別のクライアント経由 — 下記を参照	そのクライアントの設定ファイル
DeepSeek	DeepSeek	別のクライアント経由 — 下記を参照	そのクライアントの設定ファイル

Claude Code、Gemini CLI、Qwen Code では、上記と同じ JSON を使用します。異なるのはファイルの場所だけです。Codex と Grok では代わりに TOML を使用します。

[mcp_servers.samong]
command = "samong-mcp"

アンダースコアに注意してください。Codex では mcpServers ではなく mcp_servers と記述します。間違えてもエラーは表示されません。

GLM と DeepSeek はモデルであり、MCP クライアントではありません。 Z.ai の GLM Coding Plan は、すでにお使いのクライアント（Claude Code、Cline、OpenCode）内で動作するように作られています。また、DeepSeek には独自の MCP クライアントがありません。そのため、ホストとなるクライアントで Samong を設定すると、モデルはそのクライアントを介してツールを利用できます。ここに記載されていないものにも同じルールが当てはまります。まず MCP に対応したクライアントを選び、次にモデルを選んでください。

バイナリが PATH にない場合は、samong-mcp の代わりにフルパスを指定してください。GUI クライアントが引き継ぐ PATH は、ターミナルの PATH と異なることがよくあります。

詳しいセットアップ手順、確認手順、CLAUDE.md のレシピについては、こちらをご覧ください： docs/AI-AGENT.md

アーキテクチャ

<vault>/
  *.md            ← source of truth (Obsidian-compatible)
  .brain/
    graph.redb    ← forward/backlinks + mtimes + index version (redb)
    tantivy/      ← full-text index (tantivy), dictionary-segmented
~/.config/samong/
  registry.redb   ← vault name -> path, for cross-vault links

.brain/ はいつでも削除できます。samong reindex を実行すれば、Markdown ファイルからすべて再構築されます。スキーマやトークナイザーのバージョンが変わると、古いインデックスは自動的に再構築されます。

開発

cargo test                              # unit + integration tests
cargo clippy --all --all-targets -- -D warnings
cargo fmt --all -- --check

注：最初の cargo test を実行する前に cd web && npm run build を実行してください。これにより、埋め込み UI のテストで実際のビルドを使用できます（実行しない場合、UI 部分のテストは自動的にスキップされます）。

Web UI の変更後は再インストールが必要です

UI はコンパイル時にバイナリへ埋め込まれる（rust-embed）ため、web/ 以下を編集した後、インストール済みの samong-server を実行しても古い UI が表示されます。ビルドしてから上書きインストールしてください。

cd web && npm run build && cd ..
cargo install --path . --force

UI の作業中は、cd web && npm run dev（ホットリロード対応、API へのプロキシあり）を使うか、cargo run --bin samong-server -- start を実行してください。後者は常に最新の web/dist を読み込むため、変更のたびに再インストールするよりもはるかに高速です。

ロードマップ

最初の一般公開以降に完了したこと：5つのプラットフォーム向けバイナリ、Web UI の「ボルトを追加」ボタン、接続状況を考慮したランキング、任意で使えるローカルのセマンティック検索です。

• セマンティック検索のデフォルト類似度下限。 ランク統合では、スコアにかかわらずセマンティック検索の上位結果が採用されるため、ありふれた一致でも2番目の位置に表示されることがあります。下限の機能自体はすでにあり、search と eval の --semantic-floor、および値を一通り試す --floors が利用できます。ただし、実際のボルトで測定する必要があり、値を推測で決めるわけにはいかないため、初期状態では設定されていません。まだ誰も実際のボルトで値を試していないため、それまではデフォルト値にふさわしい数値はありません。
• より小さな埋め込みモデル。 465 MB は大きすぎます。同じモデルの量子化版なら、大幅にサイズを削減できます。
• バンドルされた分かち書き辞書にない単語に対応するユーザー辞書。
• Tauri を使ったデスクトップアプリとしてのパッケージ化。
• Git にインデックスを付ける中央サーバー — チームのボルトをまとめて検索できるようにし、同期ではなくリポジトリから取り込みます。独自の同期プロトコルは決して作りません。競合、履歴、オフライン、認証の問題は、すでに Git が解決しています。
• デバイス間の同期と AI 機能（ノートの要約、ボルトへの質問）は、オープンコアのレイヤーとして後日提供します。

ライセンス

Apache-2.0 — 自由に使用、変更し、商用目的で配布できます。自作のクローズドソースソフトウェアに組み込むこともできます。著作権表示を残し、帰属を明記してください。

すべてのサードパーティコンポーネントは THIRD-PARTY.md に記載しています。分かち書き辞書の words_th.txt は PyThaiNLP（Apache-2.0）から提供されています。

名前とロゴ

「Samong」とロゴは Apache-2.0 の対象外です。 コードをフォークして変更し、販売することはできます。ただし、個別に配布するものには別の名前を付けてください。どのバージョンを誰が保守しているのか、ユーザーが混乱しないようにするためです。このプロジェクトに言及したり、比較したり、Samong との互換性をうたったりするのに許可は必要ありません。

対象外であることは、該当するファイルのそばにある site/brand/LICENSE に明記されています。ルートの LICENSE だけでは、これらのファイルも対象だと誤解されるおそれがあるためです。Apache-2.0 は商標権を認めませんが、アートワークには広範な権利を与えており、このリポジトリを複製しても、6つの SVG の扱いが異なるとは判断できません。また、許可を得ずにできることの一覧も記載しています。その大半は許可なしで行えます。