CocoIndexとは｜AIエージェント向けインクリメンタル処理OSSの仕組み

LangChain や LlamaIndex で RAG／AIエージェントの MVP は組めたものの、ソース更新のたびにフルリインデックスが走り、コストとレイテンシが膨らむ──そうした課題を抱えるエンジニアは少なくありません。

「インクリメンタル処理」をうたう OSS として注目されているのが CocoIndex です。GitHub のスター数は 8,988（執筆時点）、Python と Rust で実装された Apache-2.0 ライセンスのオープンソースです。

ただし初見のエンジニアにとっては、「具体的に何をしてくれる OSS なのか」「LlamaIndex や Pathway とどう違うのか」「自社スタックに合うか」を一度に把握するのは容易ではありません。

本記事では、公式 README と公式ドキュメントを一次情報源として、CocoIndex の概念モデル・インクリメンタル処理の仕組み・主要機能・類似 OSS との違い・採用判断軸を整理します。本記事は公開情報にもとづく解説であり、動作検証の報告ではない点をあらかじめお断りします。

CocoIndexとは｜AIエージェント向けの「常時最新」データ基盤

CocoIndex は、AIエージェントや LLM アプリケーションが参照するコンテキストを常に最新の状態で提供するためのオープンソースフレームワークです。GitHub リポジトリの description には「Incremental engine for long horizon agents」と記載されており、長期的に動作するエージェント向けのインクリメンタル処理エンジンと位置付けられています（出典: cocoindex-io/cocoindex）。

公式 README によると、CocoIndex は「コードベース、議事録、メールボックス、Slack、PDF、動画」といった多様なソースを、AIエージェントが推論に使える「ライブで継続的にフレッシュなコンテキスト」へ変換する役割を担います。

なお CocoIndex は LangChain や LlamaIndex の代替ではありません。LangChain／LlamaIndex はクエリ層（プロンプト構築・リトリーバル・応答合成）を中心に抽象化していますが、CocoIndex はその下層の「インデックスを維持する基盤」に焦点を絞っており、両者は補完関係にあります。

コアコンセプト｜「Target = F(Source)」の宣言的データフロー

公式 README で示される中核モデルが「Target = F(Source)」です。React の宣言的 UI、スプレッドシート、データベースのマテリアライズドビューと同じ発想で、プログラマは「現在のソース状態に対し、ターゲットがどうあるべきか」を関数として宣言します。実際にどの行を更新・破棄するかはエンジンが差分計算で導き出すため、変更検知ジョブや stale データ掃除の運用コードを書く必要がなくなります。

CocoIndex のアーキテクチャは 5 つの抽象から構成されます。

特に Lineage と Incremental engine は、汎用 ETL フレームワークでは標準装備されないことが多い要素です。コアエンジンは Rust、Python API は PyO3 経由で公開されており、宣言は Python の表現力で書きつつホットパスは Rust で処理する構成です。公式サイト（cocoindex.io）の記載によれば、対応 Python は 3.10〜3.13、メタストアとして PostgreSQL が必要になります。

インクリメンタル処理の仕組み｜デルタ伝播とリネージュ

CocoIndex のインクリメンタル処理は、単に「変更検知して再計算する」だけではありません。公式 Quickstart（cocoindex.io/docs/getting_started/quickstart/）と README の記載によると、エンジンは以下の流れで差分を伝播させます。

1. ソースのどの部分（ファイル・レコード）が変わったかを特定する
2. その変更が join／lookup を跨いでターゲットのどの行に影響するかを追跡する
3. 影響行のみを再計算してターゲットを更新する
4. 有効でなくなった「stale 行」をリタイア（削除・無効化）する

「stale 行のリタイア」まで自動化される点が、メタデータ確認＋追加埋め込みで済ませるタイプのインクリメンタル更新と一線を画す部分です。ベクトルインデックスでは、削除済みソースに対応するエンベディングが残ると検索品質が劣化しますが、CocoIndex はこの問題を構造的に防ぐよう設計されています。

加えて CocoIndex は、ターゲットの各行が「ソースのどのバイト範囲」に由来するかをリネージュとして記録します。AIエージェント応答の出典トレースや、本番運用のトラブルシュートで強力に機能する仕組みです。リリースノート（出典: GitHub Releases）によると v1.0.3（2026-05-05）で @coco.fn(memo=True) による引数単位のメモ化対応が追加され、重い埋め込み計算や LLM 呼び出しを伴うフローでの不要な再実行を避けられます。

主要機能とユースケース

公式 README に記載された対応ソース・ターゲットを整理すると以下のとおりです。

