Skip to main content

​
Memory Systems Database

The Memory Systems Database defines how MOOD MNKY agents store, retain, and recall information across interactions. It provides the architecture for context retention, personalization, and continuous learning that enables agents to deliver coherent, personalized experiences.

​
Purpose and Role

The Memory Systems Database defines “how” agents remember, enabling them to maintain context, recall past interactions, and deliver personalized experiences.
This database documents:
  • Memory types and their specific purposes
  • Storage mechanisms and durations
  • Retrieval processes and priorities
  • Memory consolidation workflows
  • Privacy and data retention policies
  • Memory optimization and efficiency

​
Schema and Structure

  • Database Schema
  • Example Entry
{
  "memory_id": "string",
  "agent_id": "string",
  "user_id": "string",
  "memory_type": "string",
  "content": "string",
  "metadata": "object",
  "created_at": "timestamp",
  "expires_at": "timestamp",
  "importance": "number",
  "access_count": "number",
  "last_accessed": "timestamp",
  "tags": "array",
  "related_memories": "array",
  "embedding": "vector"
}

​
Field Descriptions

A unique identifier for the memory item.
The ID of the agent that owns this memory.
The ID of the user this memory relates to, if applicable.
The category of memory (short_term, working, long_term).
The actual information stored in the memory.
Additional contextual information about the memory.
When the memory was first created.
When the memory should expire, if applicable.
A value from 0-1 indicating the memory’s importance.
How many times this memory has been accessed.
When the memory was last retrieved.
Keywords for categorization and retrieval.
Vector representation for semantic search.

​
Memory Types

The MOOD MNKY memory system employs a cognitive-inspired architecture with three distinct memory types:

Short-term Memory

  • Current conversation context
  • Recent exchanges (last 10-20 messages)
  • Active session information
  • Temporary preferences
  • Immediate task context
  • Short duration (minutes to hours)

Working Memory

  • Active topics and goals
  • Current user needs
  • Contextual knowledge
  • Intermediate reasoning
  • Task-specific information
  • Medium duration (hours to days)

Long-term Memory

  • User preferences and profile
  • Historical interactions
  • Recurring patterns
  • Persistent knowledge
  • Relationship context
  • Extended duration (months to years)

​
Memory Operations

​
Memory Creation and Storage

from agents import Agent, Tool, Runner
from memory_system import MemorySystem

# Initialize memory system
memory = MemorySystem()

# Define memory creation tool
def store_memory(content: str, memory_type: str, importance: float = 0.5, 
                 tags: list = None, user_id: str = None) -> dict:
    """Store information in the agent's memory."""
    return memory.create(
        content=content,
        memory_type=memory_type,
        importance=importance,
        tags=tags or [],
        user_id=user_id
    )

# Create tool for the agent
memory_tool = Tool(
    name="store_memory",
    description="Store important information in memory",
    function=store_memory
)

# Create agent with the tool
agent = Agent(
    name="MOOD MNKY",
    instructions="You are MOOD MNKY, the brand assistant. Remember important information about users.",
    tools=[memory_tool]
)

# Run the agent
runner = Runner()
result = await runner.run(agent, "I have sensitive skin and prefer fragrance-free products")

​
Memory Retrieval

from agents import Agent, Tool, Runner
from memory_system import MemorySystem

# Initialize memory system
memory = MemorySystem()

# Define memory retrieval tool
def retrieve_memories(query: str, memory_type: str = None, 
                      limit: int = 5, user_id: str = None) -> list:
    """Retrieve relevant memories based on the query."""
    return memory.search(
        query=query,
        memory_type=memory_type,
        limit=limit,
        user_id=user_id
    )

# Create tool for the agent
retrieval_tool = Tool(
    name="retrieve_memories",
    description="Recall relevant information from memory",
    function=retrieve_memories
)

# Create agent with the tool
agent = Agent(
    name="MOOD MNKY",
    instructions="You are MOOD MNKY, the brand assistant. Use your memory to provide personalized assistance.",
    tools=[retrieval_tool]
)

# Run the agent
runner = Runner()
result = await runner.run(agent, "What products would you recommend for me?")

​
Integration with OpenAI Agents SDK

​
Memory-Aware Agent Creation

from agents import Agent, Runner
from memory_system import MemorySystem

# Initialize memory system
memory = MemorySystem()

async def create_memory_aware_agent(user_id: str) -> Agent:
    # Retrieve relevant memories for the user
    user_memories = memory.get_user_summary(user_id)
    
    # Create agent with memory-infused instructions
    agent = Agent(
        name="MOOD MNKY",
        instructions=f"""You are MOOD MNKY, the brand assistant.
        
        What you know about this user:
        {user_memories}
        
        Use this information to provide personalized assistance."""
    )
    
    return agent

# Create and run agent for a specific user
agent = await create_memory_aware_agent("usr_425b3c")
runner = Runner()
result = await runner.run(agent, "Can you recommend something new for me to try?")

​
Memory MCP Server Integration

from agents import Agent, Runner
from agents.mcp.server import MCPServerSse, MCPServerSseParams

