AI エージェント向け: ドキュメントインデックスは https://www.mongodb.com/ja-jp/docs/llms.txt で利用できます。すべてのページの markdown バージョンは、いずれかの URL パスに .md を追加することで利用できます。

MongoDBと Vercel AI SDK を統合する

MongoDB は、 AIアプリケーションとエージェントを構築するための TypeScriptフレームワークである Vercel AI SDK と統合できます。統合は @mongodb-developer/vercel-ui-memory npmパッケージから利用でき、エージェントに対してMongoDBベースの永続メモリを提供します。統合には、次のメモリ階層が含まれます。

  • セッションメモリ: 現在のセッションのやり取りを保存

  • セマンティック メモリ: 人物やユーザーの嗜好などの名前付きエンティティに関する長期的な知識を保存

  • 手順メモリ: タスクやワークフローなどの使い方に関する知識を保存

  • エポック メモリ: 主要なイベントと結果のレコードを保存

  • スクレイピング メモリ: エポック メモリにプロモートできる一時的な作業ノートを保存

MongoDB統合はMongoDBにメモリを保存し、 MongoDB ベクトル検索インデックスを自動的に作成し、各メモリ階層に保持ポリシーを適用します。埋め込みは、クライアント側のモデルで生成することも、Atlas 自動埋め込みを使用してサーバー側で生成することもできます。

はじめる

MongoDBを使用するように Vercel AI SDK を構成するチュートリアルを完了するには、 「 MongoDB Vercel AI SDK 統合を使い始める 」を参照してください。

インストール

Vercel AI SDK のMongoDBメモリプロバイダーをインストールするには、次のコマンドを実行します。

npm install @mongodb-developer/vercel-ai-memory

パッケージには、ai、mongodb、zod パッケージが依存関係として必要です。このページでは、 voyage-ai-providerパッケージを必要とする MongoDB AI埋め込みモデルについても参照してください。これらの依存関係をインストールするには、次のコマンドを実行します。

npm install ai mongodb zod voyage-ai-provider

注意

統合は Vercel AI SDK v6 および v7 をサポートしています。

使用法

このセクションでは、 MongoDBメモリプロバイダーを使用するエージェントを作成する方法について説明します。

メモリ プロバイダーの作成

MongoDBメモリプロバイダーを作成するには、createMongoDBMemory() メソッドを呼び出し、 MongoDB接続文字列と埋め込みモデルを引数として渡します。対応する埋め込みモデル プロバイダーを使用する例を表示するには、Voyage AI タブまたは OpenAIタブを選択します。

投票AI埋め込みモデルを使用するには、voyage-ai-provider パッケージをインストールします。 Atlas で作成する投票AI APIキーには、baseURL メソッドのcreateVoyage() オプションで指定するMongoDBの投票AIエンドポイントが必要です。 Vyage AI APIキーの作成方法については、「 Vyage AIモデルAPIキーの管理 」を参照してください。

次の例では、Voyage AI埋め込みモデルを使用するメモリプロバイダーを作成します。

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { createVoyage } from 'voyage-ai-provider'
const voyage = createVoyage({  apiKey: process.env.VOYAGE_API_KEY,  baseURL: 'https://ai.mongodb.com/v1',})
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),})

プロバイダーは最初のツール使用でMongoDBに接続します。最初のリクエスト の前に接続して検索インデックスを作成するには、connect() メソッドを呼び出します。アプリケーションがシャットダウンしたときにMongoDB接続を閉じるには、close() メソッドを呼び出します。

エージェントの作成

メモリプロバイダーをエージェントに接続するには、 MongoDBメモリプロバイダーを呼び出し、userId と sessionId 引数を渡します。次に、メモリ ツールをエージェントに渡します。次の例では、メモリ ツールの範囲が 1 人のユーザーとセッションに限定されるエージェントを作成します。

import { openai } from '@ai-sdk/openai'import { ToolLoopAgent } from 'ai'
const agent = new ToolLoopAgent({  model: openai('gpt-4.1'),  tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),})

各メモリ層は、これらの識別子にスコープが設定されたメモリを保存および検索します。 createMongoDBMemory() メソッドに渡した userId と sessionId の値を使用するには、引数なしでMongoDBメモリ プロバイダーを呼び出します。

メモリ プロバイダーの設定

このセクションでは、createMongoDBMemory() メソッド パラメータを設定してMongoDBメモリ プロバイダーをカスタマイズする方法について説明します。

埋め込みモード

