Como Exportar para Neo4j

Guia prático para criar knowledge graphs a partir de anotações Synesis

1 Como Exportar para Neo4j

Este guia mostra como transformar suas anotações Synesis em um grafo de conhecimento no Neo4j, permitindo análises avançadas de rede, visualizações interativas e integração com sistemas de GraphRAG.

Você deve usar este guia se:

Precisa visualizar relações complexas entre conceitos
Quer calcular métricas de centralidade, comunidades ou PageRank
Precisa integrar com sistemas de IA (Claude Desktop via MCP)
Quer análises de rede para publicações acadêmicas

1.1 Pré-requisitos

Python 3.11+ instalado
Projeto Synesis compilável (válido)
Neo4j Desktop ou Neo4j Cloud (AuraDB)

1.2 Passo 1: Instalar Neo4j

1.2.1 Opção A: Neo4j Desktop (Recomendado para desenvolvimento local)

Baixe Neo4j Desktop: https://neo4j.com/download/
Instale e crie um novo projeto
Crie um novo banco de dados (DBMS):
- Nome: synesis-knowledge-graph
- Password: escolha uma senha forte
- Versão: 5.x (última disponível)
Inicie o banco de dados (botão “Start”)

Checkpoint ✓

Abra o Neo4j Browser (botão “Open”) e execute:

RETURN "Hello, Neo4j!" AS message

Se retornar a mensagem, está funcionando!

1.2.2 Opção B: Neo4j AuraDB (Cloud - Gratuito até 200K nós)

Acesse: https://neo4j.com/cloud/aura/
Crie conta gratuita
Crie nova instância AuraDB Free
Baixe as credenciais (arquivo .txt com URI, user, password)
Guarde essas credenciais em local seguro

1.3 Passo 2: Instalar synesis2graph

pip install synesis2graph

Verifique a instalação:

synesis2graph --version

Deve retornar: synesis2graph version 0.1.2

1.4 Passo 3: Criar Arquivo de Configuração

Crie um arquivo neo4j_config.toml no diretório do seu projeto:

1.4.1 Para Neo4j Desktop:

[neo4j]
uri = "bolt://localhost:7687"
user = "neo4j"
password = "SuaSenhaAqui"
database = "neo4j"  # ou nome customizado

1.4.2 Para Neo4j AuraDB:

[neo4j]
uri = "neo4j+s://xxxxx.databases.neo4j.io"  # Copie da suas credenciais
user = "neo4j"
password = "SuaSenhaAuraDB"
database = "neo4j"

Segurança

NUNCA comite neo4j_config.toml para Git! Adicione ao .gitignore:

echo "neo4j_config.toml" >> .gitignore

1.5 Passo 4: Executar a Exportação

synesis2graph --project meu_projeto.synp --config neo4j_config.toml

Output esperado:

🔍 Carregando projeto Synesis...
✓ Projeto válido: meu_projeto
✓ Template carregado: template.synt
✓ Ontologia carregada: 15 conceitos, 4 relações

🔗 Conectando ao Neo4j...
✓ Conectado: bolt://localhost:7687

🚀 Sincronizando grafo...
  [████████████████████████] 100% - 234 nós, 156 arestas

📊 Calculando métricas...
✓ Degree Centralidade
✓ Betweenness Centralidade
✓ Closeness Centralidade

✅ Exportação concluída em 3.2s

Checkpoint ✓

Abra o Neo4j Browser e execute:

MATCH (n) RETURN count(n) AS total_nodes

Deve retornar o número de nós exportados.

1.6 Passo 5: Explorar o Grafo no Neo4j Browser

1.6.1 Visualizar Todos os Nós

MATCH (n)
RETURN n
LIMIT 100

1.6.2 Visualizar Código Específico

MATCH (c:Code {name: "Custo"})
RETURN c

1.6.3 Visualizar Relações de um Código

MATCH path = (c:Code {name: "Custo"})-[r]->(target)
RETURN path

1.6.4 Ver Anotações Conectadas a um Código

MATCH (i:Item)-[:HAS_CODE]->(c:Code {name: "Custo"})
RETURN i.quote AS citacao, i.memo AS interpretacao

1.7 Passo 6: Consultas Analíticas Úteis

