MongoDB AI 애플리케이션 및 에이전트 구축을 위한 TypeScript 프레임워크 Vercel AI SDK와 통합할 수 있습니다. 통합은 @mongodb-developer/vercel-ai-memory npm 패키지 에서 사용할 수 있으며 에이전트를 위해 MongoDB 지원 영구 메모리를 제공합니다. 통합에는 다음과 같은 메모리 계층이 포함됩니다.
세션 메모리: 현재 세션의 대화 차례를 저장합니다.
시맨틱 메모리: 사람 및 사용자 기본 설정과 같은명명된 엔터티에 대한 장기 지식을 저장합니다.
절차적 메모리: 작업 및 워크플로와 같은 방법 지식을 저장합니다.
일화 메모리: 주요 이벤트 및 결과에 대한 기록을 저장합니다.
ScratchPad 메모리: 일시적인 메모리로 승격할 수 있는 임시 작업 메모를 저장합니다.
MongoDB 통합은 MongoDB 에 메모리를 저장하고, MongoDB Vector Search 인덱스를 자동으로 생성하고, 각 메모리 계층 에 보존 정책을 적용합니다. 클라이언트 사이드 모델을 사용하여 임베딩을 생성하거나 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 패키지 필요한 Voyage AI 임베딩 모델도 참조합니다. 이러한 종속성을 설치하려면 다음 명령을 실행 .
npm install ai mongodb zod voyage-ai-provider참고
통합은 Vercel AI SDK v6 및 v7를 지원합니다.
사용법
이 섹션에서는 MongoDB 메모리 제공자 사용하는 에이전트 만드는 방법에 대해 설명합니다.
메모리 제공자 만들기
MongoDB 메모리 제공자 생성하려면 createMongoDBMemory() 메서드를 호출하고 MongoDB 연결 문자열 과 임베딩 모델을 인수로 전달합니다. 해당 임베딩 모델 제공자 사용하는 예시 를 보려면 Voyage AI 또는 OpenAI 탭 선택합니다.
Voyage AI 임베딩 모델을 사용하려면 voyage-ai-provider 패키지 설치합니다. Atlas 에서 생성하는 Voyage AI API 키에는 createVoyage() 메서드의 baseURL 옵션으로 지정하는 MongoDB Voyage AI 엔드포인트가 필요합니다. Voyage AI API 키를 생성하는 방법을 학습 Voyage 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'),})다음 예시 OpenAI 임베딩 모델을 사용하는 메모리 제공자 생성합니다.
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: openai.embedding('text-embedding-3-small'),})제공자 도구를 처음 사용할 때 MongoDB 에 연결합니다. 첫 번째 요청 전에 검색 인덱스를 연결하고 생성하려면 connect() 메서드를 호출합니다. 애플리케이션 종료될 때 MongoDB 연결을 닫으려면 close() 메서드를 호출합니다.
에이전트 만들기
메모리 제공자 에이전트 에 연결하려면 MongoDB 메모리 제공자 호출하고 userId 및 sessionId 인수를 전달합니다. 그런 다음 메모리 도구를 에이전트 에 전달합니다. 다음 예시 한 명의 사용자와 세션으로 메모리 도구 범위가 지정된 에이전트 만듭니다.
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 두 가지 임베딩 모드를 지원합니다.
수동 임베딩: 지정한 임베딩 모델을 사용하여 클라이언트 측에서 임베딩 벡터를 생성합니다.
자동 임베딩: MongoDB 텍스트를 수동으로 생성할 필요 없이 서버 측에 텍스트를 임베딩합니다.자세한 내용은 자동 임베딩 을(를) 참조하세요. 자세한 내용은 자동 임베딩을(를) 참조하세요.
Atlas Automated Embedding 탭 선택하여 Atlas 쿼리 텍스트를 자동으로 임베드하도록 허용하거나 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 유형에 대한 벡터 인덱스를 생성하고, 일반 텍스트 문자열로 $vectorSearch 쿼리를 실행합니다. Atlas 자동 임베딩에는 임베딩 API 키나 클라이언트 임베딩 파이프라인 필요하지 않습니다.
참고
자동화된 임베딩을 사용하려면 Atlas 조직 에서 Voyage AI 사용하도록 설정해야 합니다. 전용 클러스터(M10 이상)에서는 저장 자동 확장 활성화 해야 합니다.
클라이언트 에서 임베딩을 생성하려면 embedder 매개변수를 createMongoDBMemory() 메서드에 전달합니다. 다음 예시 이 구성을 보여 주며 OpenAI 임베딩 모델을 사용합니다.
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: openai.embedding('text-embedding-3-small'),})embedder 매개변수는 OpenAI, Cohere 및 Google의 모델을 포함하여 Vercel AI SDK EmbeddingModel 인터페이스를 구현하는 모든 모델을 허용합니다. voyage-ai-provider 패키지 통해 Voyage AI 임베딩 모델을 사용할 수도 있습니다. 사용 가능한 제공자를 보려면 Vercel AI SDK 문서에서 AI SDK 제공자를 참조하세요. 통합은 벡터 차원의 수를 자동으로 감지하므로 구성하지 않아도 됩니다.
데이터 토폴로지
기본값 으로 통합은 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 필드 와 모드 에 필요한 추가 필드를 지정합니다. 다음 표에서는 사용 가능한 모드와 해당 필드에 대해 설명합니다.
모드 | 필드 | 설명 |
|---|---|---|
| 필수: | 메모리는 만료되지 않습니다. |
| 필수: | 메모리는 인덱싱된 |
| 필수: | TTL(time-to-live)은 |
| 필수: |
|
다음 예시 시맨틱 메모리에 대한 보존 정책을 구성하여 일주일 후에 중요한 메모리만 저장합니다.
createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: voyage.embeddingModel('voyage-4'), retention: { semantic: { mode: 'ttl+importance', ttlSeconds: 604800, minImportance: 6 }, },})세션 메모리 모드
세션 메모리는 다음 두 모드를 지원하며, 둘 다 동일한 컬렉션 에서 지원됩니다.
도구 기반 모드: 모델이 세션 턴을 저장하고 호출하는 시점을 결정합니다.
후크 기반 모드: 런타임이 자동으로 세션 턴을 저장하고 호출합니다.
해당 코드 예시 보려면 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.',})후크 기반 모드 에서 런타임은 모델의 결정에 관계없이 모든 모델 호출 전에 이전 턴을 읽고 도구 루프가 완료된 후에는 모든 사용자, 어시스턴트 및 도구 턴을 씁니다. 프로덕션 환경에서는 이 모드 사용하는 것이 좋습니다.
세션 컬렉션 사용 가능한 상태로 유지하면서 모델에서 세션 명령을 숨기려면 topology 매개변수의 hideToolCommands 옵션을 ['session']로 설정하다 . 다음 예시 prepareCall 훅에서 세션 기록을 복원하고 onFinish 훅의 모든 턴을 유지합니다.
import { createMongoDBMemory } from '@mongodb-developer/vercel-ai-memory'import { openai } from '@ai-sdk/openai'import { ToolLoopAgent, isLoopFinished } from 'ai'import { z } from 'zod'
const mongodbMemory = createMongoDBMemory({ uri: process.env.MONGODB_URI!, embedder: openai.embedding('text-embedding-3-small'), topology: { hideToolCommands: ['session'] },})
const agent = new ToolLoopAgent({ model: openai('gpt-4o-mini'),
callOptionsSchema: z.object({ userId: z.string(), sessionId: z.string(), prompt: z.string(), }),
prepareCall: async ({ options, prompt: _p, messages: _m, ...settings }) => { const { userId, sessionId, prompt } = options! const history = await mongodbMemory.loadSession({ userId, sessionId }) return { ...settings, tools: mongodbMemory({ userId, sessionId }), messages: [...history, { role: 'user', content: prompt }], experimental_context: { userId, sessionId, prompt }, } },
onFinish: mongodbMemory.onFinish(), stopWhen: isLoopFinished(),})loadSession() 메서드는 messages 필드 의 시작 부분에 추가한 이전 사용자 및 어시스턴트 턴을 반환합니다. onFinish() 메서드는 사용자 프롬프트와 모든 어시스턴트 및 도구 메시지를 유지합니다. 통합은 도구 회전을 기록 기록으로 저장하지만 도구 결과로 재생하지는 않습니다.
다른 메모리 계층은 두 모드 모두에서 모델 제어 하에 유지됩니다. 모델은 매 차례마다 쓰는 대신 저장하고 호출할 시맨틱, 절차적, 일화적 메모리를 선택해야 합니다.
메모리 도구 명령
이 통합은 command 필드 허용하고 해당 메모리 계층 으로 명령을 전송하는 단일 memory 도구를 제공합니다. 다음 표에서는 각 계층 에서 사용할 수 있는 명령에 대해 설명합니다.
메모리 계층 | 명령. | 설명 |
|---|---|---|
Session |
|
|
semantic |
|
|
절차적 |
|
|
에피소드형 |
|
|
ScratchPad |
|
|
모든 계층 |
|
|
모델이 호출할 명령을 선택하므로 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.`,})컬렉션 및 인덱스
처음 사용 시 통합 기능은 데이터베이스 에 다음 컬렉션을 생성합니다.
컬렉션 | 기본 보존 정책 | 벡터 인덱스 |
|---|---|---|
|
| none |
|
|
|
|
|
|
|
|
|
|
| none |
또한 통합은 각 컬렉션 에 expire_at TTL 인덱스 생성하며, 이 인덱스는 expire_at 필드 에 저장된 시간에 각 메모리를 만료합니다. memory_forget 명령과 dynamic 보존 모드 이 필드 설정하다 메모리를 만료합니다.
참고
MongoDB Vector Search 인덱스는 비동기적으로 빌드 . 새 데이터베이스 에서는 검색 전에 인덱스가 빌드 될 때까지 몇 초 정도 기다립니다.
추가 리소스
MongoDB 에서 Vercel AI SDK를 사용하는 방법에 대해 자세히 학습 다음 리소스를 참조하세요.
vercel-ai-memory GitHub 리포지토리