메모리

벡터 검색과 자동 컨텍스트 통합을 갖춘 영구 대화 메모리

Overview#

메모리 시스템은 에이전트에게 장기 기억 기능을 제공하여 과거 대화를 기억하고, 상호작용에서 학습하고, 세션 간에 컨텍스트를 유지할 수 있게 합니다. 메모리가 활성화되면 에이전트는 이전 대화에서 관련 정보를 자동으로 저장하고 검색하여 더 개인화되고 컨텍스트를 인식하는 경험을 만듭니다.

Enabling Memory#

memory 옵션을 true로 설정하여 에이전트의 메모리를 활성화하세요.

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

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

Basic Usage#

메모리가 대화 전반에 걸쳐 어떻게 작동하는지 보여주는 전체 예제입니다.

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

// Create an agent with memory
const agent = await Agent.create({
  name: 'PersonalAssistant',
  model: 'gpt-6-astra',
  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-6-astra',
  memory: true
});

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

Memory Methods#

메모리가 활성화되면 에이전트는 다음과 같은 메모리 관리 메서드를 사용할 수 있습니다.

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

Similarity Search Mathematics#

벡터 유사도를 사용해 메모리를 검색할 때, 시스템은 쿼리와 메모리 임베딩 간의 유사도 점수를 계산합니다.

Cosine Similarity Score#

similarity=q⃗⋅m⃗∣∣q⃗∣∣⋅∣∣m⃗∣∣∈[0,1]\text{similarity} = \frac{\vec{q} \cdot \vec{m}}{||\vec{q}|| \cdot ||\vec{m}||} \in [0, 1]

Where:

  • q⃗\vec{q}는 쿼리 임베딩 벡터입니다
  • m⃗\vec{m}은 메모리 임베딩 벡터입니다
  • 결과 값은 0(완전히 다름)부터 1(동일함)까지의 범위입니다

Distance-Based Score#

거리 기반 지표의 경우, 유사도 점수는 다음과 같이 계산됩니다. score=11+d(q⃗,m⃗)\text{score} = \frac{1}{1 + d(\vec{q}, \vec{m})}

여기서 dd는 벡터 간의 유클리드 거리입니다.

Threshold Filtering#

메모리는 다음 조건을 만족할 때만 반환됩니다. similarity≥θ\text{similarity} \geq \theta

여기서 θ\theta는 similarityThreshold 매개변수입니다 (기본값: 0.7).

Memory Object Structure#

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

Response Types#

각 메모리 메서드가 무엇을 반환하는지 이해하면 코드에서 응답을 올바르게 처리하는 데 도움이 됩니다.

Memory Object Response#

메모리를 생성하거나 조회할 때, 완전한 Memory 객체를 받습니다.

typescript
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 List Response#

검색 및 목록 조회 메서드는 Memory 객체의 배열을 반환합니다.

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

Generate Embedding Response#

임베딩 생성은 상세한 성공/실패 객체를 반환합니다.

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

Delete Response#

삭제 작업은 성공 여부를 나타내는 불리언 값을 반환합니다.

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

Clear Memories Response#

모든 메모리를 삭제하면 삭제된 항목 수를 반환합니다.

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