{
  "markdown": "# Samong 🧠\n\n[![CI](https://github.com/waanvar/samong/actions/workflows/ci.yml/badge.svg)](https://github.com/waanvar/samong/actions/workflows/ci.yml)\n[![crates.io](https://img.shields.io/crates/v/samong.svg)](https://crates.io/crates/samong)\n[![MCP registry](https://img.shields.io/badge/MCP%20registry-io.github.waanvar%2Fsamong-6f8dff)](https://registry.modelcontextprotocol.io)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n\n**A local-first knowledge base for the notes already in your repositories**\n\nYou solved it once and wrote it down. Six months later the note is still in the\nrepo and you cannot find it. Point Samong at a project root and the `.md` files\nyou would commit become searchable and linked — and readable by the AI tools you\nalready work with. Plain Markdown,\n[Obsidian](https://obsidian.md)-compatible (`[[wikilink]]` /\n`[[wikilink|alias]]`), no account, no cloud, one binary.\n\n![Samong — the graph is the workspace, with note titles, hub sizing and folder clusters](docs/graph-dark.png)\n\n## Why Samong\n\n- 📁 **A note is a `.md` file you would commit.** Point it at a repository, not\n  at a special notes folder. `.gitignore` is respected and dependency\n  directories are always skipped, so a project root indexes your ADRs, runbooks\n  and design docs without dragging in `node_modules` — and `samong doctor` tells\n  you exactly what counted and what did not.\n- 🤖 **Your notes become an agent's memory.** `samong-mcp` speaks MCP, so Claude\n  Code and Claude Desktop search, read and write the same knowledge base you do.\n  No pasting context back in every session ([setup](docs/AI-AGENT.md)).\n- 🗺 **The graph is the workspace, not a novelty tab.** A vault is a shape;\n  typing dims everything that does not match, so a query becomes a place.\n- 🔎 **Notes are addressed by path, not by title.** One repository holds twenty\n  files called `README.md`. A title cannot tell them apart, and an index keyed on\n  titles silently collapses them — so search results, the API and the MCP tools\n  all carry the real path.\n- 📚 **Learn from documentation you never commit.** `.gitignore` answers \"what do\n  I distribute?\"; a knowledge base has to answer \"what do I learn from?\".\n  `scope.include` pulls a dependency's own docs in as read-only reference notes —\n  one project, one brain, no second vault.\n- 🔗 **One repository per vault, links across all of them.** `[[other-vault/note]]`\n  resolves across every registered vault, and backlinks come back the other way\n  without any cross-vault index to keep in sync.\n- 🧭 **Ranked by relevance *and* connectedness.** When the words cannot tell two\n  notes apart, the one the rest of your notes point at comes first. Capped at a\n  25% boost, so a popular note never outranks one that plainly matches better.\n- 🧠 **Semantic search, optional and local.** Build with `--features semantic`\n  and run `samong embed` to rank by meaning as well as by words, with a\n  multilingual model that never leaves your machine. Off by default on purpose:\n  see below.\n- ⚡ **Fast, and yours.** Link graph in [redb](https://github.com/cberner/redb),\n  search in [tantivy](https://github.com/quickwit-oss/tantivy), incremental\n  reindexing that only touches changed files. Every index lives in\n  `<vault>/.brain/` and can be rebuilt from the `.md` files at any time — there\n  is nothing to lock you in.\n\n## Install\n\nFour ways in, in the order that costs you least trouble.\n\n### 1. A package manager\n\n**macOS and Linux** — [waanvar/homebrew-samong](https://github.com/waanvar/homebrew-samong):\n\n```sh\nbrew tap waanvar/samong\nbrew install samong\n```\n\n**Windows** — [waanvar/scoop-samong](https://github.com/waanvar/scoop-samong):\n\n```powershell\nscoop bucket add samong https://github.com/waanvar/scoop-samong\nscoop install samong\n```\n\nOnce the winget submission is accepted this becomes `winget install Waanvar.Samong`\nwith nothing to add first, since winget ships with Windows. The manifests are in\n`packaging/winget/` and CI installs from them on every push; the pull request to\nMicrosoft is the only step left. **If you are on Windows and want to avoid the\nSmartScreen warning below, this section is the answer** — not the download links.\n\n**Arch Linux** — `paru -S samong-bin`, once the package is submitted. Until then\n`packaging/aur/` builds it: `cd packaging/aur && makepkg -si`.\n\n**No Gatekeeper prompt, no SmartScreen warning.** Both fetch the archive\nthemselves and verify it against the SHA-256 published beside it. Nothing arrives\nthrough a browser, so macOS never sets the `com.apple.quarantine` attribute it\nwould otherwise refuse to open, and Windows has no download reputation to weigh.\nEach tap's CI installs on a real runner and asserts this rather than assuming it.\n\n### 2. With Rust already installed\n\n```sh\ncargo install samong\n```\n\nBuilds all four binaries with the web UI inside them; needs Rust 1.88 or newer.\nCompiling locally, there is likewise no download for either OS to object to.\n\n### 3. Download and double-click\n\nDownload, extract, **double-click**:\n\n| | |\n|---|---|\n| **Windows** | `Open Samong.exe` |\n| **macOS** | `Samong.app` |\n| **Linux** | `samong-app` (copy `samong.desktop` to `~/.local/share/applications/` for a menu entry) |\n\nNo terminal, no configuration, no account. On the very first run it makes a\nvault at **`Documents/Samong`** with two notes in it, indexes them, and opens\nyour browser. Everything after that is your own folder of Markdown files.\n\nThe `⏻` button in the top right stops it — the server outlives the browser tab,\nso closing the tab is not the same as quitting.\n\n> Already have notes somewhere? Use **+ Add vault…** in the vault menu and point\n> it at that folder. Nothing is moved or converted.\n\nTwo environment variables exist for the awkward cases, because a double-clicked\nprogram has no arguments: `SAMONG_PORT` when 3117-3128 are all taken by\nsomething that stays, and `SAMONG_NO_OPEN=1` to start without a browser.\nIf the launcher fails it writes `~/.config/samong/launcher.log` and opens it.\n\n### 4. Download the binaries and run them yourself\n\nGrab one from [Releases](https://github.com/waanvar/samong/releases), extract,\nrun. Direct links that always point at the newest release:\n[Linux](https://github.com/waanvar/samong/releases/latest/download/samong-x86_64-linux.tar.gz) ·\n[Windows](https://github.com/waanvar/samong/releases/latest/download/samong-x86_64-windows.zip) ·\n[macOS Apple Silicon](https://github.com/waanvar/samong/releases/latest/download/samong-aarch64-macos.tar.gz) ·\n[macOS Intel](https://github.com/waanvar/samong/releases/latest/download/samong-x86_64-macos.tar.gz). **No Rust or Node needed** — the web UI is already inside the binary. Four\nplatforms: `x86_64-linux`, `x86_64-windows`, `aarch64-macos` (Apple Silicon),\n`x86_64-macos` (Intel).\n\nVerify what you downloaded against the `.sha256` published beside it:\n\n```sh\nsha256sum -c samong-x86_64-linux.tar.gz.sha256\n```\n\n#### ⚠️ Downloaded binaries are not code-signed\n\nThis applies to options 3 and 4 above — anything that arrives through a browser.\nA package manager and `cargo install` are unaffected: neither leaves a download\nfor the OS to be suspicious of.\n\nSamong has no code-signing certificate, so the OS gets in the way:\n\n**macOS** — Gatekeeper *refuses* to open it (not merely a warning). Either\nright-click `Samong.app` → **Open**, which asks once, or clear the flag:\n\n```sh\nxattr -dr com.apple.quarantine Samong.app samong samong-server samong-mcp\n```\n\n**Windows** — SmartScreen warns and names the publisher as unknown; choose\n**More info → Run anyway**. The executables do carry an embedded icon and version\ninformation, so the dialog names Samong rather than a bare filename, but that is\nas far as it goes without a certificate.\n\n> Both happen to any open-source project without a paid certificate and are not a\n> sign that something is wrong with the file — but do check the checksum above,\n> and only download from the official Releases page.\n\n**Buying a certificate would not remove the Windows warning**, which is worth\nsaying because it looks like it should. A certificate replaces \"Unknown publisher\"\nwith a name; the warning itself is driven by SmartScreen *reputation*, and since\n2024 not even an EV certificate grants that on sight. Reputation is also tied to\nthe certificate's thumbprint, so it resets when the certificate is renewed — at\nmost every 459 days under the rules that took effect in February 2026.\n\n**Option 1 avoids all of this**, today and for free. Scoop, Homebrew and winget\nfetch and verify the archive themselves, so there is no browser download for\neither OS to weigh.\n\n### Or build from source\n\nNeeds [**Rust**](https://rustup.rs) (stable) and [**Node.js**](https://nodejs.org)\n20+ (Node only if you want the web UI, which is embedded into the binary at build\ntime — without it you get the CLI + API).\n\n```sh\ngit clone https://github.com/waanvar/samong.git\ncd samong\ncd web && npm install && npm run build   # build the web UI first (it gets embedded)\ncd .. && cargo install --path .          # installs samong / samong-server / samong-mcp\n```\n\n> **Order matters**: build the web UI before `cargo build`/`cargo install` —\n> `samong-server` **embeds the web UI into the binary**, so it ships as a single\n> file with no UI folder alongside it. (To build without installing, use\n> `cargo build --release`; binaries land in `target/release/`.)\n\nUpdate to the latest version later with `samong update` (see *Updating* below).\n\n## Quickstart\n\n```sh\nmkdir my-vault && cd my-vault\nsamong new \"My First Note\"         # create + index\nsamong vault add my-vault .        # register in ~/.config/samong\nsamong-server start               # opens http://127.0.0.1:3117 in your browser\n```\n\n`samong-server start` serves the embedded web UI and opens your browser — no UI\nfiles needed alongside it. Change the port with `--port 8080`, skip the browser\nwith `--no-open` (the old `samong-server --port 8080` form still works).\n\n![The same vault in the light theme](docs/graph-light.png)\n\n## CLI commands\n\n| Command | What it does |\n|---|---|\n| `samong new <title>` | Create a note + index it |\n| `samong edit <title>` | Open in `$EDITOR`, reindex on close |\n| `samong rename <old> <new>` | Rename + rewrite every `[[wikilink]]` pointing at it |\n| `samong delete <title>` | Delete + warn about dangling backlinks |\n| `samong links <title> [--all-vaults]` | Forward links + backlinks (incl. cross-vault) |\n| `samong orphans` / `samong broken` | Unlinked notes / links to missing notes |\n| `samong search <q> [--vault <name>\\|--all-vaults] [--limit N]` | Full-text search |\n| `samong graph [--all-vaults]` | Link-graph edges |\n| `samong list` | List every note |\n| `samong reindex [--full]` | Sync the index (changed files only / everything) |\n| `samong embed [--reference]` | Embed notes for semantic search (needs `--features semantic`) |\n| `samong pack <dir> [--include-reference]` | Copy the publishable part of the vault out — notes and manifest, never the index |\n| `samong watch` | Watch the vault, keep the index fresh |\n| `samong vault add/list/remove` | Manage the central registry |\n| `samong vault install <git-url>` | Install someone else's vault as read-only reference notes |\n| `samong vault update [name]` | Pull the latest content for installed vaults |\n| `samong vault verify [name] [--require-signature]` | Check installed vaults are what their publishers published |\n| `samong doctor` | Report what counts as a note, what was skipped, and any ambiguous titles |\n| `samong update [--check]` | Update to the latest GitHub release (--check only reports) |\n| `samong-app` | The double-click launcher: finds or creates a vault, serves, opens the browser |\n\n### What counts as a note (vault scope)\n\nOne rule: **a note is a `.md` file you would commit.** Point `samong vault add`\nstraight at a project root — no configuration needed. Samong will:\n\n- respect `.gitignore`, so `node_modules/`, `dist/` and `target/` never get indexed\n- always skip dependency directories even when they are not gitignored\n  (`node_modules`, `vendor`, `site-packages`, `__pycache__`, `Pods`, `bower_components`)\n- skip every dot-directory (`.git`, `.obsidian`, `.brain`)\n\n`samong doctor` shows what that adds up to:\n\n```sh\nsamong doctor\n# vault: /home/me/myproject\n# gitignore: respected\n# 4 note(s) in scope\n# skipped 90 .md file(s) not tracked as notes (web 90)\n```\n\nTo adjust it, add `samong.toml` at the vault root — **commit it**, so every\nmachine and any central server reads the same rules. Every field is optional:\n\n```toml\n[vault]\nname = \"myproject\"        # the name used in [[myproject/note]] links\n\n[scope]\nnotes_dir = \"docs\"        # only scan this subtree (default \".\")\nexclude = [\"archive/**\"]  # extra rules, gitignore syntax\ninclude = []              # directories to index anyway (see below)\nfollow_gitignore = true   # turn off to index gitignored files too\nmax_depth = 0             # 0 = unlimited\n```\n\nIf your repo gitignores its own notes, `.samongignore` brings them back. Same\nsyntax as gitignore, negation included:\n\n```\n!notes/\ndrafts/\n```\n\n### Learning from documentation you never commit (`scope.include`)\n\n`.gitignore` answers **\"what do I distribute?\"**. A knowledge base has to answer\n**\"what do I learn from?\"** — not the same question. The clearest case is\ndocumentation shipped inside a dependency: Next.js puts 400-odd Markdown files\nin `node_modules`.\n\n```toml\n[scope]\ninclude = [\"node_modules/next/dist/docs\"]\n```\n\nThose become **reference notes** — same vault, same index, so `[[installation]]`\nfrom your own note resolves. One project, one brain; no second vault.\n\n> `.samongignore` with `!node_modules/...` cannot do this. Dependency\n> directories are pruned before the walker looks inside them, so there is nothing\n> for a negation to match, and gitignore itself cannot re-include a path whose\n> parent is excluded. `scope.include` is the right lever.\n\n**Two things to know:**\n\n1. **Reference notes are machine-local.** `samong.toml` travels with git;\n   `node_modules` does not. A machine that has not installed dependencies — or a\n   server holding only git history — will not find them. That is *not* an error:\n   Samong skips them and prints one warning line, and `samong doctor` reports\n   which roots are present.\n2. **Reference notes are read-only.** `save_note` / `PUT` / `delete` / `rename`\n   refuse them: the file belongs to a dependency and any edit would be erased on\n   the next install. This matters most for agents — `save_note(\"installation\")`\n   must not overwrite a framework's own docs page.\n\n`exclude` applies to the main scan only. To leave part of an include root out,\npoint `include` at a narrower directory.\n\n> Deliberately ignored: the global gitignore (`~/.config/git/ignore`),\n> `.git/info/exclude`, and `.gitignore` files above the vault. Those are\n> per-machine, and honoring them would make one repo index differently on two\n> laptops.\n\n### Installing a vault someone else published\n\nA vault can be handed to another person. `samong pack` copies out the\npublishable part — notes and manifest, never the index — and the reader installs\nthe result straight from git:\n\n```bash\nsamong vault install https://github.com/someone/sre-handbook.git\n```\n\nThat clones into `vendor/sre-handbook`, adds it to `scope.include`, adds it to\nyour `.gitignore`, and reindexes. The notes land as **reference notes** by the\nrules above: same graph, same search, `[[Runbook]]` from your own note resolves\ninto them — and read-only, because an edit would be erased by the next\n`samong vault update`.\n\nThe `.gitignore` line is written for you, with the reason attached:\n\n```gitignore\n# installed vaults (samong vault install)\n# Someone else's notes. Committing them here would redistribute\n# content that is not yours to redistribute.\n/vendor/sre-handbook/\n```\n\n**Results say whose they are.** A hit from an installed vault carries that\nvault's name and licence, in the CLI, the web UI, the API and the MCP tools:\n\n```\nvendor/sre-handbook/Runbook.md: When the queue backs up, drain it before …\n  ↳ from SRE Handbook · CC-BY-4.0\n```\n\nThe moment worth protecting is not search, it is the paragraph somebody copies\nout of a result into work of their own — after which nothing records where it\ncame from. A vault that states no licence is reported as\n`licence not stated` rather than left blank: that is an answer, not a gap.\n\n### Proving a vault is the publisher's (`samong vault verify`)\n\nIntegrity is not the missing piece — an installed vault is a git checkout, and\nevery byte is already covered by the commit hash. A `SHA256SUMS` beside the\ncontent would restate that, and restate it weaker: whoever can change a note can\nchange the checksum file next to it.\n\nWhat is missing is **authenticity**, which is a signature. Publishers should sign\n**commits**, not release tags — `samong vault update` follows a branch, so\nreaders take commits between tags and a tag signature says nothing about the\ncommit they just pulled:\n\n```bash\ngit config commit.gpgsign true\n```\n\nReaders get that key **pinned at install**, the way SSH pins a host key: whoever\ngave you the URL is the authority the first time, and every update afterwards is\nchecked against it.\n\n```bash\nsamong vault verify                       # who signed each one, and has anything changed\nsamong vault verify --require-signature   # fail on unproven, not only on wrong\n```\n\n- An update signed by a **different key — or suddenly not signed at all** — is\n  refused *before* the merge, so nothing reaches your working tree or your index.\n  (Dropping the signature is the cheapest attack on pinning, so it counts as\n  changing it.) Accept a genuine key change deliberately:\n  `git -C vendor/<name> config --unset samong.signer`.\n- **Local changes are reported, including untracked files.** A stray `.md`\n  dropped into an installed vault would be indexed and would show up in search\n  attributed to its publisher.\n- **Unsigned vaults pass by default.** Almost every vault in the world is\n  unsigned today, and a check that always fails is a check nobody runs;\n  `--require-signature` is there for anyone who has decided otherwise.\n\nNothing about who published what is stored outside the checkout. The clone is\nits own provenance, and a record kept elsewhere could only drift away from it.\n\n### Updating\n\n`samong update` downloads the latest GitHub release and replaces all three\nbinaries (samong / samong-server / samong-mcp) in place — including the embedded\nweb UI. `samong update --check` reports whether a newer version exists without\ninstalling, and `samong-server start` prints a one-line notice when an update is\navailable (best-effort; never blocks, never fails offline).\n\n> A published GitHub release is required first\n> (`git tag v0.1.0 && git push origin v0.1.0` triggers the workflow that builds\n> binaries for all three OSes) before `samong update` can find anything.\n\n## Semantic search (optional)\n\nLexical search only finds notes that use the words you typed. When you cannot\nremember the words you wrote, it finds nothing. Semantic search fixes that by\ncomparing meaning — and it is **off by default**, which is a decision, not an\noversight.\n\n```bash\ncargo install --path . --features semantic\nsamong embed              # your notes; run it again after you write a lot\nsamong embed --reference  # also the vendored docs from scope.include (slow)\nsamong search \"how do we stop repeated requests\"\n```\n\n**What it costs you.** The feature pulls in ONNX Runtime, and the first `embed`\ndownloads `intfloat/multilingual-e5-small` from Hugging Face into\n`~/.config/samong/models` — **465 MB on disk**, measured, not estimated: a 470 MB\nfloat32 ONNX graph plus a 17 MB tokenizer. Your notes and your queries still never\nleave the machine, and nothing needs a network after that download. But \"one\nbinary, nothing to fetch\" stops being true, and that promise is why people choose\nthis over a cloud tool — so it is yours to opt into, not ours to impose.\n\nEmbedding is the slowest thing the program does. A real measurement: 430 notes,\nmost of them vendored Next.js documentation, took **11m 25s** on a laptop CPU.\nThat is also why reference notes are excluded unless you ask for them — they were\n95% of that time.\n\n**The model is multilingual on purpose.** The nearest comparable project embeds\nwith an English-only model, which quietly makes its semantic search useless for\nanyone whose notes are not in English. This one covers 100+ languages.\n\n**How the two rankings combine.** Reciprocal Rank Fusion, not a weighted sum of\nscores: BM25 is unbounded and cosine similarity is −1 to 1, so mixing the raw\nnumbers needs a calibration that drifts with every vault. Fusing *positions*\nneeds none. A note ranked well by both wins; a note ranked first by only one still\nplaces.\n\nNotes are chunked (~900 characters, split at paragraph breaks) so a long document\nis matched by its relevant section rather than its first page, and each note\nscores as its best chunk. Vectors live in `<vault>/.brain/vectors.redb`, stamped\nwith the same content hash the reindexer uses, so re-embedding skips unchanged\nnotes. Delete that file and the vault is exactly what it was.\n\n`samong doctor` reports how many notes have vectors, so \"semantic search did not\nhelp\" can be told apart from \"nothing was embedded\".\n\n## Web UI\n\nAn original design, not an Obsidian clone. The whole UI is **embedded into the\n`samong-server` binary** (rust-embed) — ships as one file, runs instantly, and\nthe fonts are bundled so it works offline.\n\n- **The graph is the workspace**, painted to canvas (d3-force for layout) so it\n  survives a vault of several hundred notes. Node size is its link count,\n  colour is its vault.\n- **Search is the way in**: `Ctrl+K` focuses the field in the frame — there is\n  no palette to open. Typing dims every node that does not match, so a query\n  becomes a place; `Esc` brings the whole map back.\n- Selecting a node opens it beside the graph, with its links as chips that say\n  whether they resolve. Reading full screen is a state on top of the map.\n- Type `[[` for note autocomplete across vaults; click wikilinks to follow\n  (missing notes are created on the spot)\n- **English or Thai**, from `?lang=`, your saved choice, or the browser, and\n  switchable in the header. English is the default.\n- Dark/light themes, autosave, real-time over WebSocket — edit a file in\n  Obsidian or any editor and the page updates itself\n- **Vault health** reports what was indexed and what was skipped, so four notes\n  where you expected ninety is a visible answer rather than a mystery\n\nUI development: `cd web && npm run dev` (Vite proxies to samong-server on\nport 3117).\n\n## API (samong-server)\n\nBinds to `127.0.0.1` only (local-first, no auth).\n\n| Endpoint | Purpose |\n|---|---|\n| `GET /api/vaults` | Registered vaults |\n| `POST /api/vaults` | Register a vault (`{name, path}`) — no terminal needed |\n| `GET /api/vaults/{vault}/notes` | Notes in a vault: `{key, title, reference}` |\n| `GET /api/vaults/{vault}/doctor` | The same scope report as `samong doctor` |\n| `GET/PUT/DELETE /api/notes/{vault}/{path}` | Read / write / delete markdown, addressed by **path** |\n| `GET /api/links/{vault}/{path}` | Forward + backlinks + cross-vault |\n| `GET /api/search?q=&vault=&limit=` | Search (omit `vault` for all vaults) — results include the file `path` |\n| `GET /api/graph?vault=` | Nodes + edges as JSON |\n| `WS /ws` | Events when .md files change |\n\n## AI agents (samong-mcp)\n\n`samong-mcp` is an MCP server over stdio. Agents get these tools:\n`search_notes`, `read_note`, `save_note`, `get_links`,\n`list_notes`, `list_vaults` — deliberately no delete tool; erasing knowledge\nstays a human action.\n\n```json\n// .mcp.json in your repo\n{ \"mcpServers\": { \"samong\": { \"command\": \"samong-mcp\" } } }\n```\n\n### Connecting each assistant\n\n**MCP is a feature of the client, not of the model.** The useful question is not\n\"can Gemini use MCP\" but \"can the program I talk to Gemini through use MCP\" — the\nsame model connects or does not depending on what you run it in.\n\n`samong-mcp` runs on your machine over stdio, so it works with any client on the\nsame machine. **A browser-only assistant cannot reach it** — ChatGPT on the web,\nGemini on the web and Grok in X all run on someone else's server, and their\nconnector features want an MCP server at a public URL. That is the opposite of\nwhat Samong is for.\n\n| Client | Model | Add it with | Config file |\n|---|---|---|---|\n| Claude Code | Claude | `claude mcp add --scope user samong -- samong-mcp` | `.mcp.json` |\n| Claude Desktop | Claude | install the `.mcpb` from the release page | `claude_desktop_config.json` |\n| Codex CLI / ChatGPT desktop | GPT | `codex mcp add samong -- samong-mcp` | `~/.codex/config.toml` |\n| Gemini CLI | Gemini | `gemini mcp add samong samong-mcp` | `~/.gemini/settings.json` |\n| Qwen Code | Qwen | `qwen mcp add samong samong-mcp` | `~/.qwen/settings.json` |\n| Kimi Code CLI | Kimi | `kimi mcp add samong -- samong-mcp` | managed by `kimi mcp` |\n| Grok Build | Grok | `grok mcp add samong -- samong-mcp` | `~/.grok/config.toml` |\n| GLM (Z.ai) | GLM | through another client — see below | that client's |\n| DeepSeek | DeepSeek | through another client — see below | that client's |\n\nClaude Code, Gemini CLI and Qwen Code all take the same JSON shown above; only the\nfile location differs. Codex and Grok take TOML instead:\n\n```toml\n[mcp_servers.samong]\ncommand = \"samong-mcp\"\n```\n\nNote the underscore — Codex spells it `mcp_servers`, not `mcpServers`, and gets it\nwrong silently.\n\n**GLM and DeepSeek are models, not MCP clients.** Z.ai's GLM Coding Plan is built\nto run inside clients you already have (Claude Code, Cline, OpenCode), and\nDeepSeek ships no MCP client of its own — so configure Samong in the host client\nand the model sees the tools through it. The same rule covers anything not listed:\npick a client that speaks MCP, then pick the model.\n\nIf a binary is not on `PATH`, use its full path instead of `samong-mcp` — the\n`PATH` a GUI client inherits is often not the one your terminal has.\n\nFull setup, a verification step and a `CLAUDE.md` recipe:\n[docs/AI-AGENT.md](docs/AI-AGENT.md)\n\n## Architecture\n\n```\n<vault>/\n  *.md            ← source of truth (Obsidian-compatible)\n  .brain/\n    graph.redb    ← forward/backlinks + mtimes + index version (redb)\n    tantivy/      ← full-text index (tantivy), dictionary-segmented\n~/.config/samong/\n  registry.redb   ← vault name -> path, for cross-vault links\n```\n\nDelete `.brain/` any time — `samong reindex` rebuilds everything from the\nMarkdown files. When the schema/tokenizer version changes, stale indexes are\nrebuilt automatically.\n\n## Development\n\n```sh\ncargo test                              # unit + integration tests\ncargo clippy --all --all-targets -- -D warnings\ncargo fmt --all -- --check\n```\n\n> Note: run `cd web && npm run build` before the first `cargo test` so the\n> embedded-UI tests exercise a real build (they self-skip the UI part otherwise).\n\n### Changing the web UI means reinstalling\n\nThe UI is **embedded into the binary at compile time** (rust-embed), so editing\nanything under `web/` and then running an already-installed `samong-server` still\nserves the old UI. Build, then install over it:\n\n```sh\ncd web && npm run build && cd ..\ncargo install --path . --force\n```\n\nWhile working on the UI, use `cd web && npm run dev` (hot reload, proxied to the\nAPI) or `cargo run --bin samong-server -- start`, which always picks up the\nlatest `web/dist` — much faster than reinstalling on every change.\n\n## Roadmap\n\nDone since the first public release: binaries for four platforms, an \"add vault\"\nbutton in the web UI, connectedness-aware ranking, and optional local semantic\nsearch.\n\n- **A similarity floor for semantic search.** Rank fusion currently admits the\n  top semantic hit unconditionally, so an unremarkable match can still reach\n  position two. The threshold has to be measured against real vaults, not guessed.\n- **A smaller embedding model.** 465 MB is a lot to ask; a quantised build of the\n  same model would cut it substantially.\n- A user dictionary, for words the bundled segmentation dictionary does not know.\n- Package as a desktop app via Tauri.\n- **A central server that indexes git** — a team's vaults, searchable together,\n  ingested from repositories rather than synced. Never a sync protocol of our own:\n  git already solved conflicts, history, offline and auth.\n- Cross-device sync and AI features (note summaries, ask-your-vault) — later, as\n  an open-core layer.\n\n## License\n\n[Apache-2.0](LICENSE) — free to use, modify, and ship commercially, including\ninside your own closed-source software. Keep the copyright notice and give\nattribution.\n\nAll third-party components are credited in [THIRD-PARTY.md](THIRD-PARTY.md) —\nthe `words_th.txt` segmentation dictionary comes from\n[PyThaiNLP](https://github.com/PyThaiNLP/pythainlp) (Apache-2.0).\n\n### Name and logo\n\n**\"Samong\" and the logo are not covered by Apache-2.0.** Fork the code, change\nit, sell it — but please pick a different name for anything you ship separately,\nso users are never confused about who maintains which version. Referring to this\nproject, comparing against it, or saying you are compatible with Samong needs no\npermission.\n\nThe exclusion is written out in **[site/brand/LICENSE](site/brand/LICENSE)**,\nbeside the files it applies to, because the root LICENSE would otherwise read as\ncovering them: Apache-2.0 withholds trademark rights but grants broad rights over\nartwork, and a clone of this repository has no way to guess that those six SVGs\nare different. That file also lists what you may do without asking — which is\nmost things.\n",
  "bytes": 29719,
  "sha": "4a701ca20fa80ae999752e0dbbfb485ed3d3a65a3cde167a633b3444ccf4c87a",
  "repo_slug": "waanvar/samong",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_waanvar_samong_8d8d58f8/readme"
}