Mémoire Conversationnelle

Gérez l'historique de conversation avec la mémoire session unique et multi-sessions dans Orka AI.

Pourquoi la Mémoire Conversationnelle ?

Les LLMs sont sans état — ils ne se souviennent pas des messages précédents. La mémoire conversationnelle résout ce problème en stockant l'historique du chat et en l'injectant dans chaque nouvelle requête. Orka fournit une gestion automatique de la mémoire avec des stratégies de nettoyage configurables pour rester dans les limites de tokens.

# Mémoire Session Unique

Utilisez la mémoire session unique pour les chatbots simples ou quand vous n'avez besoin de suivre qu'une seule conversation à la fois.

import { Memory } from 'orkajs/memory';
 
const memory = new Memory({
  maxMessages: 50,           // Keep at most 50 messages
  strategy: 'sliding_window' // Trimming strategy
});
 
// Add messages to the conversation
memory.addMessage({ role: 'user', content: 'My name is Alice.' });
memory.addMessage({ role: 'assistant', content: 'Hello Alice! How can I help you today?' });
memory.addMessage({ role: 'user', content: 'What is my name?' });
 
// Get the full history
const history = memory.getHistory();
/*
[
  { role: 'user', content: 'My name is Alice.', timestamp: 1708000000000 },
  { role: 'assistant', content: 'Hello Alice! How can I help you today?', timestamp: 1708000001000 },
  { role: 'user', content: 'What is my name?', timestamp: 1708000002000 }
]
*/
 
// Clear the conversation
memory.clear();

- Méthodes de Memory

addMessage(message: ChatMessage): void

Ajoute un message à la conversation. Applique automatiquement le nettoyage si maxMessages est dépassé.

getHistory(): ChatMessage[]

Retourne l'historique de conversation actuel sous forme de tableau de messages.

clear(): void

Efface tous les messages de l'historique de conversation.

getMessageCount(): number

Retourne le nombre actuel de messages dans la conversation.

# Mémoire Multi-Sessions

Pour les applications multi-utilisateurs (APIs, chatbots servant plusieurs utilisateurs), utilisez SessionMemory pour gérer des conversations séparées par utilisateur/session. Chaque session a sa propre mémoire isolée avec un nettoyage automatique basé sur le TTL.

import { SessionMemory } from 'orkajs/memory';
 
const sessions = new SessionMemory({
  maxMessages: 50,           // Per-session message limit
  strategy: 'sliding_window',
  ttlMs: 3600_000,           // Sessions expire after 1 hour of inactivity
});
 
// User A's conversation
sessions.addMessage('user-alice', { role: 'user', content: 'Hello!' });
sessions.addMessage('user-alice', { role: 'assistant', content: 'Hi Alice!' });
 
// User B's conversation (completely separate)
sessions.addMessage('user-bob', { role: 'user', content: 'Help me with my order.' });
sessions.addMessage('user-bob', { role: 'assistant', content: 'Of course! What is your order ID?' });
 
// Retrieve history by session ID
const aliceHistory = sessions.getHistory('user-alice');
const bobHistory = sessions.getHistory('user-bob');
 
// List all active sessions
console.log(sessions.getActiveSessions()); // ['user-alice', 'user-bob']
 
// Clear a specific session
sessions.clearSession('user-alice');
 
// Clear all sessions
sessions.clearAll();

- Méthodes de SessionMemory

addMessage(sessionId: string, message: ChatMessage): void

Ajoute un message à une session spécifique. Crée la session si elle n'existe pas.

getHistory(sessionId: string): ChatMessage[]

Retourne l'historique de conversation pour une session spécifique.

getActiveSessions(): string[]

Retourne un tableau de tous les IDs de sessions actives.

clearSession(sessionId: string): void

Efface et supprime une session spécifique.

Stratégies de Nettoyage

Quand la conversation devient trop longue, Orka nettoie automatiquement les anciens messages en utilisant l'une des trois stratégies :

Stratégie	Description
sliding_window	Conserve les N messages les plus récents, en préservant les messages système
buffer	Conserve les messages qui tiennent dans le budget de tokens estimé
summary	Compresse les anciens messages en un résumé, préservant le contexte tout en réduisant la taille

💡 Stratégie Summary

La stratégie summary est idéale pour les longues conversations où vous voulez préserver le contexte sans garder tous les messages. Quand le nombre de messages dépasse le seuil, les anciens messages sont compressés en un résumé de message système.

const memory = new Memory({
  strategy: 'summary',
  maxMessages: 20,
  summaryThreshold: 10, // Summarize when 10+ messages overflow
  llm: orka.getLLM(),   // LLM used to generate summaries
});
 
// After 30 messages, the first 10 are compressed into a summary:
// [{ role: 'system', content: 'Summary: User Alice discussed...' }, ...recent 20 messages]

# Configuration

Configurez la mémoire lors de la création de votre instance Orka :

import { createOrka, OpenAIAdapter, MemoryVectorAdapter } from 'orkajs';
 
const orka = createOrka({
  llm: new OpenAIAdapter({ apiKey: process.env.OPENAI_API_KEY! }),
  vectorDB: new MemoryVectorAdapter(),
  memory: {
    maxMessages: 50,           // Maximum messages to keep
    maxTokensEstimate: 4000,   // For 'buffer' strategy
    strategy: 'sliding_window', // 'sliding_window' | 'buffer' | 'summary'
  },
});
 
// Access memory directly
const memory = orka.memory();
memory.addMessage({ role: 'user', content: 'Hello!' });
 
// Or use with ask() - memory is automatically managed
const response = await orka.ask({
  question: 'What did I say earlier?',
  useMemory: true, // Injects conversation history into the prompt
});

- Options de Configuration

maxMessages: number

Nombre maximum de messages à conserver. Les anciens messages sont nettoyés selon la stratégie.

maxTokensEstimate: number

Pour la stratégie 'buffer' : budget de tokens estimé. Les messages sont nettoyés pour tenir.

strategy: 'sliding_window' | 'buffer' | 'summary'

Comment nettoyer les messages quand les limites sont dépassées. Défaut : sliding_window.

ttlMs: number

Pour SessionMemory : durée de vie en millisecondes. Les sessions expirent après cette durée d'inactivité.

Imports Tree-shakeable

// ✅ Import only what you need
import { Memory } from 'orkajs/memory';
import { SessionMemory } from 'orkajs/memory';
 
// ✅ Or import from index
import { Memory, SessionMemory } from 'orkajs/memory';