CocoIndex – Incremental engine mã nguồn mở cho long-horizon AI agent

Tóm tắt nhanh:

• CocoIndex là một incremental engine khai báo (declarative) viết bằng Python, có lõi Rust, được thiết kế chuyên biệt cho long-horizon AI agent cần ngữ cảnh luôn tươi mới.
• Triết lý cốt lõi: Target = F(Source). Bạn chỉ khai báo trạng thái đích mong muốn, engine tự động đồng bộ và chỉ tái xử lý phần delta (thay đổi) thay vì rebuild toàn bộ pipeline.
• Lợi ích đo được: độ trễ dưới 1 giây từ khi nguồn thay đổi đến khi agent thấy ngữ cảnh mới, giảm 10 lần chi phí embedding/LLM ở quy mô lớn, và lineage end-to-end giúp truy vết mọi vector về đúng byte nguồn.
• Vượt trội hơn vector database thuần ở context dài hạn nhờ caching theo hash(input) + hash(code), retry/dead-letter queue cấp production, và xử lý song song mặc định.
• Cài đặt cực nhanh: pip install -U cocoindex trên Python 3.11–3.13, sẵn sàng pipeline RAG/Knowledge-Graph trong khoảng 5–10 phút.

Vì sao long-horizon AI agent cần một incremental engine?

Các AI agent hiện đại không còn chỉ trả lời một câu hỏi đơn lẻ. Chúng theo đuổi những mục tiêu kéo dài hàng giờ, hàng ngày hoặc hàng tuần – viết lại codebase, theo dõi cuộc họp, vận hành quy trình kinh doanh. Vấn đề nằm ở chỗ: ngữ cảnh của agent bị lệch ngay khi dữ liệu nguồn thay đổi. Nếu một file .md được sửa lúc 10 giờ sáng nhưng pipeline batch chỉ chạy lại lúc nửa đêm, thì suốt 14 tiếng đó agent đang đưa ra quyết định dựa trên dữ liệu cũ.

CocoIndex giải quyết đúng bài toán này. Đây là một framework Python mã nguồn mở (lõi Rust) biến codebase, meeting notes, inbox, Slack, PDF và video thành ngữ cảnh “always fresh” cho LLM app, với chi phí xử lý chỉ tính trên phần thay đổi. Theo mô tả chính thức tại kho lưu trữ GitHub của CocoIndex, triết lý của nó là “React for data engineering” – bạn khai báo mong muốn (declarative), engine lo phần còn lại.

Cơ chế incremental engine: Target = F(Source)

Trái tim của CocoIndex là một mental model duy nhất: bạn định nghĩa một hàm F (transformation) ánh xạ từ Source sang Target, rồi để engine duy trì sự đồng bộ vĩnh viễn giữa hai bên.

Engine theo dõi provenance theo từng dòng (per-row provenance). Khi:

• Source thay đổi: Chỉ những target row có liên quan đến file/byte đã sửa mới được tính lại.
• Code (hàm F) thay đổi: Engine so sánh hash(code) mới với phiên bản đã cache và chỉ chạy lại đúng những output phụ thuộc vào đoạn code đã thay đổi.

Nhờ memoization theo hash(input) + hash(code), tỉ lệ cache hit khi re-index thường đạt 80–90%, và một corpus 10.000 dòng chỉ phải tái xử lý phần 0,1% bị động vào.

Tại sao CocoIndex tối ưu hơn vector database truyền thống cho ngữ cảnh agent dài hạn?

Một vector database thuần (Pinecone, Weaviate, Qdrant) là một lớp lưu trữ tốt – nhưng nó không phải pipeline. Khi áp dụng cho long-horizon agent, ta nhanh chóng đụng tường:

• Không có cơ chế delta: Mỗi lần dữ liệu nguồn cập nhật, lập trình viên phải tự viết logic detect change, re-embed và upsert. Lặp đi lặp lại với hàng chục connector là cơn ác mộng vận hành.
• Không có lineage: Khi agent trả lời sai, gần như không thể truy ngược một vector về byte nguồn cụ thể nào để debug.
• Không có code-aware caching: Khi đổi model embedding hay logic chunking, bạn buộc phải reindex toàn bộ corpus, đốt tiền API.
• Thiếu khung production-grade: Retry, exponential back-off, dead-letter queue, xử lý song song – đều phải tự code.

CocoIndex đặt một control plane đứng trước vector store (pgvector, LanceDB, Qdrant…), đồng thời hỗ trợ relational DB, data warehouse, graph DB (Neo4j, Kuzu, FalkorDB), message queue và feature store. Vector DB vẫn được dùng – chỉ là CocoIndex biến nó từ “kho dữ liệu” thành “kho dữ liệu luôn tự đồng bộ với nguồn”.

Hướng dẫn cài đặt CocoIndex từng bước

Yêu cầu hệ thống:

