Mémoire

Mémoire de conversation persistante avec recherche vectorielle et intégration automatique du contexte

Mémoire de conversation persistante avec recherche vectorielle et intégration automatique du contexte

Vue d'ensemble

Le système de Memory dote les agents de capacités de mémoire à long terme, leur permettant de se souvenir des conversations passées, d'apprendre des interactions et de maintenir le contexte entre les sessions. Lorsque la mémoire est activée, les agents stockent et récupèrent automatiquement les informations pertinentes des conversations précédentes, créant une expérience plus personnalisée et contextuelle.

Activer la mémoire

Activez la mémoire pour un agent en définissant l'option memory sur true :

import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'MemoryAgent',
  model: 'gpt-4o',
  memory: true  // Enable persistent memory
});

Utilisation de base

Voici un exemple complet montrant comment la mémoire fonctionne entre les conversations :

import { Agent } from '@astreus-ai/astreus';

// Create an agent with memory
const agent = await Agent.create({
  name: 'PersonalAssistant',
  model: 'gpt-4o',
  memory: true,
  systemPrompt: 'You are a helpful personal assistant who remembers user preferences.'
});

// First conversation
const response1 = await agent.ask('My name is John and I love TypeScript');
console.log(response1);
// Output: "Nice to meet you, John! It's great that you love TypeScript..."

// Later conversation - agent remembers
const response2 = await agent.ask('What programming language do I like?');
console.log(response2);
// Output: "You mentioned that you love TypeScript, John!"

// Memory persists even after restarting
const sameAgent = await Agent.create({
  name: 'PersonalAssistant', // Same name retrieves existing memories
  model: 'gpt-4o',
  memory: true
});

const response3 = await sameAgent.ask('Do you remember my name?');
console.log(response3);
// Output: "Yes, your name is John!"

Méthodes de mémoire

Lorsque la mémoire est activée, les agents ont accès à ces méthodes de gestion de la mémoire :

// Add a memory manually
const memory = await agent.addMemory(
  'Important project information: Budget is $50k',
  { type: 'project', category: 'budget' },  // Optional metadata
  { graphId: 'project-123', taskId: 'task-456', sessionId: 'session-789' }  // Optional context for memory isolation
);

// Remember conversation with role context
const userMemory = await agent.rememberConversation(
  'I prefer TypeScript over JavaScript',
  'user'
);

// Get a specific memory by ID
const existingMemory = await agent.getMemory(memory.id);

// Search memories by content (semantic search with embeddings)
const budgetMemories = await agent.searchMemories('budget', {
  limit: 5,
  startDate: new Date('2024-01-01')
});

// Vector similarity search for semantic matching
const happyMemories = await agent.searchMemoriesBySimilarity('joyful moments', {
  similarityThreshold: 0.7,  // Minimum similarity score
  limit: 10
});

// List all memories with options
const allMemories = await agent.listMemories({
  limit: 20,
  orderBy: 'createdAt',
  order: 'desc'
});

// Update a memory
const updatedMemory = await agent.updateMemory(memory.id, {
  content: 'Updated budget: $75k',
  metadata: { type: 'project', category: 'budget', updated: true }
});

// Delete a specific memory
const deleted = await agent.deleteMemory(memory.id);

// Generate embedding for existing memory (migration/repair)
const result = await agent.generateEmbeddingForMemory(memory.id);
if (result.success) {
  console.log('✅ Embedding generated successfully');
}

// Clear all memories
const deletedCount = await agent.clearMemories();

// Clear memories with options
const deletedCount = await agent.clearMemories({
  syncWithContext: false  // Prevent context synchronization (default: true)
});

Mathématiques de la recherche par similarité

Lors de la recherche de mémoires par similarité vectorielle, le système calcule des scores de similarité entre les embeddings de la requête et de la mémoire :

Score de similarité cosinus

$\text{similarity} = \frac{\vec{q} \cdot \vec{m}}{||\vec{q}|| \cdot ||\vec{m}||} \in [0, 1]$

Où :

$\vec{q}$ est le vecteur d'embedding de la requête
$\vec{m}$ est le vecteur d'embedding de la mémoire
Le résultat varie de 0 (complètement différent) à 1 (identique)

Score basé sur la distance

Pour les métriques de distance, le score de similarité est calculé comme suit : $\text{score} = \frac{1}{1 + d(\vec{q}, \vec{m})}$

Où $d$ est la distance euclidienne entre les vecteurs.

Filtrage par seuil

Les mémoires ne sont retournées que si : $\text{similarity} \geq \theta$

