Serialization

index.on(pool).save("index.safegraphs")
copy = DenseIndex.load_ram("index.safegraphs", executor=pool)  # A new, mutable index in host memory
view = DenseIndex.view_ram("index.safegraphs")  # Served in place, read-only

Loading creates a handle rather than filling one, its geometry read from the checkpoint’s own headers, and a cancelled or failed load creates none. The executor a load fans out over is its executor= keyword, and without one it reads on the calling thread. A view maps the file instead of copying it, so opening costs the headers alone, and every mutating verb on it raises ReadOnlyError. To learn a checkpoint’s shape without opening a shard, ask for its metadata, a DenseMetadata struct sequence whose fields are the geometry every empty constructor takes:

metadata = DenseIndex.metadata_read("index.safegraphs")
empty = DenseIndex.init_ram(
    metadata.dimensions, metadata.metric, metadata.quantization, connectivity=metadata.connectivity
)

Residency is never among those fields, because where the payload lives stays the caller’s choice.

save_buffer returns one monolith of every shard as a Monolith over the arena it is handed, and load_ram_buffer and metadata_read_buffer read one back from any buffer.