Identity and Memory

`identifyUser` receives the normalized provider, tenant, installation,
actor, conversation, and event. Return an application-controlled
`{ id, name }` when a trusted mapping exists, or `null` when the actor is
intentionally unlinked.

<FrontendOnly frontend="slack">

For Slack, `tenant.id` identifies the workspace and `actor.id` identifies
the Slack account. Channels, private channels, group DMs, and shared
threads can all contain several actors, so include the workspace in the
external-identity key.

```ts title="channel.ts"
import { createChannel } from "@copilotkit/channels";
import { makeAgent } from "./agent.js";

const linkedAccounts = new Map([
  [
    "slack:T0123:U0456",
    { id: "user_42", name: "Ada Lovelace" },
  ],
]);

export const channel = createChannel({
  name: "support",
  identifyUser: async ({ provider, tenant, actor }) =>
    linkedAccounts.get(`${provider}:${tenant.id}:${actor.id}`) ?? null,
  agent: makeAgent,
});
```

</FrontendOnly>

<FrontendOnly frontend="teams">

For Microsoft Teams, `tenant.id` identifies the Microsoft tenant and
`actor.id` identifies the Teams account. Team channels and group chats can
contain several actors, so include the tenant in the external-identity key.

```ts title="channel.ts"
import { createChannel } from "@copilotkit/channels";
import { makeAgent } from "./agent.js";

const linkedAccounts = new Map([
  [
    "teams:tenant-123:user-456",
    { id: "user_42", name: "Ada Lovelace" },
  ],
]);

export const channel = createChannel({
  name: "support",
  identifyUser: async ({ provider, tenant, actor }) =>
    linkedAccounts.get(`${provider}:${tenant.id}:${actor.id}`) ?? null,
  agent: makeAgent,
});
```

</FrontendOnly>

Replace the map with a lookup in the account-linking data your application
owns. Do not automatically link accounts by email address, display name, or
handle. Those attributes can change or collide across provider tenants.

Returning `null` means that the actor is deliberately unlinked. Throw only
when the identity system itself failed. When the adapter provides
`lookupProfile`, you may use it to enrich a confirmed provider identity,
but profile data does not establish a canonical application account by
itself.

Intelligence Memory is off unless the current `runAgent` call grants
access. Each `user` or `project` scope accepts `"none"`, `"read"`, or
`"read-write"`:

```ts title="channel.ts"
channel.onMessage(async ({ thread, message }) => {
  await thread.runAgent({
    prompt: message.text,
    memory: {
      user: "read",
      project: "read-write",
    },
  });
});
```

Omitting a scope disables it for that run. Project-only Memory works when
`identifyUser` returns `null`; user Memory fails before the agent starts
unless the current event resolved to an application user.

In a shared channel or group chat, project Memory is the safer default.
Grant user Memory only when the current turn clearly acts for the resolved
individual. Never reuse the installer, thread creator, or first participant
as the personal Memory subject for everyone else.

A resumed run can grant Memory too. In the callback for a registered
component, choose which trusted participant supplies the subject when you
grant user Memory:

```tsx title="approval-button.tsx"
import { Button } from "@copilotkit/channels/ui";

export function ApprovalButton() {
  return (
    <Button
      value={{ approved: true }}
      onClick={async ({ thread, action }) => {
        const value = action.value;
        if (value === undefined) {
          await thread.post("The approval value was missing.");
          return;
        }

        await thread.resume(value, {
          memory: {
            user: "read",
            project: "read",
          },
          subject: "initiator",
        });
      }}
    >
      Approve
    </Button>
  );
}
```

- `"initiator"` keeps the application user who started the continuation
  chain.
- `"actor"` uses the application user resolved for the current interaction.
- Project-only Memory needs no subject.
- Callers cannot provide an arbitrary raw user ID.

Use `"initiator"` when an approval belongs to the person who started the
workflow. Use `"actor"` when the current approver should supply the personal
context. See [Interactive messages and approvals](/channels/interactive)
for the complete registered component and post-and-resume flow.

Exercise the mapping with separate provider accounts before enabling it in
a shared conversation:

1. Send a message from two actors in the same conversation. Confirm each
   event looks up the full provider, tenant, and actor tuple and resolves
   the correct application user independently.
2. Test an intentionally unlinked actor. A project-only run should work;
   requesting user Memory should fail with
   `channel_memory_user_required` before the agent starts.
3. If the Channel uses approvals, start a workflow as one user and click it
   as another. Verify `"initiator"` preserves the starter and `"actor"`
   selects the current approver.
4. Check application logs and telemetry. Record the stable error code and
   your application user ID when needed, but do not log provider tokens,
   message contents, or Memory contents.

The boundary is ready when every event resolves its current actor, personal
Memory follows only that resolved user, and project Memory follows the
explicit grant for the run.