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

# Subjects & isolation

> What a subject is, how each end-user's memory stays private, and how to model your users.

A **subject** is your id for one end-user — or one device — inside a project.
It's the unit of memory isolation in Atlaso Build.

## The mental model

* A **project** is your app or environment. It holds one API key (or several).
* A **subject** is one of your users. You choose the string: `user_8213`, an
  email, a tenant id, a device serial — anything stable, up to 128 characters
  matching `^[A-Za-z0-9_.:@\-]{1,128}$`.
* Each **`(project × subject)`** pair is one **isolated memory bag**. Everything
  you `remember` for a subject is recalled only for that same subject.

```
project: acme-travel
├── subject: user_8213   → { window seats, vegetarian, … }
├── subject: user_5590   → { aisle seats, allergic to nuts, … }
└── subject: kiosk_lobby → { … }
```

## How private is it, really

Isolation is **cryptographic**, not just a `WHERE` clause. Atlaso derives an
opaque tenant key from your project id and the subject with a keyed HMAC, and
the memory engine only ever sees that derived key as the identity. So:

* Two subjects in the same project can never read each other's memories.
* The same subject string in two different projects (`acme-travel` and
  `acme-staging`) are completely separate bags — they never collide.
* Developer memory lives in its own storage plane, entirely separate from
  Atlaso's consumer users.

You don't manage any of this — you just pick subject strings.

## The subject header is a claim, not a login

When you send `X-Atlaso-Subject: user_8213`, Atlaso trusts that **your server
already authenticated that user**. Whoever holds the project key can name any
subject — that's why the key stays server-side and you do your own auth first.

For devices where you can't hold the key server-side, mint a
[per-device credential](/build/devices) instead: the subject is baked into the
credential, so a compromised device can only ever touch its own bag.

## Choosing subject ids

* **Use a stable, opaque id** you control — your internal user id is ideal.
* **Don't** put personal data in the subject if you can avoid it. Atlaso scrubs
  recognized secrets, credentials, and high-entropy tokens from memory
  *content*, not subject identifiers — treat the subject like an identifier.
* **One real user = one subject.** If the same person uses your app on phone and
  web, use the same subject so their memory follows them. If you want a device
  to have its own separate memory, give it its own subject.

<Note>
  There's no "create subject" call — a subject springs into existence the first
  time you `remember` for it, and is gone once you
  [purge](/build/api-reference#delete-a-subject-gdpr) it.
</Note>