codebase-synapse

🧠 Codebase Synapse

让你的 AI Agent 深入理解整个代码库。

一个 MCP 服务，可将代码库索引为本地知识图谱，并提供 52 个 AI 工具——语义搜索、调用图遍历、Git 考古、影响范围分析等。

支持 Claude Code · Cursor · Windsurf · Zed · 任意 MCP 客户端

问题

AI 编码 Agent（Claude、Cursor 等）功能强大，但可用上下文有限。它们只能看到你打开或提供给它们的文件。询问调用链、架构模式或影响范围，它们往往只能猜测。

Codebase Synapse 解决了这个问题。它会将整个代码库索引为存储在 SQLite 中的本地知识图谱，让 AI Agent 基于结构分析给出可靠答案，而不是产生幻觉。

工作原理

graph LR
    A["📁 Your Codebase"] -->|Tree-sitter| B["🧩 Parser"]
    B -->|Symbols & Edges| C["🕸️ Knowledge Graph"]
    C -->|SQLite| D["💾 Local DB"]
    D -->|52 MCP Tools| E["🤖 AI Agent"]
    
    style A fill:#1a1b26,stroke:#7aa2f7,color:#c0caf5
    style B fill:#1a1b26,stroke:#bb9af7,color:#c0caf5
    style C fill:#1a1b26,stroke:#9ece6a,color:#c0caf5
    style D fill:#1a1b26,stroke:#e0af68,color:#c0caf5
    style E fill:#1a1b26,stroke:#f7768e,color:#c0caf5

⚡ 快速开始

1. 为项目建立索引（CLI，Zoekt 风格）

codebase-synapse index /path/to/your/repo

索引通过独立的 CLI 命令运行，并写入 ~/.codebase-synapse/codebase.db。首次建立索引耗时较长；再次运行时只会重新索引有更改的文件。MCP 服务不会建立索引，只会读取预先构建的索引。

2. 启动 MCP 服务

npx codebase-synapse

就是这么简单。无需 Docker，无需设置数据库，也无需云服务。服务通过 stdio 启动，并向 MCP 客户端提供预先构建的索引。

配置客户端

{
  "mcpServers": {
    "codebase-synapse": {
      "command": "npx",
      "args": ["-y", "codebase-synapse"]
    }
  }
}

{
  "mcpServers": {
    "codebase-synapse": {
      "command": "npx",
      "args": ["-y", "codebase-synapse"]
    }
  }
}

npx -y codebase-synapse

✨ 功能

🔍 搜索与发现

🕸️ 知识图谱

🏗️ 架构

🔬 Git 考古分析

🧠 记忆与上下文

🛡️ 代码库防护

额外附送：codebase-guard 是 Claude Code 的一个 PreToolUse 钩子，会在 Agent 先运行 impact_analysis 之前，阻止其写入高影响力文件。

它使用知识图谱中的 PageRank 分数和影响范围数据来识别架构枢纽。再也不会意外修改核心文件。

🔧 技术详情

支持的语言

Rust · Python · TypeScript · JavaScript · Go · Java · C# · PHP · C · C++

架构

src/
├── parser/       # Tree-sitter parsing & entity extraction
├── graph/        # Knowledge graph, PageRank, Leiden clustering
├── indexer/      # Repository indexing pipeline
├── search/       # BM25 full-text + vector cosine + hybrid RRF
├── embedding/    # Candle-based local embeddings (feature-gated)
├── memory/       # Persistent & session memory stores
├── mcp/          # MCP protocol transport + 52 tool handlers
├── git/          # Git archaeology, intent classification, hotspots
├── context/      # Budgeted context preparation for AI
├── cypher/       # Nom-based Cypher parser → SQL CTE planner
├── similarity/   # MinHash + LSH structural similarity
├── semantic/     # Multi-signal scoring (tokens, directory, AST)
└── cli/          # Interactive TUI installer + artifact export/import

🤝 参与贡献

欢迎贡献！本项目使用标准的 Rust 工具链：

# Run tests
cargo test

# Lint
cargo clippy -- -D warnings

# Format
cargo fmt --all

📄 许可证

Apache-2.0