Memory Stores Guide¶

Learn how to configure and use memory stores for persistent data in the AgenticAI Core SDK.

Overview¶

Memory stores provide persistent data storage across different scopes (user, application, or session). They enable your applications to maintain state and remember information between interactions.

Design-Time Configuration¶

Basic Setup¶

Define memory stores during application configuration:

from agenticai_core.designtime.models.memory_store import (
    MemoryStore, Namespace, NamespaceType,
    RetentionPolicy, RetentionPeriod, Scope
)

user_preferences = MemoryStore(
    name="User Preferences",
    technical_name="user_preferences",
    type="hotpath",
    description="Stores user-specific preferences",
    schema_definition={
        "type": "object",
        "properties": {
            "firstname": {"type": "string"},
            "lastname": {"type": "string"},
            "theme": {"type": "string"},
            "language": {"type": "string"}
        }
    },
    strict_schema=False,
    namespaces=[
        Namespace(
            name="session_id",
            type=NamespaceType.DYNAMIC,
            value="{session_id}",
            description="Session identifier"
        )
    ],
    scope=Scope.USER_SPECIFIC,
    retention_policy=RetentionPolicy(
        type=RetentionPeriod.MONTH,
        value=6
    )
)

Add to Application¶

from agenticai_core.designtime.models.app import AppBuilder

app_config = AppBuilder() \
    .set_name("My App") \
    .set_memory_store(user_preferences) \
    .build()

app = App(**app_config)

Memory Store Scopes¶

USER_SPECIFIC¶

Data unique to each user (recommended for most use cases):

MemoryStore(
    name="User Data",
    scope=Scope.USER_SPECIFIC,
    ...
)

APPLICATION_WIDE¶

Global data shared across all users:

MemoryStore(
    name="App Config",
    scope=Scope.APPLICATION_WIDE,
    ...
)

SESSION_LEVEL¶

Temporary session data cleared when session ends:

MemoryStore(
    name="Session Cache",
    scope=Scope.SESSION_LEVEL,
    ...
)

Retention Policies¶

Session-Based¶

Data cleared when session ends:

RetentionPolicy(
    type=RetentionPeriod.SESSION,
    value=1
)

Time-Based¶

Data retained for specified duration:

# 7 days
RetentionPolicy(type=RetentionPeriod.DAY, value=7)

# 2 weeks
RetentionPolicy(type=RetentionPeriod.WEEK, value=2)

# 6 months
RetentionPolicy(type=RetentionPeriod.MONTH, value=6)

Runtime Usage in Tools¶

Set Content¶

Save data to memory store:

from agenticai_core.designtime.models.tool import Tool
from agenticai_core.runtime.sessions.request_context import RequestContext

@Tool.register(description="Save user preferences")
async def save_preferences(firstname: str, lastname: str, theme: str = "light"):
    context = RequestContext()
    memory = context.get_memory()

    user_data = {
        "firstname": firstname,
        "lastname": lastname,
        "theme": theme
    }

    result = await memory.set_content('user_preferences', user_data)

    if result.success:
        return f"Preferences saved for {firstname} {lastname}"
    else:
        return "Failed to save preferences"

Get Content¶

Retrieve data with projections:

@Tool.register(description="Get user greeting")
async def get_greeting():
    context = RequestContext()
    memory = context.get_memory()

    # Read with projections (1 = include field)
    result = await memory.get_content('user_preferences', {
        'firstname': 1,
        'lastname': 1,
        'theme': 1
    })

    if result.success and result.data:
        firstname = result.data.get('firstname', 'Guest')
        lastname = result.data.get('lastname', '')
        theme = result.data.get('theme', 'light')

        greeting = f"Hello {firstname} {lastname}!"
        if theme == 'dark':
            greeting += " 🌙"
        else:
            greeting += " ☀️"

        return greeting

    return "Hello Guest! Please set your preferences first."

Delete Content¶

Clear data from memory store:

@Tool.register(description="Clear user data")
async def clear_data():
    context = RequestContext()
    memory = context.get_memory()

    result = await memory.delete_content('user_preferences')

    if result.success:
        return "Data cleared successfully"
    else:
        return "Failed to clear data"

Schema Definition¶

Use JSON Schema for validation:

schema_definition = {
    "type": "object",
    "properties": {
        "user_data": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "email": {"type": "string", "format": "email"},
                "age": {"type": "integer", "minimum": 0}
            },
            "required": ["name", "email"]
        },
        "preferences": {
            "type": "array",
            "items": {"type": "string"}
        }
    }
}

Namespaces¶

Partition data based on different dimensions:

Dynamic Namespaces¶

Namespace(
    name="session_id",
    type=NamespaceType.DYNAMIC,
    value="{session_id}",
    description="Session identifier"
)

Namespace(
    name="user_id",
    type=NamespaceType.DYNAMIC,
    value="{user_id}",
    description="User identifier"
)

Static Namespaces¶

Namespace(
    name="app_version",
    type=NamespaceType.STATIC,
    value="v1.0",
    description="Application version"
)

Multiple Namespaces¶

memory_store = MemoryStore(
    name="Conversation History",
    namespaces=[
        Namespace(
            name="user_id",
            type=NamespaceType.DYNAMIC,
            value="{user_id}",
            description="User identifier"
        ),
        Namespace(
            name="session_id",
            type=NamespaceType.DYNAMIC,
            value="{session_id}",
            description="Session identifier"
        ),
        Namespace(
            name="environment",
            type=NamespaceType.STATIC,
            value="production",
            description="Deployment environment"
        )
    ],
    ...
)

Best Practices¶

Schema Design
- Define clear, specific schemas
- Use strict_schema=True for production
- Include required fields
- Validate data types
Scope Selection
- Use USER_SPECIFIC for personal data
- Use APPLICATION_WIDE for shared resources
- Use SESSION_LEVEL for temporary data
Retention Policies
- Choose appropriate periods
- Consider data privacy requirements
- Clean up old data regularly
Error Handling
- Always check result.success
- Provide fallback values
- Log errors appropriately
- Handle missing data gracefully
Performance
- Use projections to retrieve only needed fields
- Minimize operations in critical paths
- Cache frequently accessed data
- Monitor memory usage
Security
- Don't store sensitive data unencrypted
- Use appropriate scopes for data isolation
- Set reasonable retention policies
- Validate data before storage

Related resources

Send Feedback