> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Memory Overview

> Long-term memory for AI agents: a profile per user, caller, or agent, written to with ingest and remember, read back with recall.

An agent that forgets everything between calls asks the same questions every time. Agent Memory gives it somewhere to keep what it learns: **a profile per user, caller, or agent**, written to as conversations happen and read back when the next one starts.

Hand over a finished session with [`ingest`](/docs/agent-memory/writing#ingest-a-session) and facts are extracted from it. Write down something you already know with [`remember`](/docs/agent-memory/writing#remember-a-fact). Ask a question with [`recall`](/docs/agent-memory/recall) and get back the facts that answer it, ranked.

## The Shape of It

The pieces, and nothing else to provision:

|               | What it is                                                                                                                                       |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Namespace** | An [isolation](/docs/agent-memory/isolation) boundary — a separate memory store per application or environment. You get one, `default`, today.   |
| **Profile**   | Who the memories are about — a customer, a caller, an agent. You choose the id: `caller:+13128675309`, `user_8891`, whatever you already key on. |
| **Source**    | What a profile stored — an ingested session or a remembered fact. Memories are extracted from it. [More](/docs/agent-memory/sources)             |
| **Memory**    | One fact. Written by extraction from a source, or verbatim by `remember`.                                                                        |

**Neither needs creating.** The first request that addresses `default` builds it, reads included, so a brand-new organization gets an empty list rather than a `404`. A profile appears the first time you write to it.

A request against a namespace other than `default` is a `404` — writing never brings it into being.

## What You Can Do

Every path below is relative to `https://api.telnyx.com/v2/ai/memory`.

| Endpoint                                                    | What it does                                                                                                           |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `POST /namespaces/{ns}/profiles/{id}/ingest`                | Store a session; facts are extracted from it                                                                           |
| `POST /namespaces/{ns}/profiles/{id}/remember`              | Store one fact exactly as written                                                                                      |
| `POST /namespaces/{ns}/profiles/{id}/recall`                | Ranked facts for a question                                                                                            |
| `GET /namespaces/{ns}/profiles/{id}/summary`                | The whole profile as one precomputed card, no query                                                                    |
| `GET /namespaces/{ns}/profiles`                             | Which profiles hold memories, and how many                                                                             |
| `GET /namespaces/{ns}/profiles/{id}/memories`               | Everything one profile holds, unranked                                                                                 |
| `GET /namespaces/{ns}/profiles/{id}/memories/{memory_id}`   | One memory, and what it came from — a `source_id` or `derived_from`                                                    |
| `GET /namespaces/{ns}/profiles/{id}/sources`                | What one profile stored: each session and remembered fact, no content. Add `?session_id=` to find one session's source |
| `GET /namespaces/{ns}/profiles/{id}/sources/{source_id}`    | One source, with its content as it was sent                                                                            |
| `DELETE /namespaces/{ns}/profiles/{id}/sources/{source_id}` | Forget one source and the memories derived from it                                                                     |
| `DELETE /namespaces/{ns}/profiles/{id}`                     | Forget everything held about one profile (takes no parameters). To forget one session, delete its source               |
| `GET`, `PATCH /namespaces/{ns}/settings`                    | How this namespace's summaries are written                                                                             |
| `GET /namespaces/{ns}/operations/{operation_id}`            | Whether a write has finished                                                                                           |

## Writes Are Asynchronous

Both write verbs answer `202 Accepted` with an `operation_id` rather than waiting. A write takes seconds — it is processed before a memory can be recalled — so the API hands you something to poll instead of holding the connection open.

`remember` skips extraction, but it is not meaningfully faster: the rest of the pipeline is what costs.

<Note>
  A memory is not recallable until its operation completes. If you write and immediately read, you will not see it yet — poll [the operation](/docs/agent-memory/writing#track-a-write) first.
</Note>

## Isolation

Memories are separated at three levels: your **organization** (the boundary between customers, taken from your API key), a **namespace** (a hard wall between your own applications or environments), and a **profile** (who each memory is about). The organization is the first segment of every identifier the service composes internally, so a profile only ever resolves inside your own organization — there is no request shape that reaches across it. One profile's memories are never returned for another.

See [Isolation](/docs/agent-memory/isolation) for when to use a namespace versus a profile-id convention.

## Related

* [Isolation](/docs/agent-memory/isolation) -- organization, namespace, and profile
* [Writing memories](/docs/agent-memory/writing) -- `ingest`, `remember`, and tracking the operation
* [Recalling memories](/docs/agent-memory/recall) -- asking questions, and reading a profile whole