Identity and memory

How these behave, and why, is on Identity and users and Memory. This page is the exact surface.

identify

Who the customer is. The trait the agent's Who is the user? setting names — user_id unless it names another — is the identifier; every other trait becomes a prompt variable.

client.identify(user: Record<string, unknown> | null, options?: { memory?: boolean }): void
useGraineIdentify(): (user: Record<string, unknown> | null, options?: { memory?: boolean }) => void
 
const identify = useGraineIdentify();
identify({ user_id: user.id, name: user.firstName }, { memory: true });

Returns nothing. It applies to the next conversation; one already running keeps the identity it started with.

Side effects

• The identifier is kept as it is and sent only to identify the customer — never in prompt variables or in what the agent reads about the customer. Graine stores the identifier your app sends so your team can see who each conversation was with — Call History shows it — and the memory service only ever receives a one-way key derived from it. A placeholder (guest, unknown, 0…), an empty value, a boolean or a decimal is no identifier at all.
• Every other trait is masked on the device and becomes a prompt variable.
• null signs out: the identity is forgotten on the device, the device is released from the customer and unlinked from their calls, and later conversations are anonymous. A different customer signs the previous one out first. Either way the chat on screen clears: the conversation was theirs.
• memory is kept for that customer on this install.

Errors none: an identifier that cannot be used is simply no identity.

Threading the main thread on iOS and Android; any thread in React Native, Dart, Kotlin Multiplatform and the browser.

setMemory

client.setMemory(enabled: boolean): void

The same as identify(currentTraits, { memory: enabled }). Returns nothing; applies to the next conversation; kept for the customer on this install. The calls engine receives it too, so a call follows the same choice.

The memory choice

The customer's current choice — what setMemory or identify(…, memory) last set, true by default. Whether the agent remembers at all is in its settings (Configuration values).

installId

This install's id: a random UUID made the first time the app runs, kept across launches, never shown to the agent.

client.installId: string | null          // null when there is nowhere to keep one
client.getInstallId(): Promise<string | null>
GraineCalls.installId(): Promise<string | null>   // the calls package: the same id

"3f6a0c1e-9b2d-4c7a-8e51-2d9f0a7b6c43"

memories

What the agent remembers about the signed-in customer, for this agent's memory scope.

client.memories(): Promise<GraineMemory[]>
useGraineMemories(): { memories: GraineMemory[]; loading: boolean; error: GraineError | null; refresh: () => Promise<void> }
 
const { memories, loading, error, refresh } = useGraineMemories();

Returns a list of GraineMemory, newest first, at most 100, each already redacted.

[
  { "id": "mem_4f9c21", "text": "Prefers a call after 6 pm on weekdays.", "createdAt": "2026-10-02T13:05:11Z", "updatedAt": null },
  { "id": "mem_1b07d4", "text": "Usually orders for two people.", "createdAt": "2026-09-21T08:14:37Z", "updatedAt": "2026-09-28T19:02:10Z" }
]

Resolves when Graine answers — one request.

Errors identity_required (nobody identified), device_limit (this install is not one of the customer's), rate_limited, network, unavailable, invalid_key, origin_refused — Errors.

Side effects none.

Threading Android calls done on the main thread.

forgetMemory

Deletes everything the agent remembers about the signed-in customer, for this agent's memory scope.

client.forgetMemory(): Promise<number>
 
const deleted = await client.forgetMemory();

Returns how many memories were deleted.

3

Resolves once they are deleted.

Errors the same as memories.

Side effects — only when it succeeds: the memories are gone for every agent sharing this memory scope, the conversation this agent kept for the customer is forgotten with them, and the chat on screen clears, with any message still waiting to go. React Native emits memories_changed ({ forgotten: true, deleted }), and useGraineMemories reloads.

When it fails — unavailable (503), device_limit, network, identity_required — nothing is deleted and the chat on screen stays as it is. Try again later for unavailable and network.

React Native only

{ "value": "u_8812", "installId": "3f6a0c1e-9b2d-4c7a-8e51-2d9f0a7b6c43", "memory": true, "timezone": "Asia/Kolkata" }