1.7.1 Top 10 Códigos Mais Frequentes

MATCH (i:Item)-[:HAS_CODE]->(c:Code)
RETURN c.name AS codigo, count(i) AS frequencia
ORDER BY frequencia DESC
LIMIT 10

1.7.2 Códigos que Co-ocorrem Frequentemente

MATCH (i:Item)-[:HAS_CODE]->(c1:Code)
MATCH (i)-[:HAS_CODE]->(c2:Code)
WHERE c1 <> c2
RETURN c1.name AS codigo1, c2.name AS codigo2, count(i) AS coocorrencia
ORDER BY coocorrencia DESC
LIMIT 20

1.7.3 Chains Mais Comuns

MATCH (c1:Code)-[r:CHAIN_RELATION]->(c2:Code)
RETURN c1.name AS origem, r.relation_type AS relacao, c2.name AS destino, count(r) AS frequencia
ORDER BY frequencia DESC

1.7.4 Nós Mais Centrais (Bridges)

MATCH (c:Code)
WHERE c.betweenness_centrality IS NOT NULL
RETURN c.name AS codigo, c.betweenness_centrality AS centralidade
ORDER BY centralidade DESC
LIMIT 10

Interpretação

Códigos com alta betweenness centralidade são “pontes” — conceitos que conectam diferentes clusters temáticos. São candidatos para categorias centrais na sua análise.

1.8 Passo 7: Atualizar o Grafo (Sincronização Incremental)

Se você adicionar novas anotações ao seu projeto Synesis:

1.8.1 Modo Replace (Padrão)

# Apaga tudo e recria
synesis2graph --project meu_projeto.synp --config neo4j_config.toml

1.8.2 Modo Merge (Atualização Incremental)

Edite neo4j_config.toml:

[sync]
mode = "merge"  # Atualiza apenas o que mudou

Execute novamente:

synesis2graph --project meu_projeto.synp --config neo4j_config.toml

Quando usar cada modo:

Modo	Quando Usar
`replace`	Mudanças estruturais (novo template, ontologia refatorada)
`merge`	Adição de novas anotações sem mudanças estruturais
`append`	Apenas adicionar (nunca atualiza nós existentes)

1.9 Passo 8: Calcular Métricas Avançadas (Graph Data Science)

Se você tem Neo4j Enterprise ou instalou o plugin GDS:

1.9.1 Instalar GDS Plugin (Neo4j Desktop)

Na tela do banco de dados, clique em “Plugins”
Instale “Graph Data Science Library”
Reinicie o banco de dados

1.9.2 Habilitar no Config

Edite neo4j_config.toml:

[metrics]
native = true
gds = true  # Agora habilitado

1.9.3 Métricas Disponíveis

Após exportar com GDS habilitado:

MATCH (c:Code)
RETURN c.name AS codigo,
       c.degree_centrality AS degree,
       c.pagerank AS pagerank,
       c.betweenness_centrality AS betweenness,
       c.community_louvain AS comunidade
ORDER BY pagerank DESC
LIMIT 20

Interpretação:

PageRank alto: Códigos que recebem muitas referências de outros códigos importantes
Community Louvain: Códigos no mesmo cluster temático terão mesmo número de comunidade
Betweenness alto: Códigos que conectam diferentes temas

1.10 Troubleshooting

1.10.1 Erro: `Connection refused (bolt://localhost:7687)`

Causa: Neo4j não está rodando.

Solução:

# Neo4j Desktop: Clique em "Start" no banco de dados
# Neo4j Server:
neo4j start

1.10.2 Erro: `Authentication failed`

Causa: Senha incorreta em neo4j_config.toml.

Solução: 1. Verifique a senha no Neo4j Desktop (Settings → “Show Password”) 2. Atualize neo4j_config.toml

1.10.3 Erro: `Database not found: neo4j`

Causa: Nome do banco de dados incorreto.

Solução: Execute no Neo4j Browser:

SHOW DATABASES

Use o nome correto em neo4j_config.toml.

1.10.4 Erro: `synesis.load() failed: Template not found`

Causa: Arquivo .synp com caminho incorreto para template.

Solução:

# Valide o projeto primeiro
synesis check meu_projeto.synp

Corrija os caminhos no .synp.

