Indexing pipeline
How uploads, notes, links, and MCP writes become searchable knowledge.
Stored source and asynchronous indexing
- API and MCP note writes use the same durable queue; file uploads also queue indexing. A successful write confirms source storage, not searchable completion.
- pending means queued, indexing means processing, ready means the last index completed, and failed includes indexing_error when processing recorded an error. Infrastructure failures before a worker starts can leave pending with no item-level error.
- Check indexing_status, indexed_at and chunks_stale after editing. Old search chunks can remain until the replacement index completes. Use get_knowledge with include_content: true for current UTF-8 file source up to 1 MiB; larger and binary files use downloads.
- Production keeps an indexing worker warm. Small text should normally finish in seconds to a few minutes, depending on queue and model latency. Hours-long pending Markdown needs investigation; retry counts alone do not prove a worker processed it.
- fpm controls video frames per minute. Zero disables frame extraction; it does not throttle notes or Markdown.
- For a failed item, inspect indexing_error. POST /v1/knowledge/{id}/reindex queues a retry with vault-write authorization. There is no separate MCP reindex tool. Repeatedly uploading the same file can create duplicates.
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.