メモリ

Astreusのドキュメントでメモリについて学び、エージェントシステムを構築するためのセットアップの手引き、APIのパターン、実践的な例を確認しましょう。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

ベクトル検索と自動的なコンテキスト統合を備えた、永続的な会話メモリ

概要

メモリシステムは、エージェントに長期記憶の機能を提供し、過去の会話を記憶し、やり取りから学習し、セッションをまたいでコンテキストを維持できるようにします。メモリが有効になっている場合、エージェントは以前の会話から関連情報を自動的に保存・取得し、よりパーソナライズされたコンテキスト認識型の体験を実現します。

メモリの有効化

memoryオプションをtrueに設定して、エージェントのメモリを有効にします。

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

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

基本的な使い方

会話をまたいでメモリがどのように機能するかを示す、完全な例です。

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

メモリメソッド

メモリが有効な場合、エージェントは次のメモリ管理メソッドを利用できます。

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

類似度検索の数学的背景

ベクトル類似度を使ってメモリを検索する際、システムはクエリとメモリの埋め込み間の類似度スコアを計算します。

コサイン類似度スコア

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

ここで:

$\vec{q}$ はクエリの埋め込みベクトル
$\vec{m}$ はメモリの埋め込みベクトル
結果は0（完全に異なる）から1（同一）の範囲

距離ベースのスコア

距離メトリクスの場合、類似度スコアは次のように計算されます。 $\text{score} = \frac{1}{1 + d(\vec{q}, \vec{m})}$

ここで $d$ はベクトル間のユークリッド距離です。

しきい値によるフィルタリング

メモリは以下の条件を満たす場合にのみ返されます。 $\text{similarity} \geq \theta$

ここで $\theta$ はsimilarityThresholdパラメータです（デフォルト: 0.7）。

メモリオブジェクトの構造

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

レスポンスの型

各メモリメソッドが何を返すかを理解しておくと、コード内でレスポンスを正しく扱えるようになります。

メモリオブジェクトのレスポンス

メモリを作成または取得すると、完全な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オブジェクトの配列を返します。

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

埋め込み生成のレスポンス

埋め込み生成は、詳細な成功/失敗オブジェクトを返します。

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

削除のレスポンス

削除操作は、成功を示すブール値を返します。

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

メモリ全削除のレスポンス

すべてのメモリを削除すると、削除された項目数が返されます。

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

最終更新日: 2026年7月6日

このセクション内

はじめに

実世界のタスクを効果的に解決する自律システムを構築するための、オープンソースAIエージェントフレームワーク。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

インストール

npm、yarn、pnpmでAstreusをインストールし、必要なNode.jsのバージョンを確認して、フレームワークでAIエージェントを構築するためのローカルプロジェクトを準備します。

クイックスタート

Astreusのドキュメントでクイックスタートについて学び、エージェントシステムを構築するためのセットアップの手引き、APIのパターン、実践的な例を確認しましょう。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

エージェント

Astreusのドキュメントでエージェントについて学び、エージェントシステムを構築するためのセットアップの手引き、APIのパターン、実践的な例を確認しましょう。信頼性の高いAstreusエージェントシステムを構築するために必要なセットアップのパターン、API、実践的な例を学びましょう。

サブエージェント

コンテキスト