Memória

Memória de conversação persistente com busca vetorial e integração automática de contexto Aprenda os padrões de configuração, as APIs e os exemplos práticos...

Memória de conversação persistente com busca vetorial e integração automática de contexto

Visão Geral

O sistema de Memória fornece aos agentes capacidades de memória de longo prazo, permitindo que se lembrem de conversas passadas, aprendam com as interações e mantenham o contexto entre sessões. Quando a memória está habilitada, os agentes armazenam e recuperam automaticamente informações relevantes de conversas anteriores, criando uma experiência mais personalizada e ciente do contexto.

Habilitando a Memória

Habilite a memória para um agente definindo a opção memory como 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

Aqui está um exemplo completo mostrando como a memória funciona entre conversas:

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 Memória

Quando a memória está habilitada, os agentes têm acesso a estes métodos de gerenciamento de memória:

// 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ática da Busca por Similaridade

Ao pesquisar memórias usando similaridade vetorial, o sistema calcula pontuações de similaridade entre a consulta e os embeddings de memória:

Pontuação de Similaridade de Cosseno

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

Onde:

$\vec{q}$ é o vetor de embedding da consulta
$\vec{m}$ é o vetor de embedding da memória
O resultado varia de 0 (completamente diferente) a 1 (idêntico)

Pontuação Baseada em Distância

Para métricas de distância, a pontuação de similaridade é calculada como: $\text{score} = \frac{1}{1 + d(\vec{q}, \vec{m})}$

Onde $d$ é a distância euclidiana entre os vetores.

Filtragem por Limiar

As memórias são retornadas apenas se: $\text{similarity} \geq \theta$

Onde $\theta$ é o parâmetro similarityThreshold (padrão: 0.7).

Estrutura do 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 Resposta

Entender o que cada método de memória retorna ajuda a tratar as respostas corretamente em seu código.

Resposta do Objeto Memory

Ao criar ou recuperar memórias, você recebe um 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')
}

Resposta de Lista de Memórias

Os métodos de busca e listagem retornam um 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(...)
  }
]

Resposta de Geração de Embedding

A geração de embedding retorna um objeto detalhado de sucesso/falha:

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

Resposta de Exclusão

Operações de exclusão retornam um booleano indicando sucesso:

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

Resposta de Limpeza de Memórias

Limpar todas as memórias retorna a contagem de itens excluídos:

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

Última atualização: 6 de julho de 2026

Nesta seção

Introdução

Framework de agentes de IA open-source para construir sistemas autônomos que resolvem tarefas do mundo real de forma eficaz.

Instalação

Instale o Astreus com npm, yarn ou pnpm, confirme a versão necessária do Node.js e prepare um projeto local para construir agentes de IA com o framework.

Início Rápido

Construa seu primeiro agente de IA com Astreus em menos de 2 minutos Aprenda os padrões de configuração, as APIs e os exemplos práticos necessários para...

Agente

Entidade central de IA com capacidades modulares e composição baseada em decorators Aprenda os padrões de configuração, as APIs e os exemplos práticos...

Sub-Agentes

Contexto