Skip to content

Memory env var naming differs between Starter Toolkit and CLI — migration guidance needed #824

@aidandaly24

Description

@aidandaly24

Description

This is not a CLI bug. The CLI has always used dynamic memory env var names (MEMORY_{NAME}_ID). However, the Starter Toolkit uses a different static convention (BEDROCK_AGENTCORE_MEMORY_ID), and users migrating between the two products encounter a silent breakage.

  • Starter Toolkit convention: BEDROCK_AGENTCORE_MEMORY_ID (static, single memory)
  • CLI convention: MEMORY_{NAME}_ID (dynamic, based on memory resource name, e.g. MEMORY_SHAREDMEMORY_ID)

These are two different products with different env var patterns. They are not directly compatible.

Current State

The agentcore import command (added in #620) already handles this — when importing a Starter Toolkit project, it warns users to update their env var references:

Warning: Memory "SharedMemory" env var must be updated in your agent code:
  - MEMORY_ID = os.getenv("BEDROCK_AGENTCORE_MEMORY_ID")
  + MEMORY_ID = os.getenv("MEMORY_SHAREDMEMORY_ID")

Users migrating from the Starter Toolkit should use agentcore import when possible, which handles the conversion and warns about env var changes.

What's Missing

  • Documentation should make it clearer that the CLI and Starter Toolkit use different env var conventions
  • Users who don't use agentcore import (e.g. manually recreating their project in the CLI) have no guidance about the env var difference
  • Consider adding a note in the memory docs (docs/memory.md) about the naming convention and how it differs from the Starter Toolkit

Context

Reported by a user who was using the Starter Toolkit pattern (BEDROCK_AGENTCORE_MEMORY_ID) and found that the CLI injects MEMORY_SHAREDMEMORY_ID instead. The env var mismatch causes os.getenv() to return None silently at runtime.

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't working

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions