Gedächtnis

Persistenter Konversationsspeicher mit Vektorsuche und automatischer Kontextintegration Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen,...

Persistenter Konversationsspeicher mit Vektorsuche und automatischer Kontextintegration

Übersicht

Das Memory-System stattet Agenten mit Langzeitgedächtnis aus, sodass sie sich an vergangene Konversationen erinnern, aus Interaktionen lernen und den Kontext über Sitzungen hinweg beibehalten können. Wenn Memory aktiviert ist, speichern und rufen Agenten automatisch relevante Informationen aus vorherigen Konversationen ab, was eine persönlichere und kontextbewusstere Erfahrung schafft.

Memory aktivieren

Aktiviere Memory für einen Agenten, indem du die Option memory auf true setzt:

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

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

Grundlegende Verwendung

Hier ist ein vollständiges Beispiel, das zeigt, wie Memory über Konversationen hinweg funktioniert:

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!"

Memory-Methoden

Wenn Memory aktiviert ist, haben Agenten Zugriff auf diese Methoden zur Speicherverwaltung:

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

Mathematik der Ähnlichkeitssuche

Bei der Suche nach Memories mittels Vektorähnlichkeit berechnet das System Ähnlichkeitswerte zwischen Query- und Memory-Embeddings:

Cosine-Similarity-Score

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

Dabei gilt:

$\vec{q}$ ist der Query-Embedding-Vektor
$\vec{m}$ ist der Memory-Embedding-Vektor
Das Ergebnis reicht von 0 (völlig unterschiedlich) bis 1 (identisch)

Distanzbasierter Score

Bei Distanzmetriken wird der Ähnlichkeitswert wie folgt berechnet: $\text{score} = \frac{1}{1 + d(\vec{q}, \vec{m})}$

Dabei ist $d$ die euklidische Distanz zwischen den Vektoren.

Schwellenwert-Filterung

Memories werden nur zurückgegeben, wenn: $\text{similarity} \geq \theta$

Dabei ist $\theta$ der Parameter similarityThreshold (Standard: 0.7).

Memory-Objektstruktur

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

Antworttypen

Zu verstehen, was jede Memory-Methode zurückgibt, hilft dir, Antworten in deinem Code korrekt zu verarbeiten.

Memory-Objekt-Antwort

Beim Erstellen oder Abrufen von Memories erhältst du ein vollständiges Memory-Objekt:

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

Memory-Listen-Antwort

Such- und Listenmethoden geben ein Array von Memory-Objekten zurück:

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(...)
  }
]

Embedding-Generierungs-Antwort

Die Embedding-Generierung gibt ein detailliertes Erfolgs-/Fehlerobjekt zurück:

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

Lösch-Antwort

Löschoperationen geben einen booleschen Wert zurück, der den Erfolg anzeigt:

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

Clear-Memories-Antwort

Das Löschen aller Memories gibt die Anzahl der gelöschten Einträge zurück:

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

Zuletzt aktualisiert: 6. Juli 2026

In diesem Abschnitt

Einführung

Open-Source-KI-Agent-Framework zum Erstellen autonomer Systeme, die reale Aufgaben effektiv lösen.

Installation

Installiere Astreus mit npm, yarn oder pnpm, überprüfe die erforderliche Node.js-Version und bereite ein lokales Projekt für die Entwicklung von KI-Agenten...

Schnellstart

Erstelle deinen ersten KI-Agenten mit Astreus in unter 2 Minuten Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du zum Aufbau...

Agent

Zentrale KI-Entität mit modularen Fähigkeiten und dekoratorbasierter Komposition Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du...