你的 Agent 需要一个「能记住、能检索、能版本管理」的知识库：产品手册、FAQ、内部规范、竞品笔记，最好是 Markdown（人和机器都好读），而且每次改动都能追溯。但裸 Markdown 文件只是文件——没有搜索、没有版本、没有结构，Agent 也只会 cat 和 grep。
KiwiFS 解决的就是这个问题：它是一个单二进制、零配置的 Markdown 文件系统，把普通 .md 文件变成「可搜索、可结构化查询、带 Git 版本、可被 Agent 读写」的知识库。它自带 62 个 MCP 工具，让 Claude / Cursor / Codex 等直接读、写、搜、批量写；底层用 SQLite FTS5 做全文检索，可插拔向量后端做语义检索；还能用 DQL（类 SQL）对 frontmatter 做结构化查询。文件永远是单一事实来源，其它索引都能重建。
先搞懂：KiwiFS 把文件变成了什么
核心思路一句话：Markdown 文件是事实来源，搜索 / 版本 / 语义检索都是派生索引，可随时重建。它把你熟悉的 cat / echo 文件操作，升级成带 Git 历史、全文检索和结构化查询的知识底座。
| 能力 | 裸 Markdown | KiwiFS |
|---|---|---|
| 搜索 | 只能 grep | SQLite FTS5 全文 + 可插拔向量语义检索 |
| 版本 | 无 | 每次写入是一次原子 Git 提交，可 blame / diff / 回溯 |
| 结构化查询 | 无 | DQL：TABLE / LIST / COUNT / WHERE / SORT / GROUP BY |
| Agent 接入 | 读文件 | 62 个 MCP 工具，读 / 写 / 搜 / 批量写 |
许可要留意：KiwiFS 采用 BSL-1.1 许可，个人自托管免费可用，但把它当作商业托管服务对外提供需单独商业授权；许可生效四年后转 Apache 2.0。自用、团队内用都 OK，别直接对外卖服务。
Step 1：安装 KiwiFS
KiwiFS 是 Go 写的单二进制，三种装法任选其一：
# 方式一：官方安装脚本（macOS / Linux）
curl -fsSL https://raw.githubusercontent.com/kiwifs/kiwifs/main/install.sh | sh
# 方式二：Homebrew（macOS / Linux）
brew install kiwifs/tap/kiwifs
# 方式三：有 Go 环境直接装
go install github.com/kiwifs/kiwifs@latest
# 验证
kiwifs --versiondocker run -p 3333:3333 -v ./knowledge:/data ameliaanhlam/kiwifs。后续所有命令在容器里语义一致。Step 2：初始化知识树
用 init 在当前目录建一个知识树，--template knowledge 会铺好 wiki 链接、backlinks、知识图谱等默认结构：
# 初始化（--root 指定知识库根目录）
kiwifs init --template knowledge --root ./knowledge
# 进去看看生成了什么
ls -la ./knowledgepages/ 下的一个 Markdown 文件，并在 frontmatter 里写 tags / owner / updated 等字段。后面 DQL 就能按这些字段筛选，Agent 既能全文搜、也能结构化查。Step 3：启动服务
用 serve 启动，REST API 跑在 :3333，自带 Web UI 在 http://localhost:3333（带 wiki 链接、backlinks、图谱视图、块编辑器）。--search sqlite 启用 FTS5 全文检索：
# 启动服务（sqlite 全文检索）
kiwifs serve --root ./knowledge --search sqlite
# 浏览器打开
open http://localhost:3333语义检索要额外配置：纯全文检索用 --search sqlite 即可；向量 / 语义检索需要自备后端——OpenAI / Ollama / Cohere + sqlite-vec、Qdrant、pgvector、Pinecone 等任选。没配就只能用全文，别指望它「理解含义」式检索。
Step 4：用 MCP 把知识库接进 Agent
KiwiFS 自带 62 个 MCP 工具，原生适配 Claude Desktop / Cursor / Codex 等任意 MCP 客户端。启动 MCP 服务后，在客户端配置里指向它即可：
# 启动 MCP 服务（指向同一份知识库）
kiwifs mcp --root ./knowledge
# 以 Claude Desktop 为例，配置片段（mcpServers 下）：
# {
# "mcpServers": {
# "kiwifs": {
# "command": "kiwifs",
# "args": ["mcp", "--root", "/绝对路径/knowledge"]
# }
# }
# }接好后，Agent 就能直接「读页面、写页面、搜索、批量写」，相当于它拥有了一个带版本管理的内存。
Step 5：用 REST / 文件接口喂入资料
除了在 Web UI 里手写，还可以用 REST 或挂载目录批量灌数据。X-Actor 头决定提交作者，文本进 Git 前会被剥离控制字符并截断到 256 字符：
# 用 REST 写一页（X-Actor 标记作者）
curl -X PUT 'localhost:3333/api/kiwi/file?path=pages/auth.md' \
-H "X-Actor: my-agent" \
-d "# Authentication
OAuth2 + JWT ..."
# 或直接往挂载目录写文件（FUSE / NFS / WebDAV 均可）
echo "# Report" > ./knowledge/pages/report.md
# 19 个导入器一键搬存量：Notion / CSV / Obsidian / Postgres / MySQL / MongoDB
kiwifs import --root ./knowledge --source notion --token "$NOTION_TOKEN"别把机密写进知识库页面：知识库通常对 Agent 开放读取，密钥、PII 等敏感信息应走脱敏或独立存储。另外每个写都是一次原子 Git 提交，X-Actor 头默认在 REST/WebDAV 上可被可信中间件覆盖，别依赖它做鉴权。
Step 6：用 DQL 做结构化查询与健康巡检
frontmatter 会被镜像进 SQLite，可用 DQL（类 SQL）按字段查询。还能用 lint 做内容健康巡检（失效链接、孤儿页、矛盾检测）：
# 查询：带 api 标签的页面，按更新时间倒序
kiwifs query "TABLE pages WHERE tags CONTAINS 'api' SORT updated DESC"
# 统计：某个 owner 名下有多少页
kiwifs query "COUNT pages WHERE owner = 'zhang'"
# 内容健康巡检：找失效链接 / 孤儿页 / 陈旧页
kiwifs lint ./knowledge多空间（multi-space）让不同团队各自独立 git 仓库与搜索索引，互不串味。WebHooks 还能在写/删事件时通知 Slack / CI。
tags / owner / updated，DQL 才能按字段筛；否则只能退化为全文检索。KiwiFS 是 pre-1.0 快速迭代期，命令细节以 docs.kiwifs.com 为准。预期效果与常见问题
预期效果：跑完上面六步，你拥有了一个「文件即事实来源、带 Git 历史、可全文+语义检索、Agent 能直接读写」的知识库。给 Agent 一句「读 pages/auth.md 里 OAuth 那段，总结成三步」，它能精准定位并给出答案；你改了文件，Git 里能看到是谁、改了什么。
| 你遇到的现象 | 大概率原因与解决 |
|---|---|
| serve 起不来 / 端口被占 | 默认 3333，换个端口或先释放；Docker 方式确认 -p 映射一致 |
| Agent 搜不到语义相关内容 | 只配了 --search sqlite（全文），需再配向量后端才支持语义检索 |
| 写入报 409 Conflict | 并发乐观锁命中，用 ETag 重新读取最新内容再写 |
| MCP 客户端连不上 | 确认 --root 用绝对路径，且 kiwifs 在客户端 PATH 中 |