# Set up MCP server for memory system
async with MCPServerSse(
    params=MCPServerSseParams(
        url="http://localhost:3000/memory-mcp",
        headers={"Authorization": f"Bearer {API_KEY}"}
    ),
    name="memory_mcp",
    cache_tools_list=True
) as memory_server:
    
    # Create agent with memory MCP server
    agent = Agent(
        name="MOOD MNKY",
        instructions="You are MOOD MNKY, the brand assistant. Use your memory to provide personalized assistance.",
        mcp_servers=[memory_server]
    )
    
    # Run the agent
    runner = Runner()
    result = await runner.run(agent, "What was that candle I liked last time?")

​
Memory Processes

Encoding

The process of creating new memories from interactions, observations, and explicit information. Includes relevance assessment, metadata tagging, and importance scoring.

Storage

The organization and persistence of memories across different systems based on memory type, including vector databases for semantic retrieval and optimized storage strategies.

Retrieval

The process of accessing relevant memories based on context, query, or task needs, using semantic search, recency weighting, and importance factors.

Consolidation

The workflow that transfers information between memory types, summarizes recurring patterns, and optimizes long-term storage for effective recall.

Forgetting

The controlled expiration of low-value or outdated memories to maintain system efficiency and comply with privacy requirements.

Reflection

The process of analyzing, connecting, and deriving insights from existing memories to improve future interactions and predictions.

​
Memory Storage Architecture

The MOOD MNKY memory system uses differentiated storage based on memory type requirements:
  • Short-term Memory
  • Working Memory
  • Long-term Memory
┌─────────────────────┐
│      Redis Cache    │
├─────────────────────┤
│ - In-memory storage │
│ - Fast access       │
│ - TTL expiration    │
│ - Session scoped    │
└─────────────────────┘

​
Retrieval Mechanisms

The memory system employs multiple retrieval strategies: 
def retrieve_by_context(context_type: str, user_id: str) -> list:
    """Retrieve memories relevant to a specific context."""
    return memory.search(
        filters={
            "metadata.context": context_type,
            "user_id": user_id
        },
        sort_by="importance",
        limit=10
    )

product_memories = retrieve_by_context("product_recommendation", "usr_425b3c")

​
Semantic Similarity

def retrieve_similar(query: str, user_id: str) -> list:
    """Find memories semantically similar to the query."""
    # Generate embedding for query
    query_embedding = generate_embedding(query)
    
    return memory.vector_search(
        vector=query_embedding,
        user_id=user_id,
        limit=5
    )

similar_memories = retrieve_similar("What scents help with sleep?", "usr_425b3c")

​
Recency-based Access

def retrieve_recent(memory_type: str, user_id: str, days: int = 7) -> list:
    """Retrieve recent memories of a specific type."""
    cutoff_date = datetime.now() - timedelta(days=days)
    
    return memory.search(
        filters={
            "memory_type": memory_type,
            "user_id": user_id,
            "created_at": {"$gte": cutoff_date}
        },
        sort_by="created_at",
        sort_order="desc",
        limit=20
    )

recent_interactions = retrieve_recent("short_term", "usr_425b3c", 3)

​
Privacy and Data Management

Retention Policies

  • Short-term: 24 hours to 7 days
  • Working memory: 30-90 days
  • Long-term: 1-2 years with consent
  • Automated expiration enforcement
  • Policy-based retention exceptions

Explicit Forgetting

  • User-initiated memory deletion
  • Right to be forgotten implementation
  • Cascade deletion across memory types
  • Audit trail of deletion requests
  • Verification of complete removal

Data Minimization

  • Relevance filtering during encoding
  • Abstraction of personal details
  • Targeted anonymization techniques
  • PII detection and special handling
  • Regular minimization reviews

Access Controls

  • Agent-specific memory isolation
  • Role-based memory access
  • Cross-agent memory sharing rules
  • Consent-based memory utilization
  • Audit logging of memory access

​
Best Practices for Memory Management

​
Memory Design Principles

  • Purpose-driven Storage: Store only information with clear future utility
  • Structured Abstraction: Standardize how similar types of information are stored
  • Context Enrichment: Include relevant metadata to improve retrieval accuracy
  • Privacy by Design: Apply minimization and consent principles from the start
  • Retrieval Optimization: Design memory formats that facilitate efficient recall

​
Implementation Guidelines

  • Memory Types Alignment: Use appropriate memory type for information’s lifespan and importance
  • Storage Technology Selection: Match storage technology to memory characteristics
  • Embedding Strategy: Create consistent, high-quality embeddings for semantic search
  • Consolidation Automation: Implement regular processes to optimize memory organization
  • Performance Monitoring: Track and optimize memory operation performance

​
Testing and Validation

  • Memory Recall Testing: Validate retrieval effectiveness and accuracy
  • Load Testing: Ensure system performance with large memory volumes
  • Privacy Compliance: Verify adherence to data protection requirements
  • Forgetting Verification: Confirm complete data removal when required
  • Cross-session Persistence: Verify appropriate memory retention between sessions

​
Additional Resources