@ai.ntellect/core 1.0.0 → 1.1.0

package/docs/modules/agenda/les-adaptateurs/README.md

@@ -0,0 +1,237 @@
+---
+description: >-
+  Un adaptateur d’Agenda est un composant permettant de gérer la persistance et
+  la récupération des tâches planifiées selon le moteur de stockage sous-jacent.
+---
+
+# Les adaptateurs
+
+### **Qu’est-ce qu’un adaptateur Agenda ?**
+
+Un **adaptateur Agenda** est un composant permettant de gérer **la planification et la persistance des tâches planifiées** en fonction du moteur sous-jacent.
+
+Il encapsule :
+
+* **Le moteur d'exécution des tâches** (**ICronService**) : responsable du déclenchement effectif des tâches.
+* **Le moteur de stockage des tâches** (**IMemoryAdapter**) : garantit la persistance et la récupération des tâches planifiées.
+
+Grâce aux adaptateurs, **l’agent peut changer de moteur sans modifier sa logique métier**.
+
+***
+
+### **Fonctionnement des adaptateurs Agenda**
+
+Tous les adaptateurs doivent implémenter **deux interfaces clés** :
+
+#### **ICronService : Gestion de l'exécution des tâches**
+
+```ts
+/**
+ * Interface pour le service de planification des tâches
+ */
+export interface ICronService {
+  /**
+   * Planifie une tâche en utilisant une expression cron.
+   * @param {string} expression - Expression cron définissant l’exécution
+   * @param {Function} callback - Fonction exécutée lors du déclenchement
+   * @returns {ICronJob} Interface de gestion de la tâche
+   */
+  schedule(expression: string, callback: () => void): ICronJob;
+}
+
+/**
+ * Interface pour contrôler une tâche planifiée
+ */
+export interface ICronJob {
+  /**
+   * Démarre la tâche planifiée
+   */
+  start(): void;
+
+  /**
+   * Arrête la tâche planifiée
+   */
+  stop(): void;
+}
+```
+
+#### **IMemoryAdapter : Persistance des tâches planifiées**
+
+```ts
+/**
+ * Interface pour la gestion de la persistance des tâches d'Agenda
+ */
+export interface IMemoryAdapter {
+  init(roomId?: string): Promise<void>;
+
+  saveJob(id: string, job: ICronJob): Promise<void>;
+  saveRequest(id: string, request: ScheduledRequest): Promise<void>;
+
+  getJob(id: string): Promise<ICronJob | undefined>;
+  getRequest(id: string): Promise<ScheduledRequest | undefined>;
+
+  deleteJob(id: string): Promise<void>;
+  deleteRequest(id: string): Promise<void>;
+
+  getAllRequests(): Promise<ScheduledRequest[]>;
+  clear(): Promise<void>;
+}
+```
+
+Ainsi, **les adaptateurs permettent d'intégrer plusieurs moteurs sans modifier l'agent.**
+
+***
+
+### **Adaptateurs intégrés (par défaut)**
+
+Le framework propose plusieurs adaptateurs intégrés.
+
+#### **1. NodeCronAdapter (exécution des tâches)**
+
+* Basé sur la bibliothèque **node-cron**.
+* Idéal pour **exécuter des tâches en local sans dépendance externe**.
+
+```ts
+import cron from "node-cron";
+import { ICronJob, ICronService } from "../../../../interfaces";
+
+/**
+ * @module NodeCronAdapter
+ * @description Adaptateur utilisant node-cron pour exécuter des tâches planifiées.
+ */
+export class NodeCronAdapter implements ICronService {
+  schedule(expression: string, callback: () => void): ICronJob {
+    const job = cron.schedule(expression, callback);
+
+    return {
+      start: () => job.start(),
+      stop: () => job.stop(),
+    };
+  }
+}
+```
+
+***
+
+#### **2. InMemoryAdapter (stockage en mémoire)**
+
+* Stocke les tâches planifiées **en RAM** via une `Map`.
+* **Non persistant** : les tâches sont perdues après un redémarrage.
+* Idéal pour **les tests et le prototypage**.
+
+```ts
+import { IMemoryAdapter } from "../../../../interfaces";
+import { ScheduledRequest } from "../../../../types";
+
+/**
+ * @module InMemoryAdapter
+ * @description Adaptateur mémoire stockant les tâches planifiées en RAM.
+ */
+export class InMemoryAdapter implements IMemoryAdapter {
+  private storage: Map<string, ScheduledRequest> = new Map();
+
+  async saveRequest(id: string, request: ScheduledRequest): Promise<void> {
+    this.storage.set(id, request);
+  }
+
+  async getRequest(id: string): Promise<ScheduledRequest | undefined> {
+    return this.storage.get(id);
+  }
+
+  async deleteRequest(id: string): Promise<void> {
+    this.storage.delete(id);
+  }
+
+  async getAllRequests(): Promise<ScheduledRequest[]> {
+    return Array.from(this.storage.values());
+  }
+
+  async clear(): Promise<void> {
+    this.storage.clear();
+  }
+}
+```
+
+***
+
+### **Créer un nouvel adaptateur : Exemple avec Redis**
+
+Si on veut **persister les tâches avec Redis**, on peut créer un nouvel adaptateur.
+
+#### **1. Installer la dépendance**
+
+```sh
+npm install ioredis
+```
+
+#### **2. Implémenter l’adaptateur**
+
+```ts
+import { IMemoryAdapter } from "../../../../interfaces";
+import Redis from "ioredis";
+import { ScheduledRequest } from "../../../../types";
+
+/**
+ * @module RedisAdapter
+ * @description Adaptateur stockant les tâches planifiées dans Redis.
+ */
+export class RedisAdapter implements IMemoryAdapter {
+  private redis: Redis;
+
+  constructor(redisUrl: string) {
+    this.redis = new Redis(redisUrl);
+  }
+
+  async saveRequest(id: string, request: ScheduledRequest): Promise<void> {
+    await this.redis.set(id, JSON.stringify(request));
+  }
+
+  async getRequest(id: string): Promise<ScheduledRequest | undefined> {
+    const data = await this.redis.get(id);
+    return data ? JSON.parse(data) : undefined;
+  }
+
+  async deleteRequest(id: string): Promise<void> {
+    await this.redis.del(id);
+  }
+
+  async getAllRequests(): Promise<ScheduledRequest[]> {
+    const keys = await this.redis.keys("*");
+    const requests = await Promise.all(keys.map((key) => this.getRequest(key)));
+    return requests.filter((req) => req !== undefined) as ScheduledRequest[];
+  }
+
+  async clear(): Promise<void> {
+    await this.redis.flushall();
+  }
+}
+```
+
+***
+
+### **Intégrer un adaptateur dans l’Agenda**
+
+Une fois l’adaptateur Redis implémenté, on peut l’intégrer **dans le module Agenda**.
+
+```ts
+import { Agenda } from "../modules/agenda";
+import { NodeCronAdapter } from "../modules/agenda/adapters/cron/node-cron";
+import { RedisAdapter } from "../modules/memory/adapters/redis";
+
+// Initialisation avec Redis et NodeCron
+const cronService = new NodeCronAdapter();
+const jobStorage = new RedisAdapter("redis://localhost:6379");
+const agenda = new Agenda(cronService, jobStorage);
+
+async function run() {
+  await agenda.scheduleRequest({
+    originalRequest: "Générer un rapport",
+    cronExpression: "0 9 * * *",
+  });
+
+  const tasks = await agenda.getScheduledRequests();
+  console.log("Tâches planifiées :", tasks);
+}
+
+run();
+```

