History Store

What is a History Store?

A History Store is the SDK storage layer for conversation messages. The SDK reads from it before each request and appends new user/assistant messages after each response. This is what enables conversation continuity.

Why it matters

Without a history store, each prompt behaves like a fresh session. With a history store, users can resume threads naturally and your assistant can reason with prior context.

Benefits

Conversation resume

Users can leave and continue later with the same conversationId.

Better responses

Prior Q/A context improves coherence and follow-up handling.

Ownership

Conversation storage lives in your infrastructure (Redis/Mongo/custom DB), not in SDK memory.

Pluggable architecture

Swap storage backend without changing request flow in your controllers.

Available history stores

RedisHistoryStore

Fast, TTL-based storage. Good for active sessions and low-latency chat.

MongoHistoryStore

Persistent storage in your Mongo database for long-lived conversation history.

Custom HistoryStore

Implement HistoryStore to use Postgres, DynamoDB, or any internal system.

Note: Saving conversations to a db store instead of redis will allow you to save conversations and reload them on demand for your users. You can have a collection/table that saves the conversationId you generate and the user the conversation belongs to, when the user decides to start a new conversation you create a new entry with a new conversationId and when the user wants to continue an existing conversation, you call the getConversation function with the existing conversationId and the Telygent Ai-sdk will fetch the previous conversation from the 'telygent_conversations' or your specified collection/table.

Usage

Pick one store implementation and pass it to the AI client.

Redis store

history-redis.ts

import {createRedisHistoryStore} from "@telygent/ai-sdk";

const historyStore = createRedisHistoryStore({
  url: process.env.REDIS_URL as string,
  ttlSeconds: 3600,
  prefix: "telygent:conv:",
});

Mongo store

history-mongo.ts

import {MongoClient} from "mongodb";
import {createMongoHistoryStore} from "@telygent/ai-sdk";

const mongoClient = new MongoClient(process.env.MONGO_URI as string);
await mongoClient.connect();
const mongoDb = mongoClient.db(process.env.MONGO_DB_NAME as string);

const historyStore = createMongoHistoryStore({
  db: mongoDb,
  collectionName: "telygent_conversations", // optional
});

// Recommended index:
// db.telygent_conversations.createIndex({conversationId: 1, timestamp: 1});

Attach to client

client.ts

import {createAiClient} from "@telygent/ai-sdk";

const client = createAiClient({
  apiKey: process.env.TELYGENT_API_KEY as string,
  registry,
  dbAdapter,
  historyStore, // Redis, Mongo, or custom
});

const response = await client.query({
  question: "Show me my recent transactions",
  conversationId: "conv_123",
  userContext: {userId: "user_1"},
});

Custom store contract

If you need another provider, implement the HistoryStorecontract. Minimum methods are getMessages and appendMessage.

custom-store.ts

import {type ConversationMessage, type HistoryStore} from "@telygent/ai-sdk";

class CustomHistoryStore implements HistoryStore {
  async getMessages(conversationId: string): Promise<ConversationMessage[]> {
    // Load from your database and return timestamp ASC
    return [];
  }

  async appendMessage(conversationId: string, message: ConversationMessage): Promise<void> {
    // Persist role, content, timestamp and optional metadata
  }
}

Attach custom store to client

custom-client.ts

import {createAiClient} from "@telygent/ai-sdk";

const historyStore = new CustomHistoryStore();

const client = createAiClient({
  apiKey: process.env.TELYGENT_API_KEY as string,
  registry,
  dbAdapter,
  historyStore,
});

Next steps

SDK DB Adapters

Connect your database for local tool execution.

Define your registry

Set allowed fields, required filters and model instructions