为代理添加内存

Overview

MongoDB Atlas Agent Engine 上的内存是在项目级别配置的。项目中的所有代理股票相同的内存服务、存储和设置。您可以在 agent.yaml文件中为单个代理启用或禁用内存。

要配置内存，请编辑 project-config.yaml文件中的 memory:区块，上传所需的API密钥作为项目密钥，然后部署代理。初始部署后，您可以更新内存设置，而无需重新部署。

要学习；了解有关内存的更多信息，包括在对话过程中如何存储和提取内存，请参阅 Agent 内存指南。

先决条件

开始之前，请确保您具备以下先决条件：

一个 agent.yaml文件和一个已部署的代理。要开始使用，请参阅Atlas助手引擎入门。
已安装 agentengine CLI并进行身份验证。要学习；了解更多信息，请参阅安装和身份验证。
用于存储内存数据的Atlas Flex（最低要求）、M10、M20 或更层级集群（推荐）。要预配集群，请参阅设置Atlas资源。
- 我们建议部署专用的 M10 或更层级集群，以容纳不断增长的内存数据和索引计数。 Atlas Flex 是可以支持内存服务的最低集群层。

注意

如果关联的Atlas 集群无法创建内存所需的“搜索”和“矢量搜索”索引， Atlas助手引擎会在 Memory: waiting 阶段停止部署，并且可能会超时并显示 Error: context deadline exceeded 错误消息。

启用内存

要为代理启用内存，请在 agent.yaml文件中设立features.memory: true，然后在启动本地环境之前将以下变量添加到 .env文件中：

VOYAGE_API_KEY：生成内存嵌入时必需的。
MONGOMEM_DB_NAME：可选。内存服务器写入内容的MongoDB 数据库名称。默认为 mdb_memory_<project-id>。

内存需要使用下一节中描述的两级项目结构。如果您使用 agentengine create 命令来构建项目， CLI会为您生成此结构。

注意

TypeScript 代理使用相同的方法启用内存。 TypeScript代理仅在处理平台请求时访问 app.memory客户端。要在该上下文之外读取或写入内存，请使用 @mongodb-js/agent-engine-sdk-memory包中的 Memory客户端，该客户端直接通过HTTP连接到内存服务器。

内存的项目结构

项目根目录有一个用于存储内存配置的 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 位于项目根目录，请在启用内存之前迁移到两级结构。扁平结构已弃用。

要迁移扁平结构，请执行以下步骤：

在项目根目录中创建一个工作区文件夹。

以下示例将创建一个名为 my-workspace 的文件夹：

mkdir my-workspace

将工作区文件移至新文件夹中。

运行以下命令，将 agent.yaml文件、代理源文件和 .env文件移动到工作区文件夹中：

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

在项目根目录创建一个 `project-config.yaml`文件。

以下示例文件project-config.yaml 显示了 memory: 部分配置：

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

确认更新后的结构。

确认您的项目符合以下结构：

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

启动本地环境。

从项目根目录运行以下命令：

agentengine dev up

配置内存

使用 agentengine memory 命令上传和同步已部署项目的内存配置。内存配置具有项目范围：一份配置文档适用于项目中的所有代理。

要为本地开发配置内存，请参阅启用内存。

配置命令事务语法

agentengine memory configure 命令会从代理目录中读取 project-config.yaml文件，提取 memory: 部分，然后将其上传到Atlas助手引擎。该命令会在上传之前确认目标项目。

重要

未来发布将删除对 agentengine memory configure 命令的支持。相反，该平台将通过用户界面支持内存管理。

以下示例显示了上传内存配置的命令语法：

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: 键不会删除现有配置。

下表描述了可用标志：

标记	说明
`--context`	已保存上下文的名称，用于标识目标平台基本URL、组织和项目。要查看保存的上下文，运行`agentic context list`。
`--project-id`	项目ID 。如果省略，该命令将使用本地身份验证状态下的项目。如果设立此标志，则还必须设立`--org-id` 和 `--base-url` 标志。
`--org-id`	组织ID。如果使用 `--project-id` 标志，则为必填项。
`--base-url`	平台基本URL。如果使用 `--project-id` 标志，则为必填项。
`--yes`	跳过确认提示。在持续集成 (CI) 环境中使用此标志。

注意

内存配置不是秘密存储。仅将非密钥设置存储在 project-config.yaml文件中。将 agentengine secret set 命令用于API密钥、连接字符串和其他凭证。 Atlas Agent Engine 会拒绝包含与常见密钥模式匹配的值的上传。

初始内存配置

在启用内存的情况下进行首次部署之前，请执行以下步骤：

