Use the Standalone Memory Service

Open the Atlas project that contains your cluster.

Navigate to the IP Access List page.

In the left navigation, select Database & Network Access in the Security section. Then, select IP Access List from the sidebar.

Add the required IP addresses.

Click the Add IP Address button on the top-right corner of the page. Add the following entries in the Access List Entry field, click Confirm, and wait until Atlas shows both as active in the Status column.

Sign in and create a context.

To sign into the Atlas Agent Engine and create a context, complete the following steps:

1. Set the following values in your shell. Replace <atlas-organization-id> and <atlas-project-id> with the IDs of the Atlas organization and project that contain your cluster:

   export PLATFORM_URL='https://agentengine.mongodb.com'export ORG_ID='<atlas-organization-id>'export PROJECT_ID='<atlas-project-id>'export MEMORY_CONTEXT='my-project'

2. Run the following commands to sign in and confirm that the project is visible:

   agentengine versionagentengine auth login --base-url "$PLATFORM_URL"agentengine project list --org-id "$ORG_ID" --base-url "$PLATFORM_URL"

3. Run the following command to save the target project as a named context:

   agentengine context create "$MEMORY_CONTEXT" \  --org-id "$ORG_ID" \  --project-id "$PROJECT_ID" \  --base-url "$PLATFORM_URL"

   A context names the platform, organization, and project. It doesn't require a workspace. Future steps pass --context "$MEMORY_CONTEXT" to target this project.

Generate the memory configuration.

Scaffold a memory-only project, and choose the LLM that memory uses for background extraction.

To use a provider's public API, such as Anthropic with its default model, run the following command:

agentengine create --memory-only --name "My Project" --llm anthropic --yes

To use an OpenAI-compatible gateway, such as Azure AI Foundry, run the following command:

agentengine create --memory-only --name "My Project" \  --llm openai-compatible \  --llm-base-url '<https-base-url-ending-in-/v1>' \  --llm-model '<exact-model-or-deployment-name>' \  --llm-auth-header 'api-key' | 'authorization' \  --yes

For the --llm-auth-header flag, choose one of the following values based on the header your gateway expects:

• api-key: Sends the key in an api-key header

• authorization: Sends Authorization: Bearer <key>

Verify your project-config.yaml file structure.

Either command from the preceding step creates a my-project directory that contains only a project-config.yaml file, with no agent.yaml file or workspace.

Navigate to the my-project directory and open the project-config.yaml file. Confirm that its memory: block resembles the following example:

memory_only: true
memory:  voyage:    model: "voyage-4-large"    dimension: 1024
  extraction_llm:    provider: openai    model: <exact-model-or-deployment-name>    base_url: <https-base-url-ending-in-/v1>    api_key_secret: LLM_API_KEY    auth_header: api-key
  background_extraction:    snapshot:      max_messages: 20      stale_minutes: 1
  extraction:    enabled:      - semantic      - episodic      - taxonomic      - procedural

If you chose the public API option, the extraction_llm block omits the base_url and auth_header fields. When you pass --llm openai-compatible, the CLI stores it in the provider field as provider: openai.

Upload project secrets.

Run the following commands to upload your project secrets and enter the corresponding values when prompted:

agentengine secret set MONGODB_URI --context "$MEMORY_CONTEXT" --project-scopeagentengine secret set VOYAGE_API_KEY --context "$MEMORY_CONTEXT" --project-scopeagentengine secret set LLM_API_KEY --context "$MEMORY_CONTEXT" --project-scope

Then, confirm that you successfully uploaded the secrets by running the following command:

agentengine secret list --context "$MEMORY_CONTEXT" --project-scope

Don't pass secret values by using the --value flag or as a positional argument. Both are deprecated, because they can expose secrets to other processes on your machine. If you set the secret from a script, pipe the value to the command by using the --stdin flag.

Start memory.

From the my-project directory, run the following commands:

agentengine memory configure ./project-config.yaml --context "$MEMORY_CONTEXT"agentengine memory apply --wait --context "$MEMORY_CONTEXT"

These commands perform the following actions:

• agentengine memory configure stores the configuration.

• agentengine memory apply provisions the memory runtime the first time, delivers the configuration, restarts memory, and waits until the runtime reports ready.

Monitor the memory status.

The memory runtime's own internal logs aren't visible. Instead, monitor the memory status in the following ways:

• Run the agentengine memory status --context "$MEMORY_CONTEXT" command.

• In the UI, open the project's Memory page from the Manage section. For a memory-only project, memory appears there, not on the Workspaces page.

If the blocked_on field remains in your memory status output and your state value does not progress to ready, contact MongoDB Support and provide your output.

Create a service account and retrieve an access token.

Your application authenticates by using a service account access token, not your CLI login. To retrieve this access token, perform the following steps:

