# 🔗 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:**

```python
# 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:**

```python
# 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:**

```python
# 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

```python
# 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

```python
# 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

```python
# 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`:

```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`:

```bash
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

```bash
# 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](https://neo4j.com/docs/)
- [Análise Técnica Completa](./ANALISE_VETOR_GRAFO.md)
- [API Reference](./API_REFERENCE.md)