Scoping memory to customers, companies and deals

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.

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" } }'

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.