End-user identity

Understand how the SDK identifies users for long-term memory scoping and how to implement a custom authentication-backed identity provider.

Every long-term memory session requires a stable end_user_id — a string the SDK sends to Convai on every connection. Convai uses it to scope stored memories: facts extracted from a conversation are stored under the combination of end_user_id and character_id. If the identifier changes between sessions, the server treats the user as a new person and no memories carry over.

The SDK provides DeviceEndUserIdProvider as a zero-config default. For applications with user authentication, you can replace it with a custom provider that returns your account IDs.


Default identity: DeviceEndUserIdProvider

DeviceEndUserIdProvider implements both IEndUserIdProvider and IEndUserIdentityProvider. It is registered automatically — no configuration required.

In the Unity Editor: Always reads or creates a GUID stored in PlayerPrefs under the key "convai.end_user_id". Every Play Mode session on the same machine shares this GUID, so memories accumulate as expected during development and testing.

In player builds: First attempts SystemInfo.deviceUniqueIdentifier. If that value is unavailable, empty, equals SystemInfo.unsupportedIdentifier, or consists entirely of zeros, it falls back to a PlayerPrefs GUID — generated once and reused across all subsequent sessions on that device.

The GUID is formatted as a 32-character hex string without hyphens (e.g., a1b2c3d4e5f6789012345678abcdef01). You will see this format in console logs and when inspecting EndUserDetails.EndUserId.

PlayerPrefs does not survive reinstalls. Clearing PlayerPrefs or reinstalling the application generates a new GUID. Convai treats the new GUID as a new user — all previously stored memories become inaccessible under the new ID (though they remain on the server under the old ID). For applications where data continuity across reinstalls matters, use a server-assigned account ID via a custom provider. See Implement a custom identity provider below.


Player ID is not end-user ID

Setting Player ID on the ConvaiPlayer component does not change the end_user_id used for memory scoping. Player ID controls only how the local player's name appears in transcripts and debug logs. Memory scoping is always determined by IEndUserIdentityProvider, not by ConvaiPlayer.


Implement a custom identity provider

If your application authenticates users, implement IEndUserIdentityProvider to return a stable, server-assigned account identifier. This ensures memories follow a user across devices and reinstalls.

Implement the interface

Use your backend-assigned account ID as the identifier. Do not use email addresses or display names — they can change, which would cause the server to treat the user as a new person.

Optionally attach metadata

Implement IEndUserMetadataProvider to send display information alongside the identity. Convai stores this metadata in EndUserDetails.Metadata and uses the "name" key to populate the display name in the editor's Long-Term Memory panel.

Register before the first connection

Call SetEndUserIdentityProvider and SetEndUserMetadataProvider on ConvaiManager before the first session connects. If ConvaiCharacter has Auto Connect enabled, the connection starts immediately after ConvaiRoomManager.Start() completes — register your provider in Awake(), not Start(), to guarantee correct ordering.


Empty or whitespace end-user ID


Identity source comparison

Scenario
Recommended source
Survives reinstall
Survives device switch

Development / testing

DeviceEndUserIdProvider (default)

No

No

Consumer app, no accounts

DeviceEndUserIdProvider (default)

No

No

Consumer app with accounts

Custom provider → server account ID

Yes

Yes

Enterprise / training platform

Custom provider → server account ID

Yes

Yes


Next steps

Manage end-user recordsMemory management API

Last updated

Was this helpful?