295 lines
7.3 KiB
Markdown
295 lines
7.3 KiB
Markdown
# 🔗 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)
|