Kamibiki（KB）
Kamibiki是一个用于代理编码的上下文搜索引擎。它索引 git存储库本地使用嵌入，并提供快速的语义 从命令行或作为MCP服务器搜索编码代理。
入门指南
先决条件
- 锈 --从以下位置安装https://rust-lang.org/tools/install
- Voyage AI API键 --注册地址：https://www.voyageai.com/和
创建API密钥。Kamibiki使用Voyage AI进行嵌入和 重新评级。
安装
git clone https://github.com/dominiccooney/kamibiki.git
cd kamibiki
cargo build --release二进制文件位于 target/release/kb你可以把它复制到某个地方 你的 PATH，或者直接运行它。
设置API密钥
kb init这会提示您输入Voyage AI API密钥，并将其保存到 ~/.kb.conf.
添加存储库
kb add
`` 是您将在其他命令中使用的简写别名。对于 例子：
kb add myproject ~/src/myproject为存储库建立索引
kb index 这会将所有跟踪的文件分块，通过Voyage AI计算嵌入 API，并将索引文件写入 .kb 存储库根目录下的文件夹。 添加 .kb 致你的 .gitignore.
索引支持增量更新——后续运行仅重新嵌入 更改了文件。如果中断，重新运行将从原来的位置恢复 关
您可以使用以下命令在特定的git修订版处进行索引 --commit:
kb index myproject --commit my-feature-branch
kb index myproject --commit abc1234
kb index myproject --commit HEAD~3当 --commit 省略，它在HEAD处索引。
通过 --compact 在目标处强制使用自包含索引 承诺。Kamibiki通常写入指向后面的小增量文件 通过提交哈希访问较旧的“父”索引——搜索遍历 链来填充未更改的块。紧凑型指数是指单一 独立文件（其父哈希为零），因此链式遍历 在那里终止。当你想放下尾巴时，这很有用 一条长长的三角洲链，或者阻止搜索咨询老用户 历史。
紧凑的重建是嵌入保留：每个块 （路径、文本）与现有块中的块匹配 .kbi 或下一个 最近的索引是逐字复制的-没有API调用-所以 重新编译您已经索引过的存储库通常只 嵌入字节实际上不同的少数块。新 索引被写入一个辅助文件，然后在 前一个；如果中断，重新运行将恢复正在进行的 结构紧凑。
kb index myproject --compact搜索
kb search 例如：
kb search myproject "how does authentication work"使用 -n 控制结果数量（默认10），以及 --commit 从特定修订中搜索：
kb search myproject "error handling" -n 5 --commit my-branch使用 . 作为在当前目录中搜索存储库的名称：
kb search . "database connection pooling"检查状态
kb status
kb status 显示索引存储库、索引文件计数和大小、最新索引 提交和嵌入计数。
命令
| 命令 | 描述 |
|---|---|
kb init | 设置Voyage AI API密钥 |
| `kb add | |
| ` | 注册一个git存储库进行索引 |
kb index [names...] [-c commit] | 更新索引（增量感知，可重启） |
kb status [name] | 显示索引状态 |
kb search [-n top] [-c commit] | 搜索存储库 |
kb alias | 为一组存储库创建简写 |
kb drop | 删除存储库的所有索引文件 |
kb gc [name] [--dry-run] | 删除git不再知道的提交的索引文件 |
kb start | 在stdio上启动MCP服务器 |
垃圾收集
kb gc 遍历每个存储库的 .kb 目录并删除任何 .kbi 其索引提交不再在git中解析的文件。这 清理已重写或重基化的分支 git自己的垃圾回收器已经收集了他们的小费提交。
一个垂死的提交的父母通常还活着（你通常会重新索引 重写树枝的尖端，而不是它的祖先），所以 kb gc 从不 在链上或链下级联删除——它只删除文件 他们自己的承诺已经消失了。作为一致性检查，如果 存活指数 parent_hash 指向其中一个文件 移除，这通常不应该发生。
使用 --dry-run 无需触摸即可预览要删除的内容 文件系统。省略 name 对每个注册的存储库进行gc。
MCP服务器
kb start 通过stdio（JSON-RPC）将Kamibiki作为MCP服务器启动 2.0，换行符分隔）。它公开了三个工具：
kb_search --在索引存储库中搜索与以下内容相关的代码 查询。参数：
name（必填）：存储库名称，或.对于当前回购query（必填）：自然语言或代码搜索查询top（可选）：结果数量，默认为10commit（可选）：要从中搜索的git修订（提交哈希，
分支名称、标签， HEAD~1等等）。默认为HEAD。
kb_status --显示已注册存储库的索引状态。 参数：
name（可选）：特定存储库名称；省略所有repos
kb_index --更新一个或多个存储库的搜索索引。 参数：
names（可选）：存储库名称数组；省略对所有内容的索引commit（可选）：对索引进行git修订（提交哈希，分支
名称、标签， HEAD~1等等）。默认为HEAD。
compact（可选）：当为true时，编写一个自包含的根索引
（父哈希为零）在目标提交时。嵌入来自 现有的 .kbi 并且重用下一个最新索引 逐字逐句；只有文本不匹配的块才会被重新嵌入。 新文件被原子性地重命名为旧文件。默认为 错误的
连接编码代理
将Kamibiki添加到MCP服务器配置中。例如，在Cline （VS Code或CLI），编辑您的MCP设置：
{
"mcpServers": {
"kamibiki": {
"command": "/path/to/kb",
"args": ["start"],
"disabled": false
}
}
}对于Cline VS Code，此文件位于 ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json. 对于Cline CLI，它位于 ~/.config/cline-cli/cline_mcp_settings.json.
配置后，您的编码代理将看到 kb_search, kb_status, 和 kb_index 作为可用的工具。根据您的型号，您可以 第一次需要提示它使用该工具——之后 倾向于经常使用它。
技术背景
Kamibiki在Rust中实现，并使用gitoxide实现高带宽 对git存储库的只读访问。它的索引是平面文件 存储在a .kb 存储库根目录下的目录。作为你的 存储库发生更改时，它会写入覆盖文件。这些是定期的 压缩以回收空间并提高搜索速度。
Kamibiki跳过二进制文件和超大文件。使用 多模态嵌入模型（例如嵌入图像）是我们 未来可能会考虑。
分块器和嵌入器
作为一个基于嵌入的搜索引擎，Kamibiki对 分块模型，将文件分成块并可能重新格式化 这些块可以添加上下文；以及投影的嵌入模型 将这些块放入向量空间。支持的组块和 嵌入模型被硬编码到二进制文件中，并写入 索引元数据。
支持的组块：
tsv1 --一种基于树的分块器，可递归分割 解析流行语言的树，直到合适的块大小为 产生。对于不支持的语言，它又回到了分裂 换行并递归合并块，直到达到合适的大小 达到。确切的块大小取决于 嵌入模型。
支持的型号：
1 = voyage-code-3@2048，二进制量化（~256字节/块）
文件格式
Kamibiki索引文件格式旨在与批量文件一起使用 数据为只读。这让我们可以依靠操作系统的 文件系统缓存、页面缓存和虚拟内存管理器 快。每个索引文件都以git哈希命名，并包含：
- 版本号，当前为1字节=1。这些文件始终使用
voyage-code-3@2048，二进制量化嵌入器。（指数是 对使用的切块机不敏感，只要它能产生 从文件的第一个字节开始的非重叠块。)
- 此索引创建的git哈希值为.64字节，以支持
具有SHA-256哈希值的存储库，但可能只有20字节/160位 SHA-1哈希。
- 父git哈希，如果此索引应覆盖在现有索引上
指数。这样，当存储库发生更改时，我们可以生成一个小 仅包含差异的索引。
- 偏移量表。偏移量是git索引中的偏移量
相关修订。偏移量可以是正的或负的s16 数字。正数表示以下n项 git索引按顺序包含在索引中。负数 表示git索引中的以下-n个项目，按顺序为 跳过。偏移量为0表示表格结束。
- 块计数表。对于包含的每个文件（由于
由索引偏移表中的正数覆盖）u16数字 大块。不支持块数超过65534的文件。 (0 块是有效的，这意味着没有块。65535已预留。)
- 每个文件和每个文件中每个块的长度表
订单。长度是u16，表示块的长度 字节。对于具有特定编码的文件，分块器必须分解块 在有效的字符边界上。
- 填充以将嵌入数据与适合的单词边界对齐
矢量处理。嵌入器组件负责 描述这种对齐。
- 嵌入数据。这应该与合适的宽度对齐
嵌入的矢量处理。
查询策略
要回答问题，Kamibiki：
- 使用相关的嵌入模型嵌入查询。
- 在嵌入中使用向量运算来计算余弦距离
空间。对于二进制量化嵌入，这是XOR和 人口。它维护一个最大堆，以保持前N个结果 最小嵌入距离。每个结果都由其 嵌入表中的偏移量。N被选择为接近 步骤5中重新排序模型的限制。
- 在嵌入表中按偏移量对前N个结果进行排序。
- 使用并行指针扫描git索引、索引表、块
计数和偏移表。查找索引条目和字节偏移量 并使用git生成块内容。
- 将查询和前N个块提交给重新排序模型（不是
超过重新排序模型的上下文长度限制）。
- 按顺序返回重新排序器的结果。
当索引有父索引时，步骤2-4的结果为 迭代地向后遍历相关索引。 首选较新索引的结果。如果在中删除了某个项目 正在搜索的修订版（不是在索引中，而是在git本身中）， 在步骤5之前抑制来自旧索引的陈旧结果。
本地更改
Kamibiki不会搜索未提交的更改。将来，我们可能会 它具有用于未提交更改的临时内存索引。