# Scoping memory to customers, companies and deals

> Where a customer, a company or a deal lives, with the requests that put it there.

## Apps or users

Use a separate app when two customers must never share anything. An app is the isolation boundary, and an app key selects exactly one. Inside one app, each user has their own memory, and a recall answers as one user. A user is a person or an entity your application recalls as, such as one company. Audiences group users, but every data point goes to the default audience, so an audience does not yet keep one customer's data point from another user.

## One app per customer

Create one app for each customer and keep its app key with that customer's records. A call made with that key can read and write that customer's memory only. Name the person with `X-Harny-User: <user>` on every call.

## One app, one user per customer

Keep one app when your team works across customers. Create one user per customer with `PUT /v1/memory/identities/{identity}`, send each customer's data points as that user with `X-Harny-User: <user>`, and recall as that user. A recall as one customer's user returns that customer's memory and not another user's.

## CRM memory by company and deal

Use one user per company, and one data point per note. Give each data point a stable `id`, a `label`, and the company and deal in `metadata`.

```bash tab=cURL
curl -X POST https://api.harny.ai/v1/memory/ingest \
  -H "Authorization: Bearer $HARNY_APP_KEY" \
  -H "X-Harny-User: acme" \
  -H "Content-Type: application/json" \
  -d '{ "id": "deal-482-note-3",
        "label": "Renewal call",
        "content": "Renewal call on 26 October. Owner to confirm terms.",
        "timestamp": "2026-10-26T15:00:00Z",
        "metadata": { "company": "acme", "deal": "482" } }'
```

```python tab=Python
import os
import requests

requests.post(
    "https://api.harny.ai/v1/memory/ingest",
    headers={
        "Authorization": f"Bearer {os.environ['HARNY_APP_KEY']}",
        "X-Harny-User": "acme",
    },
    json={
        "id": "deal-482-note-3",
        "label": "Renewal call",
        "content": "Renewal call on 26 October. Owner to confirm terms.",
        "timestamp": "2026-10-26T15:00:00Z",
        "metadata": {"company": "acme", "deal": "482"},
    },
)
```

```typescript tab=TypeScript
await fetch("https://api.harny.ai/v1/memory/ingest", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HARNY_APP_KEY}`,
    "X-Harny-User": "acme",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    id: "deal-482-note-3",
    label: "Renewal call",
    content: "Renewal call on 26 October. Owner to confirm terms.",
    timestamp: "2026-10-26T15:00:00Z",
    metadata: { company: "acme", deal: "482" },
  }),
});
```

## Read one scope

Recall as the user that holds the scope. A recall with `X-Harny-User: acme` and `"identity": "acme"` reads Acme's memory and nothing else. Recall returns each data point's `metadata` in `sources[].metadata`, so your application can group results by deal.

## A lead who changes company

Send new notes under the new company's user. The earlier notes stay with the first company, where they were written. To carry a fact across, send it again under the new company with its original `timestamp`.

## Call transcripts with attendees

Send one data point per call, with the call's id as `id`, the transcript as `content`, and the attendees in `metadata`. Recall reads one user's memory, so send the data point as the user who should recall it, such as the company.

## A fact that changes

Send the same `id` with changed content to replace the record. Harny removes the memories built on the old text and then ingests the new text. Fields you leave out of the resend keep their stored values. Send a new `id` to add a dated fact next to the earlier one. Both stay in memory, each with its date.

## Four rules

1. Use one app per customer when their memory must never mix.
2. Send `X-Harny-User` on every app-key call. Omit it only with a user key (`fsk_`).
3. Keep the `id` stable for a record that changes, and use a new `id` for a new dated fact.
4. Send `idempotencyKey` on every write that your application may retry.