개요
MongoDB Atlas Agent Engine의 메모리는 프로젝트 수준에서 구성됩니다. 프로젝트 의 모든 에이전트는 동일한 메모리 서비스, 저장 및 설정을 주식 . agent.yaml 파일 에서 개별 에이전트에 대한 메모리를 활성화 하거나 비활성화할 수 있습니다.
메모리를 구성하려면 project-config.yaml 파일 에서 memory: 차단 편집하고 필요한 API 키를 프로젝트 시크릿으로 업로드한 다음 에이전트 를 배포 . 초기 배포서버 후에는 다시 배포하지 않고도 메모리 설정을 업데이트 할 수 있습니다.
대화 중 메모리가 저장되고 추출되는 방법을 포함하여 메모리에 대해 자세히 학습 에이전트 메모리 가이드 참조하세요.
전제 조건
시작하기 전에 다음 전제 조건이 있는지 확인하세요.
agent.yaml파일 및 배포된 에이전트. 시작하려면 Atlas Agent 엔진 시작하기를 참조하세요.agentengineCLI 설치되고 인증되었습니다. 자세한 학습 은 설치 및 인증을 참조하세요.메모리 데이터를 저장 위한 Atlas Flex(최소 요구 사항),
M10,M20또는 상위 계층 클러스터 (권장). 클러스터 를 프로비저닝하려면 Atlas 리소스 설정을 참조하세요.- 메모리 데이터와 인덱스 수의 증가에 따라 이를 수용할 수 있도록 전용
M10이상의 계층 클러스터 배포하는 것이 좋습니다. Atlas Flex는 메모리 서비스를 지원 수 있는 가장 낮은 클러스터 계층 입니다.
참고
연결된 Atlas cluster 메모리에 필요한 검색 및 벡터 검색 인덱스를 생성할 수 없는 경우, Atlas Agent Engine은 Memory: waiting 단계에서 배포서버 중지하고 Error: context deadline exceeded 오류 메시지와 함께 시간 초과될 수 있습니다.
메모리 활성화
에이전트 에 대한 메모리를 활성화 하려면 agent.yaml 파일 에 features.memory: true를 설정하다 다음, 로컬 환경을 시작하기 전에 .env 파일 에 다음 변수를 추가합니다:
VOYAGE_API_KEY: 메모리 임베딩을 생성하는 데 필요합니다.MONGOMEM_DB_NAME: 선택 사항입니다. 메모리 서버 기록하는 MongoDB database 이름입니다. 기본값은mdb_memory_<project-id>입니다.
메모리에는 다음 섹션에 설명된 2단계 프로젝트 구조가 필요합니다. agentengine create 명령을 사용하여 프로젝트 를 스캐폴딩하는 경우 CLI 이 구조를 생성합니다.
참고
TypeScript 에이전트는 동일한 방법을 사용하여 메모리를 활성화 . TypeScript 에이전트 플랫폼 요청 처리하는 동안에만 app.memory 클라이언트 액세스합니다. 해당 컨텍스트 외부에서 메모리를 읽거나 쓰기 (write) HTTP 통해 메모리 서버 에 직접 연결되는 @mongodb-js/agent-engine-sdk-memory 패키지 의 Memory 클라이언트 사용합니다.
메모리에 대한 프로젝트 구조
프로젝트 루트에는 메모리 구성을 저장하는 project-config.yaml 파일 있습니다. agent.yaml 파일 포함된 각 작업 공간은 프로젝트 루트의 하위 폴더입니다. 다음 예시 메모리 구성에 예상되는 프로젝트 구조를 보여줍니다.
my-project/ ├── project-config.yaml └── my-workspace/ └── agent.yaml
project-config.yaml 파일 프로젝트 의 메모리 서버 구성하는 memory: 섹션이 있습니다. 다음 예시 사용 가능한 메모리 구성 옵션과 해당 기본값 옵션을 보여줍니다.
memory: # Memory-server log level. One of: debug | info | warning | error | # critical. log_level: info # Voyage AI embeddings. # The Voyage API key is NOT set here — upload it as a project # secret with: # agentengine secret set VOYAGE_API_KEY <value> voyage: model: "voyage-4-large" dimension: 1024 # Short-term memory write-path behavior. short_term: # Embed each turn's content when it is written (only when the # caller supplies no embedding), so it is searchable by # relevance immediately instead of waiting for background # embedding. Adds embedding latency to the write. embed_on_write: false # LLM used for background extraction. # The API key is NOT set here — upload it as a project secret. If # your agent already uses a supported LLM connection, upload that # same key under the shared LLM_API_KEY name so the agent and # extraction reuse one secret: # agentengine secret set LLM_API_KEY <value> # Otherwise, upload a provider-named key instead, for example: # agentengine secret set OPENAI_API_KEY <value> extraction_llm: provider: openai # one of: openai | anthropic | gemini | cerebras model: null # overrides the provider's default model base_url: null # optional: route requests through a gateway # or proxy instead of the provider's default # endpoint. Required only for gateway # connections; omit to call the provider # directly. api_key_secret: null # optional: the name of the project secret # that holds the extraction LLM's API key. # One of: LLM_API_KEY, OPENAI_API_KEY, # ANTHROPIC_API_KEY, GEMINI_API_KEY, or # CEREBRAS_API_KEY. If omitted, extraction # checks provider-named keys before # LLM_API_KEY. auth_header: null # optional: the header the gateway expects for # the API key. One of: authorization (Bearer) # or api-key. Omit for native provider # authentication. background_extraction: snapshot: max_messages: 20 stale_minutes: 3 embed_stm_before_promotion: true topic_shift_enabled: false topic_shift_threshold: 0.35 delete_promoted: false ttl_days: 30 # Extraction pipeline. Add memory types to the 'enabled' list to # turn extraction on, for example: # enabled: # - semantic # - episodic # Valid types: semantic, episodic, taxonomic, entity, preferences, # procedural. # NOTE: Removing the 'enabled' line entirely re-enables ALL types. # Keep it as [] to extract nothing. extraction: enabled: []
배포된 프로젝트 에 대한 메모리 구성을 업로드하고 동기화 하려면 메모리 구성을 참조하세요.
프로젝트 구조 마이그레이션
프로젝트 에서 프로젝트 루트에 agent.yaml가 있는 플랫 구조를 사용하는 경우, 메모리를 활성화하기 전에 2단계 구조로 마이그레이션 . 플랫 구조는 더 이상 사용되지 않습니다.
플랫 구조를 마이그레이션 하려면 다음 단계를 수행하세요.
메모리 구성
agentengine memory 명령을 사용하여 배포된 프로젝트에 대한 프로젝트의 메모리 구성을 업로드하고 동기화 . 메모리 구성은 프로젝트 범위로 이루어지며, 하나의 구성 문서 프로젝트 의 모든 에이전트에 적용됩니다.
로컬 개발을 위한 메모리를 구성하려면 메모리 활성화를 참조하세요.
구성 명령 구문
agentengine memory configure 명령은 에이전트 디렉토리 에서 project-config.yaml 파일 읽고 memory: 섹션을 추출하여 Atlas Agent Engine에 업로드합니다. 이 명령은 업로드하기 전에 대상 프로젝트 확인합니다.
중요
향후 출시하다 agentengine memory configure 명령에 대한 지원 제거 . 대신 플랫폼은 UI 통해 메모리 관리 지원 합니다.
다음 예시 메모리 구성을 업로드하는 명령 구문을 보여줍니다.
agentengine memory configure <path> [--project-id <id> --org-id <id> --base-url <url>]
또는 다음 예시 와 같이 agentic memory configure 명령을 사용하고 --context 플래그만 전달할 수 있습니다.
agentengine memory configure <path> [--context <name>]
경고
project-config.yaml 파일 memory: 키가 포함되어 있지 않으면 명령은 오류를 반환합니다. 누락된 memory: 키가 기존 구성을 제거 하지 않습니다.
다음 표에서는 사용 가능한 플래그에 대해 설명합니다.
플래그 | 설명 |
|---|---|
| 대상 플랫폼 기본 URL, 조직 및 프로젝트 식별하는 저장된 컨텍스트의 이름입니다. 저장된 컨텍스트를 보려면 |
| 프로젝트 ID . 생략하면 명령은 로컬 인증 상태 의 프로젝트 사용합니다. 이 플래그를 설정하다 경우, |
| 조직 ID. |
| 플랫폼 기본 URL. |
| 확인 메시지를 건너뜁니다. CI(지속적 통합) 환경에서 이 플래그를 사용합니다. |
참고
메모리 구성은 비밀 저장 아닙니다. 비밀이 아닌 설정만 project-config.yaml 파일 에 저장합니다. API 키, 연결 문자열 및 기타 자격 증명 에 agentengine secret set 명령을 사용합니다. Atlas Agent 엔진은 일반적인 비밀 패턴과 일치하는 값이 포함된 업로드를 거부합니다.
초기 메모리 구성
메모리를 활성화한 상태에서 첫 번째 배포서버 시작하기 전에 다음 단계를 수행하세요.
project-config.yaml 파일 에서 memory: 차단 편집합니다.
프로젝트 루트에서 project-config.yaml을 열고 메모리 설정을 구성합니다. 사용 가능한 옵션을 보려면 메모리의 프로젝트 구조를 참조하세요.
필요한 시크릿을 업로드합니다.
다음 명령을 실행하여 시크릿을 업로드하고 --project-scope 플래그를 포함하여 프로젝트 범위 시크릿을 대상으로 합니다.
agentengine secret set VOYAGE_API_KEY --project-scope agentengine secret set LLM_API_KEY --project-scope
agentic create --llm <provider> --memory 명령으로 프로젝트 스캐폴딩하고 지원되는 LLM 제공자 선택한 경우, CLI 이미 project-config.yaml 파일 에 extraction_llm.api_key_secret: LLM_API_KEY를 추가했습니다. 이는 에이전트의 .env 파일 사용하는 것과 동일한 시크릿 이름이므로 한 번 업로드하면 에이전트 와 메모리 추출 모두에 키를 제공합니다.
참고
OPENAI_API_KEY 또는 ANTHROPIC_API_KEY와 같은 제공자 이름의 키를 계속 사용할 수 있습니다. 명시적인 api_key_secret 값이 없으면 추출은 LLM_API_KEY 이전에 제공자 이름이 지정된 키를 확인합니다. 메모리에 에이전트 와 별도의 자격 증명이 필요하거나 여러 제공자에 대한 키가 있고 하나를 선택하려는 경우 api_key_secret 필드 명시적으로 설정합니다.
api_key_secret을 LLM_API_KEY 이외의 값으로 설정하다 경우, 이전 명령의 LLM_API_KEY를 해당 이름으로 대신 바꿉니다.
메모리 구성 업데이트
메모리 구성을 변경할 때 에이전트 를 다시 배포할 필요는 없습니다. 실행 배포서버 에 업데이트된 메모리 설정을 적용 하려면 다음 단계를 수행하세요.
새 메모리 설정으로 project-config.yaml 파일 의 memory: 차단 편집합니다.
프로젝트 루트에서 project-config.yaml을 열고 메모리 설정을 구성합니다. 사용 가능한 옵션을 보려면 메모리의 프로젝트 구조를 참조하세요.
사용자 지정 메모리 유형 선언
사용자 지정 메모리 유형은 네 가지 내장 메모리 유형에 해당하지 않는 도메인별 레코드를 저장 . 사용자 지정 메모리 유형을 선언하고 사용하려면 다음 단계를 수행하세요.
사용자 지정 유형을 선언합니다.
project-config.yaml 파일 의 memory: 섹션에 custom_memory_types: 차단 추가합니다. 다음 예시 사용자 지정 customer_profile 유형을 생성합니다.
memory: custom_memory_types: # Custom memory types (max 5) - name: customer_profile collection: profiles tags: - name: location - name: tier - name: profile.location # One level of nested tag keys
각 사용자 지정 메모리 유형에는 다음과 같은 필드가 있습니다.
name: (필수) 유형 이름입니다. 값은 소문자로 시작해야 하며 소문자, 숫자, 밑줄만 포함할 수 있습니다. 내장 유형 이름을 사용하거나 길이가 64자를 초과할 수 없습니다.collection: (필수) 유형의 레코드를 저장하는 프로젝트 메모리 데이터베이스 의 컬렉션 입니다.tags: (선택 사항) 필터링 가능한 태그를 지정하다 키(유형당 최대 10개). 태그를 지정하다 키는 점 표기법 사용하여profile.location과 같이 한 수준까지 중첩할 수 있습니다. 태그 값은 비어 있지 않은 문자열, 숫자 또는 부울이어야 합니다.
사용자 지정 메모리 레코드를 읽고 쓰기 (write) .
애플리케이션 에서 save() 및 retrieve() 메서드를 사용하여 사용자 지정 메모리 레코드를 쓰기 (write) 읽습니다.
memory.save( memory_type="customer_profile", content="Prefers direct vendor onboarding contact.", tags={"tier": "gold"}, ) hits = memory.retrieve( memory_type="customer_profile", query="How should we onboard this customer?", tags={"tier": "gold"}, top_k=5, )
에이전트에서 메모리 액세스
메모리가 활성화된 상태에서 에이전트 배포 경우, 플랫폼은 애플리케이션 객체 에 app.memory 클라이언트 제공합니다. 이 클라이언트 사용하여 에이전트 에서 메모리를 읽고 쓰기 (write) . 플랫폼은 런타임 컨텍스트에서 현재 사용자와 세션을 확인하므로 user_id 또는 session_id 인수를 app.memory에 명시적으로 전달할 필요가 없습니다.
중요
서비스 계정 메모리 ID
서비스 계정이 배포된 에이전트 호출하면 Atlas Agent Engine은 서비스 계정의 자체 ID를 런타임 메모리 ID로 사용합니다. 플랫폼은 호출 요청 또는 agentengine invoke --user-id 플래그가 제공하는 모든 최종 사용자 user_id 값을 무시합니다.
자동 회전 기록, 추출, 통합 및 app.memory 작업은 이 확인된 ID를 사용합니다. 결과적으로 동일한 서비스 계정을 통해 인증하는 호출은 하나의 메모리 사용자 범위를 주식 .
이 제한은 서비스 계정이 호출하는 배포된 에이전트에만 적용됩니다. 독립형 프로젝트 범위 메모리 서비스는 영향을 받지 않습니다. 이 서비스는 호출자로부터 명시적인 user_id 및 session_id 값을 계속 받습니다.
최종 사용자별로 메모리를 격리하려면 애플리케이션 에서 독립형 메모리 서비스를 호출하고 각 호출에 명시적인 user_id 및 session_id 값을 전달합니다. 자세한 학습 은 독립형 메모리 서비스 사용을 참조하세요.
agent-engine-sdk-langgraph 에이전트 에서 메모리 액세스 하려면 다음 단계를 수행하세요. 모든 Atlas Agent Engine 에이전트 템플릿은 agent-engine-sdk-langgraph 패키지 사용하므로 이러한 단계는 에이전트의 사용 사례 에 관계없이 적용 .
app.memory 클라이언트 에 액세스합니다.
에이전트 코드에서 app.memory 클라이언트 조회 하고 이를 사용하여 메모리를 읽고 쓰기 (write) . 다음 예시 이 클라이언트 액세스 방법을 보여줍니다.
from agent_engine_sdk_langgraph import App app = App(app_name="support-agent") def build_graph(): # Your LangGraph state machine. ... # Later, in a request handler for a conversation turn: memory = app.memory
참고
배포된 에이전트 의 경우 플랫폼은 대화 턴을 자동으로 기록합니다. 대화 차례를 저장하기 위해 record_turn()을(를) 호출할 필요가 없습니다.
다음 단계
에이전트 에 대한 메모리를 활성화한 후 로컬에서 에이전트 를 테스트하고 배포 수 있습니다. 에이전트 테스트하는 방법을 학습 에이전트 테스트를 참조하세요. 에이전트 배포 방법을 학습 배포를 참조하세요.
Atlas Agent Engine 외부에서 실행되는 애플리케이션 의 메모리를 사용하려면 독립형 메모리 서비스 앱 사용 가이드 참조하세요.