Use the Standalone Memory Service

Create a memory-only project.

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

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

The command generates a project directory that contains only a project-config.yaml file, with no agent.yaml file or workspace.

Create and select the project on the platform.

1. Run the following command to register the project. The command prints the new project ID:

   agentengine project create "My Project"

2. Select the new project as active. Replace <project-id> with the project ID printed by the previous command:

   agentengine auth login --project-id <project-id>

Configure memory settings.

1. Open the project-config.yaml file and set your secret names and the extraction provider under the memory: block.

2. Run the following commands to set the required secrets for your project:

   agentengine secret set MONGODB_URI --value "<value>" --project-id <project-id>
   agentengine secret set VOYAGE_API_KEY --value "<value>" --project-id <project-id>
   agentengine secret set ANTHROPIC_API_KEY --value "<value>" --project-id <project-id>

   Replace the following placeholder values:

   • <value>: Value of the secret.

     • MONGODB_URI: Connection string of your Atlas cluster.

     • VOYAGE_API_KEY: Your Voyage AI key.

     • ANTHROPIC_API_KEY: Your LLM provider key.

   • <project-id>: Project object ID returned by the agentengine project create command. This flag is required because the memory-only workflow does not include an agents.yaml file.

   Replace ANTHROPIC_API_KEY with the key name for your LLM provider if you use a different provider.

3. Store the memory configuration:

   agentengine memory configure

Provision the memory server.

Start the memory runtime and wait until it is ready:

agentengine memory apply --wait

Create a service account and retrieve an access token.

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

   agentengine service-account create memory-service --project-id <project-id> --role PROJECT_OWNER

   Replace the <project-id> placeholder with your project ID. Save the client ID and client secret from the command output. The Atlas Agent Engine shows the client secret only once.

2. Run the following command to exchange the client ID and client secret for an access token:

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

   Replace the <client-id> placeholder with your client ID. curl prompts for the client secret without echoing it.

   Tip

   The access token is valid for one hour. Request a new token before the current one expires.

Install the Python SDK.

Install the agent-engine-sdk-memory package from the platform's private registry, using the access token that you exported in the previous step:

pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

uv pip install agent-engine-sdk-memory \
  --extra-index-url "https://ignore:$ACCESS_TOKEN@agentengine.mongodb.com/api/v1/packages/python/simple"

The URL uses username:password format. ignore is a placeholder username, because the registry authenticates using only the access token in the password field. $ACCESS_TOKEN resolves to the access token that you exported in the previous step.

Record and retrieve conversation context.

In your application, add the following code to create a client, bind a user identity, record turns as they happen, and retrieve relevant context in later conversations:

from agent_engine_sdk_memory import (
    Memory,
    MemoryRequestContext,
)
# Create the client using your access token.
memory = Memory(service_account_token="<your-access-token>")
# Bind the user and session for this conversation.
chat = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_123",
    )
)
# Record turns as they happen.
chat.record_turn(
    role="user",
    content="I always fly out of Boston.",
)
chat.record_turn(
    role="assistant",
    content="Got it, Boston is saved as your home airport.",
)
# In a later conversation, recall what matters.
later = memory.bind(
    MemoryRequestContext(
        user_id="user_1",
        session_id="thread_456",
    )
)
context = later.build_context(
    query="Where should the flight book from?"
)
hits = later.search("home airport", top_k=5)

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, --llm, --memory, or --open-egress flags.

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 agentic-platform-memory package.

Run the following command to install the agentic-platform-memory package:

pip install agentic-platform-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 agentic_platform_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 turn.
session.record_turn(role="user", content="I 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)