package/docs/modules/agenda/les-adaptateurs/nodecronadapter.md

@@ -0,0 +1,91 @@
+---
+description: >-
+  Le NodeCronAdapter est utilise bibliothèque node-cron pour exécuter des tâches
+  à intervalles réguliers.
+---
+
+# NodeCronAdapter
+
+`NodeCronAdapter` est une implémentation de l’interface `ICronService` basée sur **node-cron**. Il permet d’exécuter des tâches planifiées selon des expressions cron standards. Cet adaptateur est conçu pour gérer des actions récurrentes sans nécessiter de persistance ni de gestion avancée des exécutions.
+
+Ce type d’adaptateur est particulièrement utile pour les tâches légères et autonomes, telles que la mise à jour de caches, l’exécution périodique de requêtes ou la maintenance automatique.
+
+***
+
+### **Spécificités techniques de NodeCronAdapter**
+
+**Encapsulation de node-cron**
+
+L’adaptateur encapsule `node-cron` en exposant une interface conforme à `ICronService`. Il simplifie l’utilisation en garantissant que chaque tâche planifiée retourne un objet contrôlable avec `start()` et `stop()`.
+
+```ts
+schedule(expression: string, callback: () => void): ICronJob {
+  const job = cron.schedule(expression, callback);
+  return {
+    start: () => job.start(),
+    stop: () => job.stop(),
+  };
+}
+```
+
+Cela permet d’abstraire `node-cron` et de **remplacer l’implémentation sous-jacente** si nécessaire, sans modifier le reste de l’application.
+
+***
+
+## **Démarrage et arrêt des tâches**
+
+Lorsqu’un job est programmé, il est créé en **état stoppé** par défaut, puis activé via `start()`. Cela permet d’éviter des exécutions accidentelles avant une configuration complète.
+
+```ts
+const job = cron.schedule(expression, callback);
+job.stop(); // S'assure que le job ne démarre pas immédiatement
+```
+
+L’arrêt d’un job via `stop()` suspend son exécution jusqu’à un nouvel appel à `start()`. Cela permet de **désactiver temporairement des tâches** sans les recréer.
+
+***
+
+#### **Limitations et considérations**
+
+#### **Dépendance à node-cron**
+
+L’adaptateur repose entièrement sur **node-cron**, qui fonctionne uniquement sous **Node.js**. Il ne peut pas être utilisé directement **dans un navigateur ou un environnement sans accès au runtime Node.js**.
+
+#### **Planification limitée aux expressions cron**
+
+NodeCronAdapter **ne gère que les expressions cron classiques**. Contrairement à d’autres gestionnaires comme **Agenda.js ou BullMQ**, il ne prend pas en charge :
+
+* La persistance des tâches.
+* La gestion des échecs avec retries.
+* Le chaînage dynamique d’exécutions.
+
+Si ces fonctionnalités sont nécessaires, un gestionnaire plus avancé peut être requis.
+
+#### **Non persistant**
+
+Les tâches planifiées existent uniquement **en mémoire** et **sont perdues en cas de redémarrage du serveur**.\
+Si une **reprise après redémarrage** est nécessaire, les tâches doivent être **stockées en base de données** et **rechargées** au démarrage.
+
+**Solution** : Stocker les jobs dans une base externe (Redis, SQLite) et les restaurer au lancement de l’application.
+
+#### **Précision limitée**
+
+Node-cron **ne garantit pas une exécution milliseconde-précise**.
+
+* Il repose sur **l’horloge système**, donc son exécution peut être affectée par **la charge CPU**.
+* Dans un environnement **serverless** (AWS Lambda, Cloud Functions), des retards peuvent apparaître si l’instance est mise en veille.
+
+Pour des tâches nécessitant **une exécution strictement précise**, une alternative comme **Systemd Timers, Quartz Scheduler ou Celery** peut être plus adaptée.
+
+***
+
+### **Cas d’usage adaptés**
+
+**`NodeCronAdapter`** est une solution efficace pour : 
+
+* **Exécuter des tâches légères** sans persistance.
+* **Rafraîchir des caches** périodiquement.
+* **Automatiser des mises à jour de données**.
+* **Gérer des workflows simples** nécessitant des intervalles définis.
+
+Cependant, pour une gestion avancée (reprise après crash, files d’attente, monitoring), des solutions comme **BullMQ, Agenda.js ou Redis-based task queues** sont recommandées.

