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 synesis-graph

pip install "synesis-graph[neo4j]"

O extra [neo4j] instala o driver do banco de dados.

Verifique a instalação:

synesis-graph --version

Deve retornar: synesis-graph, version 0.3.1

Nome anterior

Esta ferramenta chamava-se synesis2graph (e antes synesis2neo4j). O pacote foi renomeado para synesis-graph e o comando agora usa subcomandos por backend — synesis-graph neo4j, synesis-graph html. Se você tem a versão antiga instalada, remova-a com pip uninstall synesis2graph.

1.4 Passo 3: Criar Arquivo de Configuração

Crie um arquivo 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 config.toml para Git! Adicione ao .gitignore:

echo "config.toml" >> .gitignore

1.5 Passo 4: Executar a Exportação

synesis-graph neo4j --project meu_projeto.synp --config config.toml

Como config.toml é o valor padrão, o --config pode ser omitido:

synesis-graph neo4j --project meu_projeto.synp

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...
✓ Métricas nativas (degree, mention_count, source_count)
✓ Métricas GDS (pagerank, betweenness, community)

✅ Exportação concluída em 3.2s

Sem o plugin GDS

A linha de métricas GDS só aparece se o plugin estiver instalado (ver Passo 8). Sem ele, o pipeline emite um aviso e conclui normalmente — as métricas nativas são calculadas de qualquer forma.

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

Os rótulos são derivados do seu template

O synesis-graph não usa rótulos fixos. O nó de conceito recebe o rótulo do nome do campo no template: um campo category gera nós :Category; um campo criterio gera :Criterio. As consultas abaixo omitem o rótulo (MATCH (c)) para funcionar em qualquer projeto — substitua pelo rótulo do seu campo se quiser restringir. Ver synesis-graph.

1.6.2 Visualizar Conceito Específico

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

1.6.3 Visualizar Relações de um Conceito

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

1.6.4 Ver Anotações Conectadas a um Conceito

MATCH (i:Item)-[:MENTIONS]->(c {name: "Custo"})
RETURN i.citation AS citacao, i.description AS interpretacao

1.7 Passo 6: Consultas Analíticas Úteis

1.7.1 Top 10 Conceitos Mais Frequentes

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

O pipeline também grava essa contagem como propriedade, o que dispensa a agregação:

MATCH (c)
WHERE c.mention_count IS NOT NULL
RETURN c.name AS conceito, c.mention_count AS frequencia, c.source_count AS fontes
ORDER BY frequencia DESC
LIMIT 10

1.7.2 Conceitos que Co-ocorrem Frequentemente

MATCH (i:Item)-[:MENTIONS]->(c1)
MATCH (i)-[:MENTIONS]->(c2)
WHERE c1 <> c2
RETURN c1.name AS conceito1, c2.name AS conceito2, count(i) AS coocorrencia
ORDER BY coocorrencia DESC
LIMIT 20

1.7.3 Chains Mais Comuns

MATCH (c1)-[r:RELATES_TO]->(c2)
RETURN c1.name AS origem, r.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)
WHERE c.betweenness IS NOT NULL
RETURN c.name AS conceito, c.betweenness AS centralidade
ORDER BY centralidade DESC
LIMIT 10

betweenness exige o plugin GDS

Esta propriedade só existe se o Graph Data Science estiver instalado (Passo 8). Sem ele, use degree — disponível sempre, calculado em Cypher puro.

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

Se você adicionar novas anotações ao projeto Synesis, execute o mesmo comando novamente:

synesis-graph neo4j --project meu_projeto.synp

A sincronização é completa: o pipeline recompila o projeto em memória e regrava o grafo. Não há modo incremental — e isso é deliberado.

Por que não há sincronização incremental

O grafo é um artefato derivado, não uma base de dados que se edita. A fonte de verdade são os arquivos .syn versionados em Git. Regravar por completo garante que o grafo corresponde exatamente ao estado atual do corpus, sem resíduos de conceitos renomeados ou anotações removidas — um risco real num modo incremental.

Se a regravação demora, o gargalo costuma ser a compilação, não a escrita: valide antes com synesis compile meu_projeto.synp --stats.

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

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

Não há nada a configurar: o pipeline detecta o plugin automaticamente. Se o GDS estiver presente, as métricas avançadas são calculadas; se não estiver, o pipeline emite um aviso e continua normalmente com as métricas nativas.

1.9.2 Métricas Disponíveis

Após exportar com GDS habilitado:

MATCH (c)
WHERE c.pagerank IS NOT NULL
RETURN c.name AS codigo,
       c.degree AS degree,
       c.pagerank AS pagerank,
       c.betweenness AS betweenness,
       c.community AS comunidade
ORDER BY pagerank DESC
LIMIT 20

Por que a consulta não filtra por rótulo

O rótulo dos nós de conceito é derivado do nome do campo no seu template — um campo category gera nós :Category, um campo ordem_2a gera :Ordem_2a. Como não há um rótulo fixo :Code, filtrar pela presença da propriedade (WHERE c.pagerank IS NOT NULL) funciona em qualquer projeto. Ver synesis-graph para o modelo completo.

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 config.toml.

Solução: 1. Verifique a senha no Neo4j Desktop (Settings → “Show Password”) 2. Atualize 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 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 o modelo de dados completo e todas as opções da ferramenta: - synesis-graph — Referência

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

Para cruzar corpora distintos num único grafo: - Como Ligar Projetos Independentes

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

Para Cypher Query Language: - Neo4j Cypher Manual

Não precisa de banco de dados?

Para explorar o grafo visualmente sem instalar o Neo4j, o backend HTML gera um arquivo único e autocontido:

synesis-graph html --project meu_projeto.synp --output grafo.html

Ver synesis-graph.

Ficou com dúvidas? Abra uma issue no repositório synesis-graph 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 synesis-graph

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 Conceito Específico

1.6.3 Visualizar Relações de um Conceito

1.6.4 Ver Anotações Conectadas a um Conceito

1.7 Passo 6: Consultas Analíticas Úteis

1.7.1 Top 10 Conceitos Mais Frequentes

1.7.2 Conceitos 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

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

1.9.1 Instalar GDS Plugin (Neo4j Desktop)

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