Samong

Samong 🧠

为仓库中的现有笔记打造的本地优先知识库

你曾经解决过某个问题，并把解法记了下来。六个月后，那条笔记仍在仓库里，你却找不到它。将 Samong 指向项目根目录，你会提交的 .md 文件就能被搜索并建立链接，而且你一直在使用的 AI 工具也能读取它们。纯 Markdown，兼容 Obsidian（[[wikilink]] / [[wikilink|alias]]），无需账号、无需云端，只需一个二进制文件。

为什么选择 Samong

• 📁 笔记就是你会提交的 .md 文件。 将它指向一个仓库，而不是专用笔记文件夹。它会遵循 .gitignore，并始终跳过依赖目录，因此项目根目录可以索引 ADR、运行手册和设计文档，而不会把 node_modules 一并纳入；samong doctor 会准确告诉你哪些内容被计入，哪些没有。
• 🤖 你的笔记会成为 Agent 的记忆。 samong-mcp 使用 MCP，因此 Claude Code 和 Claude Desktop 可以与你一样搜索、读取和编写同一个知识库。无需在每次会话中反复粘贴上下文（设置）。
• 🗺 图谱是工作区，而非一个新奇的标签页。 知识库是一种形态；输入内容时，不匹配的内容都会变暗，因此查询本身就成了一个空间。
• 🔎 笔记按路径而非标题寻址。 一个仓库里可能有二十个名为 README.md 的文件。标题无法区分它们，按标题建立的索引还会悄悄将它们合并，因此搜索结果、API 和 MCP 工具都会携带实际路径。
• 📚 从你不会提交的文档中学习。 .gitignore 回答的是“我要分发什么？”，而知识库必须回答“我要从什么内容中学习？”。scope.include 会将依赖自身的文档作为只读参考笔记纳入其中——一个项目，一个大脑，无需第二个知识库。
• 🔗 每个知识库对应一个仓库，链接可以跨越所有知识库。 [[other-vault/note]] 可以解析所有已注册知识库中的链接，反向链接也会自动返回，无需维护跨知识库索引。
• 🧭 按相关性和关联度排序。 当关键词无法区分两条笔记时，其他笔记指向的那条会排在前面。加权上限为 25%，因此热门笔记不会排在明显更匹配的笔记之前。
• 🧠 可选的本地语义搜索。 使用 --features semantic 构建，并运行 samong embed，即可通过多语言模型按含义和关键词排序；模型不会离开你的设备。默认关闭是有意为之：见下文。
• ⚡ 快速，而且由你掌控。 使用 redb 保存链接图谱，使用 tantivy 进行搜索，并通过增量重新索引只处理更改过的文件。所有索引都存储在 <vault>/.brain/ 中，随时都可以从 .md 文件重建——没有任何东西会让你受制于它。

安装

有四种安装方式，按所需操作从少到多排列。

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 install Waanvar.Samong 安装，无需预先添加任何内容，因为 Windows 自带 winget。清单位于 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 也没有可供评估的下载信誉。每个 tap 的 CI 都会在真实运行器上安装，并通过断言验证这一点，而不是想当然。

2. 已安装 Rust

cargo install samong

构建全部四个二进制文件，Web UI 已包含其中；需要 Rust 1.88 或更高版本。在本地编译，同样不会发生任何一个操作系统可能拦截的下载。

3. 下载并双击

下载、解压，然后双击：

Windows	Open Samong.exe
macOS	Samong.app
Linux	samong-app（将 samong.desktop 复制到 ~/.local/share/applications/，即可在菜单中显示）

无需终端、配置或账户。首次运行时，它会在 Documents/Samong 中创建一个库，其中包含两条笔记，为它们建立索引，然后打开浏览器。此后，所有内容都是你自己的 Markdown 文件夹。

右上角的 ⏻ 按钮可停止程序——服务会在浏览器标签页关闭后继续运行，因此关闭标签页并不等于退出。

已经有存放笔记的文件夹？在库菜单中选择 + 添加库…，然后指定该文件夹即可。不会移动或转换任何内容。

