Use Cases & Personas

Who indx is for, and the concrete jobs it does for them.

The premise is simple: most real knowledge does not live in a single file — it lives in the arrangement of files. If you’re new here, start with What is indx? or jump straight to the quickstart.

The four personas

indx is designed around four representative users. They differ in what they’re building and what constrains them, but they share one frustration: today’s tooling answers “what does this file say?” when they need to know “how does this body of knowledge fit together?”

Persona	Who they are	Primary need	Pain today
Maya — RAG / Agent Engineer	Builds retrieval and agent apps on LangChain / LlamaIndex.	Grounded, well-structured context with relationships — not a flat chunk soup.	Hand-wires parser + splitter + embedder + store; loses folder context; answers are shallow because cross-document links are gone.
Devin — Enterprise / Air-gapped ML Lead	Owns the document-AI platform at a bank, hospital, or government agency. Data cannot leave the network.	Fully local, auditable, reproducible ingestion across large on-prem document estates.	SaaS parsers and cloud LLMs are non-starters; existing OSS tools assume internet and discard structure needed for compliance and lineage.
Priya — OSS Developer / Integrator	Maintains internal handbooks, codebases, and tooling; contributes to OSS.	A composable, no-lock-in library she can extend with her own parser, store, or output.	Monolithic ingestion tools are hard to extend; swapping an embedder or store means rewriting the pipeline.
Dr. Chen — Researcher	Works with large archives of papers, datasets, and notes.	Turn a messy research archive into a navigable, citable knowledge graph.	Papers reference each other and share datasets, but tools index them in isolation; no portable artifact to share with collaborators.

The common thread

Every persona wants the map: the structure, relationships, and document-type semantics that file-level parsers throw away. indx keeps the map and hands it to the agent. It composes parsers like Docling rather than replacing them.

The use-case catalogue

Each use case ties back to one of the personas above.

Grounded RAG / agent retrieval

For Maya. Feed an agent a knowledge space instead of a vector blob.

In indx, every Chunk carries its source Document, its position, and links to its neighbors — so context travels with the text. Answers come back with source folder, document type, and continues / references edges attached, which means fewer hallucinations and traceable citations.

Folder lineage is preserved on every document, so an agent can filter and reason by location (“only contracts under /2024/acme”) instead of matching against an undifferentiated pile of text.

What you get: chunks that carry their source document, position, and neighbor links, so your agent can expand context and follow continues / references edges instead of retrieving orphaned fragments.

See Core objects for the Chunk and Relation models, and Inspect & query to try retrieval before wiring it into production.

Enterprise on-prem & air-gapped estates

For Devin. Point indx at a decade of SharePoint exports or a file server and turn legacy folders into a queryable knowledge base — without a single byte leaving the network.

The shipped default stack is cloud-backed and needs OPENAI_API_KEY: openai:gpt-5-mini for enrichment and openai:text-embedding-3-small for embeddings. The opt-in local profile runs fully local instead. Install it with pip install "indx[local]" to get:

• docling for parsing
• ollama:qwen2.5 for enrichment
• bge-m3 for embeddings
• qdrant (embedded/local mode) for the store and a .indx output

For a fully no-DB, air-gapped run, swap in the jsonl store (--store jsonl), which inlines vectors into the .indx archive so nothing needs to be installed or served.

The core also ships zero-dependency fallbacks: a plaintext parser, hash embedder, jsonl store, none VLM, and .indx + jsonl writers. Select them and a complete run works offline with no API key — for example, --parser plaintext --embedder hash --store jsonl --llm none.

Every run is reproducible, which matters for compliance. The chosen configuration — versions, models, and config — is recorded into the KnowledgeSpace manifest, so any space can be audited and re-created.

What you get: run the entire pipeline with a local parser, local LLM, and a no-DB output, so no document or embedding ever leaves the network.

The full offline path is documented in the local & air-gapped guide, with reproducibility details in the reproducibility guide.

Codebases & handbooks

For Priya. Repos, design docs, and runbooks have deep structure. A test file belongs to a module that belongs to a service, and an onboarding doc sits beside its siblings.

indx detects document types and derives sibling, parent, and continues relations across the tree. So “how do I onboard?” retrieves the onboarding doc and its neighbors rather than random matches.

Because structure becomes signal, an assistant built on the space understands the shape of your engineering knowledge instead of guessing at it.

What you get: indx detects document types and relationships across a handbook or codebase, so retrieval surfaces the right doc and its siblings, not random matches.

Research paper & data archives

For Dr. Chen. Mixed PDFs, notebooks, and datasets become one navigable space with citation relations intact.

The Relate stage derives two kinds of edge:

• references edges, so you can follow citations across the archive.
• duplicate-of edges, so you can dedupe versions of the same paper.

The result is a knowledge graph ready for literature agents and synthesis. Because it serializes to a portable archive, you can hand it directly to a collaborator.

The full RelationType set — sibling, parent, references, continues, duplicate-of — is documented in the data models reference and the Relate stage.

Portability — ship knowledge as a file

For everyone. A KnowledgeSpace serializes to a single, self-contained, versioned .indx archive.

Build it in CI, hand it to a teammate, or mount it in a serverless function. The whole knowledge estate travels and re-loads without re-processing — no need to repeat the work on the other end.

You can also inspect and query the same archive directly with the CLI, so you can sanity-check structure and retrieval before it ever reaches production.

In code this is symmetric and explicit:

from indx import KnowledgeSpace

space = KnowledgeSpace.load("./ai-ready/handbook.indx")
print(space.stats)
hits = space.search("data retention", k=5)

Learn more in the .indx archive reference and the SDK reference.

Vendor-free migration foundation

For Devin and Priya. Every major component is a typed, swappable slot: parser, LLM, VLM, embedder, store, and output. So the pipeline you write today survives the model you’ll use next year.

indx acts as a neutral intermediate layer. Build the knowledge space once, then emit it to JSONL, LangChain, LlamaIndex, or any supported vector store without re-deriving anything. Re-embed, re-store, or re-export with the same code.

That makes indx a migration foundation rather than another thing to migrate off of.

What you get: a neutral intermediate layer that outputs to LangChain / LlamaIndex / JSONL / any vector DB, so a platform lead locked into a vendor’s ingestion can migrate stacks without re-deriving their knowledge.

Not a database, not a runtime

indx writes to stores like Qdrant, pgvector, Chroma, LanceDB, and JSONL. It does not store or serve vectors at runtime, and it is not a hosted retrieval or agent runtime. It builds the portable knowledge space. Serving and orchestration stay downstream and stay yours.

See the output formats guide for the available writers and the bring-your-own-stack overview for how slots fit together.

Where to go next

• New to indx? Read What is indx?, then run the quickstart and build your first knowledge space.
• Need it fully offline? Follow the local & air-gapped guide.
• Picking your stack? See guides on choosing a parser, an embedder, and a store.
• Curious about the bigger picture? Read use-case-driven design principles, the roadmap, and the FAQ.