> 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/quickstarts/quickstart-agent-memory.md).

# Agent memory

Give an AI agent durable, on-device memory — partition per user and session with scope\_key, store conversation turns, and recall them on demand.

LLM agents forget everything between calls. Telys gives them durable, on-device memory: store what the user says, then recall the relevant pieces before the next reply. This page builds that loop in a few lines of Python, keeping each user and session isolated with `scope_key`.

{% hint style="info" %}
This assumes Telys is installed and you are signed in (`pipx install telys` then `telys login`). New to Telys? Start with the [Quickstart: your first collection](https://docs.telys.ai/quickstarts/quickstart-first-collection.md). The examples need the signed runtime and native kernel, both installed by `telys login`.
{% endhint %}

## Isolate memory with scope keys

A collection's `partition_by` field is its physical partition key. Give each user+session its own partition by putting a composed key in that field. `scope_key` joins its parts into one stable string (with a `\x1f` separator), so `scope_key("alice", "session-42")` and `scope_key("bob", "session-42")` never collide.

```python
from telys import scope_key

print(repr(scope_key("alice", "session-42")))
```

**Expected output:**

```
'alice\x1fsession-42'
```

{% hint style="warning" %}
`partition_by` is a single physical key, not a composite. If you pass a list or tuple, only element `[0]` is used. Compose multiple parts into one string with `scope_key(...)`. See [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md).
{% endhint %}

{% stepper %}
{% step %}

#### Create the memory collection

Partition by `scope` — the field that holds each `scope_key` value.

```python
from telys import Telys, Eq, scope_key
from telys.embedding import AlgentaMultigramEmbedder

t = Telys("./agent-memory")
emb = AlgentaMultigramEmbedder()

memory = t.create_collection(
    "chat",
    dim=emb.profile.dimension,
    partition_by="scope",
    embedder=emb,
)
```

{% endstep %}

{% step %}

#### Wrap remember and recall

Two helpers are all an agent needs. `remember` uses `upsert_texts`, so re-running a turn replaces it instead of raising `KeyError`. `recall` scopes the search to one partition with `where=Eq("scope", scope)`, so a user only ever reads their own memory.

```python
def remember(scope, turn_id, text, role="turn"):
    memory.upsert_texts(
        [text],
        ids=[f"{scope}:{turn_id}"],
        metadata=[{"scope": scope, "role": role}],
    )

def recall(scope, query, k=3):
    hits = memory.search_text(
        query,
        top_k=k,
        where=Eq("scope", scope),
    )
    return hits["ids"]
```

Prefixing each id with its `scope` keeps ids unique across users in one collection.
{% endstep %}

{% step %}

#### Store turns, then recall

Store a few turns for one user+session, persist, then ask a question that should surface the relevant memory.

```python
# one user, one session -> one partition
scope = scope_key("alice", "session-42")

for turn_id, text in [
    ("t1", "I prefer metric units."),
    ("t2", "I'm planning a trip to Kyoto in October."),
    ("t3", "My budget for the trip is 2000 dollars."),
]:
    remember(scope, turn_id, text)

memory.save()

# later, before the agent answers, recall the relevant memory
print(recall(scope, "how much can I spend on the trip?"))
```

**Expected result:**

```
['alice\x1fsession-42:t3', 'alice\x1fsession-42:t2', 'alice\x1fsession-42:t1']
```

The budget turn (`t3`) ranks first, the trip turn (`t2`) next. Feed those recalled strings into the model's prompt as context for the reply.
{% endstep %}

{% step %}

#### Update a fact

When the user changes their mind, upsert the same id to replace the stored fact in place. `upsert_texts` inserts or replaces; `save()` commits it.

```python
remember(scope, "t1", "I now prefer imperial units.")  # replaces t1
memory.save()

print(recall(scope, "which units do I like?", k=1))
```

**Expected result:**

```
['alice\x1fsession-42:t1']
```

Recall the same id and you get the updated fact. Because every write and read is scoped, `scope_key("bob", "session-42")` sees an empty memory — one agent's users never leak into another's.
{% endstep %}
{% endstepper %}

{% hint style="success" %}
Prefer no Python? The MCP path is the zero-code alternative: run `telys mcp install` and your MCP client (Claude Desktop, Cursor) gets the full Telys memory surface — 19 tools, from `telys_add` and `telys_search` to `telys_update`, `telys_delete`, and maintenance — over a shared memory directory. The agent stores, updates, and recalls memory itself. See [MCP overview](https://docs.telys.ai/mcp/overview.md).
{% endhint %}

## 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>MCP overview</strong></td><td>Give an agent memory tools with no application code at all.</td><td><a href="https://docs.telys.ai/mcp/overview.md">Overview</a></td></tr><tr><td><strong>Agent long-term memory</strong></td><td>The full recipe: retention, summarization, and multi-session recall.</td><td><a href="https://docs.telys.ai/recipes/agent-long-term-memory.md">Agent long-term memory</a></td></tr><tr><td><strong>Partitions &#x26; scope keys</strong></td><td>How partitioning and scope_key isolate and speed up recall.</td><td><a href="https://docs.telys.ai/understand-telys/partitions-scope-key.md">Partitions &amp; scopes</a></td></tr><tr><td><strong>Update records</strong></td><td>upsert_texts vs update_texts, and when to use each.</td><td><a href="https://docs.telys.ai/working-with-data/update-records.md">Update records</a></td></tr></tbody></table>
