Cedar provides a flexible storage system for managing chat messages with automatic persistence and automatic thread management. By default, Cedar uses no storage - no persistence unless you configure a storage adapter.

Storage Requirements: Message persistence requires both userId and threadId to be set. Without these IDs, storage operations are skipped and messages remain in memory only.

Quick Start

Cedar works out of the box with no storage (no persistence). To enable persistence, configure a storage adapter.

Storage Options

Cedar supports three storage adapters:

Local Storage (default) - Browser localStorage
No Storage - Disables persistence
Custom Storage - Your own implementation

Configure storage by passing the messageStorage prop to CedarCopilot:

import { CedarCopilot } from 'cedar-os';

function App() {
	return (
		<CedarCopilot
			// No storage prop needed - uses local storage by default.
			// Optionally pass in user ID
			userId='user-123'>
			<YourChatComponent />
		</CedarCopilot>
	);
}

import { CedarCopilot } from 'cedar-os';

function App() {
	return (
		<CedarCopilot
			messageStorage={{
				type: 'local',
				options: {
					key: 'my-app', // Optional: defaults to 'cedar'
				},
			}}
			userId='user-123'>
			<YourChatComponent />
		</CedarCopilot>
	);
}

import { CedarCopilot } from 'cedar-os';

function App() {
	return (
		<CedarCopilot messageStorage={{ type: 'none' }} userId='user-123'>
			<YourChatComponent />
		</CedarCopilot>
	);
}

import { CedarCopilot } from 'cedar-os';

const myCustomAdapter = {
	async listThreads(userId) {
		return await myDatabase.getThreads(userId);
	},
	async loadMessages(userId, threadId) {
		return await myDatabase.getMessages(userId, threadId);
	},
	async persistMessage(userId, threadId, message) {
		await myDatabase.appendMessage(userId, threadId, message);
	},
};

function App() {
	return (
		<CedarCopilot
			messageStorage={{
				type: 'custom',
				adapter: myCustomAdapter,
			}}
			userId='user-123'>
			<YourChatComponent />
		</CedarCopilot>
	);
}

Additional Configuration Requirements by Storage Type

Local Storage & No Storage

No additional configuration needed - these options work out of the box.

Custom Storage

Implement your own storage solution by providing a custom adapter:

interface MessageStorageBaseAdapter {
	// Required methods
	loadMessages(userId: string, threadId: string): Promise<Message[]>;
	persistMessage(
		userId: string,
		threadId: string,
		message: Message
	): Promise<Message>; // returns the saved message

	// Optional thread methods
	listThreads?(userId: string): Promise<MessageThreadMeta[]>;
	createThread?(
		userId: string,
		threadId: string,
		meta: MessageThreadMeta
	): Promise<MessageThreadMeta>; // returns new meta
	updateThread?(
		userId: string,
		threadId: string,
		meta: MessageThreadMeta
	): Promise<MessageThreadMeta>; // returns updated meta
	deleteThread?(
		userId: string,
		threadId: string
	): Promise<MessageThreadMeta | undefined>; // returns deleted meta (optional)

	// Optional message methods
	updateMessage?(
		userId: string,
		threadId: string,
		message: Message
	): Promise<Message>; // returns updated message
	deleteMessage?(
		userId: string,
		threadId: string,
		messageId: string
	): Promise<Message | undefined>; // returns deleted message (optional)
}

import { CedarCopilot } from 'cedar-os';

// Your custom storage implementation
const myCustomAdapter = {
	async listThreads(userId) {
		return await myDatabase.getThreads(userId);
	},

	async loadMessages(userId, threadId) {
		return await myDatabase.getMessages(userId, threadId);
	},

	async persistMessage(userId, threadId, message) {
		await myDatabase.appendMessage(userId, threadId, message);
	},
};

function App() {
	return (
		<CedarCopilot
			messageStorage={{
				type: 'custom',
				adapter: myCustomAdapter,
			}}
			userId='user-123' // User ID passed in initial configuration
		>
			<YourChatComponent />
		</CedarCopilot>
	);
}

How Default Message Storage Works

Cedar preconfigures several storage methods that orchestrate your adapter’s functionality. Understanding these helps you work with Cedar’s storage system effectively.

Preconfigured Storage Methods

Cedar provides these methods out of the box. These methods are automatically called by Cedar at appropriate times - you don’t need to call them directly. To customize their behavior, you can override them in your implementation.

1. `initializeChat({threadId?: string, userId?: string})`

This method orchestrates the initial loading of threads and messages. It’s automatically called:

When the message storage adapter is first set
When userId or threadId changes in Cedar state

