Entenda como o MiroFish transforma documentos em grafos de conhecimento navegáveis que alimentam a memória e a personalidade de cada agente.
RAG (Retrieval-Augmented Generation) é a técnica de enriquecer prompts de LLMs com informações recuperadas de uma base de dados. O RAG tradicional divide documentos em chunks e busca os mais similares por embedding vetorial. O GraphRAG vai além: extrai entidades e relações, construindo um grafo navegável que preserva a estrutura do conhecimento.
No RAG tradicional, se você busca "CEO da empresa X", pode receber um chunk que menciona o CEO mas não conecta com a empresa. No GraphRAG, a relação "João [é CEO de] Empresa X" está explícita no grafo. Isso permite respostas que navegam relações complexas: "Quem são os parceiros da empresa que João lidera?" - algo impossível com busca vetorial pura.
Um grafo de conhecimento é uma estrutura de dados composta por nós (entidades) e arestas (relações) que representam conhecimento de forma navegável. No MiroFish, o grafo é a espinha dorsal que conecta pessoas, organizações, eventos, opiniões e conceitos.
Cada fato é armazenado como uma tripla: Sujeito → Predicado → Objeto. Por exemplo: "Elon Musk [fundou] Tesla", "Tesla [compete_com] BYD", "BYD [é_popular_em] China". Navegando essas relações, o sistema pode inferir que opiniões sobre Elon Musk podem afetar percepções sobre Tesla e, por extensão, sobre o mercado de veículos elétricos na China.
Um grafo de conhecimento típico para uma simulação do MiroFish contém entre 500 e 5.000 nós (entidades) e 2.000 a 20.000 arestas (relações). A extração é feita por LLMs que processam os documentos de entrada, identificando automaticamente entidades nomeadas e as relações entre elas com precisão superior a 85%.
Ao preparar documentos para o GraphRAG, prefira textos que mencionem relações explícitas entre entidades (reportagens, artigos de análise) em vez de textos opinativos sem referências concretas. Quanto mais relações o LLM puder extrair, mais rico será o grafo.
O MiroFish combina três métodos de busca para maximizar a qualidade do contexto fornecido aos agentes: busca semântica (por significado), BM25 (por palavras-chave) e travessia de grafo (por relações estruturais).
Busca Semântica: Converte a consulta e os documentos em vetores e encontra os mais próximos no espaço vetorial. Boa para encontrar conteúdo com significado similar, mesmo com palavras diferentes.
BM25: Algoritmo clássico de busca por palavras-chave ponderadas pela frequência e raridade. Excelente para encontrar menções específicas de termos técnicos ou nomes próprios.
Travessia de Grafo: Partindo de uma entidade, navega as relações do grafo para encontrar entidades conectadas. Captura contexto que os outros dois métodos perdem.
O agente precisa de contexto sobre um tópico. A consulta é enviada aos três mecanismos de busca simultaneamente.
Semântica, BM25 e travessia de grafo executam em paralelo, cada uma retornando seus top resultados.
Os resultados são combinados, deduplicados e reordenados por relevância usando um modelo de reranking.
O contexto final, rico e diversificado, é injetado no prompt do agente para sua próxima ação.
Uma das decisões arquiteturais mais importantes do MiroFish é onde armazenar o grafo de conhecimento. O projeto original usa o Zep Cloud (serviço pago na nuvem), enquanto o fork inematds optou pelo KuzuDB, um banco de grafos embarcado que roda localmente.
Zep Cloud: Serviço gerenciado que oferece GraphRAG como serviço, com APIs prontas e escalabilidade automática. Custo mensal, dados trafegam pela internet, depende de disponibilidade do serviço. KuzuDB: Banco de grafos embarcado em C++, roda como uma biblioteca dentro da aplicação. Zero custo, dados ficam locais, funciona offline. Tradeoff: exige mais configuração e não escala horizontalmente.
O GraphRAG é a primeira etapa do pipeline do MiroFish. Documentos de entrada são processados por um LLM que extrai entidades e relações, constrói o grafo de conhecimento e depois usa esse grafo para gerar personas diversas e contextualizar os agentes durante a simulação.
O fluxo completo: (1) Documentos são ingeridos (artigos, posts, relatórios); (2) Um LLM extrai entidades (pessoas, empresas, eventos) e relações (trabalha_em, compete_com, apoiou); (3) Essas triplas são armazenadas no grafo; (4) O grafo é consultado para gerar personas diversas com opiniões embasadas; (5) Durante a simulação, agentes consultam o grafo para recuperar contexto relevante antes de cada ação.
A qualidade do grafo de conhecimento determina diretamente a qualidade da simulação. Invista em documentos de entrada diversificados: artigos de diferentes perspectivas, posts de diferentes demografias e análises de diferentes fontes. Um grafo enviesado gera personas enviesadas.
O processo de extração de entidades e relações consome entre 2.000 e 10.000 tokens por documento de entrada, dependendo do comprimento e complexidade. Para uma simulação típica com 20-30 documentos, o custo de GraphRAG building fica entre US$ 0,50 e US$ 3 usando modelos como DeepSeek ou Qwen.
Graphiti é a camada que adiciona a dimensão temporal ao grafo de conhecimento. Fatos não são estáticos - opiniões mudam, empresas se transformam, contextos evoluem. O Graphiti registra quando cada fato foi aprendido e como resolver conflitos quando informações novas contradizem antigas.
Cada aresta no grafo tem um timestamp e um nível de confiança. Se em janeiro o grafo diz "João [apoia] Candidato A" e em março um novo documento diz "João [apoia] Candidato B", o Graphiti não simplesmente sobrescreve - ele mantém ambos os fatos com seus timestamps e marca o mais recente como ativo. Isso permite que agentes tenham memória de como opiniões evoluíram ao longo do tempo.
A resolução de conflitos temporais é especialmente importante em simulações de longo prazo ou quando os dados de entrada cobrem períodos extensos. Sem temporalidade, o grafo pode conter informações contraditórias que geram agentes com opiniões incoerentes. O Graphiti resolve esse problema automaticamente usando heurísticas de recência e confiança.
Ao preparar dados para uma simulação, inclua timestamps nos documentos quando possível. Isso permite que o Graphiti ordene corretamente a evolução dos fatos e gere agentes com uma linha temporal coerente de opiniões e conhecimentos.