How to persist and load an index in LlamaIndex

A LlamaIndex index held only in memory disappears when its Python process exits. Persisting the storage context keeps the indexed nodes, vectors, and index metadata on disk so another process can resume retrieval without ingesting the source documents again.

The local SimpleVectorStore path is selected with persist_dir. Calling index.storage_context.persist() writes the stores there, while StorageContext.from_defaults() reconstructs them for load_index_from_storage().

Index construction and later retrieval must use compatible embedding models. The local smoke test uses MockEmbedding to isolate the persistence mechanism without an API key; use the same production embedding model and settings on both sides of an application restart.

1. Install LlamaIndex core in the active Python environment.

   $ python3 -m pip install --upgrade llama-index-core

   The active virtual environment should be the one used by the indexing and retrieval processes.
   Related: How to install LlamaIndex with pip

2. Create build_index.py with one document and a deterministic test embedding.

   build_index.py

   from llama_index.core import Document, VectorStoreIndex
   from llama_index.core.embeddings import MockEmbedding
    
   documents = [
       Document(
           text=(
               "Billing support runbook: refund ticket 7421 belongs to Maya. "
               "Escalate refund answers to the docs-review queue."
           )
       )
   ]
   embed_model = MockEmbedding(embed_dim=8)

   MockEmbedding verifies storage and reload behavior, not semantic ranking. Application indexing and retrieval require the same production embedding model.
   Related: How to set an embedding model in LlamaIndex

3. Append index construction and persistence to build_index.py.

   index = VectorStoreIndex.from_documents(
       documents,
       embed_model=embed_model,
   )
   index.storage_context.persist(persist_dir="support-index-storage")

   Persisting writes store files into support-index-storage. A new smoke-test directory prevents an existing index from being overwritten.

4. Run build_index.py to write the local storage context.

   $ python3 build_index.py

5. List the persisted store files in support-index-storage.

   $ ls support-index-storage
   default__vector_store.json
   docstore.json
   graph_store.json
   image__vector_store.json
   index_store.json

   The exact filenames can vary by configured stores, but the directory must contain the document, index, and vector-store data required by the selected storage context.

6. Create load_index.py for a saved-document query through the reconstructed index.

   load_index.py

   from llama_index.core import StorageContext, load_index_from_storage
   from llama_index.core.embeddings import MockEmbedding
    
   embed_model = MockEmbedding(embed_dim=8)
   storage_context = StorageContext.from_defaults(
       persist_dir="support-index-storage"
   )
   index = load_index_from_storage(
       storage_context,
       embed_model=embed_model,
   )
   retriever = index.as_retriever(similarity_top_k=1)
   result = retriever.retrieve("Which runbook covers refund ticket 7421?")[0]
    
   print(result.node.get_content(metadata_mode="none"))

7. Run load_index.py in a new Python process to confirm retrieval from the persisted index.

   $ python3 load_index.py
   Billing support runbook: refund ticket 7421 belongs to Maya. Escalate refund answers to the docs-review queue.