编辑 `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已将 extraction_llm.api_key_secret: LLM_API_KEY 添加到您的 project-config.yaml文件中。这与代理的 .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 替换为该名称。

存储内存配置。

从项目根目录运行以下命令，将 memory:区块从 project-config.yaml文件上传到Atlas助手引擎：

agentengine memory configure

部署代理。

运行以下命令以部署代理并预配内存服务器：

agentengine deploy

部署命令会同步待处理的内存配置，并将内存服务器预配为项目运行时的一部分。

更新内存配置

内存配置更改不需要重新部署代理。应用更新的内存设置应用于运行的部署，请执行以下步骤：

使用新的内存设置编辑 `project-config.yaml`文件中的 `memory:`区块。

打开项目根目录下的 project-config.yaml 并配置内存设置。要查看可用选项，请参阅内存的项目结构。

存储更新的配置。

从项目根目录运行以下命令：

agentengine memory configure

应用配置。

agentengine memory apply

agentengine memory apply 命令会重新启动内存服务器，以便注册新配置。该平台会异步传递配置更改，这些更改会在 Pod 重新启动或初创企业时应用更新的配置时生效。如果存储的配置尚未同步，agentengine deploy 命令则会在下一次部署进程中同步配置。

声明自定义内存类型

自定义内存类型存储与四种内置内存类型不对应的特定于域的记录。要声明和使用自定义内存类型，请执行以下步骤：

声明您的自定义类型。

将 custom_memory_types:区块添加到 project-config.yaml文件的 memory: 部分。以下示例创建了一个自定义 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。标签值必须是非空字符串、数字或布尔值。

配置新类型。

运行以下命令，上传更新后的配置，并将其应用到内存服务器，内存服务器会预配每种新类型：

agentengine memory configure
agentengine memory apply

注意

上传声明自定义内存类型的配置后，您将无法编辑或删除该类型的集合或标签集。要更改类型，请声明新的类型名称。

读取和写入自定义内存记录。

在应用程序中，使用 save() 和 retrieve() 方法写入和读取自定义内存记录：

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客户端。使用此客户端可从代理读取和写入内存。平台会从运行时上下文解析当前用户和会话，因此您无需将 user_id 或 session_id 参数显式传递给 app.memory。

重要

服务帐户内存身份

当服务帐户调用已部署的代理时， Atlas Agent Engine 会使用服务帐户自己的身份作为运行时内存身份。平台会忽略调用请求或 agentengine invoke --user-id 标志提供的任何最终用户 user_id 值。

自动轮流记录、提取、合并和 app.memory 操作会使用此已解析身份。因此，通过同一服务帐户进行身份验证的调用股票一个内存用户作用域。

此限制仅适用于服务帐户调用的已部署代理。独立运行的、项目范围的内存服务不受影响。此服务继续接受来自调用者的显式 user_id 和 session_id 值。

要按最终用户隔离内存，请从应用程序中调用独立运行内存服务，并将显式 user_id 和 session_id 值传递给每个调用。要学习；了解更多信息，请参阅使用独立内存服务。

要从 agent-engine-sdk-langgraph代理访问权限内存，请执行以下步骤。每个Atlas Agent Engine代理模板都使用 agent-engine-sdk-langgraph包，因此无论代理的使用案例如何，这些步骤都应用。

访问 `app.memory`客户端。

在代理代码中，检索app.memory客户端并使用它来读取和写入内存。以下示例展示了如何访问权限此客户端：

from agent_engine_sdk_langgraph import App
app = App(app_name="support-agent")
@app.entrypoint
def build_graph():
    # Your LangGraph state machine.
    ...
# Later, in a request handler for a conversation turn:
memory = app.memory

检索与用户消息相关的上下文。

使用 app.memory.build_context() 方法检索与消息相关的内存并将其格式化为上下文，如以下示例所示：

def handle_turn(user_message: str) -> str:
    ctx = memory.build_context(
        query=user_message,
        max_tokens=2000,
    )
    prompt = f"{ctx.formatted_context}\n\nUser: {user_message}"
    return prompt

直接写入长期记忆。

使用 save_* 方法将事实直接存储在内存中。以下示例将写入语义内存：

memory.save_semantic(
    text="Prefers email over phone for support follow-ups.",
    label="contact_preference",
)

搜索相关内存。

使用 search_* 方法检索与查询匹配的内存。以下示例运行语义内存查询：

chunks = memory.search_semantic(
    query="How should we contact this customer?",
    top_k=5,
)

注意

对于已部署的代理，平台会自动记录会话轮次。您无需调用 record_turn() 来保存对话轮次。

后续步骤

为代理启用内存后，您可以在本地测试代理并部署。要学习；了解如何测试代理，请参阅测试代理。要学习；了解如何部署代理，请参阅部署。

要使用在Atlas Agent Engine 外部运行的应用程序的内存，请参阅使用独立内存服务应用程序指南。