1.10.5 Performance Lenta em Projetos Grandes

Se você tem 10K+ anotações:

Aumente batch_size:
```
[sync]
batch_size = 5000
```
Desabilite métricas temporariamente:
```
[metrics]
native = false
gds = false
```

Calcule métricas manualmente depois:

// Degree Centralidade
CALL gds.degree.mutate('myGraph', {mutateProperty: 'degree'})

1.11 Casos de Uso Avançados

1.11.1 Integração com Claude Desktop (MCP)

Após exportar para Neo4j, você pode conectar com Claude Desktop via Model Context Protocol:

# ~/.claude/config.toml
[mcp.servers.synesis-graph]
command = "npx"
args = ["-y", "@neo4j/mcp-server", "--uri", "bolt://localhost:7687", "--user", "neo4j", "--password", "SuaSenha"]

Agora Claude pode consultar seu grafo diretamente em linguagem natural!

Consulte: https://modelcontextprotocol.io/docs/

1.11.2 Exportar Visualização para Publicação

Use Bloom (Neo4j Enterprise) ou Neodash (open-source):

# Instalar Neodash
docker run -p 5005:5005 neo4jlabs/neodash:latest

Acesse http://localhost:5005 e conecte ao seu grafo.

1.11.3 Análise de Evolução Temporal

Se suas anotações têm timestamps:

MATCH (i:Item)
WHERE i.timestamp IS NOT NULL
WITH i, i.timestamp AS time
ORDER BY time
RETURN date(time) AS data, count(i) AS anotacoes_por_dia

1.12 Referências

Para conceitos sobre grafos de conhecimento: - Conceitos de Knowledge Graphs

Para detalhes da API Synesis: - API Synesis (synesis.load)

Para Cypher Query Language: - Neo4j Cypher Manual

Ficou com dúvidas? Abra uma issue no repositório synesis2graph ou consulte GitHub Discussions.

1 Como Exportar para Neo4j

1.1 Pré-requisitos

1.2 Passo 1: Instalar Neo4j

1.2.1 Opção A: Neo4j Desktop (Recomendado para desenvolvimento local)

1.2.2 Opção B: Neo4j AuraDB (Cloud - Gratuito até 200K nós)

1.3 Passo 2: Instalar synesis2graph

1.4 Passo 3: Criar Arquivo de Configuração

1.4.1 Para Neo4j Desktop:

1.4.2 Para Neo4j AuraDB:

1.5 Passo 4: Executar a Exportação

1.6 Passo 5: Explorar o Grafo no Neo4j Browser

1.6.1 Visualizar Todos os Nós

1.6.2 Visualizar Código Específico

1.6.3 Visualizar Relações de um Código

1.6.4 Ver Anotações Conectadas a um Código

1.7 Passo 6: Consultas Analíticas Úteis

1.7.1 Top 10 Códigos Mais Frequentes

1.7.2 Códigos que Co-ocorrem Frequentemente

1.7.3 Chains Mais Comuns

1.7.4 Nós Mais Centrais (Bridges)

1.8 Passo 7: Atualizar o Grafo (Sincronização Incremental)

1.8.1 Modo Replace (Padrão)

1.8.2 Modo Merge (Atualização Incremental)

1.9 Passo 8: Calcular Métricas Avançadas (Graph Data Science)

1.9.1 Instalar GDS Plugin (Neo4j Desktop)

1.9.2 Habilitar no Config

1.9.3 Métricas Disponíveis

1.10 Troubleshooting

1.10.1 Erro: Connection refused (bolt://localhost:7687)

1.10.2 Erro: Authentication failed

1.10.3 Erro: Database not found: neo4j

1.10.4 Erro: synesis.load() failed: Template not found

1.10.5 Performance Lenta em Projetos Grandes

1.11 Casos de Uso Avançados

1.11.1 Integração com Claude Desktop (MCP)

1.11.2 Exportar Visualização para Publicação

1.11.3 Análise de Evolução Temporal

1.12 Referências

1.10.1 Erro: `Connection refused (bolt://localhost:7687)`

1.10.2 Erro: `Authentication failed`

1.10.3 Erro: `Database not found: neo4j`

1.10.4 Erro: `synesis.load() failed: Template not found`