메모리
벡터 검색과 자동 컨텍스트 통합을 갖춘 영구 대화 메모리
Overview#
메모리 시스템은 에이전트에게 장기 기억 기능을 제공하여 과거 대화를 기억하고, 상호작용에서 학습하고, 세션 간에 컨텍스트를 유지할 수 있게 합니다. 메모리가 활성화되면 에이전트는 이전 대화에서 관련 정보를 자동으로 저장하고 검색하여 더 개인화되고 컨텍스트를 인식하는 경험을 만듭니다.
Enabling Memory#
memory 옵션을 true로 설정하여 에이전트의 메모리를 활성화하세요.
import { Agent } from '@astreus-ai/astreus';
const agent = await Agent.create({
name: 'MemoryAgent',
model: 'gpt-6-astra',
memory: true // Enable persistent memory
});Basic Usage#
메모리가 대화 전반에 걸쳐 어떻게 작동하는지 보여주는 전체 예제입니다.
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#
메모리가 활성화되면 에이전트는 다음과 같은 메모리 관리 메서드를 사용할 수 있습니다.
// 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#
Where:
- 는 쿼리 임베딩 벡터입니다
- 은 메모리 임베딩 벡터입니다
- 결과 값은 0(완전히 다름)부터 1(동일함)까지의 범위입니다
Distance-Based Score#
거리 기반 지표의 경우, 유사도 점수는 다음과 같이 계산됩니다.
여기서 는 벡터 간의 유클리드 거리입니다.
Threshold Filtering#
메모리는 다음 조건을 만족할 때만 반환됩니다.
여기서 는 similarityThreshold 매개변수입니다 (기본값: 0.7).
Memory Object Structure#
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 객체를 받습니다.
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 객체의 배열을 반환합니다.
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#
임베딩 생성은 상세한 성공/실패 객체를 반환합니다.
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#
삭제 작업은 성공 여부를 나타내는 불리언 값을 반환합니다.
const deleted = await agent.deleteMemory(memory.id);
// Returns: true or falseClear Memories Response#
모든 메모리를 삭제하면 삭제된 항목 수를 반환합니다.
const deletedCount = await agent.clearMemories();
// Returns: 15 (number of memories deleted)