针对特殊情况提供了两个环境变量，因为双击启动的程序无法接收参数：当 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 已包含在二进制文件中。支持五个平台：x86_64-linux、aarch64-linux（Raspberry Pi、ARM 服务、Asahi）、x86_64-windows、aarch64-macos（Apple Silicon）、x86_64-macos（Intel）。目前还没有适用于 ARM 版 Windows 的归档文件。

请使用旁边发布的 .sha256 校验你下载的文件：

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

⚠️ 下载的二进制文件未经代码签名

这适用于上文的选项 3 和 4，即通过浏览器获取的所有内容。 软件包管理器和 cargo install 不受影响：它们都不会留下让操作系统起疑的下载文件。

Samong 没有代码签名证书，因此操作系统会阻止运行：

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 会自行获取并验证压缩包，因此两个操作系统都无需评估浏览器下载的文件。

或从源代码构建

需要 Rust（stable）和 Node.js 20+（只有想要 Web UI 时才需要 Node；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

顺序很重要：先构建 Web UI，再运行 cargo build/cargo install — 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]	显示出向链接和反向链接（包括跨知识库链接）
samong orphans / samong broken	未链接的笔记 / 指向缺失笔记的链接
samong search <q> [--vault <name>|--all-vaults] [--limit N] [--explain]	全文搜索；--explain 会显示每条结果的排序依据
samong graph [--all-vaults]	显示链接图中的边
samong list	每行显示一条笔记的键值，即 answers、链接和 MCP 服务使用的标识
samong reindex [--full]	同步索引（仅更改的文件 / 所有文件）
samong embed [--reference]	为笔记生成嵌入，以便进行语义搜索（需要 --features semantic）
samong pack <dir> [--include-reference]	将知识库中可发布的内容复制到指定目录——笔记和清单，不包含索引
samong watch	监视知识库并保持索引最新
samong vault add/list/remove	管理中央注册表
samong vault install <git-url>	将他人的知识库安装为只读参考笔记
samong vault update [name]	拉取已安装知识库的最新内容
samong vault verify [name] [--require-signature]	检查已安装知识库是否与发布者发布的内容一致
samong doctor	报告哪些文件算作笔记、哪些文件被跳过，以及是否存在有歧义的标题
samong eval <questions.toml> [--at N] [--vault <name>]	使用实际问题评估搜索效果——hit@k、MRR，以及无法回答的问题被回答的频率（文档）
samong update [--check]	更新到最新的 GitHub 发布版本（--check 仅报告可用更新）
samong-app	双击启动器：查找或创建知识库、启动服务并打开浏览器

哪些文件算作笔记（知识库范围）

规则只有一条：笔记是你会提交的 .md 文件。 直接将项目根目录传给 samong vault add 即可，无需配置。Samong 会：

• 遵循 .gitignore，因此 node_modules/、dist/ 和 target/ 永远不会编入索引
• 即使依赖目录未被 Git 忽略，也始终跳过这些目录 （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)

如需调整，请在知识库根目录添加 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

如果你的代码仓库通过 Git 忽略了自己的笔记，可使用 .samongignore 将其重新纳入。语法与 gitignore 相同，也支持取反：

!notes/
drafts/

从永远不会提交的文档中学习（scope.include）

.gitignore 回答的是**“我要分发什么？”**。知识库必须回答 “我要从什么中学习？”——这不是同一个问题。最明显的例子是 依赖项中附带的文档：Next.js 在 node_modules 中放了 400 多个 Markdown 文件。

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

这些会成为参考笔记——同一个库、同一个索引，因此你自己的笔记中的 [[installation]] 可以解析到它们。一个项目，一个大脑；不需要第二个库。

.samongignore 中的 !node_modules/... 无法做到这一点。遍历器查看目录内容之前， 依赖目录就已被排除，因此没有任何内容可供否定规则匹配；而且 gitignore 本身无法重新包含 父路径已被排除的路径。scope.include 才是正确的办法。

需要了解两点：