semantic_search、procedural_search、episodic_search コマンドはベクトル検索クエリを実行してメモリを検索します。ベクトル検索を実行中前に、統合はクエリテキストを埋め込みます。

Atlas は 2 つの埋め込みモードをサポートしています。

  • 手動埋め込み: 指定した埋め込みモデルを使用して、クライアント側で埋め込みベクトルを生成します。

  • 自動埋め込み: MongoDB は、手動で生成する必要なく、サーバー側にテキストを埋め込みます。「 自動埋め込み 」を参照してください。「自動埋め込み」を参照してください。

Atlas Automated EmbeddingAtlas がクエリテキストを自動的に埋め込むようにするには []タブを選択します。または、デフォルトの埋め込み動作を表示するには []タブを選択します。Client embedding model

Atlas が埋め込みを自動的に生成および管理できるようにするには、autoEmbed パラメータを createMongoDBMemory() メソッドに渡します。次の例に、この構成を示します。

import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'
const mongodbMemory = createMongoDBMemory({  uri: process.env.MONGODB_URI!,  autoEmbed: { model: 'voyage-4' },})

このモードでは 、統合はソース テキストを保存し、autoEmbed 型のベクトルインデックスを作成し、プレーンテキスト string で $vectorSearch クエリを発行します。 Atlas Automated埋め込みには、埋め込みAPIキーまたはクライアント埋め込みパイプラインは必要ありません。

注意

自動埋め込みには、Voyage AIが有効になっている Atlas組織が必要です。専有クラスター（M10 以上）では、ストレージのオートスケーリングを有効にする必要があります。

データトポロジー

デフォルトでは 、統合は データベースにメモリを保存し、「agent_memory コレクションとインデックス 」セクションで説明されているデフォルトのコレクションとインデックス名を使用します。データベース、コレクション、インデックス名をカスタマイズするには、 パラメータをtopology createMongoDBMemory()メソッドに渡します。

次の例では、セッション メモリ階層とセマンティック メモリ階層のカスタム名を提供しています。

createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),  topology: {    dbName: 'my_app',    collections: {      session: 'agent_sessions',      semantic: 'agent_facts',    },    vectorIndexNames: {      semantic: 'agent_facts_vs',    },  },})

保持ポリシー

メモリの有効期限が切れるタイミングを制御するには、各メモリ型に対して保持ポリシーを設定できます。保持ポリシーを構成するには、retention パラメータを createMongoDBMemory() メソッドに渡します。

ポリシーを構成するときは、modeフィールドとモードに必要な追加のフィールドを指定します。次の表では、使用可能なモードとそのフィールドについて説明しています。

モード
フィールド
説明

none

必須: mode

メモリは期限切れになりません。

ttl

必須:mode 、ttlSeconds
任意:field

メモリは、インデックス付き Dateフィールドのタイムスタンプからカウントして、ttlSecondsフィールドで指定された秒数の後に期限切れになります。

ttl+importance

必須:mode 、ttlSeconds 、minImportance
任意:field

タイムアウトするメモリ（TTL）は、importance 値が minImportanceフィールドの値を下回るメモリにのみ適用されます。

dynamic

必須:mode 、computeExpireAt
任意:refreshOnRead

computeExpireAt() 関数は、統合によってメモリが書込まれたときに各メモリの有効期限を計算し、メモリが読み取られ、refreshOnReadフィールドが true のときにその時間を再計算します。このモードを使用して、重要なメモリを頻繁に取得されるメモリを、ほとんど使用されないメモリよりも長く保持します。

次の例では、セマンティック メモリの保持ポリシーを構成し、重要なメモリのみを 1 週間後に保存します。

createMongoDBMemory({  uri: process.env.MONGODB_URI!,  embedder: voyage.embeddingModel('voyage-4'),  retention: {    semantic: { mode: 'ttl+importance', ttlSeconds: 604800, minImportance: 6 },  },})

セッション メモリ モード

セッション メモリは、どちらも同じコレクションによってバックアップされる次の 2 つのモードをサポートします。

  • ツール駆動型モード: セッション オン を保存し、呼び出すタイミングがモデルに決定されます

  • フックドライバーモード: ランタイムが自動的にセッションを保存し、呼び出します

対応するコード例を表示するには、Tool-driven タブまたは Hook-drivenタブを選択します。

