srag (Wrxck)

srag

在所有存储库中进行语义代码搜索。索引你的项目一次，然后通过MCP查询它们——你的AI编码助手可以即时访问你写过的每一个模式、实现和约定。

为什么？

AI编码助手擅长编写代码，但他们不知道 *你的* 代码。当你已经有一个身份验证流时，他们会建议一个新的身份验证流。当你的日志模式就在那里时，他们会发明一种日志模式。他们会问你在另一个项目中已经回答过的问题。

srag解决了这个问题。对存储库进行索引，您的助手可以在语义上搜索所有存储库，找到相关的实现、模式和约定，而无需解释任何内容。

用例

重用自己的实现

“添加OAuth令牌刷新”→ Agent跨项目查找您的现有实现，复制模式，包括您已经处理的边缘情况

一致的代码风格

代理查询 get_project_patterns 在编写代码之前，请查看您使用的 snake_case 对于功能和 PascalCase 对于类型，会自动跟随

找到你写的东西

“我是如何处理限速的？”→ 语义搜索可以找到相关的代码，即使你不记得是哪个项目或你叫它什么

跨项目知识

在项目A中工作，需要与您以前在项目B中使用过的API集成→ 代理找到您之前的集成，重用错误处理和重试逻辑

使用上下文进行调试

“为什么会失败？”→ Agent在代码库中搜索类似的错误处理模式，查找您之前是如何解决同类问题的

上车吧

回到旧项目？查询索引以了解架构，查找定义内容的位置，查看使用的模式

代码审查上下文

“这就是我们通常的做法吗？”→ 搜索类似的实现，以检查与既定模式的一致性

查找重复项

将代码片段传递给 find_similar_code → 发现代码库中几乎可以重构的重复项

实际价值会随着时间的推移而复合。你索引的项目越多，你的助手可以从中提取的模式就越多。质量随模型而变化——更好的模型可以更好地利用检索到的上下文。

安装

你需要先安装Rust和Python 3.10+。

Linux

./install.sh

这将二进制文件构建为 ~/.local/bin/srag 并设置Python ML后端。

如果 ~/.local/bin 不在您的路径中：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

macOS

./install.sh

该脚本将请求sudo将二进制文件安装到 /usr/local/bin。数据转到 ~/Library/Application Support/srag.

如果你还没有Rust/Python：

brew install rust python@3.12

Windows

使用WSL（Windows Linux子系统）并按照Linux说明进行操作。原生Windows支持尚未到位，但WSL工作正常。

用法

# index a project
srag index /path/to/repo

# re-index all projects (incremental, skips unchanged files)
srag sync

# start file watcher for auto-reindexing
srag watch

# interactive chat
srag chat

# one-shot query
srag query -p myproject -q "what was that authentication we implemented in {project_name}?"

# show index stats
srag status --detailed

MCP服务器

srag mcp 通过stdio启动MCP服务器，以便与AI工具（Claude Code、Cursor等）集成。

直接运行时，它不会产生任何终端输出，而是通过stdin/stdout上的JSON-RPC进行通信。

与Claude Code有内置集成，它将找到您的MCP配置（如果没有，则创建一个），下次使用它时，您可以要求您的代理从srag检查MCP工具——它应该能找到它们。这是安装脚本的一部分。

现在，这就是它成为一个非常强大的工具的地方，因为不仅你的代理能够通过查询嵌入更快地找到代码，而且你在这样做的时候可能会使用更少的令牌，因为这种格式对LLM来说更方便。

我还发现，当代理可以引用您现有的模式时，他们倾向于编写更一致的代码，而不是每次都发明新的模式。

可用的MCP工具

测试MCP服务器

npx @modelcontextprotocol/inspector srag mcp

配置

Config住在 ~/.config/srag/config.toml 在Linux或 ~/Library/Application Support/srag/config.toml 在macOS上。您可以调整要使用的LLM提供程序、上下文大小和文件忽略模式。有一个 config.example.toml 如果你想看看有什么可用的，可以在repo中查看。

对于外部LLM提供商（Anthropic、OpenAI），只需将API键放在配置目录中 api_key.txt 或者设置适当的环境变量。

运作原理

Rust CLI处理文件发现、基于树的代码分块和SQLite+HNSW向量索引。Python sidecar进程管理ML位——嵌入、重新排序和LLM推理。

当您查询时，它会使用互惠排名融合进行混合搜索（向量相似性+全文），然后在将结果传递给LLM之前对其进行重新排名。分块是语言感知的，因此它提取函数、类和其他有意义的单元，而不仅仅是按行数拆分。

还内置了提示注入检测和秘密编校，因此您不会意外地将API密钥泄漏到查询中。

卸载

./uninstall.sh

这删除了二进制Python环境，并提供了清理Claude MCP配置的功能。它会在做任何事情之前准确地显示要删除的内容。

发展

./test.sh    # run all tests (rust + python)
./lint.sh    # run linters (clippy, rustfmt, ruff)
./format.sh  # auto-format code

贡献

欢迎投稿-请参阅 贡献.md 了解详情。

替代方案

还有其他几个语义代码搜索工具值得考虑。以下是srag的比较：

|---------|------|--------|----------|-------------| | 搜索 | |语义向量搜索|是|是|有|有| |全文关键字搜索|是|是|否|是（BM25）| |混合搜索（向量+FTS）|是，RRF融合|是|否|是| |重新排名|是|否|否|是（Jina）| | 索引 | |AST感知组块|是的，树保姆|是的|树保姆|树保姆| |增量（基于哈希）|是，blake3|是|是，mtime|是，SHA-256| |文件监视器|是|是|否|否| |第一次查询时自动索引|是|否|否|不| | 语言 |9（AST）+基于行的|12+|9|2| | 安全 | |快速注射检测|是|否|否|不| |秘密编辑|是|否|否|不| | 整合 | |MCP服务器|是|是|有|有| |多项目支持|是|是，工作区|否|否| |跨项目搜索|是|是|否|否| | 隐私 | |完全本地选项|是|是（Ollama）|是|否（需要Jina API）| | 其他 | |模式分析|是|否|否|不| |类似代码查找器|是|否|否|不| |互动聊天|是|否|否|不| |调用图跟踪|是|是|否|否|

何时使用什么

如果您有以下情况，请选择srag：

• 需要安全功能（快速注射检测、秘密编辑）
• 想要混合搜索和重新排序，以获得更好的准确性
• 有多个项目，需要跨项目搜索
• 更喜欢无需手动设置的自动索引
• 想要分析整个代码库中的编码模式
• 需要调用图跟踪（查找函数的调用者/被调用者）

选择 希腊 如果你：

• 想要一个不依赖Python的二进制文件
• 需要最广泛的语言支持（12+）
• 想要预先构建的AI代理技能

选择 CodeGrok 如果你：

• 希望GPU加速嵌入生成
• 需要详细的符号元数据（签名、文档字符串）
• 更喜欢更简单、更专注的工具

选择 DeepContext 如果你：

• 想要Jina的嵌入模型
• 需要自动测试/生成文件排除
• 主要使用Types/Python

支持的语言

srag使用tree sitter进行AST感知代码分块：

基于线条的组块 用于配置和文档文件：Markdown、JSON、YAML、TOML、Shell脚本、SQL、HTML、CSS和环境文件。

许可证

GPL-3.0-见 许可证 了解详情。