Session Persistence

Beta — This feature is in alpha. APIs may change before stable release.

Persist the full conversation state — including compaction metadata and message history — across page reloads with zero extra code.

Basic Setup

useMessageHistory({
  persistSession: true,
  storageKey: "my-app-chat", // default: "copilot-session"
});

What gets persisted

Data	Where	Notes
`compactionState` (small metadata)	`localStorage`	Sync, available immediately on cold start
`displayMessages` (can be large)	`IndexedDB`	Async, avoids localStorage quota issues

Both are keyed by storageKey. Multiple chat instances can coexist with different keys.

Clear Everything

const { resetSession } = useMessageHistory({ persistSession: true });

// Clears state AND storage
await resetSession();

Multiple Chat Instances

// Support chat — separate session
<CopilotProvider widgetToken="...">
  <SupportChat>
    {/* useMessageHistory({ storageKey: "support-chat" }) */}
  </SupportChat>
</CopilotProvider>

// Sales chat — separate session
<CopilotProvider widgetToken="...">
  <SalesChat>
    {/* useMessageHistory({ storageKey: "sales-chat" }) */}
  </SalesChat>
</CopilotProvider>

Full Setup Example

// app/layout.tsx
import { CopilotProvider } from "@yourgpt/copilot-sdk/react";

export default function RootLayout({ children }) {
  return (
    <CopilotProvider
      widgetToken="YOUR_TOKEN"
      messageHistory={{
        strategy: "summary-buffer",
        maxContextTokens: 128000,
        compactionThreshold: 0.75,
        compactionUrl: "/api/compact",
        persistSession: true,
        storageKey: "my-app",
        onCompaction: (e) => console.log("Compacted:", e),
      }}
    >
      {children}
    </CopilotProvider>
  );
}

Compaction — how the session is summarized
Token Tracking — monitor context window usage