• Python 3.11 đến 3.13
• macOS, Linux hoặc Windows
• (Tuỳ chọn) PostgreSQL nếu dùng pgvector làm target

Bước 1 – Cài đặt package qua pip, uv hoặc Poetry:

# Dùng pip (khuyến nghị cho người mới)
pip install -U cocoindex

# Hoặc với uv (nhanh hơn)
uv pip install -U cocoindex

# Hoặc với Poetry trong dự án có sẵn
poetry add cocoindex

Bước 2 – Cài thêm extras nếu cần embedding tích hợp sẵn:

pip install -U "cocoindex[embeddings]"

Bước 3 – Xác minh cài đặt:

cocoindex --version
python -c "import cocoindex; print(cocoindex.__version__)"

Bước 4 – Chuẩn bị Postgres (nếu dùng pgvector):

# Trên macOS với Homebrew
brew install postgresql@16 pgvector
brew services start postgresql@16

# Tạo database
createdb cocoindex
psql cocoindex -c "CREATE EXTENSION IF NOT EXISTS vector;"

Bước 5 – Cấu hình biến môi trường:

export COCOINDEX_DATABASE_URL="postgres://localhost/cocoindex"

Hướng dẫn sử dụng thực tế: từ khai báo flow đến truy vấn

Sau khi cài xong, hãy dựng một pipeline RAG đơn giản: đọc thư mục ./docs, chia nhỏ văn bản, embed và đẩy vào pgvector – đầy đủ tính năng incremental.

Khởi tạo file main.py:

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

PG = "postgres://localhost/cocoindex"

@coco.fn(memo=True)  # cache theo hash(input) + hash(code)
async def index_file(file, table):
    text = await file.read_text()
    for chunk in RecursiveSplitter().split(text):
        table.declare_row(
            text=chunk.text,
            embedding=embed(chunk.text),  # hàm embedding tự định nghĩa
        )

@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()

Chạy backfill lần đầu và mọi lần sau:

# Setup schema + chạy lần đầu để backfill
cocoindex update --setup main.py

# Các lần sau chỉ cần
cocoindex update main.py

Lần đầu sẽ embed toàn bộ tài liệu. Mọi lần chạy tiếp theo, chỉ những file đã sửa mới được re-embed – đây chính là điểm khác biệt so với pipeline thủ công viết bằng LangChain hoặc script ETL truyền thống.

Truy vấn để phục vụ AI agent:

import psycopg
from your_embedding_module import embed

def retrieve(query: str, k: int = 5):
    qv = embed(query)
    with psycopg.connect(PG) as conn:
        rows = conn.execute(
            """
            SELECT text, embedding <=> %s AS distance
            FROM docs
            ORDER BY distance ASC
            LIMIT %s;
            """,
            (qv, k),
        ).fetchall()
    return [r[0] for r in rows]

context = retrieve("How does the incremental engine work?")
# Đưa context này vào prompt của AI agent

Mở rộng cho hệ thống production

CocoIndex không dừng ở local file. Trong thư mục examples của repo GitHub, bạn sẽ tìm thấy 20+ starter sẵn dùng được cập nhật hàng tuần:

• Real-time code index: Walk git repo, AST-aware chunking, embed với sentence-transformers, upsert pgvector hoặc LanceDB – chính là engine đứng sau MCP server cho Claude Code và Cursor.
• PDF RAG index: Ingest từ local, S3 hoặc Google Drive, chunk recursive, embed, đẩy vào vector DB.
• HN trending topics: Pull thread Hacker News qua Algolia, dùng Gemini 2.5 Flash trích xuất topic có kiểu, ranking theo trọng số.
• Conversation knowledge graph: LLM trích xuất entity, decision, action item từ transcript và upsert Neo4j hoặc Kuzu.

Mọi pipeline đều thừa hưởng tám subsystem luôn bật của control plane: live caching, pipeline catalog, version tracking, lineage, task scheduling, metrics collection, failure management và continuously learning.

CocoIndex không phải là một vector database mới, cũng không phải một LangChain killer. Nó lấp vào khoảng trống giữa “dữ liệu nguồn liên tục thay đổi” và “AI agent cần ngữ cảnh tươi mới mọi lúc” – khoảng trống mà mọi đội ngũ xây long-horizon agent đều đang phải tự lấp bằng code keo dán. Với mô hình khai báo Target = F(Source), incremental theo delta, lineage end-to-end và lõi Rust production-grade, CocoIndex giúp bạn rút ngắn thời gian từ ý tưởng đến agent vận hành thực tế xuống còn vài phút thay vì vài tuần.

Nếu bạn đang xây dựng AI agent có vòng đời dài, xử lý dữ liệu doanh nghiệp đa dạng, hoặc đơn giản là chán cảnh viết lại pipeline ETL mỗi khi đổi model embedding, đây là thời điểm phù hợp để thử nghiệm.