package/docs/modules/introduction.md

@@ -0,0 +1,55 @@
+# Modular Extensions
+
+`@ai.ntellect/core` is built on a **Pluggable Architecture**. While the core engine handles GraphFlows and Petri Nets, specialized capabilities are provided via **Modules**.
+
+## 🧩 What is a Module?
+
+A module is an optional, independent component that extends the framework's capabilities. Instead of bloating the core engine, we use a **Service-Adapter pattern** to ensure that modules are:
+- **Swappable**: Change your database or NLP provider without touching your workflow logic.
+- **Optional**: Only include the modules your specific agent needs.
+- **Testable**: Each module has a single responsibility and a clean interface.
+
+---
+
+## 🛠️ Available Modules
+
+### 1. Memory System
+Handles the persistence and retrieval of data. It's the "long-term brain" of your agent.
+- **Core Interface**: `IMemoryAdapter`
+- **Adapters**: 
+  - `InMemoryAdapter`: Fast, volatile storage for testing.
+  - `RedisAdapter`: Distributed, high-performance persistence.
+  - `MeilisearchAdapter`: Full-text and semantic search for RAG.
+
+### 2. Agenda (Scheduling)
+Adds a temporal dimension to your agents. Instead of just reacting to users, your agent can **act on its own**.
+- **Core Interface**: `ICronService`
+- **Capabilities**: 
+  - Schedule a `GraphFlow` to run every Monday at 9 AM.
+  - Trigger a "follow-up" node 24 hours after a user interaction.
+  - Manage recurring maintenance tasks.
+
+### 3. NLP Engine
+Provides lightweight natural language processing for tasks that don't require a full LLM call (saving latency and cost).
+- **Capabilities**: Sentiment analysis, entity extraction, and keyword classification.
+- **Integration**: Used as a standard `GraphNode` within a workflow.
+
+---
+
+## 📐 Design Principles
+
+### Dependency Inversion (IoC)
+Modules never depend on a specific technology. They depend on **Interfaces**.
+For example, the `Memory` module doesn't know about Redis; it knows about `IMemoryAdapter`. You inject the adapter at runtime:
+
+```typescript
+const memory = new Memory(new RedisAdapter({ url: "redis://localhost:6379" }));
+```
+
+### Synergy with GraphFlow
+Modules are designed to be called from within `GraphNodes`. 
+- A node can save a result to **Memory**.
+- A node can schedule a future run via the **Agenda**.
+- A node can classify a string using the **NLP** module.
+
+**This creates a powerful loop: LLM classifies $\rightarrow$ GraphFlow executes $\rightarrow$ Modules persist/schedule.**

