用途
Codebase Context 旨在解决编程智能体不理解代码库的问题。智能体能读取文件，但仍需自行发现仓库结构、团队遵循的模式以及值得复制的范例。该工具通过代码搜索、团队模式、强范例和项目记忆，为智能体提供本地视图，使其消耗更少 token、花费更少时间，并产出更熟悉项目风格的代码。
主要能力
- 语义代码搜索：search_codebase 按任务对文件和符号排序，而不是返回无结构的大段内容。智能体可先请求紧凑结果，再读取所需代码。
- 团队模式与范例：get_team_patterns 展示仓库中采用的方法，并指向代表性文件。2.2.0 版本包含 Angular、React、Next.js 的专用分析器，其他技术栈使用通用分析器；NestJS 支持属于更新的源码候选版本。
- 项目记忆：remember 可存储约定、决策、易错点或过往失败；get_memory 在后续会话中检索相关条目，即使智能体或编辑器更换也可使用。
- 本地索引：扫描项目、构建关键词索引，并创建本地语义嵌入（用于按含义匹配代码，而不仅靠精确词）。
- 仓库理解：智能体可请求包含结构、模式和代表性文件的紧凑代码库地图。
- 多仓库路由：一个 stdio 服务器可跨多个仓库路由，在工具调用中提供 project 参数以选择目标仓库；某次成功选择会成为该进程中后续调用的默认值。
使用方式
通过 Model Context Protocol (MCP) 以本地方式运行。默认连接为 stdio：客户端在需要时启动服务器。HTTP 是依赖客户端支持的高级选项。
在 AI 客户端中需运行对应命令注册。要求 Node.js 22 或更高版本。命令使用已发布的 npm 2.2.0 包，配置中无需项目文件夹（该包存在交互式 init 的注册缺陷，请使用文档给出的命令）。注册后在新会话中向智能体提出类似提示：
Use Codebase Context to find [feature] in this repository. Pass this repository's absolute path as project when checking get_indexing_status and searching. Wait for indexing if needed, read codebase://context, then search_codebase and open a returned source file. Show me the relevant files.
初始索引可能需要下载本地模型。Codex Desktop 需在项目内创建或合并 .codex/config.toml。其他客户端使用各自的设置命令。
也可从终端使用：在项目根目录运行命令，首次索引因扫描项目和创建本地嵌入可能耗时较长，之后可检查地图并搜索所需代码。
适用场景
- 希望减少智能体探索代码库时的 token 消耗。
- 团队希望智能体遵循既有模式并使用代表性范例。
- 需要跨会话保留项目约定、决策与易错点。
- 在本地隐私优先的前提下进行语义代码检索。
- 跨多个仓库工作时按需选择项目。
限制
- 本地语义索引比纯文本索引开销更大，尤其在全新检出和仅用 CPU 的机器上。
- 检索指标仅描述预期文件覆盖率、文件精度与峰值私有内存，不代表补丁正确性或端到端编码质量。
- 配对 token 观察仅覆盖两个固定调研任务，记录的是观察到的智能体行为，不是通用的 token 或时间保证。
- 各客户端的设置检查级别不同，详细指南区分了书面配置、客户端识别配置、本地连接及仅对照官方文档检查的说明。
- 2.2.0 包含 Angular、React、Next.js 专用分析器；NestJS 支持在更新的源码候选中；其他项目使用通用分析器及该技术栈可用的语言解析器。
- 默认每个项目可搜索块上限为 5000，较大仓库可在 .codebase-context/config.json 中提高。
- 当没有默认或明确的客户端根目录时，智能体必须在工具调用中指明仓库；stdio 路由检查未证明并发 HTTP 客户端隔离。
- 云嵌入为可选；若选择云提供商，代码块会发送给该提供商以创建搜索索引。Codebase Context 不控制 AI 客户端自身向模型提供商发送搜索或文件内容的连接。若提交并推送 .codebase-context/memory.json，项目记忆会随仓库传播。生成的索引应加入 .gitignore。
- 许可证为 Elastic-2.0。