Où $\theta$ est le paramètre similarityThreshold (par défaut : 0.7).

Structure de l'objet Memory

interface Memory {
  id: string;               // Unique memory identifier (UUID)
  agentId: string;          // ID of the owning agent (UUID)
  graphId?: string;         // Graph context (for memory isolation)
  taskId?: string;          // Task context (for memory isolation)
  sessionId?: string;       // Session context (for memory isolation)
  content: string;          // Memory content
  embedding?: number[];     // Vector embedding (auto-generated)
  metadata?: MetadataObject; // Custom metadata
  createdAt: Date;          // When memory was created
  updatedAt: Date;          // Last update time
}

interface MemorySearchOptions {
  limit?: number;           // Max results (default: 10 for search, 100 for list)
  offset?: number;          // Skip results (default: 0)
  pageSize?: number;        // Pagination size for large result sets
  graphId?: string;         // Filter by graph context
  taskId?: string;          // Filter by task context
  sessionId?: string;       // Filter by session context
  orderBy?: 'createdAt' | 'updatedAt' | 'relevance'; // Sort field
  order?: 'asc' | 'desc';   // Sort order (default: 'desc')
  startDate?: Date;         // Filter from date
  endDate?: Date;           // Filter to date
  similarityThreshold?: number; // Similarity threshold (0-1, default: 0.7)
  useEmbedding?: boolean;   // Use embedding search (default: true)
}

Types de réponse

Comprendre ce que chaque méthode de mémoire retourne vous aide à gérer correctement les réponses dans votre code.

Réponse Memory Object

Lors de la création ou de la récupération de mémoires, vous recevez un objet Memory complet :

const memory = await agent.addMemory("User prefers dark mode", {
  type: "preference",
  importance: "high"
});

// Response structure:
{
  id: "550e8400-e29b-41d4-a716-446655440000",  // UUID string
  agentId: "agent-uuid-123",                    // UUID string
  content: "User prefers dark mode",
  embedding: [0.1, 0.2, 0.3, ..., 0.768],      // 1536 dimensions array
  metadata: {
    type: "preference",
    importance: "high"
  },
  createdAt: Date('2024-01-15T10:30:00Z'),
  updatedAt: Date('2024-01-15T10:30:00Z')
}

Réponse Memory List

Les méthodes de recherche et de liste retournent un tableau d'objets Memory :

const memories = await agent.searchMemories("preferences", {
  limit: 5,
  similarityThreshold: 0.7
});

// Response structure:
[
  {
    id: "memory-uuid-1",
    agentId: "agent-uuid",
    content: "User prefers dark mode",
    embedding: [0.1, 0.2, ...],
    metadata: { type: "preference" },
    createdAt: Date(...),
    updatedAt: Date(...)
  },
  {
    id: "memory-uuid-2",
    agentId: "agent-uuid",
    content: "User timezone is PST",
    embedding: [0.15, 0.25, ...],
    metadata: { type: "preference" },
    createdAt: Date(...),
    updatedAt: Date(...)
  }
]

Réponse Generate Embedding

La génération d'embedding retourne un objet détaillé de succès/échec :

const result = await agent.generateEmbeddingForMemory(memory.id);

// Response structure:
{
  success: true,
  message: "Embedding generated successfully",
  embedding: [0.1, 0.2, 0.3, ..., 0.768]  // Optional: included on success
}

// On failure (possible messages):
{
  success: false,
  message: "Memory not found"  // or "Memory already has embedding", "Failed to generate embedding", etc.
}

Réponse Delete

Les opérations de suppression retournent un booléen indiquant le succès :

const deleted = await agent.deleteMemory(memory.id);
// Returns: true or false

Réponse Clear Memories

Effacer toutes les mémoires retourne le nombre d'éléments supprimés :

const deletedCount = await agent.clearMemories();
// Returns: 15 (number of memories deleted)

Dernière mise à jour : 6 juillet 2026

Dans cette section

Introduction

Framework d'agent IA open-source pour construire des systèmes autonomes qui résolvent efficacement des tâches concrètes.

Installation

Installez Astreus avec npm, yarn ou pnpm, vérifiez la version requise de Node.js, et préparez un projet local pour créer des agents IA avec le framework.

Démarrage rapide

Créez votre premier agent IA avec Astreus en moins de 2 minutes Découvrez les schémas de configuration, les API et les exemples pratiques nécessaires pour...

Agent

Entité IA centrale avec des capacités modulaires et une composition basée sur des décorateurs

Sous-agents

Contexte