package/docs/modules/les-adaptateurs.md

@@ -0,0 +1,52 @@
+---
+description: Dans @ai.ntellect/core, chaque module dispose d'adaptateurs par défaut.
+---
+
+# Les adaptateurs
+
+Les modules de `@ai.ntellect/core` proposent des **adaptateurs par défaut** qui couvrent les besoins les plus fréquents. Mais l’architecture du framework permet également de créer et brancher des adaptateurs personnalisés, implémentés en dehors du code source principal.
+
+### Pourquoi des adaptateurs
+
+Le concept d’« adaptateur » sert à séparer la **logique métier** (la logique du module lui-même) de l’**implémentation technique** (accès à une base de données, intégration avec un service de planification, etc.). Un module définit une **interface** (ex. `IMemoryAdapter`, `ICronService`), et chaque adaptateur s’engage à respecter cette interface. Ainsi, on peut :
+
+• Basculer d’un backend à un autre (ex. passer de « in-memory » à « redis ») sans réécrire toute l’application.\
+• Développer un adaptateur pour un service ou une base particulière (cloud SaaS, interne à l’entreprise) sans forker ou modifier le cœur du module.
+
+### Adaptateurs par défaut
+
+Les adaptateurs par défaut sont inclus dans le dossier `adapters/` de chaque module. Parmi les exemples courants :
+
+• In-memory (pratique pour les tests et les prototypes)\
+• node-cron (permet de planifier des tâches en local)\
+• redis ou meilisearch (assure la persistance pour un module Memory)
+
+Ces adaptateurs offrent une solution standard prête à l’emploi, et servent aussi de référence pour comprendre comment en créer d’autres.
+
+### Création d’un adaptateur externe
+
+Si aucun adaptateur par défaut ne répond aux besoins d’une application, il est possible de développer un adaptateur externe dans un projet distinct. 
+
+L’essentiel est de se conformer à l’interface attendue par le module. 
+
+Par exemple, un module Memory attend un `IMemoryAdapter` qui définisse les méthodes de création, lecture, suppression, etc. 
+
+Une fois l’adaptateur codé :
+
+• Il peut être testé et validé de façon indépendante (tests unitaires ciblés).\
+• Il est ensuite injecté au module (par exemple, `new Memory(myCustomAdapter)`).\
+• L’ensemble du code client continuera de fonctionner normalement, car il dépend de l’interface, pas de l’implémentation sous-jacente.
+
+### Intérêt de la modularité
+
+Grâce à la logique d’adaptateurs, chaque module demeure décorrélé de la technologie employée : un nœud GraphFlow ou un agent IA peut appeler le module Memory ou l’Agenda sans connaître les détails du backend. 
+
+Les bénéfices principaux sont :
+
+• Flexibilité : on peut démarrer en mode simple (in-memory) et évoluer vers une base plus robuste (redis, SaaS externe) quand le besoin se fait sentir.\
+• Maintenabilité : si un adaptateur est défaillant ou nécessite une optimisation, on corrige cette partie sans toucher à la logique métier du module.\
+• Personnalisation : toute entreprise ayant un service interne (base de données, moteur d’indexation, service de scheduling) peut l’intégrer en codant un adaptateur conforme à l’interface requise.
+
+### En résumé
+
+Les adaptateurs, qu’ils soient **par défaut** (inclus dans le framework) ou **externes** (développés spécifiquement pour un cas d’usage), offrent une **souplesse** et une **extensibilité** essentielles. En respectant l’interface imposée par le module, il devient possible de changer ou d’ajouter de nouvelles implémentations sans affecter le reste de l’application, ni le cœur du framework. C’est là un élément clé de la philosophie modulaire de `@ai.ntellect/core`.

