Detalhes do Projeto MemoRizz

Visão Geral do Projeto

MemoRizz é uma biblioteca Python de gerenciamento de memória projetada especificamente para aplicações de IA, fornecendo aos agentes de IA a capacidade de armazenar informações de forma persistente, com consciência de contexto e pesquisa semântica. Este projeto integra perfeitamente o MongoDB com a tecnologia de embeddings vetoriais, capacitando os agentes com funções cognitivas complexas, incluindo rastreamento do histórico de conversas, gerenciamento do uso de ferramentas e manutenção de papéis consistentes.

⚠️ Aviso Importante: MemoRizz é uma biblioteca experimental e destina-se apenas a fins educacionais. Não é recomendada para uso em ambientes de produção ou com dados sensíveis.

Principais Recursos

🧠 Memória Persistente

• Permite que os agentes de IA retenham a memória entre as sessões
• Suporta armazenamento e recuperação de informações de longo prazo
• Gerenciamento de memória com consciência de contexto

🔍 Pesquisa Semântica

• Encontre informações relevantes usando linguagem natural
• Pesquisa de similaridade baseada em embeddings vetoriais
• Integração com a Pesquisa Vetorial do MongoDB Atlas

🛠️ Integração de Ferramentas

• Descoberta e execução automática de funções
• Converte funções Python em ferramentas invocáveis por LLMs
• Indexação semântica e descoberta de ferramentas por linguagem natural

👤 Sistema de Persona

• Criação de papéis de agente consistentes e especializados
• Personalização do comportamento e estilo de resposta do agente
• Definição de histórico e objetivos do papel

📊 Pesquisa Vetorial

• Recuperação eficiente com a Pesquisa Vetorial do MongoDB Atlas
• Embedding e indexação automática de informações armazenadas
• Suporte a múltiplas classificações de tipos de memória

Arquitetura do Sistema

┌─────────────────┐
│ MemAgent        │ ← Interface de agente de alto nível
├─────────────────┤
│ Persona         │ ← Personalidade e comportamento do agente
├─────────────────┤
│ Toolbox         │ ← Registro e descoberta de funções
├─────────────────┤
│ Memory Provider │ ← Camada de abstração de armazenamento
├─────────────────┤
│ Vector Search   │ ← Similaridade semântica e recuperação
├─────────────────┤
│ MongoDB         │ ← Backend de armazenamento persistente
└─────────────────┘

Requisitos de Instalação

• Python 3.7+
• Conta MongoDB Atlas (ou MongoDB local com pesquisa vetorial)
• Chave de API OpenAI (para embeddings e funcionalidades LLM)

Método de Instalação

pip install memorizz

Exemplo de Uso Básico

1. Configuração Básica do Agente

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

# Configurar a chave da API
os.environ["OPENAI_API_KEY"] = "your-openai-api-key"

# Configurar o provedor de memória MongoDB
mongodb_config = MongoDBConfig(uri="your-mongodb-atlas-uri")
memory_provider = MongoDBProvider(mongodb_config)

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

# Iniciar conversa - o agente manterá a memória entre as sessões
response = agent.run("Hello! My name is John and I'm a software engineer.")
print(response)

# Mais tarde, em outra sessão...
response = agent.run("What did I tell you about myself?")
print(response)  # O agente lembra que John é engenheiro de software

2. Uso do Sistema de Persona

from memorizz.persona import Persona

# Criar persona de especialista técnico
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."
)

# Aplicar a persona ao agente
agent.set_persona(tech_expert)
agent.save()

# Agora o agente responderá como um especialista técnico
response = agent.run("How should I design a scalable microservices architecture?")

3. Integração de Ferramentas

from memorizz.database.mongodb import MongoDBTools, MongoDBToolsConfig

# Configurar o banco de dados de ferramentas
tools_config = MongoDBToolsConfig(
    uri="your-mongodb-atlas-uri",
    database_name="my_tools_db"
)

# Registrar ferramentas usando o decorador
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."""
        # Seu código de integração da API de clima
        return f"Weather in {city}: 72°F, sunny"

# Adicionar ferramentas ao agente
agent.add_tool(toolbox=tools)

# O agente agora pode descobrir e usar essas ferramentas automaticamente
response = agent.run("What's the weather in San Francisco and calculate interest on $1000 at 5% for 3 years?")

Tipos de Memória

MemoRizz suporta diferentes categorias de memória para organizar informações:

• Conversation: Histórico de chat e contexto de diálogo
• Task: Informações orientadas a objetivos e rastreamento de progresso
• Workflow: Informações de processos de múltiplos passos
• General: Conhecimento factual e informações declarativas
• Working: Espaço de processamento temporário (contexto LLM)

Recursos Avançados

Armazenamento e Recuperação de Memória

# Armazenar informações com embedding automático
agent.store_memory("I prefer Python for backend development", memory_type="general")

# Mais tarde, uma consulta semanticamente relevante recuperará essas informações
response = agent.run("What programming languages do I like?")
# O agente encontrará e usará a preferência armazenada

Controle de Memória com Metadados

# Armazenar informações com metadados
agent.store_memory(
    content="Completed project X with React and Node.js",
    memory_type="task",
    metadata={"project": "X", "technologies": ["React", "Node.js"]}
)

# Recuperar memória específica
memories = agent.retrieve_memories(
    query="projects with React",
    memory_type="task",
    limit=5
)

Configuração do Ambiente

# Obrigatório
export OPENAI_API_KEY="your-openai-api-key"
export MONGODB_URI="your-mongodb-atlas-uri"

# Opcional
export MONGODB_DB_NAME="memorizz"  # Nome do banco de dados padrão

Passos de Configuração

1. Crie um cluster MongoDB Atlas
2. Habilite a Pesquisa Vetorial no cluster
3. Crie um banco de dados e coleções para seu agente
4. Obtenha a string de conexão

Perguntas Frequentes

• Conexão MongoDB: Certifique-se de que seu IP esteja na lista de permissões no Atlas
• Pesquisa Vetorial: Verifique se a pesquisa vetorial está habilitada no cluster
• Chave de API: Verifique se a chave de API OpenAI é válida e tem créditos

Projetos de Exemplo

Confira exemplos de trabalho completos no diretório examples/:

• Agente Básico: Um agente de conversação simples com memória
• Agente Especializado: Um especialista técnico com persona
• Integração de Ferramentas: Um agente com chamadas de função personalizadas
• Gerenciamento de Memória: Armazenamento e recuperação avançados de memória

Valor de Aprendizagem Técnica

Esta biblioteca demonstra os seguintes conceitos-chave:

• Arquitetura de Agentes de IA: Memória, raciocínio e uso de ferramentas
• Bancos de Dados Vetoriais: Pesquisa e recuperação semântica
• Integração LLM: Chamada de função e gerenciamento de contexto
• Design de Software: Abstrações claras e arquitetura escalável