ツール駆動モードでは、メモリ ツールを通じて session_append コマンドと session_recent コマンドを呼び出すことで、モデルはセッションを保存し、読み取ります。このモードは最も簡単な構成ですが、モデルによってはタームを保存したり、タームの前にロードしたりしないように選択する場合があります。プロトタイプやデモには、 ツール駆動型モードを使用します。このモードでは、簡単性が完全な 対話レコードよりも優先順位されます。

次の例では、 応答を生成し、返しを保存するタイミングをモデルが決定できるようにします。

const result = await agent.generate({  prompt: 'My name is Alice and I am a marine biologist. Remember that.',})

その他のメモリ層は、両方のモードでモデル制御の下にあります。モデルは、タームごとに書き込みを行うのではなく、どのセマンティック メモリ、手順メモリ、エポック メモリを保存して呼び出すかを選択する必要があります。

メモリ ツール コマンド

この統合により、commandフィールドを受け入れ、対応するメモリ階層にコマンドを送信する単一の memory ツールが提供されます。以下の表では、各階層で使用できるコマンドについて説明しています。

メモリ階層
コマンド
説明

セッション

session_append
session_recent

session_append コマンドは 1 回のタームを保存し、session_recent コマンドは最新のタームを返します。

セマンティック

semantic_save
semantic_search

semantic_save コマンドはエンティティの知識を保存し、semantic_search コマンドはベクトル検索を実行してそれを取得します。セマンティック メモリは一時的にバージョン化され、履歴が保持されます。

手続き型

procedural_save
procedural_search

procedural_save コマンドは手順を保存し、procedural_search コマンドはベクトル検索を実行してそれを取得します。手順メモリは一時的にバージョン化され、履歴が保持されます。

エピソード

episodic_save
episodic_search

episodic_save コマンドはイベントを記録し、episodic_search コマンドはベクトル検索を実行してそれを取得します。

スクレイピング

scratchpad_write
scratchpad_read
scratchpad_promote

scratchpad_write コマンドは一時的なノードを書込み、scratchpad_read コマンドは現在のノードを読み取り、scratchpad_promote コマンドはノードをエポック メモリにプロモートします。

任意の階層

memory_forget

memory_forget コマンドは、削除対象の特定のメモリをマークします。このコマンドはいつでも使用でき、ユーザーがエージェントにメモリを忘れるよう要求した場合に使用できます。

呼び出すコマンドはモデルが選択するため、commandフィールドは明示的に設定しないでください。ただし、エージェントの手順でコマンドを参照できます。次の例では、使用するコマンドを指定するエージェントを示しています。

const agent = new ToolLoopAgent({  model: openai('gpt-4.1'),  tools: mongodbMemory({ userId: 'alice', sessionId: 'sess-001' }),  instructions: `You are an assistant with persistent memory.    At the start of each session, call session_recent to restore    context. Save important facts with semantic_save. If the user    asks you to forget something, call memory_forget.`,})

コレクションとインデックス

最初の使用時に、統合によってデータベースに次のコレクションが作成されます。

コレクション
デフォルトの保持ポリシー
ベクトル インデックス

session_memory

ttlモード: ドキュメントの created_atフィールドのタイムスタンプから 24 時間後にメモリが期限切れになります

なし

semantic_memory

noneモード: メモリは期限切れになりません

semantic_vector_indexは、コサイン類似度を使用し、埋め込みのベクトル次元を自動的に検出します

procedural_memory

noneモード: メモリは期限切れになりません

procedural_vector_indexは、コサイン類似度を使用し、埋め込みのベクトル次元を自動的に検出します

episodic_memory

ttlモード は、ドキュメントの stats.last_retrievedフィールドのタイムスタンプから 1 年後にメモリを期限切れにします。

episodic_vector_indexは、コサイン類似度を使用し、埋め込みのベクトル次元を自動的に検出します

scratchpad_memory

ttlモード: ドキュメントの created_atフィールドのタイムスタンプから 1 時間後にメモリが期限切れになります

なし

この統合では各コレクションに expire_at TTLインデックスも作成されます。これにより、expire_atフィールドに保存されている時点で各メモリが期限切れになります。 memory_forget コマンドと dynamic 保持モードは、このフィールドをメモリ期限切れに設定します。

注意

MongoDB ベクトル検索インデックスは非同期にビルドされます。新しいデータベースで、検索する前にインデックスが構築されるまで数秒待ちます。

追加リソース

MongoDBで Vercel AI SDK を使用する方法の詳細については、次のリソースを参照してください。

戻る
整数AI
次へ
はじめる
このページを評価

項目一覧