minions-ai-agents/docs/HYBRID_MEMORY_USAGE.md

🔗 Sistema de Memória Híbrida - Guia de Uso

Visão Geral

O sistema de memória do Antigravity Brain combina bancos de dados vetoriais (Qdrant) com grafos de relacionamento (Neo4j) para oferecer aos agentes de IA duas formas complementares de buscar e armazenar informações:

1. Busca Vetorial (Qdrant): Busca semântica rápida por similaridade
2. Grafos de Relacionamento (Neo4j): Navegação estrutural entre entidades relacionadas

Os agentes podem escolher qual abordagem usar dependendo da necessidade da tarefa.

---

🛠️ Ferramentas Disponíveis

1. SearchMemoryTool (Busca Híbrida)

Busca memórias no sistema. Permite escolher entre busca rápida ou busca contextualizada.

Parâmetros:

• query (obrigatório): Pergunta ou tópico a buscar
• use_relationships (opcional, padrão: True): Se usar relacionamentos do grafo

Exemplos de Uso:

# Busca rápida apenas (apenas vetorial)
SearchMemoryTool()._run(
    query="problemas de Zabbix",
    use_relationships=False
)

# Busca contextualizada (vetorial + relacionamentos)
SearchMemoryTool()._run(
    query="problemas de Zabbix",
    use_relationships=True  # Expande com memórias relacionadas
)

Quando usar cada modo:

• use_relationships=False:

  • Resposta rápida necessária
  • Informação direta e simples
  • Não precisa de contexto adicional

• use_relationships=True:

  • Precisa entender relacionamentos
  • Contexto histórico importante
  • Quer ver cadeias de problemas/soluções
  • Classificação complexa

2. SaveMemoryTool (Salvar com Relacionamentos)

Salva informações críticas e opcionalmente extrai relacionamentos automaticamente.

Parâmetros:

• fact (obrigatório): Informação crítica a salvar
• extract_relationships (opcional, padrão: True): Se extrair relacionamentos

Exemplos de Uso:

# Salvar sem extração de relacionamentos (mais rápido)
SaveMemoryTool()._run(
    fact="Template Zabbix atualizado para versão 7.0",
    extract_relationships=False
)

# Salvar com extração automática de relacionamentos
SaveMemoryTool()._run(
    fact="Problema: Zabbix não monitora CPU. Solução: Atualizar template criado por Arthur Mendes",
    extract_relationships=True  # Extrai: Problema → Solução → Agente
)

O que acontece quando extract_relationships=True:

1. Salva no Qdrant (vetorial) - sempre executado
2. Cria nó no Neo4j com metadados
3. Usa LLM para extrair:
   • Tipo de entidade (Problem, Solution, Agent, etc.)
   • Relacionamentos (SOLVES, CREATED_BY, RELATED_TO, etc.)
   • Entidades mencionadas
4. Cria conexões no grafo automaticamente

3. SearchByEntityTool (Busca por Entidade)

Busca todas as memórias relacionadas a uma entidade específica (agente, tecnologia, projeto).

Parâmetros:

• entity_name (obrigatório): Nome da entidade
• entity_type (opcional): Tipo (Agent, Technology, Project, Problem, Solution)
• limit (opcional, padrão: 10): Limite de resultados

Exemplos de Uso:

# Buscar tudo sobre um agente
SearchByEntityTool()._run(
    entity_name="Arthur Mendes",
    entity_type="Agent"
)

# Buscar tudo sobre uma tecnologia
SearchByEntityTool()._run(
    entity_name="Zabbix",
    entity_type="Technology"
)

# Buscar sem especificar tipo
SearchByEntityTool()._run(
    entity_name="Infrastructure Project"
)

---

🎯 Decisão de Uso para Agentes

Quando usar busca simples (use_relationships=False):

✅ Use quando:

• Precisa de informação direta e rápida
• Pergunta é simples: "Qual é a versão do Zabbix?"
• Não precisa de contexto histórico
• Classificação binária (sim/não)
• Performance é crítica

❌ Não use quando:

• Precisa entender cadeia de eventos
• Contexto de relacionamentos é importante
• Quer ver padrões históricos

Quando usar busca com relacionamentos (use_relationships=True):

✅ Use quando:

• Precisa entender "por quê" e "como"
• Quer ver problemas relacionados e suas soluções
• Classificação complexa necessária
• Precisa rastrear decisões passadas
• Contexto histórico é importante

❌ Não use quando:

• Resposta precisa ser instantânea
• Informação é trivial
• Sistema de grafo não está disponível

Quando usar busca por entidade (SearchByEntityTool):

✅ Use quando:

• Quer tudo relacionado a uma pessoa/projeto/tecnologia
• Precisa fazer auditoria ou relatório
• Quer mapear responsabilidades
• Precisa entender impacto de uma decisão

---

📊 Exemplos Práticos

Exemplo 1: Validação de Template Zabbix

Cenário: Agente precisa validar template Zabbix

# 1. Busca rápida: há algum problema conhecido com este template?
SearchMemoryTool()._run(
    query="template Zabbix problemas validação",
    use_relationships=False
)

# 2. Se encontrar problema, buscar contexto completo
SearchMemoryTool()._run(
    query="template Zabbix UUID",
    use_relationships=True  # Ver cadeia: problema → solução → agente
)

Exemplo 2: Criar Novo Agente

Cenário: Criar agente para DevOps

# 1. Verificar se já existe agente similar
SearchMemoryTool()._run(
    query="agente DevOps",
    use_relationships=True  # Ver relacionamentos com outros agentes
)

# 2. Salvar novo agente com relacionamentos
SaveMemoryTool()._run(
    fact="Novo agente Bob criado para DevOps, especializado em Docker e Kubernetes",
    extract_relationships=True  # Conectar com tecnologias mencionadas
)

Exemplo 3: Rastrear Problema

Cenário: Usuário reporta problema recorrente

# Buscar tudo sobre o problema usando entidade
SearchByEntityTool()._run(
    entity_name="Zabbix CPU monitoring",
    entity_type="Problem"
)

# Buscar soluções relacionadas
SearchMemoryTool()._run(
    query="solução monitoramento CPU Zabbix",
    use_relationships=True  # Ver problemas → soluções → implementações
)

---

🔧 Configuração

Variáveis de Ambiente

Adicione ao .env:

# Neo4j Configuration (Graph Database)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=antigravity2024
NEO4J_DATABASE=neo4j

Docker Compose

O Neo4j já está configurado no docker-compose.yml:

docker-compose up -d neo4j

Verificar Conexão

Acesse o Neo4j Browser em: http://localhost:7474

---

🚀 Performance

Benchmarks aproximados:

• Busca vetorial apenas: ~50-200ms
• Busca com relacionamentos: ~200-500ms
• Extração de relacionamentos: ~1-3s (depende do LLM)

Otimizações:

• Use use_relationships=False para queries frequentes
• Use extract_relationships=False ao salvar muitas memórias rapidamente
• Batch de relacionamentos pode ser extraído posteriormente

---

🐛 Troubleshooting

Neo4j não conecta

# Verificar se container está rodando
docker ps | grep neo4j

# Ver logs
docker logs antigravity_neo4j

# Reiniciar
docker-compose restart neo4j

Relacionamentos não são extraídos

• Verificar se LLM está configurado corretamente
• Verificar logs: logger.error em graph_wrapper.py
• Testar conexão Neo4j manualmente

Busca muito lenta

• Reduzir limit nos parâmetros
• Usar use_relationships=False quando não necessário
• Verificar índices no Neo4j: SHOW INDEXES

---

📚 Referências

• Documentação Neo4j
• Análise Técnica Completa
• API Reference