MemoRizz Project Detailed Introduction

Project Overview

MemoRizz is a Python memory management library specifically designed for AI applications, providing AI agents with persistent, context-aware, and semantically searchable information storage capabilities. By seamlessly integrating MongoDB with vector embedding technology, this project empowers agents with sophisticated cognitive functions, including conversation history tracking, tool usage management, and consistent role maintenance.

⚠️ Important Warning: MemoRizz is an experimental library intended for educational purposes only. It is not recommended for use in production environments or with sensitive data.

Core Features

🧠 Persistent Memory

• Enables AI agents to retain memory across sessions
• Supports long-term information storage and retrieval
• Context-aware memory management

🔍 Semantic Search

• Find relevant information using natural language
• Similarity search based on vector embeddings
• MongoDB Atlas Vector Search integration

🛠️ Tool Integration

• Automatic discovery and execution of functions
• Converts Python functions into LLM-callable tools
• Semantic indexing and natural language discovery of tools

👤 Persona System

• Create consistent, specialized agent roles
• Customize agent behavior and response style
• Set role background and objectives

📊 Vector Search

• Efficient retrieval with MongoDB Atlas Vector Search
• Automatic embedding and indexing of stored information
• Supports multiple memory type classifications

System Architecture

┌─────────────────┐
│ MemAgent        │ ← High-level agent interface
├─────────────────┤
│ Persona         │ ← Agent personality and behavior
├─────────────────┤
│ Toolbox         │ ← Function registration and discovery
├─────────────────┤
│ Memory Provider │ ← Storage abstraction layer
├─────────────────┤
│ Vector Search   │ ← Semantic similarity and retrieval
├─────────────────┤
│ MongoDB         │ ← Persistent storage backend
└─────────────────┘

Installation Requirements

• Python 3.7+
• MongoDB Atlas account (or local MongoDB with Vector Search)
• OpenAI API Key (for embeddings and LLM features)

Installation Method

pip install memorizz

Basic Usage Examples

1. Basic Agent Setup

import os
from memorizz.memory_provider.mongodb.provider import MongoDBConfig, MongoDBProvider
from memorizz.memagent import MemAgent
from memorizz.llms.openai import OpenAI

# Set API Key
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# Configure MongoDB memory provider
mongodb_config = MongoDBConfig(uri="your-mongodb-atlas-uri")
memory_provider = MongoDBProvider(mongodb_config)

# Create MemAgent
agent = MemAgent(
    model=OpenAI(model="gpt-4"),
    instruction="You are a helpful assistant with persistent memory.",
    memory_provider=memory_provider
)

# Start conversation - agent will retain memory across sessions
response = agent.run("Hello! My name is John and I'm a software engineer.")
print(response)

# Later in another session...
response = agent.run("What did I tell you about myself?")
print(response)  # Agent remembers John is a software engineer

2. Persona System Usage

from memorizz.persona import Persona

# Create a tech expert persona
tech_expert = Persona(
    name="TechExpert",
    role="Senior Software Engineer",
    goals="Help developers solve complex technical problems with detailed explanations.",
    background="10+ years experience in Python, AI/ML, and distributed systems."
)

# Apply persona to agent
agent.set_persona(tech_expert)
agent.save()

# Now the agent will respond as a tech expert
response = agent.run("How should I design a scalable microservices architecture?")

3. Tool Integration

from memorizz.database.mongodb import MongoDBTools, MongoDBToolsConfig

# Configure tool database
tools_config = MongoDBToolsConfig(
    uri="your-mongodb-atlas-uri",
    database_name="my_tools_db"
)

# Register tools using a decorator
with MongoDBTools(tools_config) as tools:
    toolbox = tools.mongodb_toolbox()
    
    @toolbox
    def calculate_compound_interest(principal: float, rate: float, time: int) -> float:
        """Calculate compound interest for financial planning."""
        return principal * (1 + rate) ** time
    
    @toolbox
    def get_weather(city: str) -> str:
        """Get current weather for a city."""
        # Your weather API integration code
        return f"Weather in {city}: 72°F, sunny"

# Add tools to the agent
agent.add_tool(toolbox=tools)

# The agent can now automatically discover and use these tools
response = agent.run("What's the weather in San Francisco and calculate interest on $1000 at 5% for 3 years?")

Memory Types

MemoRizz supports different memory categories to organize information:

• Conversation: Chat history and conversational context
• Task: Goal-oriented information and progress tracking
• Workflow: Multi-step process information
• General: Factual knowledge and declarative information
• Working: Temporary processing space (LLM context)

Advanced Features

Memory Storage and Retrieval

# Store information with automatic embedding
agent.store_memory("I prefer Python for backend development", memory_type="general")

# Later, semantically related queries will retrieve this information
response = agent.run("What programming languages do I like?")
# The agent will find and use the stored preference

Memory Control with Metadata

# Store information with metadata
agent.store_memory(
    content="Completed project X with React and Node.js",
    memory_type="task",
    metadata={"project": "X", "technologies": ["React", "Node.js"]}
)

# Retrieve specific memories
memories = agent.retrieve_memories(
    query="projects with React",
    memory_type="task",
    limit=5
)

Environment Configuration

# Required
export OPENAI_API_KEY="your-openai-api-key"
export MONGODB_URI="your-mongodb-atlas-uri"

# Optional
export MONGODB_DB_NAME="memorizz"  # Default database name

Setup Steps

1. Create a MongoDB Atlas cluster
2. Enable Vector Search on your cluster
3. Create a database and collection for your agent
4. Obtain your connection string

Common Issues

• MongoDB Connection: Ensure your IP is whitelisted in Atlas
• Vector Search: Verify Vector Search is enabled on your cluster
• API Key: Check if your OpenAI API key is valid and has credits

Example Projects

See full working examples in the examples/ directory:

• Basic Agent: Simple conversational agent with memory
• Specialized Agent: Tech expert with a persona
• Tool Integration: Agent with custom function calling
• Memory Management: Advanced memory storage and retrieval

Technical Learning Value

This library demonstrates the following key concepts:

• AI Agent Architecture: Memory, reasoning, and tool usage
• Vector Databases: Semantic search and retrieval
• LLM Integration: Function calling and context management
• Software Design: Clear abstractions and scalable architecture