Here’s what it does with your adapter:

// Cedar's initializeChat flow:
1. Get userId (from params or Cedar state)
2. Get threadId (from params or Cedar state)
3. Call adapter.listThreads(userId) to load user's threads
4. If no thread is selected and threads exist:
   - Automatically select the first thread
5. If **no threads exist** and `adapter.createThread` is available:
   - A brand-new thread is created (ID `thread-{timestamp}-{rand}`)
   - The new thread metadata is persisted via `adapter.createThread`
   - Cedar sets this new ID in state
6. Use the provided threadId OR the auto-selected / newly-created threadId
7. Clear any existing messages in the UI
8. If both userId and threadId exist:
   - Call adapter.loadMessages(userId, threadId)
   - Display the loaded messages

2. `persistMessageStorageMessage(message)`

This method handles message persistence with intelligent thread management:

// Cedar's persistMessageStorageMessage flow:
1. Get userId from Cedar state (skip entire process if no userId)
2. Get threadId from Cedar state
3. Call adapter.persistMessage(userId, threadId, message)
4. If adapter.updateThread is available:
   - Update thread metadata (preserving original title if exists)
   - Set updatedAt to current timestamp
5. Reload and refresh the thread list via loadAndSelectThreads()

3. `sendMessage()` Storage Actions

When a user sends a message, Cedar performs these storage operations:

// Cedar's sendMessage storage flow:
1. Add user message to UI via addMessage()
   - addMessage() automatically calls persistMessageStorageMessage()
   - This triggers the persistence flow described above
2. When assistant responds:
   - For non-streaming: Add response via addMessage() (auto-persisted)
   - For streaming:
     - Append content to messages during stream
     - Persist all new messages after stream completes

Best practice: make your load endpoints idempotent. Implementations of listThreads or loadMessages should NOT perform any mutations such as creating threads or messages. Cedar may call these functions multiple times during normal operation; if they create data each time you could end up with duplicated threads or messages.

Automatic Behaviors

Thread & Message Loading:

When storage adapter is set: Adapter is configured but chat initialization happens separately
When user ID or thread ID changes: Triggers initializeChat which:
- Loads all threads for the user
- May auto-select first thread if none selected
- Loads messages for the selected thread
When userId is undefined: Storage operations are skipped entirely
When threadId is undefined: A new UUID is generated during message persistence

User and Thread Management

User ID and thread ID are both stored as Cedar State variables and are automatically sent to the backend for Mastra and Custom backends. See Agent Backend Connection docs for more details.

Setting User ID

User ID is a Cedar State variable that can be set in two ways: Method 1: Initial Configuration (Recommended) Pass the user ID directly to CedarCopilot as a prop. This is the simplest and most common approach:

import { CedarCopilot } from 'cedar-os';

function App({ userId }: { userId: string }) {
	return (
		<CedarCopilot
			userId={userId} // Set user ID in initial configuration
			messageStorage={{
				type: 'local', // or 'none', 'custom'
			}}>
			<YourChatComponent />
		</CedarCopilot>
	);
}

When you pass userId to CedarCopilot, it automatically: - Registers it as a Cedar State variable (null values become empty strings) - Triggers initializeChat which loads threads for that user - Makes it available throughout your app via Cedar State

Method 2: Dynamic Setting via State APIs Use this when you need to change users at runtime (e.g., after login, user switching):

import { setCedarState } from 'cedar-os';

function LoginHandler() {
	const handleLogin = async (credentials) => {
		const user = await loginUser(credentials);

		// Set user ID - Cedar will load this user's threads
		setCedarState('userId', user.id);
	};

	return <LoginForm onSubmit={handleLogin} />;
}

import { useCedarState } from 'cedar-os';

function UserSwitcher() {
	const [userId, setUserId] = useCedarState('userId', null);

	const switchUser = (newUserId: string) => {
		// This will trigger thread reload for the new user
		setUserId(newUserId);
	};

	return (
		<select onChange={(e) => switchUser(e.target.value)}>
			<option value='user-1'>User 1</option>
			<option value='user-2'>User 2</option>
		</select>
	);
}

import { getCedarState } from 'cedar-os';

function CurrentUserDisplay() {
	const userId = getCedarState('userId');

	return <div>Current user: {userId || 'Not logged in'}</div>;
}

When the user ID changes:

Cedar loads threads for the new user
If no thread is selected, may auto-select first thread (if listThreads is implemented)
Messages are cleared and reloaded based on the user’s threads

Setting Thread ID

Thread ID is a Cedar State variable that can be set in three ways: Method 1: Initial Configuration Pass the thread ID directly to CedarCopilot as a prop. This is useful when you want to start with a specific thread:

