How do you persist a LlamaIndex index and reload it without re-embedding?

## The storage context is the real unit of persistence People think of a LlamaIndex index as "the vectors". It is actually an object over a `StorageContext` with several independent stores: - **docstore** — the `TextNode` objects themselves: text, metadata, relationships, and the hash of each source document. - **index store** — the index's own metadata: its type, its id, and for structured index types the structure (a tree's parent/child links, a keyword table's mapping). - **vector store** — the embeddings. - **graph store / property graph store** — used by graph index types. Persisting means serialising whichever of these are local. ## The default, all-local flow ``` index.storage_context.persist(persist_dir="./storage") ``` writes JSON files into that directory — `docstore.json`, `index_store.json`, and for the in-memory default store `default__vector_store.json`. Reloading is two steps, and the two-step shape is what candidates get wrong: ``` storage_context = StorageContext.from_defaults(persist_dir="./storage") index = load_index_from_storage(storage_context) ``` `from_defaults(persist_dir=...)` reconstitutes the stores from the files; `load_index_from_storage()` reads the index store to work out which index type to instantiate and hands you a live index object. No embedding model is called, which is the whole point: rebuilding with `from_documents()` would re-embed every node and re-bill you for data you already have. ## Multiple indexes in one directory A storage context can hold several indexes. Each index has an id, and if you never set one it is a random UUID. Call `index.set_index_id("faq")` before persisting, then load with `load_index_from_storage(storage_context, index_id="faq")`. With more than one index present and no id supplied, the load cannot decide and fails — an error people meet the first time they persist two indexes into the same folder. ## The external-vector-store case This is the part interviewers push on. When you built the index against a real vector store — wired in via `StorageContext.from_defaults(vector_store=...)` — the embeddings went to that system, not to your process. `persist()` then writes only the docstore and index store; there is nothing local to write for the vectors. Reloading with `load_index_from_storage()` against a bare `persist_dir` gives you an index whose vector store is the empty local default, and queries return nothing. The correct reattachment is: ``` index = VectorStoreIndex.from_vector_store(vector_store) ``` which constructs an index directly over the existing remote data with no local files at all. This works because most integrations set `stores_text=True`: they keep the node text alongside the vector, so retrieval can return whole nodes without consulting a docstore. That convenience has a consequence — with no docstore, the operations that need document hashes and node-to-document links, notably refresh and delete-by-document, have nothing to work from. If you want those, persist the docstore too and pass both the vector store and the persisted directory when constructing the storage context. ## Practical shape A typical service does: try to load; on failure, build and persist. Keep the embedding model identical across build and load — vectors are only comparable within the model that produced them, and reloading an index while a different `Settings.embed_model` is active silently degrades every query rather than raising. Treat the persist directory as a build artifact, versioned with the embedding model name, so swapping models forces a visible rebuild rather than a quiet mismatch.