记忆

在 Astreus 文档中了解记忆，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

具备向量搜索和自动上下文集成能力的持久化对话记忆

概述

记忆(Memory)系统为代理提供长期记忆能力,使其能够记住过去的对话、从交互中学习,并在多个会话之间保持上下文的连续性。启用记忆后,代理会自动存储并检索历史对话中的相关信息,从而带来更加个性化和具备上下文感知能力的体验。

启用记忆

将 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日

本节内容

简介

在 Astreus 文档中了解简介，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

安装

使用 npm、yarn 或 pnpm 安装 Astreus,确认所需的 Node.js 版本,并准备好本地项目以使用该框架构建 AI 代理。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

快速开始

在 Astreus 文档中了解快速开始，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

智能体

在 Astreus 文档中了解智能体，获取用于构建智能体系统的设置指导、API 模式和实用示例。了解构建可靠的 Astreus 智能体系统所需的设置模式、API 和实用示例。

子智能体

上下文