> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Memory 类

`Memory` class 为 Mastra 中的对话历史记录管理和基于 thread 的消息存储提供了可靠的系统。它支持对话持久化存储、语义搜索和高效的消息检索。你必须为对话历史记录配置 storage provider；如果启用 semantic recall，还需要提供 vector store 和 embedder。

## 使用示例

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'

export const agent = new Agent({
  id: 'test-agent',
  name: 'test-agent',
  instructions: 'You are an agent with memory.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    options: {
      workingMemory: {
        enabled: true,
      },
    },
  }),
})
```

> **备注:** 要在 Agent 上启用 `workingMemory`，需要在主 Mastra 实例上配置 storage provider。有关更多信息，请参阅 [Mastra class](https://mastra.zisheng.pro/reference/core/mastra-class)。

## 构造函数参数

**storage** (`MastraCompositeStore`): 用于持久化 memory 数据的存储实现。如果未提供，则默认为 new DefaultStorage({ config: { url: "file:memory.db" } })。

**vector** (`MastraVector | false`): 用于语义搜索的 vector store。设为 false 可禁用向量操作。

**embedder** (`EmbeddingModel<string> | EmbeddingModelV2<string>`): 用于向量嵌入的 embedder 实例。启用 semantic recall 时必需。

**options** (`MemoryConfig`): Memory 配置选项。

**options.lastMessages** (`number | false`): 要包含在上下文中的最近消息数量。设为 false 可完全禁用消息历史记录功能（消息既不会加载到上下文中，也不会保存）。使用 Number.MAX\_SAFE\_INTEGER 可无限制地检索所有消息。若只加载消息而不保存新消息，请使用 readOnly 选项。

**options.readOnly** (`boolean`): 为 true 时，阻止 memory 保存新消息，并将 working memory 作为只读上下文提供（不提供 updateWorkingMemory tool）。适用于预览、内部路由 Agent，或应引用但不修改 memory 的 sub-agent 等只读操作。

**options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): 在消息历史记录中启用语义搜索。可以是布尔值或包含配置选项的对象。启用后，需要同时配置 vector store 和 embedder。topK 默认为 4，messageRange 默认为 {before: 1, after: 1}。

**options.workingMemory** (`WorkingMemory`): Working memory 功能的配置。可以是 { enabled: boolean; template?: string; schema?: ZodObject\<any> | JSONSchema7; scope?: 'thread' | 'resource' }，也可以是用于禁用的 { enabled: boolean }。

**options.observationalMemory** (`boolean | ObservationalMemoryOptions`): 为长上下文 Agent memory 启用 Observational Memory。设为 true 可使用默认设置，也可以传入配置对象来自定义 token 预算、模型和作用域。配置详情请参阅 Observational Memory 参考文档。

**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): 控制根据对话转录自动生成 thread 标题。可以是布尔值，也可以是包含自定义模型和 instructions 的对象。

## 返回值

**memory** (`Memory`): 采用指定配置的新 Memory 实例。

## 扩展使用示例

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { LibSQLStore, LibSQLVector } from '@mastra/libsql'

export const agent = new Agent({
  name: 'test-agent',
  instructions: 'You are an agent with memory.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new LibSQLStore({
      id: 'test-agent-storage',
      url: 'file:./working-memory.db',
    }),
    vector: new LibSQLVector({
      id: 'test-agent-vector',
      url: 'file:./vector-memory.db',
    }),
    options: {
      lastMessages: 10,
      semanticRecall: {
        topK: 3,
        messageRange: 2,
        scope: 'resource',
      },
      workingMemory: {
        enabled: true,
      },
      generateTitle: true,
    },
  }),
})
```

## 配置索引的 PostgreSQL

```typescript
import { Memory } from '@mastra/memory'
import { Agent } from '@mastra/core/agent'
import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
import { PgStore, PgVector } from '@mastra/pg'

export const agent = new Agent({
  name: 'pg-agent',
  instructions: 'You are an agent with optimized PostgreSQL memory.',
  model: 'openai/gpt-5.6-sol',
  memory: new Memory({
    storage: new PgStore({
      id: 'pg-agent-storage',
      connectionString: process.env.DATABASE_URL,
    }),
    vector: new PgVector({
      id: 'pg-agent-vector',
      connectionString: process.env.DATABASE_URL,
    }),
    embedder: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
    options: {
      lastMessages: 20,
      semanticRecall: {
        topK: 5,
        messageRange: 3,
        scope: 'resource',
        indexConfig: {
          type: 'hnsw', // Use HNSW for better performance
          metric: 'dotproduct', // Optimal for OpenAI embeddings
          m: 16, // Number of bi-directional links
          efConstruction: 64, // Construction-time candidate list size
        },
      },
      workingMemory: {
        enabled: true,
      },
    },
  }),
})
```

### 相关

- [Memory 入门](https://mastra.zisheng.pro/docs/memory/overview)
- [语义召回](https://mastra.zisheng.pro/docs/memory/semantic-recall)
- [Working Memory](https://mastra.zisheng.pro/docs/memory/working-memory)
- [Observational Memory](https://mastra.zisheng.pro/docs/memory/observational-memory)
- [Memory Processor](https://mastra.zisheng.pro/docs/memory/memory-processors)
- [createThread](https://mastra.zisheng.pro/reference/memory/createThread)
- [recall](https://mastra.zisheng.pro/reference/memory/recall)
- [getThreadById](https://mastra.zisheng.pro/reference/memory/getThreadById)
- [listThreads](https://mastra.zisheng.pro/reference/memory/listThreads)
- [deleteMessages](https://mastra.zisheng.pro/reference/memory/deleteMessages)
- [cloneThread](https://mastra.zisheng.pro/reference/memory/cloneThread)
- [Clone 实用方法](https://mastra.zisheng.pro/reference/memory/clone-utilities)