import { CedarCopilot } from 'cedar-os';

function App({ userId, threadId }: { userId: string; threadId: string }) {
	return (
		<CedarCopilot
			userId={userId}
			threadId={threadId} // Set initial thread ID
			messageStorage={{
				type: 'local',
			}}>
			<YourChatComponent />
		</CedarCopilot>
	);
}

Like userId, threadId is registered as a Cedar State variable with null values converted to empty strings. This triggers initializeChat to load messages for the specified thread.

Method 2: Explicit Setting (User Control) Use this when users manually select threads, navigate to specific conversations, or create new threads at runtime:

import { setCedarState } from 'cedar-os';

function ConversationSwitcher() {
	const switchToThread = (threadId: string) => {
		// Cedar will save current thread and load the new one
		setCedarState('threadId', threadId);
	};

	return (
		<div>
			<button onClick={() => switchToThread('project-discussion')}>
				Project Discussion
			</button>
			<button onClick={() => switchToThread('support-ticket')}>
				Support Ticket
			</button>
		</div>
	);
}

import { useCedarState } from 'cedar-os';

function ConversationManager() {
	const [threadId, setThreadId] = useCedarState('threadId', null);

	return (
		<div>
			<p>Current thread: {threadId || 'No thread selected'}</p>
			<button onClick={() => setThreadId('new-thread-123')}>
				Start New Thread
			</button>
		</div>
	);
}

// From anywhere in your application
import { setCedarState, getCedarState } from 'cedar-os';

// Set a specific thread
setCedarState('threadId', 'thread-abc-123');

// Get current thread
const currentThread = getCedarState('threadId');

// Navigate to a thread from URL params
const threadFromUrl = searchParams.get('thread');
if (threadFromUrl) {
	setCedarState('threadId', threadFromUrl);
}

Method 3: Automatic Selection via listThreads If you implement the listThreads method in your storage adapter, Cedar will automatically select the first available thread when no thread is currently selected. This is perfect for app initialization:

const myStorageAdapter = {
	async listThreads(userId) {
		// Return user's threads from your backend/database
		return [
			{
				id: 'thread-1',
				title: 'General Chat',
				updatedAt: '2024-01-20T10:00:00Z',
			},
			{
				id: 'thread-2',
				title: 'Project Discussion',
				updatedAt: '2024-01-19T15:30:00Z',
			},
		];
	},
	// ... other required methods
};

// When storage adapter is set or threads are loaded:
// - If threadId is null AND threads exist
// - Cedar automatically calls: setCedarState('threadId', threads[0].id)
// - In this example, 'thread-1' would be selected

When the thread ID changes (via any method), Cedar automatically:

Clears the current messages from the UI
Loads messages for the new thread from storage
Updates the UI with the new thread’s messages

Next Steps

Learn about custom message rendering for rich content
Explore streaming responses for real-time interactions
Set up agent backend connections for AI responses

Introduction to Cedar-OS

Getting Started

Connecting to an Agent

Chat

Agentic State

State Diff Management (Beta)

Agent Context

Voice (Beta)

Spells

Advanced Workflows

External Integrations (Coming Soon)

Customising Cedar

Learn more about Cedar ❤️🌳

Components

Changelog

Message Storage Configuration

Quick Start

Storage Options

Additional Configuration Requirements by Storage Type

Local Storage & No Storage

Custom Storage

How Default Message Storage Works

Preconfigured Storage Methods

1. `initializeChat({threadId?: string, userId?: string})`

2. `persistMessageStorageMessage(message)`

3. `sendMessage()` Storage Actions

Automatic Behaviors

User and Thread Management

Setting User ID

Setting Thread ID

Next Steps

​Quick Start

​Storage Options

​Additional Configuration Requirements by Storage Type

​Local Storage & No Storage

​Custom Storage

​How Default Message Storage Works

​Preconfigured Storage Methods

​1. initializeChat({threadId?: string, userId?: string})

​2. persistMessageStorageMessage(message)

​3. sendMessage() Storage Actions

​Automatic Behaviors

​User and Thread Management

​Setting User ID

​Setting Thread ID

​Next Steps

Quick Start

Storage Options

Additional Configuration Requirements by Storage Type

Local Storage & No Storage

Custom Storage

How Default Message Storage Works

Preconfigured Storage Methods

1. `initializeChat({threadId?: string, userId?: string})`

2. `persistMessageStorageMessage(message)`

3. `sendMessage()` Storage Actions

Automatic Behaviors

User and Thread Management

Setting User ID

Setting Thread ID

Next Steps