1. Run the following command to create a service account for the project:

   agentengine service-account create memory-client \  --context "$MEMORY_CONTEXT" \  --role PROJECT_OWNER \  --enable-atlas-pairing

   Save the client ID and client secret from the command output. The Atlas Agent Engine shows the client secret only once.

   Important

   The PROJECT_OWNER role requires a paired Atlas service account. The --enable-atlas-pairing flag enables Atlas service-account pairing for the project, which allows the agentengine service-account create command to create this service account. Without the flag, non-interactive commands fail with a "Atlas service account pairing is disabled for this project" message.

2. Export your client ID, and then run the following command to exchange the client ID and client secret for an access token. curl prompts for the client secret without echoing it:

   export MEMORY_CLIENT_ID='<client-id>'
   export ACCESS_TOKEN=$(curl --fail-with-body --silent --show-error \  --user "$MEMORY_CLIENT_ID" \  --data grant_type=client_credentials \  "$PLATFORM_URL/api/v1/oauth/token" | jq -er .access_token)

   In a script or CI pipeline, read the client secret from your secret manager in code instead of relying on the interactive prompt. Don't pass the client secret as a command-line argument.

   Tip

   The access token is valid for one hour. Request a new token before the current one expires, and don't print it.

Install the Python SDK.

Run the following commands to install the agent-engine-sdk-memory package from PyPI, and pin the version:

python3 -m venv .venvsource .venv/bin/activatepython -m pip install 'agent-engine-sdk-memory==0.11.8'

Record and retrieve conversation context.

In your application, add the following code to create a client, bind a user identity, record turns, and retrieve relevant context for the same session:

import jsonimport osimport uuid
from agent_engine_sdk_memory import Memory, MemoryRequestContext
run_id = uuid.uuid4().hexsession_id = f"memory-setup-{run_id}"
with Memory(    base_url=os.environ["PLATFORM_URL"],    project_id=os.environ["PROJECT_ID"],    service_account_token=os.environ["ACCESS_TOKEN"],) as memory:    chat = memory.bind(        MemoryRequestContext(            user_id=f"memory-setup-user-{run_id}",            session_id=session_id,        )    )
    # Record turns.    chat.record_turn(role="user", content="My home airport is Boston Logan.")    chat.record_turn(role="assistant", content="Understood, I noted your home airport as Boston Logan.")
    # Retrieve context from the same session.    context = chat.build_context(        query="What is my home airport?",        enabled_sources={"stm"},        max_tokens=2048,    )    assert "Boston Logan" in json.dumps(context.formatted_context), (        "The recorded turn was not returned"    )    print("PASS: turn recording and same-session context")

To learn more about the SDK, including how identity and context retrieval work, see the agent-engine-sdk-memory reference.

Scaffold a local memory project.

Run the following command to scaffold a memory-only project for local development. Replace "My Project" with your project name:

agentengine create --memory-only --name "My Project"

The command writes a project-config.yaml file that sets memory_only to true and specifies the memory configuration schema.

This command does not generate an agent.yaml file, an agents/ directory, or agent runtime code. You cannot combine the --memory-only flag with the --template, --memory, or --open-egress flags. To choose the extraction provider at scaffold time, you can combine the --memory-only flag with --llm.

Configure environment variables.

Create an .env file in your project directory, and then set the following variables in the file:

• VOYAGE_API_KEY: Required for Voyage AI embeddings

• LLM provider key, such as ANTHROPIC_API_KEY: Required if background extraction is enabled in project-config.yaml

You don't need to set the MONGODB_URI variable. The agentengine dev up command provisions and connects to the bundled local MongoDB container automatically. If you want to use an external MongoDB instance instead, set this variable.

Start the local stack.

From the project directory, run the following command to start the local memory stack:

agentengine dev up

For a memory-only project, this command starts only the following containers:

• mongodb: A local Atlas-compatible MongoDB instance

• memory-server: The memory runtime service

• oe: The local Orchestration Engine proxy that the SDK connects through

The command output includes the URLs for the local oe and memory-server services. Copy the oe URL to use in a future step.

Use the following commands to manage the local stack:

Install the agent-engine-sdk-memory package.

Run the following command to install the agent-engine-sdk-memory package:

pip install agent-engine-sdk-memory

Connect the SDK to the local stack.

Navigate to your Python application directory. This directory can be separate from the project directory that you created in the first step.

Then, connect to the local stack by adding the following code to your application. Replace http://localhost:<oe-port> with the URL that you copied from the agentengine dev up command output.

from agent_engine_sdk_memory import Memory, MemoryRequestContext
# Set the base_url to the local oe URL printed by "agentengine dev up".memory = Memory(base_url="http://localhost:<oe-port>")
# Bind conversation identity.session = memory.bind(    MemoryRequestContext(        user_id="user_123",        session_id="session_456",    ))
# Record a user turn and an assistant turn.session.record_turn(role="user", content="I prefer window seats on flights.")session.record_turn(role="assistant", content="Got it, I'll remember that you prefer window seats on flights.")
# Build context.context = session.build_context(    query="What seat preferences are known?",    enabled_sources={"stm", "semantic", "episodic"},)print(context.formatted_context)