Indexing pipeline
How uploads, notes, links, and MCP writes become searchable knowledge.
What becomes knowledge
Every searchable object starts as a knowledge row in a vault. That includes uploaded files, inline notes, fetched links, API-created items, and agent writes through MCP.
The knowledge type is intentionally small: file, image, link, or note. Uploaded photos are file rows with an image MIME type; image rows are reserved for explicit image items and pipeline-generated children such as PDF pages or video frames.
- Vault membership and bearer scopes decide which rows a user, token, or agent can read.
- Stored files keep file metadata; notes and links carry their content inline.
- URL extraction can create one-hop linked knowledge items from links found in indexed text.
Extraction paths
The dispatcher routes each item by content type. Simple text, markdown, code, and note bodies can extract synchronously; heavier media runs through asynchronous jobs and reports progress through indexing status.
PDF and Office files use a routing step before OCR. Native PDF text is preferred when it is usable; otherwise the system routes to a fallback OCR path. Office documents are converted before using the same PDF routing model.
- Images use OCR and visual description paths so screenshots and photos can still contribute searchable text.
- Audio uses transcription; video combines transcription with selected frames routed through the image pipeline.
- Quota-dependent work is skipped with a clear status reason instead of exposing partial sidecar output.
Supported file formats
Uploads and connectors use the same capability catalog as the indexing router. A connector imports safe text formats by default; optional format selections can only add formats the pipeline actually supports.
Unsupported repository files remain in the connector's skipped-file report with their exact path and reason. Adding a format to the shared catalog makes it available to uploads, connector reconciliation, documentation, and indexing together.
- Text and source: .adoc, .asciidoc, .astro, .bash, .c, .cc, .cfg, .cjs, .clj, .cljs, .conf, .cpp, .cs, .css, .csv, .dart, .editorconfig, .edn, .env, .erl, .ex, .exs, .fish, .go, .gql, .gradle, .graphql, .groovy, .h, .hcl, .hh, .hpp, .hs, .htm, .html, .ini, .ipynb, .java, .jl, .js, .json, .json5, .jsonc, .jsx, .kt, .kts, .less, .log, .lua, .m, .markdown, .md, .mdx, .mjs, .ml, .mli, .mm, .org, .php, .pl, .pm, .prisma, .properties, .proto, .ps1, .py, .r, .rb, .rs, .rst, .sass, .scala, .scss, .sh, .sol, .sql, .svelte, .svg, .swift, .tex, .tf, .tfvars, .toml, .ts, .tsv, .tsx, .txt, .vue, .xml, .yaml, .yml, .zig, .zsh
- Documents: .doc, .docx, .odt, .pdf, .pptx, .xls, .xlsx
- Images: .bmp, .gif, .ico, .jpeg, .jpg, .png, .webp
- Audio: .aac, .flac, .m4a, .mp3, .ogg, .wav
- Video: .avi, .mkv, .mov, .mp4, .webm
- Supported extensionless files: .dockerignore, .editorconfig, .eslintrc, .gitattributes, .gitignore, .nvmrc, .prettierrc, authors, changelog, codeowners, contributing, dockerfile, gemfile, justfile, licence, license, makefile, notice, procfile, rakefile, readme
Index artifacts
Once text exists, the pipeline chunks it, generates embeddings, and stores those chunks for hybrid retrieval. It also creates document-level summaries so broad queries can match a whole document even when the best paragraph is not obvious.
Entity extraction, tags, temporal fields, and validity windows are stored with the row so search, graph views, filters, and chat citations all agree on the same metadata.
- Chunk-level hits provide the most specific citation surface.
- Summary embeddings provide document-level recall for broad or title-like queries.
- Temporal metadata supports recency ranking, validity filtering, and historical/forensic searches.
Status and failure handling
Indexing status tells consumers whether a row is pending, indexing, ready, or failed. Search and chat only rely on ready indexed content by default, which keeps unfinished extraction from surfacing as a weak answer.
Dispatch failures and quota skips are surfaced in processing details instead of leaving rows pending indefinitely. Reindex actions retry the pipeline with the current vault settings.
- Use the vault detail UI or API status endpoints to inspect failed or skipped work.
- Reindex is the right recovery path after a parser failure, quota change, or updated pipeline setting.
- Agent-safe removal uses forget_knowledge; permanent purge remains a human Trash action.
Reference contract
This guide explains behavior. Exact request and response fields live in the REST API reference, and the MCP tool parameter tables mirror the server-side tool schemas.