> 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

`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`, the applied tuner, 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](/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="/pages/vAtnT9NtTA0el7skR3vX">/pages/vAtnT9NtTA0el7skR3vX</a></td></tr><tr><td><strong>Delete &#x26; compact</strong></td><td>Reclaim disk before you save.</td><td><a href="/pages/RllSb4oFIVsEKxs8s4a3">/pages/RllSb4oFIVsEKxs8s4a3</a></td></tr><tr><td><strong>On-disk layout</strong></td><td>Every file Telys writes and where.</td><td><a href="/pages/2zslEGbkkXRBUP6ppFSD">/pages/2zslEGbkkXRBUP6ppFSD</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/working-with-data/snapshots-and-persistence.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.