Summary
The current naming convention in src/bedrock_agentcore/memory/client.py uses the term "memories" inconsistently across different methods, leading to potential confusion about what entities are being referenced. Specifically:
list_memories() - Lists high-level memory stores/resourcesretrieve_memories() - Retrieves individual memory items/events from within a memory store
Problem Description
The term "memories" is being used to refer to two distinct concepts:
- Memory Stores/Resources: The top-level containers that hold conversational data (what
list_memories() returns)
- Memory Items/Events: Individual pieces of stored information within those memory stores (what
retrieve_memories() returns)
This creates semantic confusion where the same plural noun refers to different conceptual entities at different hierarchical levels.
Current confusing usage:
# This returns memory stores/resources
for memory in client.list_memories():
print(f"Memory ID: {memory.get('id')}")
# This returns memory items/events from within a memory store
memories = client.retrieve_memories(
memory_id=memory.get("id"),
namespace="/summaries/User84/OrderSupportSession1",
query="can you summarize the support issue"
)Impact
- Developer confusion: New users may expect both methods to return similar entity types
- Code readability: Variable naming becomes ambiguous (
memories could refer to stores or items)
- API consistency: The naming doesn't clearly indicate the hierarchical relationship between these concepts
- Documentation overhead: Requires extra explanation to clarify the difference
Suggested Solution
Rename methods to clearly distinguish between the two entity types:
Option 1: Explicit hierarchy naming
# Current
list_memories() → list_memory_stores()
retrieve_memories() → retrieve_memory_items()
# Or alternatively
list_memories() → list_memory_resources()
retrieve_memories() → retrieve_memory_entries()
Option 2: Domain-specific naming
# Current
list_memories() → list_memory_stores()
retrieve_memories() → retrieve_events() # Aligns with create_event() and list_events()
Option 3: Consistent plural/singular pattern
# Current
list_memories() → list_memory_stores()
retrieve_memories() → retrieve_memory_items()
Recommendation
Option 2 seems most appropriate as it:
- Aligns with existing method names (
create_event(), list_events())
- Uses domain-appropriate terminology (events are the atomic units stored)
- Maintains clarity about the hierarchical relationship
- Minimises breaking changes by keeping the most intuitive name (
list_memories() → list_memory_stores())
Summary
The current naming convention in
src/bedrock_agentcore/memory/client.pyuses the term "memories" inconsistently across different methods, leading to potential confusion about what entities are being referenced. Specifically:list_memories()- Lists high-level memory stores/resourcesretrieve_memories()- Retrieves individual memory items/events from within a memory storeProblem Description
The term "memories" is being used to refer to two distinct concepts:
list_memories()returns)retrieve_memories()returns)This creates semantic confusion where the same plural noun refers to different conceptual entities at different hierarchical levels.
Current confusing usage:
Impact
memoriescould refer to stores or items)Suggested Solution
Rename methods to clearly distinguish between the two entity types:
Option 1: Explicit hierarchy naming
Option 2: Domain-specific naming
Option 3: Consistent plural/singular pattern
Recommendation
Option 2 seems most appropriate as it:
create_event(),list_events())list_memories()→list_memory_stores())