Chat History

The History class manages conversation history for Baleybots agents. It stores segments (the canonical UI representation) and derives API messages for LLM calls.

Creating a history

In-memory (default)

import { History } from '@baleybots/core';

const history = History.inMemory();

// With a message limit
const history = History.inMemory(50); // keeps last 50 messages

File-based

import { History } from '@baleybots/core';

const history = History.file('./chat-history.json');

Custom storage

Implement the HistoryStorage interface:

import { History } from '@baleybots/core';
import type { HistoryStorage, StoredHistory } from '@baleybots/core';

class RedisStorage implements HistoryStorage {
  constructor(private redis: RedisClient, private key: string) {}

  async load(): Promise<StoredHistory | null> {
    const data = await this.redis.get(this.key);
    return data ? JSON.parse(data) : null;
  }

  async save(history: StoredHistory): Promise<void> {
    await this.redis.set(this.key, JSON.stringify(history));
  }

  async clear(): Promise<void> {
    await this.redis.del(this.key);
  }
}

const history = new History(new RedisStorage(redis, 'chat:user-123'));

Using history with bot.process()

Pass history via the conversationHistory option:

import { Baleybot, History } from '@baleybots/core';

const bot = Baleybot.create({
  name: 'assistant',
  goal: 'Help users with their questions',
});

const history = History.inMemory();

// First message
const response1 = await bot.process('My name is Alice', {
  conversationHistory: history,
});

// Second message -- the bot remembers the first
const response2 = await bot.process('What is my name?', {
  conversationHistory: history,
});
// "Your name is Alice."

The history automatically records user messages and assistant responses as segments. On each call, it derives the API messages that get sent to the LLM.

Using history with useChat

In React, useChat manages history internally. You can provide a custom storage backend:

import { useChat } from '@baleybots/react';

const { segments, sendStreaming } = useChat({
  model: 'openai|gpt-4.1-mini',
  storage: new RedisStorage(redis, 'chat:user-123'),
});

Storage format

History is stored as a V2 format with segments interleaved:

interface StoredHistory {
  version: 2;
  segments: StreamSegment[];
}

Segments include UserSegment entries (the user's messages) interleaved with assistant segments (TextSegment, ToolCallSegment, etc.), preserving the full conversation flow.