Riferimenti Contestuali — Citazioni Precise

Bentornati alla nostra serie su Hermes Agent! Oggi ci immergiamo in qualcosa che rende il vostro agente enormemente più utile: i riferimenti contestuali. Se avete mai desiderato che il vostro agente potesse indicare esattamente dove ha trovato un’informazione—come un vero articolo di ricerca con le citazioni—questa è la funzione che fa per voi.

Cosa Sono i Riferimenti Contestuali?

Pensate ai riferimenti contestuali come alle note a piè di pagina di un libro. Quando il vostro agente elabora un documento, una conversazione o un file, ora può ricordare da dove provengono specifiche informazioni. Invece di dire semplicemente “il cielo è blu”, può dire “il cielo è blu (da rapporto_meteo.md, riga 42)”.

Questo cambia le regole del gioco per:

• Attività di ricerca — verificate le fonti all’istante
• Revisioni del codice — rintracciate dove è stato introdotto un bug
• Lavoro legale o di conformità — dimostrate da dove proviene un fatto
• Conversazioni lunghe — ricordate quale messaggio conteneva un dettaglio chiave

Come Funziona

La magia avviene dietro le quinte. Quando fornite al vostro agente documenti, cronologia chat o file, Hermes traccia automaticamente l’origine di ogni contenuto. Non dovete fare nulla di speciale—funziona e basta.

Ecco un semplice esempio:

hermes chat --with file:contratto.pdf

Fate una domanda come “Qual è la clausola di recesso?” e l’agente risponderà con una citazione che indica la sezione esatta del PDF.

Le Nuove Opzioni di Configurazione

L’ultimo aggiornamento introduce nuovi potenti modi per controllare il comportamento dei riferimenti contestuali. Tutte queste opzioni si trovano nel file ~/.hermes/config.yaml.

Attivazione e Disattivazione

Di default, i riferimenti contestuali sono attivi per i contenuti basati su file. Ma potete controllarli per ogni sessione:

context_references:
  enabled: true              # interruttore principale
  include_line_numbers: true # aggiunge i numeri di riga alle citazioni
  max_citations: 5           # limita il numero di riferimenti per risposta

Formati di Citazione

Potete scegliere come appaiono le citazioni nelle risposte:

context_references:
  format: markdown  # opzioni: markdown, plain, json

• markdown — [fonte: file.md, riga 12] (si visualizza bene nelle interfacce chat)
• plain — (file.md:12) (compatto, ideale per i terminali)
• json — output strutturato per uso programmatico

Lavorare con le Sessioni

I riferimenti contestuali danno il meglio di sé nelle sessioni di lunga durata. L’agente ricorda quale messaggio ha introdotto un fatto, anche ore dopo:

hermes chat --session progetto-ricerca

Chiedete “Cosa avevamo imparato sui prezzi prima?” e ottenete una citazione che indica il messaggio esatto di due ore fa.

Consigli Pratici

1. Usate Nomi di File Descrittivi

La citazione include il nome del file, quindi rendetelo significativo:

hermes chat --with docs/report-finanziario-Q3.md

Meglio di file1.txt, vero?

2. Combinatelo con la Memoria

I riferimenti contestuali funzionano perfettamente con il sistema di memoria di Hermes. Quando l’agente salva qualcosa in memories/, registra anche la fonte. In seguito, quando recupera quel ricordo, può dirvi da dove proviene l’informazione originale.

3. Verificate la Vostra Configurazione

Dopo aver aggiornato Hermes, eseguite:

hermes config check
hermes config migrate

Questo garantisce che abbiate tutte le opzioni più recenti disponibili.

Un Esempio Rapido

Vediamolo in azione:

hermes chat --with ~/note/note-riunione.md

Voi: “Quali azioni abbiamo concordato?”

Agente: “In base alle note della riunione, avete concordato di:

1. Finalizzare il budget Q3 (da note-riunione.md, riga 15)
2. Programmare la demo con il cliente (da note-riunione.md, riga 22)
3. Aggiornare la timeline del progetto (da note-riunione.md, riga 28)“

Vedete come ogni elemento ha la propria citazione? Sono i riferimenti contestuali che fanno il loro lavoro.

Promemoria sulla Priorità della Configurazione

Ricordate, le impostazioni vengono risolte in questo ordine:

1. Argomenti CLI — priorità massima
2. config.yaml — il vostro file di configurazione principale
3. .env — solo per i segreti
4. Default integrati — fallback

Quindi potete sovrascrivere le impostazioni dei riferimenti contestuali per singolo comando:

hermes chat --with file:report.pdf --set context_references.format=plain

Conclusione

I riferimenti contestuali trasformano il vostro agente da una “scatola nera” in un assistente trasparente e verificabile. Che stiate facendo ricerca, debug del codice o semplicemente vogliate fidarvi di più delle risposte del vostro agente, questa funzione vi fornisce le prove.

Provatela con i vostri documenti e vedete quanto vi sentite più sicuri quando ogni risposta arriva con una fonte. Il vostro io futuro—che cerca di ricordare da dove proveniva quel fatto—vi ringrazierà.

Buone citazioni! 🎯