# History and transcripts

> Distinguish Intelligence-managed conversation history from the optional SDK transcript store, and use each without duplicating turns.

Your agent needs earlier messages to answer well. Some apps also need one
record per user across Slack and Teams. Pick the source by what you need:

| Need                                                | Use                                                                     |
| --------------------------------------------------- | ----------------------------------------------------------------------- |
| Continue the current Slack or Teams conversation    | Managed conversation history                                            |
| Inspect recent text in one provider thread          | `thread.getMessages()`                                                  |
| Carry user context between Slack and Teams          | SDK transcripts with a stable identity                                  |
| Store workflow progress                             | `thread.state()`                                                        |
| Meet application deletion or retention requirements | A durable SDK transcript store plus your provider/Intelligence policies |

Managed conversation history rebuilds the current provider thread for the
agent. SDK transcripts are an application-owned record, keyed by identity, that
can span providers and conversations. They are not interchangeable.

## Use managed conversation history [#use-managed-conversation-history]

On each delivered turn, Intelligence fetches recent messages for that native
conversation and seeds a fresh agent instance. The default history limit in the
managed adapter is 20 messages.

The managed conversation history already holds the current turn, with its text and hydrated
attachments. Call `runAgent()` without a `prompt` to answer it:

```ts title="channel.ts"
channel.onMessage(async ({ thread }) => {
  await thread.runAgent();
});
```

Create a fresh agent for every `conversationKey`; the managed adapter assigns
the managed conversation history to that instance. Sharing one mutable agent between
threads can leak or overwrite history.

## Read the current provider thread [#read-the-current-provider-thread]

`thread.getMessages()` returns a best-effort, oldest-first text view of recent
history:

```ts title="read-thread.ts"
const messages = await thread.getMessages();
const transcript = messages
  .map((message) => `${message.isBot ? "Agent" : "User"}: ${message.text}`)
  .join("\n");
```

On the managed path, `getMessages()` throws when the history fetch fails. Catch
the error if the turn must continue without history. The method is text-oriented: binary image, audio, and video content is
available to the agent through multimodal history, but is not reproduced as
binary data in `ThreadMessage`.

## Add cross-platform SDK transcripts [#add-cross-platform-sdk-transcripts]

Use SDK transcripts when your application needs a user-centric record across
Slack and Teams. Configure top-level `identifyUser` and `store.transcripts`.
When identity resolves to `null`, the transcript bridge skips personal reads
and writes.

<Callout type="info" title="Resolve the current actor first">
  Read [Identity and Memory](/teams/identity-and-memory) before using a
  provider actor as an application user. A shared provider conversation has no
  personal owner, and each event resolves its actor independently.
</Callout>

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

const channel = createChannel({
  name: process.env.CHANNEL_CODE,
  identifyUser: async ({ provider, actor }) => {
    const account = await accounts.findByExternalIdentity({
      provider,
      externalUserId: actor.id,
    });
    return account ? { id: account.id, name: account.name } : null;
  },
  agent: makeAgent,
  store: {
    adapter: durableStateStore,
    transcripts: {
      retention: "30d",
      maxPerUser: 500,
    },
  },
});
```

Provider user ids are not cross-platform identities. Resolve them to a stable
application user id, verified email, or another identity your application
controls. Returning `null` skips transcript storage for that turn.

The transcript list facet must be durable if this record must survive a restart.
The default `MemoryStore` is not sufficient.

## Let `runAgent` bridge the transcript once [#let-runagent-bridge-the-transcript-once]

Set `transcript: true` to inject prior SDK transcript entries, append the
current user turn, run the agent, and capture its reply:

```ts title="channel.ts"
channel.onMessage(async ({ thread, message }) => {
  await thread.runAgent({
    prompt: message.text,
    transcript: { limit: 20 },
  });
});
```

Do not also call `channel.transcripts.append()` for the same user and assistant
turns. `runAgent({ transcript: ... })` owns that bridge and manual appends would
duplicate the record.

## Query and delete the application record [#query-and-delete-the-application-record]

`channel.transcripts` is available after the runner starts the Channel:

```ts title="transcripts.ts"
const recent = await channel.transcripts.list({
  userId: "usr_123",
  limit: 50,
});

const { deleted } = await channel.transcripts.delete({
  userId: "usr_123",
});
```

`list()` returns entries oldest-first. You can filter by platform, thread id, or
role. Managed entries use the native `"slack"` or `"teams"` provider. Resolve
cross-provider identity through the application `userId`; use the platform
filter only when you intentionally want one provider's entries.

`delete()` removes the SDK-owned transcript for that user; provider history and
any separate Intelligence retention policy remain independent.

See the [`Transcripts` reference](/reference/channels/classes/Transcripts) and
[persistence guide](/teams/persistence-and-scaling) before enabling this in
production.
