使用说明
印迹
GPU加速了Claude code的局部语义代码索引。使用CUDA优化的推理嵌入您的代码库，通过增量更新维护实时向量索引，并通过MCP工具提供精确的上下文。用智能检索取代暴力文件读取。
为什么
Claude Code读取整个文件以查找相关上下文——这里是函数签名，那里是类型定义。在大型代码库中，这会快速通过上下文窗口。
Engram在本地维护一个持久的语义索引。Claude Code没有读取10个文件来找到3个重要的函数，而是查询Engram并精确地返回相关的代码片段——包括文件路径、行号和相似性得分。每次查询低于3毫秒，完全在GPU上。
特性
- 语义代码搜索 --提出自然问题（“深度融合是如何实现的”），获取排名代码片段
- 符号查找 --在所有索引项目中按名称查找函数、类、结构
- 上下文检索 --给定一个文件和一行，从整个代码库中提取相关代码
- 会话记忆 --在Claude Code会话中保持关键决策的连续性
- 多项目 --单个进程索引多个代码库，结果按相关性合并
- 无阻塞启动 --MCP服务器立即响应；索引在后台运行，进度通过工具响应报告
- 增量更新 --文件观察器检测更改，仅对更改的内容重新索引（内容哈希）
- AST感知分块 --树状图将9种语言解析为精确的语义单位（函数、类、方法）
- GPU加速 --ONNX运行时+CUDA嵌入、批处理推理、低于3ms的查询
运作原理
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ File Watcher │────>│ Chunker │────>│ Embedder │
│ (filesystem) │ │ (tree-sitter│ │ (ONNX+CUDA) │
└──────────────┘ │ or regex) │ └──────┬───────┘
└──────────────┘ │
v
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Claude Code │<────│ MCP Server │<────│ Vector Index │
│ (queries) │ │ (stdio) │ │ (HNSW) │
└──────────────┘ └──────────────┘ └──────────────┘
- 文件监视器 监控项目的更改（新文件、编辑、删除）
- Chunker 使用树型AST解析（或正则表达式回退）将代码拆分为语义单元
- 嵌入器 通过ONNX Runtime+CUDA在GPU上运行所有MiniLM-L6-v2
- 向量索引 将嵌入存储在HNSW图中，用于快速近似最近邻搜索
- MCP服务器 通过stdio公开工具——Claude Code自然查询
MCP工具
| 工具 | 说明 |
|---|---|
search_code |
语义搜索：“深度融合是如何实现的”→ 排名片段 |
search_symbol |
按符号名称查找：函数、类、结构 |
get_context |
给定一个文件和行范围，在整个项目中检索相关代码 |
get_session_memory |
检索以前编码会话的摘要 |
save_session_summary |
坚持本届会议的关键决定/变更 |
需求
- Windows 10/11（计划在v2.0中支持Linux）
- CMake 3.24+，Visual Studio 2022（MSVC）
- 配备CUDA 12.x+cuDNN 9.x的NVIDIA GPU（用于GPU嵌入；核心功能无需GPU即可工作）
- ONNX Runtime 1.24+GPU包（可选）
- 支持MCP的Claude代码
技术栈
| 层 | 技术 |
|---|---|
| 语言 | C++17（MSVC） |
| GPU推理 | ONNX运行时+CUDA执行提供程序 |
| 矢量索引 | hnswlib（HNSW，余弦相似度） |
| 代码解析 | 树形图（9种语言）+正则表达式回退 |
| 协议 | MCP-over-stio（JSON-RPC 2.0） |
| 序列化 | nlohmann/json |
| 日志记录 | spdlog（stderr） |
| 测试 | 谷歌测试（177项测试） |
建筑
# Core build (no GPU embedding — symbol search and session memory still work)
cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
cd build && ctest -C Release --output-on-failure
# With tree-sitter for AST-aware chunking (more accurate symbol boundaries)
cmake -B build -G "Visual Studio 17 2022" -A x64 \
-DENGRAM_USE_TREESITTER=ON
cmake --build build --config Release
# With ONNX Runtime for GPU-accelerated semantic search
cmake -B build -G "Visual Studio 17 2022" -A x64 \
-DENGRAM_USE_ONNX=ON \
-DONNXRUNTIME_ROOT="path/to/onnxruntime-win-x64-gpu"
cmake --build build --config Release
# Full build (tree-sitter + ONNX)
cmake -B build -G "Visual Studio 17 2022" -A x64 \
-DENGRAM_USE_TREESITTER=ON \
-DENGRAM_USE_ONNX=ON \
-DONNXRUNTIME_ROOT="path/to/onnxruntime-win-x64-gpu"
cmake --build build --config Release
模型导出
在运行GPU嵌入之前，导出ONNX模型：
# Create a Python venv (once)
python -m venv .venv
.venv/Scripts/activate # Windows
# Install dependencies
pip install torch transformers onnx onnxruntime-gpu
# Export all-MiniLM-L6-v2 (384-dim, ~86MB) — recommended for 6GB VRAM GPUs
python scripts/export_model.py --model minilm --output models/ --validate
# Or export with INT8 quantization for smaller size
python scripts/export_model.py --model minilm --output models/ --quantize --validate
这写道 models/all-MiniLM-L6-v2.onnx 和 models/tokenizer.json.
用法
# Run the MCP server directly (for testing)
./build/bin/engram-mcp.exe --project /path/to/your/repo --model models/all-MiniLM-L6-v2.onnx --treesitter
# Register with Claude Code (user scope — available in all projects)
claude mcp add engram --scope user -- \
/path/to/engram-mcp.exe \
--project /path/to/your/repo \
--model /path/to/models/all-MiniLM-L6-v2.onnx
# On restart, engram automatically detects changed files via content hashing
# and only re-indexes what changed. Use --reindex to force a full rebuild:
claude mcp remove engram --scope user
claude mcp add engram --scope user -- \
/path/to/engram-mcp.exe \
--project /path/to/your/repo \
--model /path/to/models/all-MiniLM-L6-v2.onnx \
--reindex
# Claude Code will automatically discover the tools in a new session.
# The bundled skill teaches Claude when to use engram vs built-in search.
# Just ask naturally: "how is camera calibration implemented?"
多项目支持
一个 engram-mcp 进程可以索引和服务多个代码库。每个项目都有自己的独立索引、块存储和会话内存。
# Index two projects at once
./build/bin/engram-mcp.exe \
--project /path/to/project-a \
--project /path/to/project-b \
--model models/all-MiniLM-L6-v2.onnx
# Or use a config file
./build/bin/engram-mcp.exe --config .engram.toml --model models/all-MiniLM-L6-v2.onnx
.engram.toml （可选配置文件）：
[[project]]
path = "E:/Repos/Engram"
[[project]]
path = "E:/Repos/OtherProject"
data_dir = "D:/EngData/OtherProject" # optional override
加载多个项目时，搜索结果包括 "project" 标识每个结果来自哪个代码库的字段。在单项目模式下，为了向后兼容，省略了此字段。
CLI选项
| 标志 | 描述 |
|---|---|
--project <path> |
要索引的代码库根（可重复用于多项目） |
--model <path> |
ONNX嵌入模型的路径 |
--data-dir <path> |
持久数据目录（仅限单个项目；默认值： <project>/.engram/) |
--config <path> |
通往 .engram.toml 配置文件（默认值： .engram.toml 在cwd） |
--dim <int> |
嵌入尺寸（默认值：384，从模型中自动检测） |
--batch-size <int> |
GPU嵌入的批量大小（默认值：32） |
--reindex |
强制完全重新索引（默认：通过内容哈希递增） |
--treesitter |
使用树保姆AST感知分块器（需要 ENGRAM_USE_TREESITTER 构建） |
--verbose |
启用调试级别日志记录 |
演出
以RTX 3060 6GB、CUDA 12.8为基准，对Engram代码库本身进行索引（43个源文件，约463 KB）。
分块速度
| 分块器 | 时间 | 分块 | 吞吐量 |
|---|---|---|---|
| 正则表达式 | 5187毫秒 | 1182 | 228个块/秒 |
| 树保姆 | 196毫秒 | 619 | 3162块/秒 |
| 加速 | 26.5倍 |
Tree sitter通过使用AST结构而不是正则表达式启发式生成更少、更精确的块。
冷索引速度
从空索引到完全可搜索的端到端时间，包括分块+GPU嵌入+索引构建：
| 阶段 | 时间 |
|---|---|
| Chunking（树保姆） | 196毫秒 |
| 嵌入（619个块，批=32） | 2208毫秒 |
| 索引保存 | ~25毫秒 |
| 完全冷启动 | 约2.4秒 |
通过内容哈希检查进行热重启，跳过未更改的文件。典型的热重启：5毫秒。
查询延迟
按查询时间细分（嵌入查询+HNSW搜索，k=10,20个查询）：
| 相位 | 平均值 | 最小值 | 最大值 |
|---|---|---|---|
| 嵌入查询 | 2.64毫秒 | 2.21毫秒 | 3.56毫秒 |
| HNSW搜索 | 0.13毫秒 | 0.08毫秒 | 0.44毫秒 |
| 总计 | 2.76毫秒 | 2.31毫秒 | 3.86毫秒 |
内存占用
| 组件 | 尺寸 |
|---|---|
| HNSW索引（磁盘上/内存中） | 2.7 MB |
| 块元数据（Chunk.json） | 820 KB |
重现
# Run the full benchmark suite
./build/bin/engram_benchmarks.exe \
--project . \
--model models/all-MiniLM-L6-v2.onnx \
--iterations 3 \
--batch-size 32 \
--warmup 3 \
--queries 20
许可证
麻省理工学院
