Storage API

Purpose and Scope

The Storage API page is the entrypoint for the storage contracts that let LlamaIndex applications keep data, index structures, embeddings, graph state, and conversation history outside a single in-memory run. In a retrieval application, storage is not one interchangeable bucket. Different runtime layers need different persistence semantics: documents and nodes must be addressable, index metadata must be recoverable, vector records must support similarity lookup, graph stores must represent relationships, and chat stores must preserve messages for stateful conversations. The official API reference reflects that split by publishing separate pages for document stores, index stores, key-value stores, vector stores, graph stores, and chat stores.

Sources: docs/api_reference/api_reference/storage/docstore/index.md, docs/api_reference/api_reference/storage/index_store/index.md, docs/api_reference/api_reference/storage/kvstore/index.md, docs/api_reference/api_reference/storage/vector_store/index.md, docs/api_reference/api_reference/storage/graph_stores/index.md, docs/api_reference/api_reference/storage/chat_store/index.md

Use this page when you are choosing which storage surface to implement, configure, or inspect. A vector database integration usually belongs to the vector store contract, while a persistence layer for raw nodes belongs to the docstore contract. A custom cache-like persistence backend belongs closer to the key-value store contract, and an agent or chat application that needs durable turns should start from the chat store contract. Keeping those boundaries clear helps avoid coupling application behavior to one backend package and makes it easier to swap local, hosted, or integration-provided storage implementations later.

Relevant Source Files

docs/api_reference/api_reference/storage/docstore/index.md — generated API reference entrypoint for llama_index.core.storage.docstore.types, the document-store type surface.
docs/api_reference/api_reference/storage/index_store/index.md — generated API reference entrypoint for llama_index.core.storage.index_store.types and the KVIndexStore member in llama_index.core.storage.index_store.
docs/api_reference/api_reference/storage/kvstore/index.md — generated API reference entrypoint for llama_index.core.storage.kvstore.types, the generic key-value storage contract family.
docs/api_reference/api_reference/storage/vector_store/index.md — generated API reference entrypoint for llama_index.core.vector_stores.types, the vector-store type surface used by vector retrieval and vector index integrations.
docs/api_reference/api_reference/storage/graph_stores/index.md — generated API reference entrypoint for llama_index.core.graph_stores.types, explicitly listing GraphStore, PropertyGraphStore, DEFAULT_PERSIST_DIR, and DEFAULT_PERSIST_FNAME.
docs/api_reference/api_reference/storage/chat_store/index.md — generated API reference entrypoint for llama_index.core.storage.chat_store.base, explicitly listing BaseChatStore.

Storage Families and Responsibilities

The docstore API is the storage family for document-like objects and parsed node data. In LlamaIndex terminology, documents are the loaded source objects and nodes are the smaller units that indexing and retrieval operate on. The docstore reference is generated from llama_index.core.storage.docstore.types, which signals that this page is primarily about the public type contract rather than one concrete backend. Readers implementing ingestion or persistence should treat the docstore as the place where node identity, stored content, and metadata are preserved for later indexing, retrieval, and response construction.

Sources: docs/api_reference/api_reference/storage/docstore/index.md

The index store API is separate because an index needs to remember more than the documents it was built from. It must preserve index-specific structures, mappings, and metadata that allow an index object to be reconstructed or reused. The reference includes llama_index.core.storage.index_store.types and also lists KVIndexStore from llama_index.core.storage.index_store, making the key-value-backed index store a named public implementation in this API family. When a user persists an index, the index store is the layer that should carry the index’s structural state rather than the raw source text alone.

Sources: docs/api_reference/api_reference/storage/index_store/index.md

The key-value store API is the lower-level persistence surface. The reference points to llama_index.core.storage.kvstore.types, which frames it as a type contract that other storage implementations can build on. A key-value abstraction is useful when higher-level stores need a simple namespace, key, and value model without committing to a full vector database or graph database. The presence of KVIndexStore in the index-store reference also shows how this lower-level family can support a more specialized storage role while remaining hidden behind the index-store contract used by application code.

Sources: docs/api_reference/api_reference/storage/kvstore/index.md, docs/api_reference/api_reference/storage/index_store/index.md

Vector stores and graph stores cover the storage backends that are most visible in retrieval-augmented generation. The vector-store reference is generated from llama_index.core.vector_stores.types, the type surface for backends that store embeddings and support vector-oriented retrieval behavior. The graph-store reference is generated from llama_index.core.graph_stores.types and explicitly lists GraphStore, PropertyGraphStore, DEFAULT_PERSIST_DIR, and DEFAULT_PERSIST_FNAME. That split matters because vector retrieval and graph retrieval make different assumptions about stored state: vectors organize semantic proximity, while graph stores preserve entities, properties, and relationships.

Sources: docs/api_reference/api_reference/storage/vector_store/index.md, docs/api_reference/api_reference/storage/graph_stores/index.md

The chat store API covers durable conversational state. The reference is generated from llama_index.core.storage.chat_store.base and lists BaseChatStore, which identifies the base contract for chat history storage. This family is especially important for chat engines, agents, and deployed applications where a conversation spans multiple turns or sessions. Unlike a docstore, a chat store is not primarily about source documents for retrieval. It is about message history and state continuity, so application code can resume or contextualize a conversation without rebuilding all runtime state from scratch.

Sources: docs/api_reference/api_reference/storage/chat_store/index.md

Compact API Reference

