Phoenixrr2113/codebase-graph
GitHub: Phoenixrr2113/codebase-graph
一个面向 AI 代理的代码知识图谱与搜索系统，通过 tree-sitter 解析、向量检索和双时态知识图谱，让大模型能够深度理解和检索代码库。
Stars: 2 | Forks: 0
# CodeGraph
一个面向 AI 代理的代码知识图谱与搜索系统。它将您的代码库索引到图数据库中，对符号和文档进行嵌入，并通过 Model Context Protocol (MCP) 服务器暴露搜索接口。
## 功能特性
- **按语义搜索代码** — vector embeddings 结合 cross-encoder reranking 能够找到您描述的函数、类或接口，即使您不知道它们的名称。内部基准测试：在一个包含约 2.3K 节点的项目中，MRR 为 0.969，Success@1 为 94%，Success@5 为 100%，延迟约为 447ms。
- **理解结构** — tree-sitter 解析器可跨 5 种一等语言（TypeScript, Python, Go, Rust, Markdown）提取 Functions, Classes, Interfaces, Variables 和 Types，并通过 generic plugin 提供对其他语言的 tree-sitter 覆盖支持。
- **追踪时间维度上的决策** — bitemporal knowledge graph（双时态知识图谱）使用 `valid_at` / `invalid_at` 时间戳存储事实，支持时间点查询（“3月1日时的情况是什么？”）。
- **接入 AI 代理** — 暴露 4 个 MCP 工具组（`search`、`knowledge`、`codebase`、`query`），可应用于 Claude Desktop、Cursor、Claude Code 或任何 MCP 客户端。
## 快速开始
```
git clone https://github.com/Phoenixrr2113/codebase-graph.git
cd codebase-graph
pnpm install
pnpm build
# 选项 A — embedded database (无需 Docker)
brew install redis # macOS — FalkorDBLite needs redis-server
echo "CODEGRAPH_DRIVER=falkordblite" > .env
echo "CODEGRAPH_DB_PATH=.codegraph/falkordb" >> .env
# 选项 B — 通过 Docker 运行 FalkorDB
# pnpm docker:db
# echo "CODEGRAPH_DRIVER=falkordb" > .env
# 索引项目
pnpm --filter @codegraph/cli start configure --projects /path/to/your/project
pnpm --filter @codegraph/cli start reindex
# 运行 MCP server (stdio transport)
pnpm --filter @codegraph/mcp-server start
```
## 与 MCP 客户端配合使用
### Claude Desktop
添加至 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```
{
"mcpServers": {
"codegraph": {
"command": "node",
"args": ["/absolute/path/to/codebase-graph/packages/mcp-server/dist/index.js"],
"env": {
"VOYAGE_API_KEY": "your-key",
"JINA_API_KEY": "your-key"
}
}
}
}
```
### Claude Code
```
claude mcp add codegraph node /absolute/path/to/codebase-graph/packages/mcp-server/dist/index.js
```
## MCP 工具
默认提供四个基于角色（persona）的工具组。设置 `CODEGRAPH_RAW_TOOLS=1` 可单独暴露底层处理程序。
| 工具 | 功能 |
|------|--------------|
| **search** | 按名称或语义查找代码/符号；获取文件或符号的上下文 |
| **knowledge** | 存储和检索实体、关系及事实（支持双时态查询） |
| **codebase** | 配置项目、重新索引、检查状态/统计信息、读取源代码 |
| **query** | 对图执行只读 Cypher 查询（面向高级用户） |
有关完整的工具参考（参数、示例、工作流），请参阅 [CLAUDE.md](./CLAUDE.md)。
## 架构
- **图存储：** FalkorDB (Docker) 或 FalkorDBLite (embedded)，每个节点类型带有 HNSW vector indexes。
- **Embeddings：** 可插拔设计 — 支持 Voyage AI (`voyage-code-3`, 1024维)、OpenRouter，或通过 `@huggingface/transformers` 运行的本地 nomic-embed (768维，可在 CPU 上运行)。
- **Reranker：** 通过 Jina (`jina-reranker-v2-base-multilingual`) 或 Voyage 实现的 cross-encoder。
- **Indexer：** 使用 tree-sitter 进行 AST 解析，基于 SHA-256 文件哈希的增量变更检测。
- **MCP 服务器：** 默认提供 4 个 persona 工具；raw mode 可暴露底层处理程序。
## 配置
环境变量（在仓库根目录的 `.env` 文件中设置）：
```
# Embedding provider (从 API keys 自动检测)
CODEGRAPH_EMBEDDING_PROVIDER=voyage # voyage | local | openrouter
VOYAGE_API_KEY=...
# Reranker provider (从 API keys 自动检测)
CODEGRAPH_RERANK_PROVIDER=jina # jina | voyage
JINA_API_KEY=...
# LLM (用于 knowledge extraction + chain-of-thought search)
LLM_PROVIDER=cerebras
CEREBRAS_API_KEY=...
# Graph driver
CODEGRAPH_DRIVER=falkordblite # falkordblite | falkordb
CODEGRAPH_DB_PATH=.codegraph/falkordb # for falkordblite
```
## 包
| 包 | 描述 |
|---------|-------------|
| [`@codegraph/core`](packages/core/) | Indexer、搜索管道、服务层、git 同步 |
| [`@codegraph/graph`](packages/graph/) | Graph DB driver 抽象、知识操作、Cypher 模板 |
| [`@codegraph/plugin-nlp`](packages/plugin-nlp/) | Embeddings、reranker、实体解析、会话/文档摄取 |
| [`@codegraph/mcp-server`](packages/mcp-server/) | 包含 4 个 persona 工具的 MCP 服务器 |
| [`@codegraph/api`](packages/api/) | 用于仪表盘的 Express REST API |
| [`@codegraph/cli`](packages/cli/) | 围绕核心服务的 CLI 包装器 |
| [`@codegraph/plugin-typescript`](packages/plugin-typescript/) | TS/JS/JSX tree-sitter 插件 |
| [`@codegraph/plugin-python`](packages/plugin-python/) | Python tree-sitter 插件 |
| [`@codegraph/plugin-go`](packages/plugin-go/) | Go tree-sitter 插件 |
| [`@codegraph/plugin-rust`](packages/plugin-rust/) | Rust tree-sitter 插件 |
| [`@codegraph/plugin-markdown`](packages/plugin-markdown/) | Markdown 解析器 |
| [`@codegraph/plugin-generic`](packages/plugin-generic/) | 用于其他语言的 Tree-sitter 备用方案 |
| [`@codegraph/plugin-common`](packages/plugin-common/) | 共享的提取工具（复杂度、AST 辅助函数） |
| [`@codegraph/plugin-languages`](packages/plugin-languages/) | 插件注册中心协调 |
| [`@codegraph/logger`](packages/logger/) | 结构化日志 + tracing 装饰器 |
| [`@codegraph/types`](packages/types/) | 共享的 TypeScript 类型定义 |
此外还包含 `apps/web`（Next.js 仪表盘，在 `localhost:3000` 提供 Graph Explorer 和 Operations 标签页）。
## 开发
```
pnpm install # Install dependencies
pnpm build # Build all packages
pnpm dev # Start dev mode
pnpm test # Run all tests
pnpm docker:db # Start FalkorDB via Docker
```
## 状态
正在积极开发中。于 2026-04-25 公开发布。目前尚未发布正式版本——请从源码安装。
## 许可证
MIT — 详见 [LICENSE](./LICENSE)。
标签：Claude Desktop, Cursor, FalkorDB, GNU通用公共许可证, Graph Database, LLM辅助编程, MCP服务器, Model Context Protocol, Node.js, pnpm, Reranker, Tree-sitter, TypeScript, 二进制发布, 代码分析, 代码库管理, 代码检索, 代码理解, 代码知识图谱, 代码索引, 代码解析, 凭证管理, 双时态知识图谱, 向量检索, 大模型工具, 威胁情报, 安全插件, 开发者工具, 开源工具, 搜索引擎, 搜索引擎查询, 源码分析, 自动化攻击, 语义化检索, 语义搜索, 请求拦截, 跨编码器, 重排序