Seu conhecimento,
conectado como grafo.

01Visão geral#

O GraphFinder é um aplicativo desktop multiplataforma (Tauri v2 + Rust + React 19) e uma ferramenta de linha de comando que indexa vaults de conhecimento em Markdown e repositórios de código em um único grafo pesquisável semanticamente.

Pipelines de RAG tradicionais cortam documentos em janelas fixas arbitrárias ou jogam arquivos inteiros no contexto do LLM, desperdiçando milhares de tokens. Já as ferramentas de notas raramente oferecem busca vetorial local ou uma API utilizável por agentes. O GraphFinder resolve os dois lados:

• Para humanos — um ambiente local-first e sem distrações para escrever Markdown puro com [[wikilinks]], explorar conexões em um grafo 2D interativo e manter total posse dos seus arquivos.
• Para agentes de IA — um servidor Model Context Protocol (MCP) embarcado que retorna resultados no nível de subseção ([[Nota#Seção]]) e símbolos de código individuais, tipicamente com cerca de 50 tokens por resultado.

Conceitos principais

02Instalação#

Opção A — Instaladores prontos (recomendado)

Cada release com tag é compilada pelo GitHub Actions para as três plataformas desktop. Baixe a mais recente na página de Releases:

Após instalar, habilite o comando de terminal para que graphfinder funcione em qualquer shell:

# Windows: adiciona a pasta de instalação ao PATH do usuário + cria atalhos graphfinder.cmd
# macOS/Linux: cria um symlink em ~/.local/bin/graphfinder
graphfinder install-cli

Opção B — Compilar a partir do código-fonte

Pré-requisitos

• Node.js 20+ e npm
• Rust 1.75+ via rustup
• Windows: Visual Studio C++ Build Tools · Linux: libwebkit2gtk-4.1-dev, build-essential, libssl-dev, libayatana-appindicator3-dev, librsvg2-dev

git clone https://github.com/GabrielTBeserra/GraphFinder.git
cd GraphFinder
npm install

# Roda o app desktop em modo de desenvolvimento (Vite na :1420 + Tauri)
npm run app

# Gera instaladores em src-tauri/target/release/bundle/
npm run tauri build

03Início rápido#

1. Abra o appInicie o GraphFinder (ou rode graphfinder sem argumentos). Um vault padrão é criado e o grafo aparece.
2. Crie ou abra um projetoUse o seletor de projetos na barra superior → Novo projeto, dê um nome e, opcionalmente, escolha uma pasta existente (de notas ou um repositório de código).
3. Escreva uma notaCrie uma nota começando com # Título, um resumo curto e depois seções ##. Conecte conceitos com [[Outra Nota]] e termine com tags como #arquitetura. Salve com Ctrl+S.
4. PesquisePressione Ctrl/⌘+K para abrir o Omnisearch — busca semântica híbrida em notas e símbolos de código.
5. Conecte seu editor de IARode graphfinder config --install ou copie um snippet do modal MCP no app. Seu agente passa a ter 24 ferramentas do GraphFinder.

Prefere o terminal? O mesmo fluxo, sem interface:

cd ~/code/meu-projeto
graphfinder sync            # registra a pasta como projeto e a indexa
graphfinder status          # notas, arquivos de código, arestas, tamanho do banco
graphfinder search "middleware de rate limiting"
graphfinder report          # auditoria de arquitetura + artefatos do grafo

04Aplicativo desktop#

A interface é organizada em uma barra lateral, o canvas central do grafo e painéis contextuais.

Atalhos de teclado

05Escrevendo notas#

O GraphFinder funciona com qualquer Markdown, mas a recuperação fica mais precisa quando as notas seguem esta estrutura:

1. Um único título H1 (# Título da Nota) seguido de um resumo executivo de 2–3 linhas.
2. Seções ##/### autocontidas de aproximadamente 40–150 tokens, com títulos descritivos (## 2. Configuração do SQLite WAL em vez de ## Config). Cada título vira um embedding próprio e um alvo de deep link.
3. Wikilinks — [[Nota]] ou [[Nota#Seção]]. Mire em 1–3 links por nota para evitar órfãos.
4. Hashtags em minúsculas — #arquitetura #sqlite #mcp no fim das seções ou da nota. Elas geram os clusters coloridos no grafo.

# Auth JWT

Como a API emite e valida JSON Web Tokens. Cobre chaves de assinatura,
política de expiração e rotação de refresh.

## 1. Assinatura de Tokens
Os tokens são assinados com RS256. As chaves giram a cada 30 dias e são
carregadas do cofre de segredos na inicialização. Veja [[Arquitetura do Sistema#2. Segredos]].

## 2. Rotação de Refresh
Cada refresh invalida a família de tokens anterior para impedir ataques de replay.

#auth #seguranca #arquitetura

Como as notas são processadas

• O parsing usa uma AST CommonMark real (pulldown-cmark). O conteúdo dentro de blocos de código é isolado, então um # em código nunca é tratado como título ou tag.
• Seções com mais de 320 tokens são divididas em janelas com sobreposição de 40 tokens para não perder contexto nas bordas.
• Renomear uma nota (pela interface ou rename_note) reescreve todos os [[Título Antigo]] no vault.
• Notas editadas fora do GraphFinder (VS Code, Cursor, Neovim…) são detectadas pelo file watcher (debounce de 500 ms).

06Motor de busca#

Cada consulta executa dois mecanismos de recuperação em paralelo e os combina:

O armazenamento é um único banco SQLite por projeto em modo WAL, permitindo indexação e consultas concorrentes. A reindexação é incremental: arquivos são comparados por timestamp e hash SHA-256, e apenas os alterados são reprocessados e revetorizados.

07Indexação de código#

Aponte o GraphFinder para um repositório e ele constrói um índice de símbolos e um grafo de dependências sem precisar de compilador ou language server.

Tipos de arquivo suportados

O que é extraído

• Símbolos — funções, classes, structs, interfaces e enums de nível superior, com intervalos de linha e estimativa de tokens. Cada símbolo é um chunk pesquisável.
• Imports locais — resolvidos para arquivos do projeto e salvos como arestas bidirecionais (code_links): imports e dependentes.
• Pacotes externos — módulos de terceiros (ex.: rusqlite, react) listados por arquivo.

O que é ignorado

Tudo que está no .gitignore, além de node_modules, target, dist, .git, arquivos binários e arquivos maiores que 1 MB.

08Análise de grafos#

Um motor de análise escrito em Rust puro trata notas e arquivos de código como um grafo unificado e responde perguntas de arquitetura.

Artefatos exportados

graphfinder report, graphfinder export, sync --export ou a ferramenta export_graph gravam em ./graphfinder-out/:

• graph.json — nós (comunidade, grau, centralidade, flag de god-node) e arestas (origem, destino, rótulo, peso). Ideal para agentes e scripts.
• GRAPH_REPORT.md — resumo executivo, métricas, tabela de God Nodes, lista de subsistemas, acoplamentos surpresa e ciclos.
• graph.html — visualizador offline sem dependências, com busca, cores por comunidade e halos nos hubs. Abra em qualquer navegador.

09Referência da CLI#

O mesmo binário é o app desktop e a CLI. Executado sem argumentos, abre a interface gráfica; com um comando, roda no terminal.

graphfinder [COMANDO] [OPÇÕES]

Exemplos

# Sync com saída legível por máquina para CI ou scripts
graphfinder sync ./services/api --json

# Como a interface chega até a camada de banco?
graphfinder path "GraphView.tsx" "db.rs"

# Por que este arquivo é importante?
graphfinder explain "src-tauri/src/engine/db.rs"

# Auditoria em uma pasta personalizada
graphfinder report --out-dir ./docs/arquitetura

# Apenas 3 resultados em um projeto específico
graphfinder search "debounce do file watcher" --path ./GraphFinder --limit 3

A partir do código-fonte, scripts npm encapsulam a CLI: npm run sync, npm run status, npm run search, npm run projects, npm run mcp.

10Configurando o MCP#

O GraphFinder implementa o Model Context Protocol com o SDK oficial em Rust (rmcp) em dois modos:

O caminho mais rápido é o registro automático:

graphfinder config --install   # Cursor, Claude Desktop, Windsurf, Cline, Roo Code…
graphfinder config --json      # apenas imprime o snippet JSON

Ou configure manualmente:

{
  "mcpServers": {
    "graphfinder": {
      "url": "http://127.0.0.1:45123/sse"
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "command": "C:\\Program Files\\GraphFinder\\GraphFinder.exe",
      "args": ["--mcp"]
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "type": "sse",
      "url": "http://127.0.0.1:45123/sse"
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "url": "http://127.0.0.1:45123/sse"
    }
  }
}

{
  "mcpServers": {
    "graphfinder": {
      "command": "graphfinder",
      "args": ["--mcp"]
    }
  }
}

11Ferramentas MCP (24)#

Todas as ferramentas aceitam o parâmetro opcional project para mirar um vault específico sem contaminação entre projetos. Parâmetros tracejados são opcionais.

Recuperação de conhecimento

Autoria e conexões

Grafo e arquitetura

Base de código

Projetos e sincronização

Rode graphfinder tools para exportar os schemas JSON de todas as ferramentas e usá-los com qualquer framework de agentes.

12Agentes de IA e skills#

O GraphFinder traz três camadas que trabalham juntas: o agente (Cursor, Claude, Antigravity…) raciocina e planeja, a skill impõe economia de tokens e qualidade das notas, e o servidor MCP executa buscas e escritas.

Skills e regras incluídas

• AGENTS.md — regras do repositório para agentes (economia de tokens, schema de notas, pipelines de decisão). O Antigravity carrega automaticamente; no Cursor adicione às Project Rules; no Claude cole no prompt do projeto.
• .agents/skills/graphfinder-curator — fluxo de autoria e curadoria (resumos, seções atômicas, suggest_links antes de store_context, tags).
• .agents/skills/graphfinder — fluxo de auditoria de arquitetura (relatórios, caminhos, explain, exportações).

Fluxos recomendados

Respondendo uma pergunta

search_semantic("sqlite wal mode")        → top 5 chunks (~50 tokens cada)
  └─ precisa da estrutura?  get_compressed_context("Arquitetura do Sistema")
  └─ precisa de uma seção?  read_section("Arquitetura do Sistema", "1. Armazenamento Local")

Salvando conhecimento

rascunho (# Título + resumo + seções ##)
  → suggest_links(rascunho)                → ex.: "Arquitetura do Sistema: 85%"
  → inserir [[Arquitetura do Sistema]] no rascunho
  → store_context(title, content, tags)    → arquivo gravado, indexado, grafo atualizado

Inspecionando código

search_code("hybrid_search", language="rust")
  → get_file_context("src-tauri/src/engine/db.rs")       # mapa de símbolos, <80 tokens
  → read_code_chunk("src-tauri/src/engine/db.rs", "hybrid_search")
  → get_code_dependencies("src-tauri/src/engine/db.rs")  # análise de impacto

Auditando a arquitetura

get_community_report()      → subsistemas, God Nodes, surpresas, ciclos
  → explain_node("db.rs")   → por que importa
  → find_path("App.tsx", "db.rs")

Exemplos de prompts

13Projetos e vaults#

Cada projeto é um workspace isolado com seu próprio diretório Markdown e seu próprio banco vetorial SQLite, então as buscas nunca vazam entre projetos.

• Vault padrão — <pasta de dados>/vault com índice em <pasta de dados>/index.db.
• Vaults gerenciados — <pasta de dados>/vaults/<project_id>/, criados pela interface ou por create_project.
• Pastas externas — qualquer caminho do disco (ex.: um repositório) registrado pela interface, por graphfinder sync <caminho> ou create_project(name, path).
• Registro — vaults/projects.json guarda o projeto ativo, nomes e caminhos personalizados.

{
  "active_project": "default",
  "custom_names": { "minha-api": "Minha API" },
  "custom_paths": { "minha-api": "C:/Repos/MinhaAPI" }
}

Onde fica a pasta de dados?

1. GRAPHFINDER_DATA_DIR, se definida.
2. O diretório atual, se contiver package.json (código-fonte / modo dev).
3. Caso contrário, a pasta de dados do sistema: %APPDATA%\GraphFinder (Windows), ~/Library/Application Support/GraphFinder (macOS), ~/.local/share/GraphFinder (Linux).

14Configuração#

O GraphFinder é configurado por variáveis de ambiente — nenhum arquivo de configuração é necessário.

# Vault em português / multilíngue em uma porta personalizada
export GRAPHFINDER_MODEL=multilingual
export GRAPHFINDER_MCP_PORT=47000
graphfinder

$env:GRAPHFINDER_MODEL = "multilingual"
graphfinder sync

15Arquitetura#

Estrutura do repositório

GraphFinder/
├── src/                      # Frontend React 19 + TypeScript
│   ├── components/           # GraphView, NoteEditor, CodeInspector, Sidebar,
│   │                         # OmnisearchModal, McpModal, ArchitecturalReportModal…
│   ├── services/             # Bindings IPC do Tauri
│   └── types.ts
├── src-tauri/                # Backend Rust
│   ├── src/main.rs           # Ponto de entrada da CLI (GUI sem argumentos)
│   ├── src/lib.rs            # Setup do Tauri, comandos IPC, servidor MCP HTTP
│   ├── src/engine/
│   │   ├── parser.rs         # AST CommonMark, chunking, wikilinks, tags
│   │   ├── embeddings.rs     # Carregamento e inferência do FastEmbed
│   │   ├── db.rs             # Schema SQLite, FTS5, busca híbrida RRF
│   │   ├── vault.rs          # Engine: sync, watcher, ciclo de vida das notas
│   │   ├── code.rs           # Detecção de linguagem, símbolos, imports
│   │   ├── graph_analytics.rs# Comunidades, centralidade, caminhos, exportação
│   │   └── project.rs        # Gerenciador multi-vault e registro
│   └── src/mcp/              # Definição das ferramentas (mod.rs) e transportes (server.rs)
├── .agents/skills/           # Skills graphfinder e graphfinder-curator
├── mcp-tools/                # Schemas exportados das ferramentas
├── docs/                     # Este site (GitHub Pages)
└── AGENTS.md · MCP_TOOLS.md · CHANGELOG.md

Stack tecnológica

16Segurança#

• Somente loopback — o servidor MCP HTTP escuta apenas em 127.0.0.1.
• Defesa contra DNS rebinding — o cabeçalho Host é validado em cada requisição.
• Validação de Origin — middleware estrito em vez de CORS permissivo.
• Content Security Policy — aplicada no tauri.conf.json.
• Proteção contra XSS — previews Markdown são sanitizados com DOMPurify.
• Proteção contra path traversal — ids de projeto são sanitizados antes de tocar o sistema de arquivos.

Reporte vulnerabilidades de forma privada conforme o SECURITY.md.

17Desenvolvimento#

Releases

Enviar uma tag no formato v* (ou rodar o workflow Release manualmente) dispara o .github/workflows/release.yml: o scripts/sync-version.js aplica a versão da tag em package.json, Cargo.toml e tauri.conf.json, e então o tauri-action compila e publica instaladores para Windows, macOS e Linux.

git tag v0.11.0
git push origin v0.11.0

Contribuindo

Relatos de bugs, sugestões, documentação e PRs são bem-vindos. Leia o CONTRIBUTING.md e o Código de Conduta.

18Problemas e FAQ#

Meu agente não conecta em 127.0.0.1:45123.

O endpoint HTTP/SSE só existe enquanto o app desktop está aberto. Abra o app ou mude o cliente para o modo stdio ("command": "graphfinder", "args": ["--mcp"]). Se alterou GRAPHFINDER_MCP_PORT, atualize a URL.

graphfinder não é reconhecido no terminal.

Rode GraphFinder.exe install-cli (ou graphfinder config --install) e abra um novo terminal para carregar o PATH atualizado.

Os resultados são ruins para português / outros idiomas.

Defina GRAPHFINDER_MODEL=multilingual e reindexe.

A primeira inicialização é lenta.

O modelo de embeddings é baixado uma vez. Nas próximas execuções ele é carregado de .fastembed_cache; aponte GRAPHFINDER_MODELS para uma cópia local em máquinas sem internet.

Alguns arquivos não aparecem no grafo de código.

Verifique se estão no .gitignore, se são binários, se passam de 1 MB ou se têm extensão não suportada. Rode graphfinder sync para forçar uma atualização incremental.

Algum dado sai da minha máquina?

Não. Embeddings, busca e análises rodam localmente. O único acesso à rede é o download único do modelo (e este site consultando a release mais recente no GitHub).

19Changelog#

Histórico completo no CHANGELOG.md e na página de Releases.