# Telnyx Agent Tools: Agent Memory (Beta) — Full Documentation
> Complete page content for Agent Memory (Beta) (Agent Tools section) of the Telnyx developer docs (https://developers.telnyx.com).
> This file: https://developers.telnyx.com/docs/development/llms/agent-tools-agent-memory-beta-llms-full-txt · Root index: https://developers.telnyx.com/llms.txt

## Agent Memory

### Overview

> Source: https://developers.telnyx.com/docs/agent-memory.md

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.

  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.

## 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

---

## Features

### Writing Memories

> Source: https://developers.telnyx.com/docs/agent-memory/writing.md

There are two ways in, and the difference is who decides what the fact is.

**`ingest`** takes a conversation and extracts the facts from it. Use it when the agent has just finished talking to someone and you want whatever mattered to be kept, without deciding in advance what that was.

**`remember`** takes one sentence you have already distilled and stores it as written. Use it when your system already knows the fact — a CRM field, a preference the user set, something a human entered.

Both answer `202 Accepted` with an `operation_id`, and the `source_id` the write is stored as — see [Sources](/docs/agent-memory/sources). Neither is readable until that operation completes.

## Ingest a Session

```bash
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/ingest?session_id=conv_8901" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "invoices go to 220 W Chicago Ave now"},
      {"role": "assistant", "content": "Got it."}
    ]
  }'
```

```json
{
  "data": {
    "operation_id": "op_01H…",
    "profile_id": "caller:+13128675309",
    "session_id": "conv_8901",
    "source_id": "b1e6c0a2-…"
  }
}
```

| Parameter | In | Required | Description |
| --- | --- | --- | --- |
| `session_id` | query | no | Your identifier for the conversation. Omit it and one is opened for you -- the response names it. |
| the body | body | yes | Stored whole, in whatever shape your framework produces. |

**The body is not a fixed shape.** `session_id` is a query parameter, so the whole body is stored exactly as it arrives -- you can post the transcript your framework already produces, even a bare array or a plain string, rather than reshaping it to carry a key. The `messages` array above is the conventional form, not a requirement.

**Re-sending the same `session_id` re-ingests that session in place** rather than adding a second copy, so a retry after a timeout is safe.

  `session_id` is a query parameter of at most 128 characters, validated on the way in -- a longer value is rejected with a `422`, the same bound the [memories listing](/docs/agent-memory/recall#read-a-profile-whole) filters on.

## Remember a Fact

```bash
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/remember" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Prefers window seats and flies out of ORD"}'
```

```json
{
  "data": {
    "operation_id": "op_01H…",
    "profile_id": "caller:+13128675309",
    "source_id": "9af23d17-…"
  }
}
```

`text` is the whole request. Sending the same text again writes the same memory rather than a second copy, so retries are safe here too.

  `remember` keeps your wording, but it does not freeze it. The service may later restate the same fact in its own prose, so a recall can answer about it in words you never wrote.

  **`ingest` is not a tool for your agent to call.** A tool is something the model invokes *during* a conversation; ingestion needs the finished transcript, and a model has no useful notion of "the conversation is over" while it is still in it. Call `ingest` from your application once the session ends. [`remember`](#remember-a-fact) is the verb that fits mid-conversation: one distilled fact, stored as written, safe to retry.

## Track a Write

Both verbs return an `operation_id`. Poll it to find out when the memory is recallable:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/operations/op_01H…" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json
{
  "data": {
    "operation_id": "op_01H…",
    "status": "completed",
    "created_at": "2026-08-26T21:14:07Z",
    "completed_at": "2026-08-26T21:14:11Z"
  }
}
```

  **Three statuses end the poll, not one.** `completed` means the memory is recallable. `failed` and `cancelled` are equally terminal and mean the write did not happen -- retry or surface the failure, but stop polling. Only `pending` and `processing` are worth another request.

A profile does not appear in [the profile listing](/docs/agent-memory/recall#who-is-in-a-namespace) until its first memory is extracted, so a still-running ingest is not there yet.

## Related

- [Recalling memories](/docs/agent-memory/recall) -- asking questions, and reading a profile whole
- [Agent Memory](/docs/agent-memory) -- namespaces, profiles, and how they are created

---

### Recalling Memories

> Source: https://developers.telnyx.com/docs/agent-memory/recall.md

Reading comes in two shapes. **Ask a question** and get the facts that answer it, ranked. Or **read a profile whole**, unranked, when you want to see everything it holds.

## Ask a Question

```bash
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/recall" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where do invoices go?", "top_k": 5}'
```

| Field | Required | Description |
| --- | --- | --- |
| `query` | yes | The question, 1-4096 characters. |
| `top_k` | no | How many memories to return, 1-100. |

  **URL-encode the profile id in the path.** A `profile_id` is free-form and often carries reserved characters — `caller:+13128675309` has both `:` and `+` — so percent-encode it when you interpolate it into a request path (`caller%3A%2B13128675309`), or the route can be changed or truncated.

Results come back in rank order, most relevant first. **Rank is the signal to build on** — read the list in the order it arrives rather than filtering on the `score` field:

```json
{
  "data": [
    {
      "id": "mem_01H…",
      "text": "Invoices go to 220 W Chicago Ave.",
      "recorded_at": "2026-08-26T21:14:11Z",
      "score": 0.82
    }
  ]
}
```

  **There is no model in the recall path.** Recall ranks and returns facts; it does not compose an answer. Putting those facts in front of your own agent is the last step, and it stays yours.

## Prime a Session Before the First Turn

`recall` answers questions, which means your agent has to have one. At the start of a session it does not: nobody has said anything yet, and "what do we know about this person?" is a weak query that returns ranked fragments rather than a picture.

That is the job `summary` does — the whole profile as one card, precomputed, no query and no retrieval at request time:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/$PROFILE_ID/summary" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json
{
  "data": {
    "profile_id": "user-42",
    "text": "## Profile Summary\n\n- Prefers Slack over email.\n- Timezone: US Central.",
    "generated_at": "2026-09-18T18:32:17Z",
    "is_stale": false
  }
}
```

A card is generated in the background. `is_stale` means newer memories have landed since the card was written — ordinary, and the card is still usable.

  **On the first read, a card may not exist yet.** For a profile whose summary has not been generated, `text` and `generated_at` come back `null` — the first read schedules one, so read again shortly. Guard for a non-null `text` before templating it into a prompt; if it is `null`, open the session without a card rather than injecting `null`.

Three things follow from a precomputed card:

- **It is fast enough for turn zero.** A voice agent cannot spend a retrieval round-trip before greeting someone.
- **It has a stable shape.** A card is a predictable block to template into a system prompt. Ranked facts vary in length and content with every query, which is awkward to budget context for.
- **It costs less.** Opening every session with "tell me about this person" pays for full multi-strategy retrieval to answer a question whose result barely moves between sessions.

So the two reads divide by moment rather than by preference:

| | When |
| --- | --- |
| `summary` | Session start, before the first turn. Fetched by your application and placed in context |
| `recall` | Mid-conversation, when the agent needs something specific |

You can steer how these cards read with [summary instructions](/docs/agent-memory/namespace-settings#summary-instructions), set once per namespace.

## Read a Profile Whole

Everything one profile holds, most recent first:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/memories" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json
{
  "data": [
    { "id": "mem_01H…", "text": "Invoices go to 220 W Chicago Ave.", "recorded_at": "2026-08-26T21:14:11Z" }
  ],
  "meta": { "page_number": 1, "page_size": 20, "total_pages": 22, "total_results": 431 }
}
```

| Parameter | Default | Description |
| --- | --- | --- |
| `session_id` | -- | Narrow to what one session put in. Maximum 128 characters. |
| `page[number]` | `1` | Which page to return, 1-based. |
| `page[size]` | `20` | Entries per page, up to 100. |

Listing depth is bounded: `page[number]` × `page[size]` cannot exceed 10,000. To reach older memories, narrow with `session_id` rather than paging deeper.

  **Don't stop on a short page.** A page can hold fewer than `page[size]` entries while more results remain, so a client that stops when `data.length < page[size]` silently drops the rest. Advance `page[number]` until it passes `meta.total_pages` (or you have read `meta.total_results`). Both listings behave this way.

  A page is also a snapshot: counts and order shift as writes land, so paging through a namespace that is being written to can repeat or miss an entry at a boundary. If that matters, page when writes are quiet, or de-duplicate on `id` as you go.

  `session_id` narrows to memories that came from that one session. **Some memories draw on several sessions and belong to none of them**, so they appear only in the unfiltered listing. A filtered read is not a subset you can page through to see everything.

## Who Is in a Namespace

Which profiles hold memories, and how many each:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json
{
  "data": [
    { "profile_id": "caller:+13128675309", "memory_count": 12 }
  ],
  "meta": { "page_number": 1, "page_size": 20, "total_pages": 1, "total_results": 1 }
}
```

Takes the same `page[number]` and `page[size]`. A profile appears once its first memory is extracted, so one whose [ingest is still running](/docs/agent-memory/writing#track-a-write) is not listed yet.

## Related

- [Writing memories](/docs/agent-memory/writing) -- `ingest`, `remember`, and tracking the operation
- [Sources](/docs/agent-memory/sources) -- what a profile stored, and tracing a memory back to it
- [Agent Memory](/docs/agent-memory) -- namespaces, profiles, and how they are created

---

### Sources

> Source: https://developers.telnyx.com/docs/agent-memory/sources.md

A **source** is what a profile stored and extracts memories from: one ingested session, or one remembered fact. [`ingest`](/docs/agent-memory/writing#ingest-a-session) and [`remember`](/docs/agent-memory/writing#remember-a-fact) return its `source_id` in their `202`, so you have it before extraction finishes. Re-ingesting a session keeps its source id and replaces what it held.

## List a profile's sources

Every source a profile stored, most recently written first, without content:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/sources" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json
{
  "data": [
    { "id": "b1e6c0a2-…", "session_id": "conv_8901", "memory_count": 3, "created_at": "2026-08-26T21:14:11Z", "updated_at": "2026-08-26T21:14:11Z" },
    { "id": "9af23d17-…", "session_id": null, "memory_count": 1, "created_at": "2026-08-25T09:02:44Z", "updated_at": "2026-08-25T09:02:44Z" }
  ],
  "meta": { "page_number": 1, "page_size": 20, "total_pages": 1, "total_results": 2 }
}
```

`session_id` is `null` for a remembered fact — the only place the two kinds differ. Paged like every listing: `page[number]` / `page[size]`, with `meta.total_pages` / `meta.total_results`.

### Find one session's source

Add `?session_id=` to look up the source a session was stored as, without paging or re-deriving its id:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/sources?session_id=conv_8901" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

It returns **zero or one** source. An unknown session, another profile's session, or one whose ingest is still queued is an empty page (`total_results: 0`) — a listing, not a `404`. A `session_id` over 128 characters is a `422`.

## Read one source

One source with its `content`, returned in the shape it was sent — a JSON body as JSON, a string as a string:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/sources/$SOURCE_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

```json
{
  "data": {
    "id": "b1e6c0a2-…",
    "session_id": "conv_8901",
    "memory_count": 3,
    "created_at": "2026-08-26T21:14:11Z",
    "updated_at": "2026-08-26T21:14:11Z",
    "content": {
      "messages": [{ "role": "user", "content": "invoices go to 220 W Chicago Ave now" }]
    }
  }
}
```

## Trace a memory to its source

Read one memory by id to see where it came from — exactly one field is set:

```bash
curl "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/memories/mem_01H…" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

- A **fact** names the source it was extracted from in `source_id` — read it with `GET …/sources/{source_id}`.
- A **derived memory** names the memories it was built from in `derived_from` — read each one to follow it back. Every read is a single call, however many memories are cited.

```json
{
  "data": {
    "id": "mem_01H…",
    "text": "Invoices go to 220 W Chicago Ave.",
    "recorded_at": "2026-08-26T21:14:11Z",
    "source_id": "b1e6c0a2-…",
    "derived_from": null
  }
}
```

## Forget one source

Forget a single source and the memories derived from it, leaving the rest of the profile intact. **This is also how you forget one session** — delete the session's source, either with the `source_id` from the ingest `202` or the one from [`?session_id=`](#find-one-sessions-source) above:

```bash
curl -X DELETE "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309/sources/$SOURCE_ID" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

A source that is not there answers `404` — an unknown id, another profile's source, or one already forgotten. Retrying is safe: on a `502` or `504`, repeat it and read a `404` as done.

  A source id is an opaque UUID. Another profile's source or memory answers `404` — the same as one that does not exist — and an id that is not a UUID is a `422`.

## Related

- [Writing memories](/docs/agent-memory/writing) — how sources get in
- [Recalling memories](/docs/agent-memory/recall) — reading a profile's memories
- [Forgetting](/docs/agent-memory/deleting) — forgetting a whole profile

---

### Forgetting

> Source: https://developers.telnyx.com/docs/agent-memory/deleting.md

Anything that stores what a person said needs a way to unsay it — a customer who asks to be forgotten, a profile created against the wrong id. Agent Memory answers that with **forget**.

## Forget a Profile

`DELETE /namespaces/{ns}/profiles/{profile_id}` forgets everything held about one profile — every memory, and the profile's summary with it.

```bash
curl -X DELETE "https://api.telnyx.com/v2/ai/memory/namespaces/default/profiles/caller:+13128675309" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

This is the route that answers a right-to-erasure request. A `2xx` means none of that profile's memories remain, and there is no undo.

  This endpoint **takes no parameters** and always deletes the whole profile. It does not accept a `session_id` — a stray one is ignored, not refused, so a request meant to forget one session would erase the entire profile. To forget one session, use its source (below), never this route.

## Forget One Session

A session is forgotten through its **source**, on the [Sources](/docs/agent-memory/sources#forget-one-source) page — `DELETE …/profiles/{id}/sources/{source_id}`. Use the `source_id` from the ingest `202`, or look it up first with [`GET …/sources?session_id=`](/docs/agent-memory/sources#find-one-sessions-source). This forgets that one session and the memories derived from it, leaving the rest of the profile intact.

  You can forget a whole profile (here) or one session, by [its source](/docs/agent-memory/sources#forget-one-source). Forgetting a single **memory** is not yet available.

## Related

- [Sources](/docs/agent-memory/sources) -- forget one session by deleting its source
- [Writing memories](/docs/agent-memory/writing) -- how memories get in
- [Recalling memories](/docs/agent-memory/recall) -- reading a profile whole

---

### Isolation Levels

> Source: https://developers.telnyx.com/docs/agent-memory/isolation.md

Agent Memory separates memories at three levels. Knowing which level does what tells you where you get a hard wall and where a naming convention is enough.

| Level | What it separates | How strong |
| --- | --- | --- |
| **Organization** | One customer from another | The tenancy boundary. Taken from your API key, never from the path — a profile only ever resolves inside your own organization, and no request reaches across it. |
| **Namespace** | One of *your* applications or environments from another | A hard wall. Each namespace is its own memory store; nothing reads from one namespace into another. |
| **Profile** | Who a memory is about — a user, caller, or agent | A soft separation *inside* a namespace. `profile_id` is a free-form string, so this boundary is convention, not enforced. |

The organization is the boundary that keeps customers apart, and you get it for free. Namespaces and profiles are how you organise *within* your own data.

## Organization — the tenancy boundary

Every identifier the service composes internally begins with your organization — banks are named `org:<organization>:<namespace>` — and the organization comes from your **API key**, not from anything in the request path. One profile's memories are never returned for another, and there is no request shape that reaches across into another organization. Nothing to configure; it is always on.

## Namespace — a hard wall within your org

A **namespace** is an isolated memory store for one application or environment — not a tenancy boundary, and not a memory layer. It does exactly one thing: it is an isolation boundary at the storage layer, one memory store per namespace. An operator can reach every memory across every profile in a namespace, and cannot reach across into another.

Reach for a namespace when you need a **hard** boundary rather than a tidy one — staging kept separate from production, or two applications whose memories must never meet.

  **Agent Memory is in beta, and today there is one namespace: `default`.** It exists for every organization, it isolates, and it carries [namespace settings](/docs/agent-memory/namespace-settings). There is no way to create, rename, list, or delete another one yet — additional namespaces are the planned way to get a second hard boundary.

### What `default` gives you

`default` exists for every organization with nothing to provision: the first request that addresses it builds it — reads included, so a brand-new organization gets an empty list rather than a `404`. Profiles are the same, created on first write. The entire setup for Agent Memory is *authenticate and write*.

A request against a namespace other than `default` returns `404` on reads and writes alike — writing never brings it into being.

## Profile — separation by convention

Because `profile_id` is a free-form string with no imposed pattern, you can separate applications, environments, or user and team layers *inside* `default` with a naming convention — nothing to provision:

```
u_123                       user memory
team:eng                    team memory
prod:caller:+13128675309    environment-scoped
```

This is a *tidy* boundary, not a hard one: nothing stops a wrong profile id from reading across within the same namespace. When the wall needs to be enforced rather than conventional, that is what a namespace is for.

  A request addresses exactly one namespace, so layered memory — user, then team, then organization — means one recall per layer and merging the results yourself. That is an argument for layering with profile ids rather than namespaces.

## Related

- [Agent Memory](/docs/agent-memory) — the profile and memory model
- [Namespace settings](/docs/agent-memory/namespace-settings) — the settings a namespace carries
- [Forgetting memories](/docs/agent-memory/deleting) — forgetting a profile's memories

---

### Namespace Settings

> Source: https://developers.telnyx.com/docs/agent-memory/namespace-settings.md

A **namespace** carries settings that apply to every profile in it, read and changed on one endpoint:

```
GET  /v2/ai/memory/namespaces/{namespace}/settings
PATCH /v2/ai/memory/namespaces/{namespace}/settings
```

Today there is one setting: **summary instructions**.

## Summary instructions

Free-form instructions that steer how a profile's [summary card](/docs/agent-memory/recall#prime-a-session-before-the-first-turn) reads — shared by every profile in the namespace.

```bash
curl -X PATCH "https://api.telnyx.com/v2/ai/memory/namespaces/default/settings" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"summary": {"instructions": "Lead with the plan tier. Keep it under 100 words."}}'
```

Read them back with `GET` on the same path. `instructions: null` means none are set and summaries use the neutral default.

| Behaviour | |
| --- | --- |
| Omitted fields | Left as they are — `{}` changes nothing |
| Clearing | `null`, empty, or whitespace-only |
| Length | 2000 characters. A longer note is **refused, not truncated** — a note cut mid-sentence is a worse steer than none |
| Scope | Summaries only. Instructions never affect what `recall` returns |

  **A change applies in the background, not instantly.** After you edit the instructions, existing summaries are brought into line over time — a rate-limited sweep converges every profile's card, dormant ones included — so you don't need new activity on a profile for it to pick up the change.

Instructions are advisory: they shape emphasis, tone, and what gets foregrounded, and they never contradict or remove a fact a profile's memories establish.

## Related

- [Recalling memories](/docs/agent-memory/recall) -- the summary card these instructions steer
- [Isolation](/docs/agent-memory/isolation) -- what a namespace is, and how it isolates

---

## API Reference (Agent Memory (Beta))

### Memory

- [Ingest a session's messages into a profile](https://developers.telnyx.com/api-reference/memory/ingest-a-sessions-messages-into-a-profile.md): Store a session. Facts are extracted from whatever you send — the body is taken as any JSON value and stored whole, so a framework's own transcript shape works…
- [Remember one fact, stored as written](https://developers.telnyx.com/api-reference/memory/remember-one-fact-stored-as-written.md): For a fact the agent has already distilled: `text` is stored as given, with nothing extracted from it. Send a transcript to `ingest` instead. Remembering the s…
- [Recall a profile's memories, ranked](https://developers.telnyx.com/api-reference/memory/recall-a-profiles-memories-ranked.md): Ranked memories for a question. Matching runs over the profile's memories and returns them in rank order with a relevance `score`; the score is null where the…
- [Get a profile's precomputed summary](https://developers.telnyx.com/api-reference/memory/get-a-profiles-precomputed-summary.md): The whole profile as one card, precomputed, with no query. Built for the start of a session, where there is no question to ask yet.

### Profiles

- [List a namespace's profiles](https://developers.telnyx.com/api-reference/profiles/list-a-namespaces-profiles.md): Profiles are never created, only written to, so this lists the ones that hold a memory. A profile whose first ingest is still running is not here yet. Ordered…
- [List a profile's memories, most recent first](https://developers.telnyx.com/api-reference/profiles/list-a-profiles-memories-most-recent-first.md): Everything stored under one profile, unranked -- ask `recall` for the memories that answer a question. A profile that holds nothing is an empty page rather tha…
- [Read one memory, and what it came from](https://developers.telnyx.com/api-reference/profiles/read-one-memory-and-what-it-came-from.md): One memory by its id, as `recall` and the listing return it, together with what it came from. A fact names its `source_id`: read it with `GET .../sources/{sour…
- [Forget a profile's memories](https://developers.telnyx.com/api-reference/profiles/forget-a-profiles-memories.md): Delete everything held about one profile. A 2xx means none of its memories are left, and its summary goes with them. There is no undo.

### Sources

- [List a profile's sources, most recently written first](https://developers.telnyx.com/api-reference/sources/list-a-profiles-sources-most-recently-written-first.md): Everything a profile has stored and extracts memories from: each ingested session, and each remembered fact, which has no session. Content is not listed; read…
- [Read one source, with what was stored](https://developers.telnyx.com/api-reference/sources/read-one-source-with-what-was-stored.md): One source and its content, as it was stored: an ingested session's payload or a remembered fact. A source whose ingest is still queued answers 404 until it ha…
- [Forget one source](https://developers.telnyx.com/api-reference/sources/forget-one-source.md): Deletes one source -- an ingested session or a remembered fact -- together with the memories derived from it. A memory derived from this source and others is d…

### Settings

- [Get a namespace's settings](https://developers.telnyx.com/api-reference/settings/get-a-namespaces-settings.md): What is currently set for this namespace. `instructions: null` means none are set and summaries use the neutral default.
- [Change a namespace's settings](https://developers.telnyx.com/api-reference/settings/change-a-namespaces-settings.md): Only the fields you send are changed; anything omitted is left as it is, so `{}` changes nothing. Sending `instructions: null`, or an empty or whitespace-only…

### Operations

- [Status of a write](https://developers.telnyx.com/api-reference/operations/status-of-a-write.md): Whether a write has finished. Both `ingest` and `remember` return an `operation_id`, and a memory is not recallable until its operation completes — extraction,…