CocoIndex：为 AI Agent 打造的增量索引引擎

大多数 RAG 系统的问题是：数据会过时。每次代码变更、文档更新或者 Slack 新消息涌入，全量重新索引成本高、延迟大，结果是 AI Agent 的上下文很快就变旧了。

CocoIndex 试图解决这个问题。它的核心思路是：声明目标状态，引擎只同步变化的部分（Δ）。代码变更时只重新处理变更文件，Python 转换函数更新时只重新执行受影响的 pipeline，剩余部分保持不变。

Stars 8,192，Apache-2.0 License，2026-05-05 最新推送，支持 Python 3.10-3.13，核心使用 Rust。

1. 核心概念：Target = F(Source)

CocoIndex 的mental model 可以用 React 的状态管理来类比：

传统数据管道：你写一次性脚本处理数据，每次运行都重新处理全部数据。

CocoIndex：你声明目标状态 Target = F(Source)，引擎保证在源或函数变化时持续同步目标。类似于 React 组件的状态声明：当 Source 或 F 变化时，引擎自动重新计算目标，且只重新计算受影响的节点。

关键属性：

• 声明式：描述"要什么"而非"怎么做"
• 增量更新：源文件变更时只处理变化的部分（Δ detection）
• 代码变化感知：当转换函数 F 从 v1 改为 v2 时，只重新执行依赖该函数的节点
• 端到端血缘：每个目标 dot 都可以追溯到源字节

2. 核心场景：CocoIndex-code（MCP Server for AI 编程）

CocoIndex-code 是其旗舰级 MCP Server，专为 AI 编程 Agent 设计（Claude Code、Cursor 等）：

• AST 感知分块：理解代码结构，不只是按行切分
• 增量语义索引：只对变更文件重新 embedding
• 调用图和 Blast Radius 分析：理解代码变更会影响到哪些其他模块
• 语义搜索：按语义而非 grep 匹配搜索代码
• 全局代码库视图：快速发现重复代码和架构模式
• 70% 更少 tokens per turn：每次请求只传输必要的上下文
• 80-90% cache hits on re-index：相同的代码不被重复处理
• 亚秒级新鲜度：每次 commit 后立即可查

支持 Python、TypeScript、Rust、Go。

3. 快速上手

# 安装
pip install -U cocoindex

# 声明目标状态
import cocoindex as coco
from cocoindex.connectors import localfs, postgres
from cocoindex.ops.text import RecursiveSplitter

@coco.fn(memo=True)  # 按 hash(input)+hash(code) 缓存
async def index_file(file, table):
    for chunk in RecursiveSplitter().split(await file.read_text()):
        table.declare_row(text=chunk.text, embedding=embed(chunk.text))

@coco.fn
async def main(src):
    table = await postgres.mount_table_target(PG, table_name="docs")
    table.declare_vector_index(column="embedding")
    await coco.mount_each(index_file, localfs.walk_dir(src).items(), table)

coco.App(coco.AppConfig(name="docs"), main, src="./docs").update_blocking()

运行一次做全量回填，之后任何时候重新运行——只有变更的文件被重新 embedding。

4. 架构设计：Δ-only Processing

源变化检测

当源文件变更时（比如 b.md 编辑），CocoIndex 通过文件哈希追踪变化，只重新处理受影响的 target dots。

函数变化检测

当转换函数 F 从 v1 改为 v2 时，CocoIndex 通过代码哈希（hash of code）判断：只有输出依赖已变化函数的 target dots 才重新执行。这避免了"函数改了但跟它无关的 dots 也要重算"的问题。

向量搜索支持

内置向量索引支持，可对接 Pinecone、Weaviate、Chroma 等向量数据库。declare_vector_index(column="embedding") 即可声明。

数据血缘（Lineage）

每个目标 dot 都能追溯到源字节。这意味着你可以回答"这个搜索结果来自哪段代码/哪个版本"，对于调试和合规场景非常重要。

5. 连接器与目标

Sources（输入）

• localfs：本地文件系统，支持通配符递归
• postgres：PostgreSQL 数据库
• 更多 connectors 持续添加

Targets（输出）

• 向量数据库：Pinecone、Weaviate、Chroma 等
• 关系数据库：PostgreSQL（作为矩阵存储）
• 知识图谱：自定义图结构
• 自定义：Python 函数处理任意输出

Transformations（转换）

内置转换操作：

• RecursiveSplitter：文本递归分块（保留语义边界）
• 自定义 Python 函数

6. 使用场景

企业知识库持续同步

将 Confluence、Notion、Slack 等持续变化的文档源接入 CocoIndex，AI Agent 始终能搜到最新内容。

AI 编程 Agent 代码上下文

Claude Code 或 Cursor 接入 CocoIndex-code MCP server 后，AI 每次都能看到最新的代码库状态，且不浪费 context tokens。

生产环境 RAG

传统 RAG 系统的数据新鲜度维护成本高，CocoIndex 的增量特性让它成为生产级 RAG 的理想选择。

数据管道血缘追踪

每个 target dot 都可追溯到源字节，对于需要数据血缘追踪的合规场景非常有用。

7. 开发者工具

CocoIndex 提供 Claude Code Skill（skills/cocoindex/），帮助 AI coding agent 写出正确的 v1 版本代码。安装后，Agent 能理解 CocoIndex 的概念、API 和模式，降低使用门槛。

8. 局限性与注意事项

1. 核心依赖 Python 环境：虽然核心是 Rust，但声明式 API 和 connectors 都是 Python
2. 需要理解声明式模型：习惯了传统脚本式 ETL 的开发者需要适应声明式思维
3. 向量数据库需自备：不内置向量数据库服务，需要连接外部服务
4. v1 阶段：仍处于快速迭代期，生产环境使用前建议评估

9. 总结

CocoIndex 的增量索引机制解决了企业级 AI Agent 的核心痛点：数据新鲜度。通过将数据管道声明为 Target = F(Source) 并由引擎维护增量同步，它让 AI Agent 可以在任何规模下获得持续新鲜的数据。

对于需要处理持续变化数据源的企业 AI 应用，或者长时间运行的 AI coding agent，CocoIndex 提供了目前最完整的增量索引方案。

项目信息

• GitHub：cocoindex-io/cocoindex
• Stars：8,192
• 语言：Python（核心）+ Rust（核心引擎）
• License：Apache-2.0
• Python 版本：3.10-3.13
• 官网：cocoindex.io
• 文档：cocoindex.io/docs
• Discord：discord.gg/zpA9S2DR7s