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

# Isolation Levels

> How Agent Memory keeps memories separated: by organization, by namespace, and by profile.

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.

<Note>
  **Agent Memory is in beta.** Every organization gets `default`, and you can create up to **four** more — **5 namespaces in total, `default` among them.** List, create, and delete them through the API (below). `default` cannot be deleted, and namespaces cannot be renamed.
</Note>

### 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 you have not created returns `404` on reads and writes alike — create it first; writing never brings it into being.

### Creating and Deleting Namespaces

Beyond `default`, create the namespaces you need — up to **5 per organization, including `default`**:

```bash theme={null}
# create a namespace
curl -X POST "https://api.telnyx.com/v2/ai/memory/namespaces" \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging"}'

# list your namespaces
curl "https://api.telnyx.com/v2/ai/memory/namespaces" \
  -H "Authorization: Bearer $TELNYX_API_KEY"

# delete a namespace, and every profile in it
curl -X DELETE "https://api.telnyx.com/v2/ai/memory/namespaces/staging" \
  -H "Authorization: Bearer $TELNYX_API_KEY"
```

Creating a sixth namespace returns `403` — an organization can hold at most five, `default` included. `default` cannot be deleted, and namespaces cannot be renamed.

<Warning>
  Deleting a namespace forgets **everything inside it** — every profile and every memory. It cannot be undone.
</Warning>

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

<Note>
  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.
</Note>

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