Add Memory to Your Agent

Create a workspace folder inside the project root.

The following example creates a folder named my-workspace:

mkdir my-workspace

Move your workspace files into the new folder.

Run the following commands to move the agent.yaml file, your agent source files, and the .env file into the workspace folder:

mv agent.yaml my-workspace/
mv .env my-workspace/

Create a project-config.yaml file at the project root.

The following sample file project-config.yaml shows the memory: section configuration:

memory:
  log_level: info
  voyage:
    model: "voyage-4-large"
    dimension: 1024
  short_term:
    embed_on_write: false
  extraction_llm:
    provider: openai
    model: null
    base_url: null
    api_key_secret: null

Confirm the updated structure.

Confirm that your project matches the following structure:

my-project/
├── project-config.yaml
└── my-workspace/
    └── agent.yaml

Start the local environment.

Run the following command from the project root:

agentengine dev up

Edit the memory: block in your project-config.yaml file.

Open project-config.yaml at the project root and configure the memory settings. To view the available options, see Project Structure for Memory.

Upload the required secrets.

Run the following commands to upload the secrets, and include the --project-scope flag to target project-scoped secrets:

agentengine secret set VOYAGE_API_KEY --project-scope
agentengine secret set LLM_API_KEY --project-scope

If you scaffolded your project with the agentic create --llm <provider> --memory command and selected a supported LLM provider, the CLI already added extraction_llm.api_key_secret: LLM_API_KEY to your project-config.yaml file. This is the same secret name your agent's .env file uses, so uploading it once supplies the key to both the agent and memory extraction.

Store the memory configuration.

From your project root, run the following command to upload the memory: block from your project-config.yaml file to the Atlas Agent Engine:

agentengine memory configure

Deploy the agent.

Run the following command to deploy the agent and provision the memory server:

agentengine deploy

The deploy command syncs the pending memory configuration and provisions the memory server as part of the project runtime.

Edit the memory: block in your project-config.yaml file with your new memory settings.

Open project-config.yaml at the project root and configure the memory settings. To view the available options, see Project Structure for Memory.

Store the updated configuration.

Run the following command from your project root:

agentengine memory configure

Apply the configuration.

agentengine memory apply

The agentengine memory apply command restarts the memory server so it registers the new configuration. The platform delivers configuration changes asynchronously and the changes take effect when the pod restarts or when the updated configuration is applied on startup. If the stored configuration is not yet synced, the agentengine deploy command syncs the configuration as part of the next deploy process.

Declare your custom types.

Add a custom_memory_types: block to the memory: section of your project-config.yaml file. The following example creates a custom customer_profile type:

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

Each custom memory type has the following fields:

• name: (Required) The type name. The value must start with a lowercase letter and contain only lowercase letters, numbers, and underscores. It cannot use any of the built-in type names or exceed 64 characters in length.

• collection: (Required) The collection in the project's memory database that stores the type's records.

• tags: (Optional) Filterable tag keys, up to ten per type. A tag key can use dot notation to nest up to one level, such as profile.location. Tag values must be non-empty strings, numbers, or booleans.

Provision the new types.

Run the following commands to upload the updated configuration and apply it to the memory server, which provisions each new type:

agentengine memory configure
agentengine memory apply

Read and write custom memory records.

In your application, use the save() and retrieve() methods to write and read custom memory records:

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,
)