メモリの概要

Mastra におけるメモリは、関連情報を要約して言語モデルのコンテキストウィンドウに取り込むことで、会話をまたいだコンテキスト管理を支援します。

Mastra は、相互補完する3つのメモリシステムをサポートします: ワーキングメモリ、会話履歴、セマンティックリコール。これらを組み合わせることで、エージェントはユーザーの嗜好を把握し、会話の流れを維持し、関連する過去メッセージを取得できます。

会話間で情報を保存・想起するには、メモリにストレージアダプタが必要です。

サポートされているオプションは次のとおりです:

• LibSQL を用いたメモリ
• Postgres を用いたメモリ
• Upstash を用いたメモリ

メモリの種類

すべてのメモリタイプは、デフォルトではスレッドスコープで、単一の会話にのみ適用されます。リソーススコープの設定にすると、同じユーザーまたはエンティティを用いるすべてのスレッド間で、ワーキングメモリとセマンティックリコールを持続させられます。

ワーキングメモリ

名前、好み、目標、その他の構造化データといったユーザー固有の情報を永続的に保存します。構造の定義にはMarkdown テンプレートまたはZod スキーマを使用します。

会話履歴

現在の会話で直近のメッセージを取り込み、短期的な一貫性を確保して対話の流れを維持します。

セマンティックリコール

意味的な関連性に基づいて、過去の会話から古いメッセージを取得します。ベクトル検索で一致を見つけ、理解を深めるために周辺の文脈も含めることができます。

メモリはどのように連携するか

Mastra は、すべてのメモリ種別を単一のコンテキストウィンドウにまとめます。合計がモデルのトークン上限を超える場合は、モデルに送信する前にメッセージをトリミングまたはフィルタリングするために、memory processors を使用してください。

はじめに

Memory を使用するには、必要な依存関係をインストールしてください:

npm install @mastra/core @mastra/memory @mastra/libsql

共有ストレージ

エージェント間でメモリを共有するには、Mastra のメインインスタンスにストレージアダプターを追加します。メモリが有効なエージェントは、この共有ストレージを使って対話を保存・参照します。

import { Mastra } from "@mastra/core/mastra";
import { LibSQLStore } from "@mastra/libsql";
 
export const mastra = new Mastra({
  // ...
  storage: new LibSQLStore({
    url: ":memory:"
  })
});

エージェントにワーキングメモリを追加する

エージェントの memory パラメータに Memory インスタンスを渡し、workingMemory.enabled を true に設定してワーキングメモリを有効にします:

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
 
export const testAgent = new Agent({
  // ..
  memory: new Memory({
    options: {
      workingMemory: {
        enabled: true
      }
    }
  })
})

専用ストレージ

エージェントごとに専用のストレージを設定でき、タスク、会話、想起した情報をエージェント間で分離して保持できます。

エージェントにストレージを追加する

エージェントに専用ストレージを割り当てるには、必要な依存関係をインストールしてインポートし、Memory コンストラクタに storage インスタンスを渡します:

import { Memory } from "@mastra/memory";
import { Agent } from "@mastra/core/agent";
import { LibSQLStore } from "@mastra/libsql";
 
export const testAgent = new Agent({
  // ...
  memory: new Memory({
    // ...
    storage: new LibSQLStore({
      url: "file:agent-memory.db"
    })
  // ...
  })
});

メモリスレッド

Mastra は関連するやり取りをまとめる記録単位としてメモリをスレッドに編成し、次の2つの識別子を使用します：

1. thread: 会話を表すグローバルに一意な ID（例：support_123）。すべてのリソースにまたがって一意である必要があります。
2. resource: そのスレッドの所有者であるユーザーまたはエンティティ（例：user_123、org_456）。

resource は特に resource-scoped memory で重要で、同一のユーザーまたはエンティティに紐づくすべてのスレッド間でメモリを永続化できます。

const stream = await agent.stream("message for agent", {
  memory: {
    thread: "user-123",
    resource: "test-123"
  }
});

Mastra Playground は thread と resource の ID を自動的に設定します。独自のアプリケーションでは、各 .generate() または .stream() 呼び出しで手動指定する必要があります。

スレッドタイトルの生成

Mastra はユーザーの最初のメッセージに基づいて、わかりやすいスレッドタイトルを自動生成できます。これを有効にするには、generateTitle を true に設定します。これにより整理しやすくなり、UI 上で会話を表示しやすくなります。

export const testAgent = new Agent({
  memory: new Memory({
    options: {
      threads: {
        generateTitle: true,
      }
    },
  })
});

タイトル生成はエージェントの応答後に非同期で実行され、応答時間には影響しません。詳細と例は 設定リファレンスの全文 を参照してください。

タイトル生成の最適化

デフォルトでは、タイトルはエージェントのモデルで生成されます。コストや挙動を最適化するには、より軽量な model とカスタムの instructions を指定してください。これにより、タイトル生成をメインの会話ロジックから分離できます。

export const testAgent = new Agent({
  // ...
  memory: new Memory({
    options: {
      threads: {
        generateTitle: {
          model: openai("gpt-4.1-nano"),
          instructions: "Generate a concise title based on the user's first message",
        },
      },
    }
  })
});

動的なモデル選択と指示文

model と instructions に関数を渡すことで、スレッドタイトルの生成を動的に設定できます。これらの関数は runtimeContext オブジェクトを受け取り、ユーザー固有の値に応じてタイトル生成を調整できます。

export const testAgent = new Agent({
  // ...
  memory: new Memory({
    options: {
      threads: {
        generateTitle: {
          model: ({ runtimeContext }) => {
            const userTier = runtimeContext.get("userTier");
            return userTier === "premium" ? openai("gpt-4.1") : openai("gpt-4.1-nano");
          },
          instructions: ({ runtimeContext }) => {
            const language = runtimeContext.get("userLanguage") || "English";
            return `ユーザーの最初のメッセージに基づき、${language} で簡潔かつ魅力的なタイトルを生成してください。`;
          }
        }
      }
    }
  })
});

会話履歴の拡張

デフォルトでは、各リクエストには現在のメモリスレッドから直近10件のメッセージが含まれ、エージェントに短期的な会話コンテキストを提供します。この上限は lastMessages パラメータで増やせます。

export const testAgent = new Agent({
  // ...
  memory: new Memory({
    options: {
      lastMessages: 100
    },
  })
});

取得されたメッセージの表示

Mastra のデプロイメントでトレースが有効になっており、メモリが lastMessages や/または semanticRecall で設定されている場合、エージェントのトレース出力にはコンテキスト用に取得されたすべてのメッセージが表示されます。これには、直近の会話履歴と、semantic recall によって想起されたメッセージの両方が含まれます。

これは、デバッグ、エージェントの意思決定の把握、そして各リクエストに対してエージェントが適切な情報を取得できているかの検証に役立ちます。

トレースの有効化と設定方法の詳細については、Tracing を参照してください。

LibSQL を使ったローカル開発

LibSQLStore を用いたローカル開発では、VS Code の拡張機能 SQLite Viewer  を使って、保存されたメモリを確認できます。

次のステップ

コア概念を理解したら、semantic recall に進み、Mastra エージェントに RAG メモリを追加する方法を学びましょう。

また、利用可能なオプションについては configuration reference を参照してください。