> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/working-with-data/snapshots-and-persistence.md).

# Save & snapshots

Persist a collection to disk with save, take a point-in-time copy with snapshot, and reopen it with open\_collection.

`create_collection` builds a collection in memory; nothing touches disk until you call `save()`. This page covers the durability lifecycle: `save()` as the commit point, `snapshot()` for a point-in-time copy, and `open_collection` to reopen what you saved.

{% hint style="info" %}
`collections()` lists only saved collections (directories that contain a `collection.json`). An unsaved collection is invisible to it and cannot be reopened until you call `save()`.
{% endhint %}

## The persistence lifecycle

{% stepper %}
{% step %}

#### Create and populate in memory

`create_collection` returns a live collection but writes nothing to disk yet.

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

telys = Telys("./telys-data")
emb = AlgentaMultigramEmbedder()

col = telys.create_collection(
    "notes",
    dim=emb.profile.dimension,   # kernel-sourced dimension for this embedder
    partition_by="scope",
    embedder=emb,
)
col.add_texts(
    texts=["First note.", "Second note."],
    ids=["note-1", "note-2"],
    metadata=[{"scope": "user:42"}, {"scope": "user:42"}],
)

telys.collections()   # -> []  (nothing saved yet)
```

{% endstep %}

{% step %}

#### Save — the commit point

`save()` writes the `id_map.npy` sidecar first, then `collection.json` **last**. Because the JSON is written last, a reader never sees a half-written commit — it gets either the previous state or the new one. `save()` returns the collection's directory.

```python
path = col.save()
print(path)                # ./telys-data/notes

telys.collections()        # -> ['notes']  (now discoverable)
```

`collection.json` persists the durable metadata: `name`, `dim`, `dtype`, `key_name`, `filter_columns`, the `id_map` sidecar reference, `telys_version`, `default_target_recall`, `applied_tuner`, `lexical`, and the embedder profile.
{% endstep %}

{% step %}

#### Reopen with `open_collection`

Reopen a saved collection in a fresh process. If you registered a provider for its embedding space, the embedder re-attaches automatically; otherwise pass one so text operations keep working.

```python
telys = Telys("./telys-data")
col = telys.open_collection("notes", embedder=AlgentaMultigramEmbedder())
print(len(col))            # -> 2
```

{% endstep %}

{% step %}

#### Take a point-in-time copy with `snapshot`

`snapshot()` captures the current state as a point-in-time copy — useful before a risky bulk update or as a checkpoint.

```python
col.snapshot()
```

{% endstep %}
{% endstepper %}

## On-disk layout

A saved collection lives in its own directory under the engine path you passed to `Telys(...)`:

```
./telys-data/
|-- notes/
    |-- collection.json     # durable metadata — written last, the commit point
    |-- id_map.npy          # external-id to row sidecar
    |-- ...                 # runtime vector slab files
```

The engine path (`./telys-data`) is whatever you pass to `Telys(path)`. It is separate from `$TELYS_HOME` (default `~/.telys`), which holds credentials and the MCP / `telys mem` store. See [On-disk layout](https://docs.telys.ai/operations/on-disk-layout.md) for the full tree.

## Expected result

Before `save()`, `collections()` is empty and the directory does not exist. After `save()`, the collection is listed and reopens with the same rows:

```
[]
./telys-data/notes
['notes']
2
```

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Build the IVF index</strong></td><td>Switch a large saved collection to approximate search.</td><td><a href="https://docs.telys.ai/working-with-data/build-ivf-index.md">Build IVF index</a></td></tr><tr><td><strong>Delete &#x26; compact</strong></td><td>Reclaim disk before you save.</td><td><a href="https://docs.telys.ai/working-with-data/delete-and-compact.md">Delete &amp; compact</a></td></tr><tr><td><strong>On-disk layout</strong></td><td>Every file Telys writes and where.</td><td><a href="https://docs.telys.ai/operations/on-disk-layout.md">On-disk layout</a></td></tr></tbody></table>
