Persistence
Purpose and Scope
Persistence in LlamaIndex is the part of a RAG application that lets indexed knowledge survive beyond one Python process. A prototype can ingest documents, create embeddings, and answer a question entirely in memory, but production systems usually need the generated state to be reusable by later queries, workers, deployments, or chat sessions. The supplied storage guide frames vector stores as containers for embedding vectors of ingested document chunks, and sometimes the chunks themselves. That makes vector-store persistence central because it preserves the expensive work of chunking and embedding instead of repeating it on every startup.
Sources: docs/src/content/docs/framework/module_guides/storing/vector_stores.md
The persistence model is best understood as a set of cooperating storage surfaces rather than one database choice. A vector store keeps the semantic representation used for nearest-neighbor retrieval. An index such as VectorStoreIndex organizes documents or nodes around that storage surface so applications can query it. Retrievers read from the index and vector store to produce relevant nodes, while memory modules can also use vector search to recall prior conversation context. Graph-store APIs add another durable shape for applications that maintain relationship-oriented knowledge rather than only embedding neighborhoods.
Sources: docs/api_reference/api_reference/indices/vector.md, docs/api_reference/api_reference/retrievers/vector.md, docs/api_reference/api_reference/memory/vector_memory.md, docs/api_reference/api_reference/storage/graph_stores/index.md
Relevant Source Files
- docs/src/content/docs/framework/community/integrations/vector_stores.md - Lists the two integration roles for vector stores: using a vector store as an index backend and loading data from a vector store like a connector.
- docs/src/content/docs/framework/module_guides/storing/vector_stores.md - Defines vector stores as holders of embedding vectors for ingested chunks, documents the simple in-memory store, and summarizes feature support across providers.
- docs/api_reference/api_reference/indices/vector.md - Publishes the API reference entry for VectorStoreIndex, the main index class tied to vector-store persistence.
- docs/api_reference/api_reference/memory/vector_memory.md - Publishes the vector memory API reference module, showing that vector-backed persistence is also relevant to conversational recall.
- docs/api_reference/api_reference/retrievers/vector.md - Publishes the vector retriever API members that query persisted vector-index state.
- docs/api_reference/api_reference/storage/graph_stores/index.md - Publishes graph-store type APIs and default persistence constants for graph storage.
Storage Roles and Data Flow
A typical persistent RAG flow begins after data loading, when the application has documents or nodes ready to index. The official indexing explanation describes VectorStoreIndex as the common index that splits documents into nodes and creates vector embeddings for each node. Once embeddings exist, the storage decision determines whether those vectors remain only in memory or are committed to a backend that can be reused. The storing guide explicitly calls the default simple vector store useful for quick experimentation and notes that it can be persisted to disk and loaded back later.
Sources: docs/src/content/docs/framework/module_guides/storing/vector_stores.md, docs/api_reference/api_reference/indices/vector.md
This separation matters operationally. Index construction is the write path: documents become chunks, chunks become embeddings, and the index records enough structure for later lookup. Retrieval is the read path: VectorIndexRetriever or VectorIndexAutoRetriever can use that vector-index state to find semantically similar content for a query. If a vector store also stores document chunks, the retrieval result may be more self-contained. If it stores only vectors or identifiers, the application must ensure the associated text and metadata remain available through the rest of its storage configuration.
Sources: docs/api_reference/api_reference/retrievers/vector.md, docs/src/content/docs/framework/module_guides/storing/vector_stores.md
Vector Store Persistence Choices
LlamaIndex offers many vector-store integrations, and the community integration guide names two distinct ways they participate in persistence. First, a vector store can be used directly as the storage backend for VectorStoreIndex, meaning the vector database is not just an external search service but part of the index implementation. Second, LlamaIndex can load data from vector stores in the same broad family as data connectors, allowing existing vectorized collections to feed other LlamaIndex structures. Those two roles help distinguish persistent index state from source data ingestion.
Sources: docs/src/content/docs/framework/community/integrations/vector_stores.md
The module guide also shows why choosing a backend is not only a hosting decision. Its feature table compares providers by type, metadata filtering, hybrid search, delete support, document storage, and async support. These capabilities affect how safe and flexible persistence will be after initial ingestion. Delete support is important when source documents change or retention policies require removal. Metadata filtering is important when one persistent collection serves multiple tenants, categories, or time ranges. Hybrid search matters when applications combine semantic similarity with keyword behavior for recall-sensitive workloads.
Sources: docs/src/content/docs/framework/module_guides/storing/vector_stores.md
For local development, the simple in-memory vector store gives a low-friction path because it is the default and can be written to disk with a persist call, then loaded from a persisted path. That path is useful for tests, tutorials, and small applications where a separate database would distract from the indexing model. For production, the integration list points to cloud and self-hosted systems such as Azure AI Search, Chroma, Elasticsearch, FAISS, Milvus, MongoDB Atlas, Cassandra, and other providers. The right backend depends on deployment constraints and required feature support.
Sources: docs/src/content/docs/framework/module_guides/storing/vector_stores.md, docs/src/content/docs/framework/community/integrations/vector_stores.md
API Components
| Component | Persistence role | Source |
|---|---|---|
| VectorStoreIndex | Index API entry point for building and querying over vector-store-backed indexed data. | docs/api_reference/api_reference/indices/vector.md |
| VectorIndexRetriever | Retriever API member for reading relevant nodes from a vector index. | docs/api_reference/api_reference/retrievers/vector.md |
| VectorIndexAutoRetriever | Retriever API member for automated vector-index retrieval behavior. | docs/api_reference/api_reference/retrievers/vector.md |
| vector_memory | Memory API module for vector-backed conversational recall. | docs/api_reference/api_reference/memory/vector_memory.md |
| GraphStore | Graph storage type API for graph-oriented persistence. | docs/api_reference/api_reference/storage/graph_stores/index.md |
| PropertyGraphStore | Property-graph storage type API for structured graph persistence. | docs/api_reference/api_reference/storage/graph_stores/index.md |
| DEFAULT_PERSIST_DIR | Default graph-store persistence directory constant exposed in the graph-store API reference. | docs/api_reference/api_reference/storage/graph_stores/index.md |
| DEFAULT_PERSIST_FNAME | Default graph-store persistence filename constant exposed in the graph-store API reference. | docs/api_reference/api_reference/storage/graph_stores/index.md |
The compact API map shows that persistence is visible both in user-facing guides and generated reference pages. VectorStoreIndex is the entry point most readers encounter first, because it connects indexing to the vector-store backend. The vector retrievers are the read-side counterparts that make persisted embeddings useful at query time. The vector memory module extends the same idea into conversational systems, where recalled prior context can be retrieved semantically. GraphStore and PropertyGraphStore indicate a parallel persistence family for graph-shaped state, with default constants documenting expected persisted graph-store locations.
Sources: docs/api_reference/api_reference/indices/vector.md, docs/api_reference/api_reference/retrievers/vector.md, docs/api_reference/api_reference/memory/vector_memory.md, docs/api_reference/api_reference/storage/graph_stores/index.md
Practical Workflow
When building a new application, start with the default simple vector store until the document model, chunking strategy, and retrieval quality are understood. Persisting that store to disk is enough to prove that the indexing output can be reused between runs. Once the application needs collaboration, deployment, larger collections, metadata filtering, deletion, async behavior, or external operational tooling, move the same VectorStoreIndex-centered design to an integration backend. The provider table should be read as an implementation checklist rather than a ranking, because different workloads value different capabilities.
Sources: docs/src/content/docs/framework/module_guides/storing/vector_stores.md, docs/src/content/docs/framework/community/integrations/vector_stores.md
Also decide where non-vector state belongs before committing to a production layout. If the vector store does not store full document chunks, maintain a durable document or node source that can reconstruct retrieved content and metadata. If the application uses graph RAG, evaluate GraphStore or PropertyGraphStore alongside vector persistence rather than treating graph data as an afterthought. If the application has chat or agent behavior, consider whether vector memory should persist conversational facts separately from the main knowledge-base index, so user memory and corpus retrieval can evolve independently.
Sources: docs/api_reference/api_reference/memory/vector_memory.md, docs/api_reference/api_reference/storage/graph_stores/index.md, docs/src/content/docs/framework/module_guides/storing/vector_stores.md
Next Steps
After this page, read the Vector Store Indexing page to understand how documents become embeddings and how VectorStoreIndex participates in retrieval. Then use the Vector Store Integrations page to compare provider-specific packages and capabilities before selecting a backend. If your application retrieves from graph-shaped knowledge, continue to Property Graph RAG and the storage API pages. For conversational systems, pair this page with Sessions and Chat Engines so persistent memory, chat stores, and vector-backed recall are designed together instead of bolted on after the first deployment.