什么是 Graphicle？
Graphicle 是一个本地运行的 Rust 程序，将代码仓库图与面向编码代理的项目记忆结合起来。它会为文件、函数、类、调用和导入建立索引，同时记住文档、决策、操作流程和过去的代理会话。
当代理或开发者提出问题时，Graphicle 会返回带引用的摘录，并标明源文件和行范围。代码图和核心上下文工具无需 API 密钥或账户即可运行；除非你明确配置了需要发送数据的模型或连接器，否则 Graphicle 不会将数据发送到任何地方。
Graphicle 支持 Claude Code、Cursor、Codex、VS Code、Claude Desktop 以及其他 MCP 客户端。它提供命令行界面、MCP 服务器、浏览器应用和一个基于 SQLite 的单一数据存储。
主要功能
- 代码图：使用基于 tree-sitter 的解析器，探索文件、符号、调用、导入、路径和受影响的代码。
- 项目记忆：搜索 Markdown、PDF、Office 和 HTML 文档、已审阅的决策、操作流程以及捕获的代理会话。
- 带引用的上下文：在令牌预算内从代码和项目知识中检索相关摘录，无需调用模型。
- 代理集成：通过一条设置命令，使用 MCP 连接受支持的编码代理。
- 与代码关联的记忆：已审阅的记忆可以锚定到其所描述的函数，并会在相关代码发生变化时变为过时状态。
- 本地优先运行：数据存储在本地，端点默认监听回环地址，Graphicle 不使用遥测或账户。
- 自动同步：回答前会同步已更改的文件；Git 钩子则可以在提交、合并和检出后进行同步。
安装 Graphicle
Graphicle 目前支持 macOS 和 Linux。在 macOS 或安装了 Homebrew 的 Linux 系统上，最简单的安装方式是：
brew install graphicle-ai/tap/graphicle如果无法使用 Homebrew，请使用发布版安装程序：
curl -fsSL https://github.com/graphicle-ai/graphicle/releases/latest/download/install.sh | sh你也可以从 GitHub 发布页面下载适用于特定平台的归档文件。目前尚未提供原生 Windows 支持，不过 README 指出，Linux 安装可能可以在 WSL2 下运行，但尚未经过测试。
设置代码仓库
进入你希望代理理解的代码仓库，然后运行设置命令：
cd your-repo
graphicle setup设置过程会为代码仓库建立索引、构建代码图，并连接检测到的编码代理。根据你机器上已安装的客户端，它可以更新 Claude Code、Codex、Cursor、VS Code、Claude Desktop 及其他 MCP 客户端的 MCP 配置。
设置还会启用会话捕获，将 Claude Code 的搜索指向代码图，向 AGENTS.md 添加简短章节，并安装有助于保持项目更新的 Git 钩子。Graphicle 会列出它更改的每个文件，并在修改前创建备份。若要让设置过程在无交互提示的情况下运行，请使用：
graphicle setup --yes若要撤销集成更改，请运行：
graphicle disconnectdisconnect 命令会移除 setup 添加的内容，但不会删除代码仓库现有的 Graphify 输出目录。
从终端提问
设置完成后，使用 graphicle ask 搜索代码仓库：
graphicle ask "where is tax added to prices?"Graphicle 会返回包含文件名、行范围、符号和摘录的证据。结果可能如下所示：
Evidence for "where is tax added to prices?"
4 excerpts · 598 of 3,000 tokens
[1] shop/pricing.py:1-7 price_with_tax()
"""Prices and tax."""
TAX_RATE = 0.2
def price_with_tax(price):
"""A price with the sales tax added."""
return round(price * (1 + TAX_RATE), 2)未配置模型时，ask 会显示证据。若要让 Graphicle 生成文字回答，请配置受支持的模型提供商，例如 Anthropic、OpenAI 或 Ollama：
graphicle config set model anthropic此外也支持通过 Ollama 使用本地模型以及兼容 OpenAI 的服务器。有关模型设置，请参阅配置文档。
将 Graphicle 与代理结合使用
graphicle setup 连接 MCP 客户端后，请让你的编码代理使用 Graphicle 回答代码仓库相关问题。例如：
使用 Graphicle 查找失败请求在哪些地方会重试。
代理可以使用 Graphicle 的代码图和记忆工具，接收带引用的摘录，并将这些结果与自身的推理结合起来。Graphicle 提供一个包含代码图工具和记忆工具的 MCP 服务器。其图工具包括 query_graph、get_neighbors 和 shortest_path 等名称。
浏览代码图和项目记忆
要打开 Graphicle 的浏览器应用，请运行：
graphicle open该应用可以让你浏览代码图、源材料和项目记忆，也可以在其中审阅和批准待处理的记忆。
若要检查安装和集成的运行状况，请运行：
graphicle doctor当代理无法连接、同步似乎不完整，或你想验证已配置的环境时，可以使用 doctor。
探索依赖关系和受影响的代码
Graphicle 可以构建和查询仅包含代码的图。首先提取代码图：
graphicle graph extract . --code-only然后询问哪些代码依赖某个符号：
graphicle graph affected "retry()"graph 命令可以搜索代码库、解释符号、追踪路径，并导出交互式 HTML 图。--code-only 模式不需要模型。
Graphicle 还可以将项目文档中对代码的提及与其引用的定义关联起来。使用文档链接图命令列出这些关系：
graphicle call graph.doc_links无需答案模型即可检索上下文
context 命令可以从代码、文档、会话和已审核记忆中检索相关摘录。它不会调用模型：
graphicle context对于包含多个代码库的工作区，可以请求跨整个工作区的上下文：
graphicle context --workspace当一个代码库中的实现依赖另一个代码库中的文档或源代码时，Graphicle 就很有用。工作区 MCP 配置请参阅 MCP 文档。
了解同步与隐私
同步期间，Graphicle 遵循 .gitignore，并跳过环境文件、密钥和凭据。会话捕获会移除 <private>...</private> 标签范围内的内容，并对凭据进行脱敏。
在 macOS 上，主要的本地数据文件夹是 ~/Library/Application Support/Graphicle。在 Linux 上，则是 ~/.local/share/graphicle。通过 graphicle graph extract 创建的图会写入项目内的 .graphicle/。
应用、HTTP 端点和 MCP 端点默认监听 127.0.0.1。只有在请求需要网络的功能时才会访问网络，例如已配置的模型或连接器、将文档或图像发送给 LLM 的完整图提取、特定的 GitHub CLI 操作或更新源。
高级技巧
让答案有充分证据支撑
使用 Graphicle 提供的带引用摘录，根据准确的文件和行号核实代理的说法。这对于调试、理解不熟悉的代码库以及审查变更尤其有用。
审核建议的记忆
代理建议的记忆不会自动成为受信任的项目知识。请在应用中审核后再批准。锚定到代码符号的记忆可能会在相关代码更改后过时，而同一文件其他位置的编辑通常不会影响其时效性。
使用 Git 钩子保持上下文最新
保留设置期间安装的钩子，以保持代码库同步。它们会在提交、合并和检出后同步，而 Graphicle 也会在回答前同步发生变更的文件。
调整代码库限制
默认情况下，一个项目最多可包含 100,000 个文本文件和 1 GiB 文本。如果你使用的是更大的代码库，可以在配置中提高这些限制。对于超大文件，系统可能只进行部分分析，或将其保留为可搜索文本，而不是停止同步。
连接其他 MCP 客户端
对于 Graphicle 无法自动检测的客户端，请添加 MCP 指南中所述的简短 JSON MCP 配置。同一个 MCP 服务器同时提供图和记忆功能。
结语
Graphicle 为代码代理提供了一个本地、可搜索的代码库结构和项目知识视图。安装后运行 graphicle setup，然后使用 ask、context、open 和 graph，通过引用来调查代码。只有在需要生成答案时才配置模型；图、同步、MCP 服务器、会话捕获和应用都可以在没有模型的情况下运行。