Referências de Contexto — Citações Precisas

Bem-vindo de volta à nossa série sobre o Hermes Agent! Hoje vamos mergulhar em algo que torna seu agente drasticamente mais útil: referências de contexto. Se você já desejou que seu agente pudesse apontar exatamente de onde tirou uma informação — como um artigo acadêmico de verdade, com citações — este recurso é para você.

O Que São Referências de Contexto?

Pense nas referências de contexto como notas de rodapé em um livro. Quando seu agente processa um documento, uma conversa ou um arquivo, ele agora consegue lembrar de onde vieram informações específicas. Em vez de apenas dizer “o céu é azul”, ele pode dizer “o céu é azul (de relatorio_clima.md, linha 42)”.

Isso é um divisor de águas para:

• Tarefas de pesquisa — verifique fontes instantaneamente
• Revisões de código — rastreie onde um bug foi introduzido
• Trabalho jurídico ou de conformidade — comprove de onde veio um fato
• Conversas longas — lembre-se de qual mensagem continha um detalhe importante

Como Funciona

A mágica acontece nos bastidores. Quando você alimenta seu agente com documentos, histórico de conversas ou arquivos, o Hermes rastreia automaticamente a origem de cada conteúdo. Você não precisa fazer nada de especial — simplesmente funciona.

Aqui está um exemplo simples:

hermes chat --with arquivo:contrato.pdf

Faça uma pergunta como “Qual é a cláusula de rescisão?” e o agente responderá com uma citação apontando para a seção exata do PDF.

As Novas Opções de Configuração

A atualização mais recente traz algumas maneiras poderosas de controlar como as referências de contexto se comportam. Tudo isso fica no arquivo ~/.hermes/config.yaml.

Ativando e Desativando

Por padrão, as referências de contexto estão ativadas para conteúdo baseado em arquivos. Mas você pode controlá-las por sessão:

context_references:
  enabled: true              # interruptor principal
  include_line_numbers: true # adiciona números de linha às citações
  max_citations: 5           # limita quantas referências por resposta

Formatos de Citação

Você pode escolher como as citações aparecem nas respostas:

context_references:
  format: markdown  # opções: markdown, plain, json

• markdown — [fonte: arquivo.md, linha 12] (renderiza bem em interfaces de chat)
• plain — (arquivo.md:12) (compacto, bom para terminais)
• json — saída estruturada para uso programático

Trabalhando com Sessões

As referências de contexto brilham em sessões de longa duração. O agente lembra qual mensagem introduziu um fato, mesmo horas depois:

hermes chat --session projeto-pesquisa

Pergunte “O que aprendemos sobre preços mais cedo?” e receba uma citação apontando para a mensagem exata de duas horas atrás.

Dicas Práticas

1. Use Nomes de Arquivo Descritivos

A citação inclui o nome do arquivo, então dê nomes significativos:

hermes chat --with docs/relatorio-financeiro-Q3.md

Melhor que arquivo1.txt, não é?

2. Combine com Memória

As referências de contexto funcionam lindamente com o sistema de memória do Hermes. Quando o agente armazena algo em memorias/, ele também registra a fonte. Depois, ao recuperar essa memória, ele pode te dizer de onde a informação veio originalmente.

3. Verifique Sua Configuração

Depois de atualizar o Hermes, execute:

hermes config check
hermes config migrate

Isso garante que você tenha todas as opções mais recentes disponíveis.

Um Exemplo Rápido

Vamos ver na prática:

hermes chat --with ~/notas/anotacoes-reuniao.md

Você: “Quais ações combinamos?”

Agente: “Com base nas anotações da reunião, vocês concordaram em:

1. Finalizar o orçamento do Q3 (de anotacoes-reuniao.md, linha 15)
2. Agendar a demonstração para o cliente (de anotacoes-reuniao.md, linha 22)
3. Atualizar o cronograma do projeto (de anotacoes-reuniao.md, linha 28)“

Viu como cada item tem sua própria citação? Isso é o trabalho das referências de contexto.

Lembrete de Precedência de Configuração

Lembre-se, as configurações são resolvidas nesta ordem:

1. Argumentos de CLI — prioridade mais alta
2. config.yaml — seu arquivo de configuração principal
3. .env — apenas para segredos
4. Padrões embutidos — plano de fallback

Então você pode sobrescrever as configurações de referência de contexto por comando:

hermes chat --with arquivo:relatorio.pdf --set context_references.format=plain

Concluindo

As referências de contexto transformam seu agente de uma “caixa-preta” em um assistente transparente e verificável. Seja para pesquisa, depuração de código ou apenas para confiar mais nas respostas do seu agente, este recurso entrega os comprovantes.

Experimente com seus próprios documentos e veja como você se sente mais confiante quando cada resposta vem com uma fonte. Seu eu do futuro — tentando lembrar de onde aquele fato veio — vai te agradecer.

Boas citações! 🎯