aoci-code

给 AI 编码代理一份 Git 管理的代码地图，改代码前先读全局

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署开发框架 🍴 复刻 228 🐛 待处理 15 👀 关注 8

访问官网 ↗ GitHub ↗

GitHub 星标 ★ 1899

维护状态活跃

是否开源开源

定价模式 🏷️完全免费开源免费，Go语言实现，需自行部署

项目预览

项目数据

分类开发框架

开发团队aoci-spec

官网地址https://www.aoci.ai

GitHubhttps://github.com/aoci-spec/aoci-code

定价模式🏷️完全免费

价格说明开源免费，Go语言实现，需自行部署

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议NOASSERTION

主要语言Go

技术栈/模型agent-memory,agents-md,ai-coding,ai-context,claude-code,code-indexing,code-intelligence,codex,coding-agent,context-engineering,cursor,database-schema,golang,llm,local-first,mcp,mcp-server,model-context-protocol,opencode,repo-map

GitHub 星标★ 1899

上线时间2026-08-08 00:00:00

代码更新2026-11-11

仓库体积9.3 MB

本站数据更新2026-11-12

维护状态活跃

收录时间2026-09-28

浏览次数17

项目介绍

aoci-code 是一个用 Go 编写的本地优先 MCP 服务器与命令行工具，核心目标是给编码智能体（Claude Code、Codex、Cursor、opencode 等）提供一份持久化、受 Git 版本管理的代码库与数据库结构地图。它把整个代码仓库的索引、符号关系、数据库 schema 等知识统一沉淀为一个可治理的仓库索引，让 AI 在动手改代码之前先读取这份上下文，从而获得长期记忆与代码智能，而不是每次从零扫描文件。项目通过 MCP 协议与主流编码代理集成，同时提供 CLI 方便人工查询和维护。它解决的是 AI 编程中上下文易丢失、跨会话记忆断裂、大仓库理解成本高的问题，让代理在修改前先建立全局认知，减少盲改和重复探索。适合需要让 AI 长期参与同一代码库开发的团队与个人。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-09-28 · 当前星标 ★ 1899

技术标签

agent-memory agents-md ai-coding claude-code code-intelligence

使用教程

ℹ 本教程由 AI 依据该项目 README 整理，个别步骤可能需要按你的环境微调。

难度：进阶约 15 分钟部署方式：本地安装 8 步

环境要求

Git（scan 的文件清单来自 Git，仓库需可被 Git 识别）
Go 工具链（仅从源码编译时需要，产物为 CGO-free 单二进制）
支持 MCP 的编码代理宿主：Claude Code、Codex、Cursor、opencode 等
可选数据库：PostgreSQL、MySQL，或受限的 openGauss 6.0.5

安装与启动步骤

1获取 aoci 可执行文件

从 GitHub Releases 下载对应操作系统与 CPU 架构的发布包并按 Release 页说明校验；没有匹配包时再从官方仓库源码编译。
```
mkdir -p build
CGO_ENABLED=0 go build -o build/aoci ./cmd/aoci
```
2放到固定绝对路径

把 aoci（Windows 为 aoci.exe）放在一个稳定的绝对路径下，之后 MCP 配置都引用该路径，移动会导致连接失效。
```
./build/aoci --version
```
3初始化并集成 MCP

init 会写入 aoci.txt、aoci.meta.txt、aoci.code.txt、AGENTS.md 等认知资产，并为当前宿主写 MCP 配置；Cursor 等不写项目配置的宿主会返回需你手动粘贴的配置。
```
aoci init
```
4运行 scan

scan 以 Git 作为文件清单来源，因此不能把 init 写入的认知资产加进忽略列表，被忽略的文件会被静默跳过导致索引建不出来。
```
aoci scan
```
5重启编码代理

索引通过 AOCI 的 MCP 工具写入，而执行 init 的会话还没加载刚写好的 MCP 服务器，必须重启；能动态加载 MCP 的宿主可能不需要。
6让代理构建索引

重启后先让代理确认 MCP 已连接，再要求它为本项目构建 AOCI 索引；如需数据库认知，按文档声明数据源并在宿主环境提供连接串变量。
7打开 AOCI 面板

代理会在后台执行 ui 命令并给出面板链接，用于查看索引与执行其他面板操作。
```
aoci ui --detach --json
```
8运行基础诊断

capabilities 查看能力，doctor 做环境体检；另一个快速验证是仓库内 examples/minimal-repository 的示例走查。
```
"$AOCI" --repo . capabilities
"$AOCI" --repo . doctor
```

关键配置

配置项	必填	说明	示例
`MCP 配置中的 command`	是	宿主启动 AOCI MCP 服务器所用的 aoci 绝对路径	`/your/path/aoci`
`overview_delivery.chunk_tokens`	否	Overview 交付的唯一分块大小设置，默认 7000，有效范围 4000-24000	`7000`
`数据库连接串环境变量`	否	数据库索引所需连接串由宿主环境提供，AOCI 本身不存凭据	`postgres://user:password@localhost:5432/mydb`

如何确认成功

运行 aoci doctor 与 capabilities，确认 mcp_service_version 和 runtime_repository_root 与预期一致。

常见问题

Q：为什么 init 之后必须重启代理？

A：索引由 AOCI 的 MCP 工具写入，而执行 init 的那个会话还没加载刚写入的 MCP 服务器；能动态加载 MCP 的宿主可能无需重启。

Q：scan 之后索引建不起来怎么办？

A：检查 aoci.txt、aoci.meta.txt、aoci.code.txt、AGENTS.md 是否被 .gitignore 或 .git/info/exclude 忽略；被忽略的资产会被静默跳过，索引无法构建。

Q：怎么确认宿主连的是哪个 aoci？

A：看 aoci_overview 或 aoci_maintain 响应中的 cognition_receipt.mcp_service_version 与 runtime_repository_root，再和宿主配置里的 command 路径核对。

Q：能接管多大的代码库？

A：实际限制是索引大小而非行数，约 50 万行以内可一次性建索引，已有 70 万行商业系统配合约 30 万 token 索引在做开发。

Q：支持哪些数据库？

A：PostgreSQL 和 MySQL，另外支持受限的 openGauss 6.0.5；连接串通过宿主环境变量提供。

注意事项

升级或回滚后要重新核对运行中的 MCP 进程，仅替换磁盘上的二进制不会改变已运行的进程。
AOCI 不存储数据库凭据，连接串环境变量由宿主环境提供。
索引与代码同仓存放并由 Git 版本管理，换人、换代理或开新会话只需读一次索引即可接续。
上下文被压缩后，代理需要按规则重新加载并重新完成一次完整 Overview 交付。

核心亮点

本地优先 + Git 版本化，索引随仓库演进可追溯、可回滚
通过 MCP 协议统一接入 Claude Code、Codex、Cursor、opencode 等主流代理
同时覆盖代码结构与数据库 schema，提供跨会话的长期记忆与代码智能

不足之处

项目早期，生态与集成案例有限
索引维护与多代理协同的实际效果需更多验证

适用场景

让 Claude Code 在大型仓库中改代码前先读取完整索引，减少盲改
团队用 Git 管理 AI 的代码知识库，随代码提交同步更新上下文
为 Cursor/Codex 提供跨会话的长期项目记忆，避免重复解释架构

替代项目

Sourcegraph、Continue、Aider

上一篇：AnyJev

下一篇：openharness