package/docs/modules/memoire/README.md

@@ -0,0 +1,68 @@
+# Module Mémoire
+
+Persistance de données pour les agents.
+
+## Utilisation
+
+```typescript
+import { Memory } from "@ai.ntellect/core";
+import { InMemoryAdapter } from "@ai.ntellect/core/modules/memory/adapters/in-memory";
+
+const memory = new Memory(new InMemoryAdapter());
+await memory.init();
+
+// Sauvegarder
+await memory.save("my_key", { data: "hello" });
+
+// Récupérer
+const result = await memory.recall("my_key");
+
+// Supprimer
+await memory.delete("my_key");
+```
+
+## Adaptateurs
+
+| Adaptateur | Description |
+|------------|-------------|
+| `InMemoryAdapter` | Stockage en mémoire (volatile) |
+| `RedisAdapter` | Redis pour persistance |
+| `MeilisearchAdapter` | Recherche vectorielle |
+
+## Redis
+
+```typescript
+import { RedisAdapter } from "@ai.ntellect/core/modules/memory/adapters/redis";
+
+const memory = new Memory(
+  new RedisAdapter({
+    host: "localhost",
+    port: 6379,
+  })
+);
+await memory.init();
+```
+
+## Meilisearch
+
+```typescript
+import { MeilisearchAdapter } from "@ai.ntellect/core/modules/memory/adapters/meilisearch";
+
+const memory = new Memory(
+  new MeilisearchAdapter({
+    apiKey: "your_key",
+    host: "http://localhost:7700",
+  })
+);
+await memory.init();
+```
+
+## API
+
+```typescript
+memory.init(): Promise<void>
+memory.save(key: string, data: any): Promise<void>
+memory.recall(key: string): Promise<any>
+memory.delete(key: string): Promise<void>
+memory.clear(): Promise<void>
+```