1. 参考笔记仅存在于本机。 samong.toml 会随 git 一起传递； node_modules 不会。尚未安装依赖项的机器，或只持有 git 历史记录的 服务器，都找不到这些笔记。这不是错误： Samong 会跳过它们，并打印一行警告；samong doctor 会报告哪些根目录存在。
2. 参考笔记是只读的。 save_note / PUT / delete / rename 会拒绝操作：文件属于某个依赖项，任何编辑都会在下次安装时被覆盖。这对 Agent 尤其重要—— save_note("installation") 不能覆盖框架自己的文档页面。

exclude 只应用于主扫描。若要从某个包含根目录中排除一部分内容， 请将 include 指向更窄的目录。

特意忽略：全局 gitignore（~/.config/git/ignore）、 .git/info/exclude，以及库目录上层的 .gitignore 文件。这些设置 因机器而异；如果遵循它们，同一个仓库在两台笔记本上的索引就会不同。

安装他人发布的库

可以将一个库交给其他人。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、Web 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，而不是留空：这是一个答案，而不是信息缺失。

证明知识库属于发布者（samong vault verify）

完整性并不是缺失的环节——已安装的知识库是一个 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。
• 本地更改会被报告，包括未跟踪的文件。 如果把一个多余的 .md 文件放进已安装的知识库，它就会被编入索引，并会在搜索中显示为由其发布者提供。
• 默认情况下，无签名的知识库也能通过。 如今世界上几乎所有知识库都没有签名，而总是失败的检查没人会运行；对于决定采用不同做法的人，可以使用 --require-signature。

关于谁发布了什么的信息，不会存储在检出目录之外。克隆本身就是其来源证明，存储在别处的记录只会逐渐与之不一致。

更新

samong update 会下载最新的 GitHub 发布版本，并原地替换全部三个二进制文件（samong / samong-server / samong-mcp），包括内嵌的 Web UI。samong update --check 会报告是否有较新版本，但不会安装；samong-server start 会在有可用更新时打印一行提示（尽力而为；绝不会阻塞，也绝不会在离线时失败）。

必须先发布 GitHub 发布版本 （git tag v0.1.0 && git push origin v0.1.0 会触发工作流，为全部三种 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 的分词器。你的笔记和查询仍然不会离开本机，而且下载完成后不再需要网络。但“只有一个二进制文件，无需下载任何内容”就不再成立了，而这正是人们选择它而非云端工具的原因——所以是否启用由你决定，而不是由我们强加。

嵌入是程序执行速度最慢的操作。实测结果：430 篇笔记，其中大多数是引入的 Next.js 文档，在笔记本电脑 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，以便对比这三个数字——如果某个下限提高了 hit@1，却也提高了无依据回答的频率，那么搜索只是变得更自信地答错了。 docs/EVAL.md 介绍了文件格式、如何构建值得信赖的问题集，以及如何解读这组评估结果。

两种排序如何合并。 使用倒数排名融合（Reciprocal Rank Fusion），而不是对分数加权求和：BM25 没有上限，而余弦相似度介于 −1 到 1 之间，因此混合原始数值需要校准，而校准会随着每个知识库而变化。融合排名位置则不需要校准。两种排序都靠前的笔记会胜出；只在其中一种排序中位列第一的笔记也仍会排在前面。

笔记会按约 900 个字符分块（在段落分隔处切分），这样长文档会根据相关部分而非第一页进行匹配，并以每篇笔记得分最高的分块作为该笔记的得分。向量存储在 <vault>/.brain/vectors.redb 中，并使用与重建索引工具相同的内容哈希进行标记，因此重新嵌入时会跳过未更改的笔记。删除该文件后，知识库就会恢复原样。

samong doctor 会报告有多少篇笔记拥有向量，以便区分“语义搜索没有帮助”和“没有内容被嵌入”。

Web UI

原创设计，并非 Obsidian 克隆。整个 UI 嵌入在 samong-server 二进制文件中（rust-embed）——以单个文件发布，启动即用，字体也已打包，因此可离线使用。