ベクトルとグラフを併用するハイブリッド検索や、ストリームと DWH の両方へ書き出す構成も Targets を組み合わせるだけで宣言できます。代表的なユースケースとしては、コードのセマンティック検索、RAG 向けドキュメントインデックス、会話からのナレッジグラフ抽出、PDF 取り込み・埋め込み、ポッドキャスト書き起こし＋エンティティ抽出などが README に挙げられています。

公式 README には、ローカルファイルを読み込み PostgreSQL のベクトルテーブルへ投入する最小構成のフロー例が掲載されています。以下は README からの抜粋です（出典: cocoindex-io/cocoindex README）。

import cocoindex as coco
from cocoindex.connectors import localfs, postgres
from cocoindex.ops.text import RecursiveSplitter

@coco.fn(memo=True)
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()

@coco.fn(memo=True) でメモ化されたチャンク化＋埋め込み処理を coco.mount_each でディレクトリ内のファイルへ展開し、PostgreSQL テーブルにベクトルインデックス付きで宣言する構造が読み取れます。

類似 OSS との比較｜Pathway・LlamaIndex との違い

CocoIndex の採用検討で比較対象になりやすい OSS が、Pathway と LlamaIndex です。

Pathway は Differential Dataflow ベースのインクリメンタル計算エンジンを持つ汎用ストリーム ETL フレームワークで、バッチ／ストリーミング統合や遅延・順序外データのハンドリングが特徴です。ライセンスは BSL 1.1（4 年後 Apache-2.0 へ自動移行）で、商用条件の確認が必要です。CocoIndex は「AIエージェント向けコンテキスト維持に特化」しており、ベクトル／グラフコネクタとリネージュを標準装備する点が異なります。

LlamaIndex はドキュメントエージェント／OCR プラットフォームで、ライセンスは MIT、300 を超えるインテグレーションを抱え、RAG の組み立てやリランキング・応答合成の最適化に強みを持ちます。LlamaIndex のインクリメンタル更新はメタデータチェック＋追加埋め込みによる「フルリビルド回避」レベルが中心ですが、CocoIndex は join／lookup を跨ぐデルタ伝播と stale 行リタイアまでを中核に据えています。CocoIndex でインデックスを維持し、LlamaIndex／LangChain でクエリ層を構築する併用も自然な構成です。

採用判断軸｜どんなプロジェクトに向いているか

ここまでの整理をふまえ、CocoIndex の採用が向くケース・向かないケース・前提条件を切り分けます。

向いているプロジェクト

• 多種多様なソース（コード／議事録／PDF／Slack 等）を継続的にインデックスし続ける必要がある
• ベクトル DB ＋ グラフ DB の複合ターゲットを宣言的に運用したい
• フルリインデックスのコスト・レイテンシが事業上の制約になっている
• AIエージェント応答の出典トレース（リネージュ）が運用要件にある
• Python ＋ PostgreSQL のスタックを許容できる

向かないケース・代替候補

• ソース更新が稀で、定期バッチのフルリインデックスで十分間に合う
• 主目的が「クエリ最適化」「リランキング」「応答合成」（LlamaIndex／LangChain のほうが選択肢豊富）
• メタストアとして PostgreSQL を導入できない
• Python 以外（TypeScript／Go／Java）が中心スタックとなっている
• バッチとストリーミングを統合する汎用 ETL 基盤が欲しい（Pathway 等のほうが適合する可能性）

採用前の前提条件

• メタストア: PostgreSQL（コントロールプレーンが永続状態を保持するため）
• ランタイム: Python 3.10〜3.13
• ライセンス: Apache-2.0（商用利用・社内利用の制約は緩い）

最新の更新動向は GitHub Releases で追跡できます。

まとめと次のアクション

採用検討に進むと判断した場合の次のアクションは、公式 Quickstart の参照です。Quickstart では PDF を Markdown へ変換しベクトルインデックスを構築する例を題材に、pip install -U cocoindex docling でのインストール、.env の設定、main.py でのフロー定義、cocoindex update main.py での実行という流れが示されています。実装手順や非互換変更の有無は変動するため、着手前に必ず公式 Quickstart の最新版を確認してください。

CocoIndex は、AIエージェントや LLM アプリケーションが参照するコンテキストを「常時最新」に保つために、ソース→ターゲットの関係を宣言的に定義し、エンジンが差分のみを反映するインクリメンタル処理フレームワークです。採用検討を進める場合は、GitHub リポジトリで最新の README とリリースノートを確認したうえで、公式サイトの Examples と公式 Quickstart を起点に、自社のユースケースに対応するソース／ターゲットの組み合わせを試算するところから始めることをおすすめします。

画像指示

アイキャッチ推奨クエリ: incremental data pipeline AI agents programming