package/docs/modules/memoire/interface-imemory.md

@@ -0,0 +1,183 @@
+---
+description: >-
+  L'interface IMemory définit une abstraction pour stocker, rechercher et gérer
+  des entrées mémorielles
+---
+
+# Interface IMemory
+
+L'interface `IMemory` définit une abstraction pour **stocker, rechercher et gérer des entrées mémorielles** dans un environnement où un agent doit retenir des informations sur le long terme ou pour des sessions temporaires.
+
+Ce module suit une **approche modulaire et agnostique** du backend, permettant d’être implémenté avec différents moteurs de stockage :
+
+* **Stockage en mémoire** (`InMemoryAdapter`)
+* **Base de données** (`MeilisearchAdapter`, `RedisAdapter`, `PostgreSQLAdapter`)
+* **Stockage distribué** (`VectorDBAdapter`, `PineconeAdapter`)
+
+***
+
+### **Objectif de l'interface**
+
+L'interface `IMemory` doit permettre :
+
+* **Le stockage structuré et sécurisé d'informations** persistantes ou temporaires.
+* **Une récupération rapide** avec support des **requêtes sémantiques** (recherche par similarité).
+* **La gestion dynamique du cycle de vie des mémoires** (création, expiration, suppression).
+* **L’adaptabilité à différents backends**, grâce aux `IMemoryAdapter` interchangeables.
+
+***
+
+### **Définition de l’interface**
+
+```typescript
+/**
+ * Interface pour la gestion de la mémoire d'un agent
+ */
+export interface IMemory {
+  /**
+   * Initialise le service mémoire avec les configurations requises
+   * @returns {Promise<void>}
+   */
+  init(): Promise<void>;
+
+  /**
+   * Crée une nouvelle entrée mémoire.
+   * @param {MemoryInput} input - Données de la mémoire à enregistrer.
+   * @returns {Promise<MemoryEntry | undefined>} Retourne l’entrée créée, ou `undefined` en cas d’échec.
+   */
+  createMemory(input: MemoryInput): Promise<MemoryEntry | undefined>;
+
+  /**
+   * Récupère une entrée mémoire par son identifiant.
+   * @param {string} id - Identifiant unique de la mémoire.
+   * @param {string} roomId - Identifiant de la session ou du contexte.
+   * @returns {Promise<MemoryEntry | null>} Retourne l'entrée mémoire si trouvée, sinon `null`.
+   */
+  getMemoryById(id: string, roomId: string): Promise<MemoryEntry | null>;
+
+  /**
+   * Effectue une recherche d’entrées mémoire selon une requête textuelle.
+   * @param {string} query - Texte de la requête.
+   * @param {MemorySearchOptions} options - Options de recherche.
+   * @returns {Promise<MemoryEntry[]>} Retourne une liste d'entrées mémorielles correspondantes.
+   */
+  searchMemory(
+    query: string,
+    options: MemorySearchOptions
+  ): Promise<MemoryEntry[]>;
+
+  /**
+   * Récupère toutes les mémoires associées à un `roomId`.
+   * @param {string} roomId - Identifiant de la session.
+   * @returns {Promise<MemoryEntry[]>} Liste des entrées mémorielles.
+   */
+  getAllMemories(roomId: string): Promise<MemoryEntry[]>;
+
+  /**
+   * Supprime une entrée mémoire spécifique.
+   * @param {string} id - Identifiant de la mémoire.
+   * @param {string} roomId - Identifiant de la session.
+   * @returns {Promise<void>}
+   */
+  deleteMemoryById(id: string, roomId: string): Promise<void>;
+
+  /**
+   * Supprime toutes les entrées mémorielles d'un `roomId`.
+   * @param {string} roomId - Identifiant de la session.
+   * @returns {Promise<void>}
+   */
+  clearMemories(roomId: string): Promise<void>;
+}
+```
+
+***
+
+### **Interfaces associées**
+
+#### **1. `MemoryInput` : Données pour une nouvelle entrée mémoire**
+
+Lorsqu’une nouvelle mémoire est créée, elle doit suivre une structure bien définie.
+
+```typescript
+/**
+ * Données nécessaires pour créer une mémoire
+ */
+export interface MemoryInput {
+  /** Identifiant unique de la mémoire (optionnel, généré si absent) */
+  id?: string;
+  /** Contenu textuel de la mémoire */
+  data: string;
+  /** Identifiant de la session ou du contexte */
+  roomId: string;
+  /** (Optionnel) Vecteur d’embedding pour recherche sémantique */
+  embedding?: number[];
+  /** Date d’expiration (TTL) */
+  expiresAt?: Date;
+}
+```
+
+#### **2. `MemoryEntry` : Représentation d’une mémoire stockée**
+
+Une mémoire active stockée doit être représentée sous cette forme.
+
+```typescript
+/**
+ * Représentation d'une mémoire stockée
+ */
+export interface MemoryEntry extends MemoryInput {
+  /** Identifiant unique attribué à la mémoire */
+  id: string;
+  /** Date de création de la mémoire */
+  createdAt: Date;
+}
+```
+
+#### **3. `MemorySearchOptions` : Options de recherche avancées**
+
+La recherche mémoire peut inclure des critères supplémentaires pour affiner les résultats.
+
+```typescript
+/**
+ * Options de recherche pour requêtes mémoire
+ */
+export interface MemorySearchOptions {
+  /** Identifiant du contexte de recherche */
+  roomId: string;
+  /** Nombre maximal de résultats */
+  limit?: number;
+  /** Score minimal de similarité si une recherche sémantique est utilisée */
+  minSimilarity?: number;
+}
+```
+
+***
+
+### **Pourquoi cette interface ?**
+
+L’interface `IMemory` permet une **gestion optimisée et évolutive** des données mémoire :
+
+1. **Abstraction complète du moteur de stockage**
+   * Permet d’implémenter `IMemory` avec **n’importe quel backend** (`Redis`, `PostgreSQL`, `VectorDB`, etc.).
+   * Découple la **logique métier** de la **logique de persistance**.
+2. **Support des recherches sémantiques**
+   * Les données peuvent être indexées sous forme de **vecteurs** (`embedding`).
+   * Permet des recherches avancées **par similarité** et non uniquement par mots-clés.
+3. **Modèle flexible et dynamique**
+   * Gestion **multi-sessions (`roomId`)** pour segmenter la mémoire selon les contextes.
+   * Prise en charge d’un **TTL** (`expiresAt`) pour éviter l’accumulation inutile de données.
+4. **Extensibilité via des adaptateurs (`IMemoryAdapter`)**
+   * Compatible avec **des moteurs de stockage externes** (`Meilisearch`, `Pinecone`, etc.).
+   * Possibilité d’intégrer **plusieurs sources de mémoire** (ex: mémoire immédiate + historique long-terme).
+
+***
+
+### **Cas d’usage**
+
+L’interface `IMemory` peut être utilisée dans plusieurs scénarios :
+
+| **Cas d'usage**                   | **Exemple**                                                      |
+| --------------------------------- | ---------------------------------------------------------------- |
+| Stockage d’historique utilisateur | Mémorisation des interactions d’un chatbot avec un utilisateur.  |
+| Recherche sémantique              | Trouver des documents ou réponses similaires à une requête.      |
+| Maintien du contexte              | Conserver un état conversationnel pour un agent autonome.        |
+| Mémoire dynamique                 | Stocker temporairement des informations utiles dans un `roomId`. |