Strands Memory Agent

A conversational AI agent with persistent memory capabilities using Strands Agents, Mem0, and local FAISS storage.

🚀 Features

• Persistent Memory: Remembers conversations and information across sessions
• Local Storage: No cloud dependencies - everything runs locally
• Intelligent Memory: Mem0's advanced memory capabilities (relationship inference, semantic understanding)
• FAISS Backend: High-performance local vector database
• OpenAI Embeddings: High-quality semantic vectors
• Conversation Loop: Interactive chat interface with memory commands

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Strands Agent  │───▶│  Custom Memory  │───▶│  Mem0 + FAISS   │
│                 │    │     Tool        │    │   Backend       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

• Strands Agent: Manages conversation flow and tool orchestration
• Custom Memory Tool: Bridges the agent with Mem0's memory system
• Mem0 + FAISS: Provides intelligent memory with local vector storage

📋 Prerequisites

• Python 3.8+
• OpenAI API key
• uv (recommended) or pip

🛠️ Installation

1. Clone the repository:

   git clone https://github.com/labeveryday/strands-memory-agent.git
   cd strands-memory-agent

2. Install dependencies:

   uv sync
   # or with pip:
   # pip install -r requirements.txt

3. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your OpenAI API key

⚙️ Configuration

Environment Variables

Create a .env file with:

OPENAI_API_KEY=your_openai_api_key_here

Memory Configuration

The memory system is configured in memory_example.py:

config = {
    "vector_store": {
        "provider": "faiss",
        "config": {
            "collection_name": "agent_memories",
            "path": "./local_memories",
            "distance_strategy": "cosine"
        }
    }
}

🚀 Usage

Basic Usage

Run the conversation loop:

uv run memory_example.py

Available Commands

• help - Show available commands
• memory - Display stored memories
• quit / exit / bye - Exit the conversation

Memory Operations

The agent can:

• Store information you share
• Search memories semantically
• List all memories for review
• Maintain context across conversations

🔧 Customization

Changing User ID

Modify the USER_ID variable in memory_example.py:

USER_ID = "your_custom_user_id"

Memory Storage Path

Change the storage location in the config:

"path": "./your_custom_path"

Distance Strategy

Choose from available FAISS distance strategies:

• "cosine" - Best for semantic similarity
• "euclidean" - L2 distance
• "inner_product" - Dot product similarity

📁 Project Structure

strands-memory-agent/
├── README.md                 # This file
├── memory_example.py         # Main application with conversation loop
├── pyproject.toml           # Project dependencies and configuration
├── .env.example             # Environment variables template
├── .gitignore               # Git ignore rules
└── local_memories/          # Memory storage directory (created automatically)

🧠 How It Works

1. Initialization: Creates Mem0 instance with FAISS backend
2. Tool Creation: Wraps Mem0 in a custom tool for Strands integration
3. Agent Setup: Creates Strands Agent with memory capabilities
4. Conversation Loop: Interactive chat with persistent memory
5. Memory Operations: Store, search, and retrieve information using Mem0's intelligence

🔍 Memory Capabilities

What Mem0 Provides

• Semantic Understanding: Not just vector similarity, but actual meaning comprehension
• Relationship Inference: Connects related memories intelligently
• Memory Consolidation: Merges and organizes information
• Context Awareness: Understands deeper meaning and context
• Temporal Reasoning: Understands when and how memories relate

What FAISS Provides

• Local Storage: No cloud dependencies
• High Performance: Optimized for speed and efficiency
• Scalability: Handles large numbers of memories
• Multiple Distance Metrics: Cosine, Euclidean, Inner Product

🐛 Troubleshooting

Common Issues

1. OpenAI API Key Error

   • Ensure .env file exists with OPENAI_API_KEY
   • Verify API key is valid and has credits

2. Memory Not Persisting

   • Check ./local_memories/ directory exists
   • Verify file permissions

3. Import Errors

   • Ensure all dependencies are installed: uv sync
   • Check Python version compatibility

Debug Mode

Enable debug logging by modifying the logging level in the code.

🔄 Development

Adding New Tools

Create new tools using the @tool decorator:

@tool
def your_custom_tool(param: str) -> str:
    """Your tool description."""
    return "Your tool result"

Then add the tool to:

multimodal_agent = Agent(
    system_prompt=MULTIMODAL_SYSTEM_PROMPT,
    tools=[memory_tool, your_custom_tool],
    model=model,
)

Extending Memory Capabilities

Modify the memory_tool function to add new actions or enhance existing ones.

📚 Dependencies

• strands-agents: AI agent framework
• mem0ai: Intelligent memory system
• faiss-cpu: Local vector database
• openai: Embedding and LLM services
• python-dotenv: Environment variable management

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Strands Agents for the agent framework
• Mem0 for intelligent memory capabilities
• FAISS for local vector storage
• OpenAI for embedding and language models

📞 Support

If you encounter issues or have questions:

1. Check the troubleshooting section above
2. Search existing issues in the repository
3. Create a new issue with detailed information

---

Happy coding! 🚀