CocoIndex boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

The target is CocoIndex's shipped incremental data-processing and context-indexing system, including its Python and Rust interfaces, state engine, connectors, operations, authoring guidance, example applications and their retrieval consumers. The intended use of this analysis is to explain how source material becomes retained, maintained and subsequently retrieved context. It is not an analysis of an enclosing autonomous agent. Classification is memory/knowledge/context-engineering system, with a whole-system boundary: indexing and maintenance are central, but shipped query programs and pipeline drivers remain inside the boundary rather than being dismissed as external API callers. SRC-1: pyproject.toml, examples/text_embedding/main.py, examples/entire_session_search/main.py, rust/sdk/cocoindex/src/app.rs.

The package states its indexing responsibility directly:

description = "With CocoIndex, users declare the transformation, CocoIndex creates & maintains an index, and keeps the derived index up to date based on source update, with minimal computation and changes." --- pyproject.toml

The in-scope classification does not imply that every pipeline uses a generative model. The shipped text-embedding application creates embeddings, declares rows in PostgreSQL and later reads those retained rows through a query path. The session-search application similarly indexes checkpoint files and retrieves session content. These are concrete context-serving uses, not solely an inference from marketing. SRC-1: examples/text_embedding/main.py, examples/entire_session_search/main.py.

async def query_once( pool: asyncpg.Pool, embedder: SentenceTransformerEmbedder, query: str, *, top_k: int = TOP_K, ) -> None: query_vec = await embedder.embed(query) --- examples/text_embedding/main.py

Entry points and state-loop coverage

Initial inspection traced these material responsibilities at the frozen revision:

• Start and maintain: the Python package installs cocoindex.cli:cli; the CLI's update command loads an application and invokes app.update, including live and full-reprocessing modes. Python App.update constructs the root processor and calls the core binding. The Rust SDK separately calls the same core application engine, so it is included rather than treated as a third-party host. SRC-1: pyproject.toml, python/cocoindex/cli.py, python/cocoindex/_internal/app.py, rust/sdk/cocoindex/src/app.rs.
• Produce and admit: the text example walks Markdown sources, mounts file processors, splits text, embeds chunks and declares target rows. LocalFS exposes snapshot and live directory walking. The core admission module supplies per-app inflight tokens and parent-to-child loans. SRC-1: examples/text_embedding/main.py, python/cocoindex/connectors/localfs/_source.py, rust/core/src/engine/admission.rs.
• Retain and reload: core component memo lookup restores prior memoization and may revalidate states before reuse. Submit-session code writes function memo records, ownership and user state. The storage documentation identifies LMDB as the internal store; this is separate from the external stores holding indexed content. SRC-1: rust/core/src/engine/component.rs, rust/core/src/state_store/submit_session.rs, docs/src/content/docs/advanced_topics/internal_storage.mdx.
• Apply and retire: the PostgreSQL row handler separates upserts and deletes; core application drop drains live components, deletes the root and clears per-app stored state. CLI reset and drop are shipped maintenance controls, not outside operators invented for this analysis. SRC-1: python/cocoindex/connectors/postgres/_target.py, rust/core/src/engine/app.rs, python/cocoindex/cli.py.
• Consume: text-embedding and session-search query programs embed queries, select retained content by vector distance and display results. Their query functions are included even though they use database clients directly instead of a CocoIndex retrieval API. SRC-1: examples/text_embedding/main.py, examples/entire_session_search/main.py.
• Guide and evaluate: the public skill supplies pipeline-writing and maintenance patterns; repository agent instructions describe contributor checks. Component-memo test source specifies repeated-update and deletion expectations. The state-store benchmark describes cold, warm and drop phases, not answer-quality evaluation. These are design and evaluation artifacts, not evidence that the checks passed in this run. SRC-1: skills/cocoindex/SKILL.md, AGENTS.md, python/tests/core/test_component_memo.py, benchmarks/state_store/README.md.

A minimal implementation anchor for retained-state reuse is:

let memo = match use_or_invalidate_component_memoization(comp_ctx, memo_fp).await {
    Ok(memo) => memo,
    Err(err) => {
        error!("component memoization restore failed: {err:?}");
        None
    }
};

--- rust/core/src/engine/component.rs

The shipped instruction layer makes its maintenance contract explicit:

By default, app.update() runs in catch-up mode: it scans all sources, processes what changed since the last run (memoized components are skipped), syncs target states, and returns. Each call still has to scan sources to discover changes. --- skills/cocoindex/SKILL.md

Top-level coverage

Every top-level tracked entry is classified below. Included means part of the functional evidence boundary, not that every file has been audited. The inspection column distinguishes direct initial reads, bounded code inspection and tree inventory. Unread material remains available at the same commit for later jobs; it is not an access gap. Whole-system here covers the shipped state loop and its supporting surfaces, not an exhaustive implementation verification.

Dependencies, exclusions and evidence limits

External source systems, databases, object stores, model providers, model weights and dependency implementations are outside this single-repository pin. Their shipped adapters and example call sites remain included. Thus the boundary supports source-grounded descriptions of calls and requested effects, not independent claims about provider accuracy, database guarantees or deployment availability. SRC-1: pyproject.toml, python/cocoindex/connectors/postgres/_target.py, python/cocoindex/ops/litellm.py, examples/text_embedding/main.py.

The separately linked CocoIndex-code product, external websites, hosted documentation revisions and enterprise deployments are not acquired sources. This prevents conclusions about that product's MCP/tool loop, real agent adoption of retrieved context, hosted behavior and enterprise-scale performance. The README links and claims do not freeze their implementation. SRC-1: README.md.

No source-access failure was encountered: HEAD matched the acquired full commit and the working tree was clean. Available but uninspected files are distinguished above from deliberate exclusions. No target code, tests, examples or provider calls were executed. No observed-run trace or causal experiment is supplied. The overall tier is code-grounded: executable source supports the boundary, while documentation and skills supply declared intent. Source-only tests and benchmarks cannot establish observed reliability, latency, retrieval quality or causal benefit.

The applicability cutoff is 2026-10-15, the supplied run date, limited to repository revision 1639793b3602408a9cb220728fb30e306d433473. It is not a claim about later releases or the state of external services on that date.

Source register