• 图谱就是工作区，绘制在 canvas 上（使用 d3-force 布局），因此即使笔记库中有数百篇笔记也能流畅运行。节点大小代表链接数量，颜色代表其所属知识库。
• 从搜索开始：Ctrl+K 会聚焦框架中的输入框——无需打开命令面板。输入内容后，不匹配的节点都会变暗，因此查询结果成为一个位置；按 Esc 可恢复显示整张图。
• 选择节点后，会在图谱旁打开该笔记，并以标签显示链接及其是否有效。全屏阅读是叠加在图谱上的一种状态。
• 输入 [[ 可跨知识库自动补全笔记；点击 wikilink 可跳转（缺失的笔记会立即创建）
• 可使用英语或泰语，语言由 ?lang=、已保存的选择或浏览器设置决定，也可以在页眉中切换。默认使用英语。
• 支持深色／浅色主题、自动保存，并通过 WebSocket 实时更新——在 Obsidian 或任何编辑器中修改文件，页面都会自动更新
• 知识库健康状况会报告已索引和已跳过的内容，因此，预期有 90 篇却只看到 4 篇时，原因一目了然

UI 开发：cd web && npm run dev（Vite 会将请求代理到端口 3117 上的 samong-server）。

API（samong-server）

仅绑定到 127.0.0.1（本地优先，无需身份验证）。

Endpoint	Purpose
GET /api/vaults	已注册的知识库
POST /api/vaults	注册知识库（{name, path}）——无需使用终端
GET /api/vaults/{vault}/notes	知识库中的笔记：{key, title, reference}
GET /api/vaults/{vault}/doctor	与 samong doctor 相同范围的报告
GET/PUT/DELETE /api/notes/{vault}/{path}	读取／写入／删除 Markdown 文件，按路径寻址
GET /api/links/{vault}/{path}	正向链接、反向链接及跨知识库链接
GET /api/search?q=&vault=&limit=	搜索（省略 vault 可搜索所有知识库）——结果包含文件 path
GET /api/graph?vault=	以 JSON 格式返回节点和边
WS /ws	.md 文件变更时发送事件

AI agents（samong-mcp）

samong-mcp 是一个基于 stdio 的 MCP 服务。Agent 可使用以下工具： search_notes、read_note、save_note、get_links、 list_notes、list_vaults——特意不提供删除工具；抹除知识应由人来操作。

Agent 无法覆盖自己尚未读取的笔记。 仅仅不提供删除工具还不够：save_note 会写入整个文件，因此，未读取笔记的 Agent 可能用一段文字替换全部内容，却收到“已保存”的提示——这不过是换了个好听名字的删除操作。因此，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 在你的机器上运行，因此可与同一台机器上的任何客户端配合使用。仅限浏览器的助手无法访问它——网页版 ChatGPT、网页版 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 将其拼写为 mcp_servers，而不是 mcpServers，拼错时也不会报错。

GLM 和 DeepSeek 是模型，不是 MCP 客户端。 Z.ai 的 GLM Coding Plan 专为在你已有的客户端（Claude Code、Cline、OpenCode）中运行而设计，而 DeepSeek 没有自带 MCP 客户端——因此请在宿主客户端中配置 Samong，模型便能通过它使用这些工具。未列出的其他产品也适用同一规则：先选择支持 MCP 的客户端，再选择模型。

如果二进制文件不在 PATH 中，请使用其完整路径，而不是 samong-mcp——图形界面客户端继承的 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——比每次修改后都重新安装快得多。

路线图

自首次公开发布以来已完成：支持五个平台的二进制文件、Web UI 中的“添加保险库”按钮、感知连通性的排名，以及可选的本地语义搜索。

• 语义搜索的默认相似度下限。 排名融合会纳入得分最高的语义搜索结果，无论其得分如何，因此普通匹配仍可能排到第二位。下限本身已经存在——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 不授予商标权，却广泛授予对艺术作品的使用权；克隆此仓库的人也无法猜到这六个 SVG 文件另有不同规定。该文件还列出了你无需征求许可即可进行的操作——大多数操作都无需征求许可。