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

# Memory 類別

`Memory` 類別為 Mastra 提供可靠的對話歷程記錄與執行緒式訊息儲存管理系統。它能永久儲存對話、執行語意搜尋，並有效率地擷取訊息。你必須為對話歷程記錄設定 storage provider；若啟用語意回憶，還需要提供 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 類別](https://mastra.zisheng.pro/zh-TW/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>`): 用於向量 embedding 的 Embedder 執行個體。啟用語意回憶時為必填。

**options** (`MemoryConfig`): Memory 設定選項。

**options.lastMessages** (`number | false`): 要納入 context 的最近訊息數量。設為 false 可完全停用訊息歷程記錄功能（訊息不會載入 context 或儲存）。使用 Number.MAX\_SAFE\_INTEGER 可不限數量地擷取所有訊息。若要載入訊息但不儲存新訊息，請使用 readOnly 選項。

**options.readOnly** (`boolean`): 設為 true 時，Memory 不會儲存新訊息，並以唯讀 context 形式提供 working memory（不含 updateWorkingMemory Tool）。適合預覽、內部路由 Agent，或應參照但不修改 Memory 的子 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`): 啟用 Observational Memory，提供長 context 的 Agent Memory。設為 true 可使用預設值，或傳入設定物件自訂 token 預算、模型與範圍。設定詳情請參閱 Observational Memory 參考。

**options.generateTitle** (`boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> }`): 控制是否根據對話逐字稿自動產生執行緒標題。可為布林值或包含自訂模型與指示的物件。

## 回傳值

**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/zh-TW/docs/memory/overview)
- [語意回憶](https://mastra.zisheng.pro/zh-TW/docs/memory/semantic-recall)
- [Working Memory](https://mastra.zisheng.pro/zh-TW/docs/memory/working-memory)
- [Observational Memory](https://mastra.zisheng.pro/zh-TW/docs/memory/observational-memory)
- [Memory Processor](https://mastra.zisheng.pro/zh-TW/docs/memory/memory-processors)
- [createThread](https://mastra.zisheng.pro/zh-TW/reference/memory/createThread)
- [recall](https://mastra.zisheng.pro/zh-TW/reference/memory/recall)
- [getThreadById](https://mastra.zisheng.pro/zh-TW/reference/memory/getThreadById)
- [listThreads](https://mastra.zisheng.pro/zh-TW/reference/memory/listThreads)
- [deleteMessages](https://mastra.zisheng.pro/zh-TW/reference/memory/deleteMessages)
- [cloneThread](https://mastra.zisheng.pro/zh-TW/reference/memory/cloneThread)
- [Clone 輔助方法](https://mastra.zisheng.pro/zh-TW/reference/memory/clone-utilities)