Memoria

Memoria de conversación persistente con búsqueda vectorial e integración automática de contexto

Memoria de conversación persistente con búsqueda vectorial e integración automática de contexto

Descripción general

El sistema de Memory dota a los agentes de capacidades de memoria a largo plazo, permitiéndoles recordar conversaciones pasadas, aprender de las interacciones y mantener el contexto entre sesiones. Cuando la memoria está habilitada, los agentes almacenan y recuperan automáticamente información relevante de conversaciones anteriores, creando una experiencia más personalizada y consciente del contexto.

Habilitar la memoria

Habilita la memoria para un agente estableciendo la opción memory en true:

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

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

Uso básico

Aquí tienes un ejemplo completo que muestra cómo funciona la memoria entre conversaciones:

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étodos de memoria

Cuando la memoria está habilitada, los agentes tienen acceso a estos métodos de gestión de memoria:

// 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)
});

Matemáticas de la búsqueda por similitud

Al buscar memorias mediante similitud vectorial, el sistema calcula puntuaciones de similitud entre los embeddings de la consulta y de la memoria:

Puntuación de similitud coseno

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

Donde:

$\vec{q}$ es el vector de embedding de la consulta
$\vec{m}$ es el vector de embedding de la memoria
El resultado varía de 0 (completamente diferente) a 1 (idéntico)

Puntuación basada en distancia

Para las métricas de distancia, la puntuación de similitud se calcula como: $\text{score} = \frac{1}{1 + d(\vec{q}, \vec{m})}$

Donde $d$ es la distancia euclídea entre los vectores.

Filtrado por umbral

Las memorias solo se devuelven si: $\text{similarity} \geq \theta$

Donde $\theta$ es el parámetro similarityThreshold (por defecto: 0.7).

Estructura del objeto 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)
}

Tipos de respuesta

Entender lo que devuelve cada método de memoria te ayuda a manejar las respuestas correctamente en tu código.

Respuesta de objeto Memory

Al crear o recuperar memorias, recibes un objeto Memory completo:

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')
}

Respuesta de lista de memorias

Los métodos de búsqueda y listado devuelven un array de objetos 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(...)
  }
]

Respuesta de generación de embedding

La generación de embeddings devuelve un objeto detallado de éxito/fallo:

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.
}

Respuesta de eliminación

Las operaciones de eliminación devuelven un booleano que indica éxito:

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

Respuesta de limpieza de memorias

Limpiar todas las memorias devuelve el número de elementos eliminados:

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

Última actualización: 6 de julio de 2026

En esta sección

Introducción

Framework de agentes de IA de código abierto para construir sistemas autónomos que resuelven tareas del mundo real de forma eficaz.

Instalación

Instala Astreus con npm, yarn o pnpm, confirma la versión de Node.js requerida y prepara un proyecto local para construir agentes de IA con el framework.

Inicio rápido

Construye tu primer agente de IA con Astreus en menos de 2 minutos Aprende los patrones de configuración, las APIs y los ejemplos prácticos necesarios para...

Agente

Entidad de IA principal con capacidades modulares y composición basada en decoradores Aprende los patrones de configuración, las APIs y los ejemplos...

Sub-agentes

Contexto