Storage family	API reference module	Public names explicitly shown in the docs entrypoint	Primary role
Docstore	`llama_index.core.storage.docstore.types`	Type surface generated from the module	Store documents, nodes, content, and metadata used by indexing and retrieval.
Index store	`llama_index.core.storage.index_store.types`; `llama_index.core.storage.index_store`	`KVIndexStore`	Store index structures and metadata needed to persist or reload indexes.
KV store	`llama_index.core.storage.kvstore.types`	Type surface generated from the module	Provide generic key-value persistence used directly or under higher-level stores.
Vector store	`llama_index.core.vector_stores.types`	Type surface generated from the module	Store vector records and expose the vector-store contract used by vector retrieval.
Graph stores	`llama_index.core.graph_stores.types`	`GraphStore`, `PropertyGraphStore`, `DEFAULT_PERSIST_DIR`, `DEFAULT_PERSIST_FNAME`	Store graph and property-graph state for graph-based retrieval workflows.
Chat store	`llama_index.core.storage.chat_store.base`	`BaseChatStore`	Store chat messages and conversation history for chat engines and agents.

This compact table is intentionally organized by public contract rather than by backend package. The API reference pages expose type modules and base classes, while concrete integrations can live elsewhere in the repository or in installable integration packages. When reading a backend implementation, first identify which row it satisfies. A vector database package should conform to the vector-store type surface; a graph database package should conform to GraphStore or PropertyGraphStore; and a custom conversation persistence backend should conform to BaseChatStore. That sequence keeps implementation details subordinate to the public interface expected by LlamaIndex runtime components.

System-to-Code Mapping

A typical LlamaIndex system moves through several storage concerns over its lifetime. During ingestion, source material is loaded and transformed into documents or nodes, which need a docstore-like contract if they are persisted. During indexing, the index object creates internal structures that belong in the index store. If the index uses embeddings, vector records are written through the vector-store contract. If the application builds graph-based context, graph state is written through the graph-store contract. If the same application exposes a chat interface, user and assistant messages are stored through the chat-store contract rather than being mixed into retrieval storage.

Sources: docs/api_reference/api_reference/storage/docstore/index.md, docs/api_reference/api_reference/storage/index_store/index.md, docs/api_reference/api_reference/storage/vector_store/index.md, docs/api_reference/api_reference/storage/graph_stores/index.md, docs/api_reference/api_reference/storage/chat_store/index.md

This mapping is useful when debugging persistence problems. If an index reloads but retrieved text is missing, inspect the document and node persistence path before blaming the vector store. If vector search returns results but an index object cannot be reconstructed, inspect the index-store path. If a chat application forgets prior turns while retrieval still works, the issue likely belongs to the chat-store configuration. The API reference layout gives maintainers a practical checklist: locate the storage family, inspect the corresponding type contract, then inspect the concrete backend implementation or configuration used by the application.

Implementation Details and Boundaries

The graph-store API entrypoint is the most explicit about individual exported names. It lists both GraphStore and PropertyGraphStore, which indicates that graph storage has a general graph contract and a property-graph-specific contract in the public reference. It also lists DEFAULT_PERSIST_DIR and DEFAULT_PERSIST_FNAME, which are persistence-related constants exposed by the graph-store types module. Readers working on graph RAG should pay attention to that API boundary because graph persistence often includes both topology and node or edge properties, and those concerns differ from plain document persistence or vector similarity search.

Sources: docs/api_reference/api_reference/storage/graph_stores/index.md

The index-store entrypoint is also notable because it documents both the type module and a concrete KVIndexStore member. That does not mean every index store must be key-value based, but it does identify a public implementation that connects the specialized index-store role to the generic key-value storage family. In practice, this is the kind of layering users should expect throughout the storage subsystem: high-level application components depend on specialized contracts, while implementations may reuse lower-level persistence abstractions. The API reference helps readers see those layers without treating all storage as a single global database.

Sources: docs/api_reference/api_reference/storage/index_store/index.md, docs/api_reference/api_reference/storage/kvstore/index.md

The chat-store entrypoint is intentionally narrow in the supplied reference snippet: it exposes BaseChatStore from the chat-store base module. That narrowness is a design signal for readers building chat or agent systems. Chat persistence should be integrated through the base chat-store contract rather than by storing serialized conversations in a docstore or vector store. Retrieval memory and conversational memory can cooperate in an application, but their storage contracts serve different reader tasks. Keeping chat history in the chat-store layer makes deployed chat engines and agent runtimes easier to reason about, test, and replace.

Sources: docs/api_reference/api_reference/storage/chat_store/index.md

How to Use This Reference

Start with the runtime feature you are implementing, then open the corresponding API reference page. For persistence of parsed source material, begin with the docstore reference. For persisted index structure, begin with the index-store reference and note whether KVIndexStore is sufficient. For backend-neutral persistence utilities, inspect the key-value store types. For semantic retrieval backends, use the vector-store types. For graph RAG and property-graph workflows, use the graph-store types. For stateful chat, use BaseChatStore. This workflow prevents a common mistake: selecting a storage backend by product name before confirming which LlamaIndex contract the runtime component actually expects.

For implementation work, treat these reference pages as the contract layer and pair them with the relevant concept page. If you are building a retrieval application, read the vector-store and index-store APIs together with the vector indexing and persistence pages. If you are building graph RAG, read the graph-store API with the property graph RAG page. If you are deploying a conversational interface, read the chat-store API with the chat engines and sessions pages. The next step is to choose the storage family first, then choose or implement a backend that satisfies that family’s public type surface.

Ask a question...