Hyper Company Brain: progettare una knowledge base per AI Agent

Quando chiedi a Claude Code di modificare codice, non sa perché tre mesi fa il team ha eliminato quel branch. Quando chiedi a ChatGPT una decisione di progetto, deve rileggere tutti i documenti prima di rispondere. Dover rispiegare ogni volta la storia del progetto è una differenza importante tra Agent e RAG normale: il secondo è bravo a recuperare documenti statici, ma la conoscenza aziendale ha tre dimensioni che non gestisce in modo nativo: validità dei fact, ambito dei permessi e catena di ragionamento delle decisioni.

Su Hacker News, Hyper dice di voler costruire un “company brain”. Sembra marketing, ma i dettagli architetturali condivisi dal fondatore nel thread di lancio hanno valore tecnico: memoria a due livelli, episodes + facts, typed edges, modello di timestamp e due percorsi di iniezione, hooks e MCP. Qui non sto facendo una recensione del prodotto. Uso queste informazioni pubbliche per scomporre il problema di design della “memoria aziendale”: checklist a cinque livelli, percorso pilot di 7 giorni e tabella dei rischi di scelta.

Tre tipi di contesto che il RAG normale non regge

RAG recupera documenti, restituisce frammenti e lascia che il modello risponda. Questo flusso funziona per una knowledge base statica, ma la conoscenza aziendale ha tre dimensioni che il RAG non gestisce di default.

Il RAG tradizionale ordina per recency o relevance. Non capisce se un’informazione sia stata supersedes da un newer fact, cioè sostituita. Hyper assegna due timestamp a ogni fact: introduced_at registra la prima comparsa, invalidated_at il momento in cui diventa non valido. Durante il retrieval, filtra i fact invalidati invece di affidarsi alla data di aggiornamento del documento.

L’ambito dei permessi è più delicato in un’organizzazione con più persone. Una chiamata Agent può rappresentare un membro specifico del team, e non dovrebbe leggere contenuti fuori dal suo progetto. Hyper usa access-control tags per marcare la visibilità di ogni fact, e il livello di retrieval filtra i risultati in base all’identità del chiamante prima di restituirli. È più granulare della “ricerca enterprise”, che spesso si ferma ai permessi del documento. Un company brain richiede filtro a livello di fact.

Il motivo della decisione è la parte più difficile per il RAG normale. Se chiedi “perché PostgreSQL invece di MongoDB?”, il RAG può restituire il paragrafo conclusivo del documento di architettura. Ma quel paragrafo potrebbe non contenere la discussione tecnica di tre mesi prima, i compromessi e la logica della decisione finale. Il livello episodes di Hyper conserva i nodi di conversazione originali, mentre il livello facts punta all’episode sorgente tramite un typed edge derived from. Così il retrieval può seguire la relazione fino alla catena di ragionamento, non solo al risultato.

Architettura di memoria a due livelli di Hyper

Hyper organizza la memoria in due livelli: Episodes come storage grezzo e Facts come livello strutturato, collegati da un knowledge graph.

Livello Episodes: conserva i nodi di conversazione originali e non elimina il contesto. Funziona come ancora di provenance per i fact. Quando un Agent deve risalire a un processo decisionale, può seguire un edge derived from dal fact al frammento di conversazione originale, non leggere solo una conclusione riassunta.

Livello Facts: usa una struttura subject-predicate-object. Ogni fact contiene soggetto, relazione e oggetto, più timestamp e typed edges. Il fondatore ha descritto pubblicamente tre tipi di typed edges:

Alibaba Cloud - Scelta top per sviluppatori, 15% di sconto esclusivo su Lighthouse

Ottieni -15% →Pubbl.

Modello di timestamp: ogni fact ha due linee temporali. La linea T registra quando è accaduto l’evento, per esempio “la decisione è stata presa a marzo”. La linea T’ registra quando il sistema ha ingerito il fact, per esempio “questo fact è stato scritto nella knowledge base a giugno”. La separazione serve perché la conoscenza aziendale arriva spesso in ritardo. Le conclusioni di una riunione possono essere inserite una settimana dopo, quindi il sistema deve distinguere quando il fatto è avvenuto e quando lo ha appreso.

Punti principali dell’architettura:

• Episodes non viene riassunto e scartato: conserva i nodi di conversazione originali, secondo quanto dichiarato dal fondatore su HN e nel contesto del paper Zep.
• Facts è strutturato in triple, ognuna con timestamp e typed edges, secondo quanto reso pubblico su HN.
• introduced_at / invalidated_at segnano il ciclo di vita del fact, e il livello retrieval filtra i contenuti invalidati.
• Il knowledge graph usa typed edges per gestire “relazioni”, non solo “fact”. È la differenza chiave rispetto a un normale database vettoriale.

L’obiettivo di questa architettura non è salvare più dati. È permettere agli Agent di trovare contesto seguendo relazioni. Un normale database vettoriale restituisce frammenti simili, ma non conosce dipendenze logiche, relazioni di sostituzione o punti di conflitto tra frammenti. Typed edges + timestamp permettono ai risultati di retrieval di portare metadati: da dove arriva questo fact, se è ancora valido, se è stato sostituito.

Due percorsi: retrieval e iniezione

Dopo aver scritto la conoscenza, l’Agent può usarla in due modi: retrieval, cioè query attiva, e iniezione, cioè ricezione passiva del contesto.

Meccanismo di retrieval secondo il fondatore su HN:

• Ricerca full-text Postgres: matching per parole chiave, adatto a query esatte come “la definizione di un API endpoint”.
• Ricerca semantica con embedding: similarità vettoriale, adatta a query sfumate come “qual era la conclusione sull’ottimizzazione delle prestazioni?”.
• Reciprocal Rank Fusion (RRF): fonde risultati full-text e semantici, restituendo un ranking complessivo.
• Filtro access-control tags: ritaglia i risultati in base all’identità del chiamante, preservando i confini dei permessi.

Questa combinazione è diversa da un database puramente vettoriale. Quest’ultimo fa solo recall semantico e può perdere risultati in query con parole chiave esatte. Hyper usa RRF per fondere le due strade e considera sia match lessicali sia similarità semantica nel ranking.

Confronto tra percorsi di iniezione: hooks e MCP sono due canali dati diversi.

Le due strade possono coesistere. Il fondatore di Hyper dice che gli hooks servono per iniettare contesto in tempo reale nell’Agent, per esempio caricando i documenti del progetto quando apri Claude Code. MCP serve quando l’Agent chiama attivamente strumenti esterni, come Notion o Gmail. Ma nel thread HN alcuni hanno messo in dubbio la trasparenza degli hooks: l’utente sa chiaramente quali dati vengono iniettati automaticamente nella conversazione dell’Agent?

In fase di scelta, controlla due cose: se gli hooks hanno prompt di installazione espliciti, e se l’ambito dei permessi del MCP server è controllato da un admin. La documentazione developer mode di OpenAI dice che le MCP apps richiedono verifica di sicurezza, e i piani Enterprise possono usare RBAC per il controllo accessi. Questo rende il modello di governance MCP relativamente maturo, mentre la trasparenza degli hooks dipende dal design del prodotto.

Checklist a cinque livelli per un company brain

Se costruisci o scegli una soluzione, verifica che tutti e cinque i livelli abbiano una risposta. Ogni assenza emergerà nell’uso reale.

Primo livello: connessione delle fonti dati

• Scelta strumenti: Notion, Gmail, Slack, GitHub, Linear, Jira, in base al workflow del team.
• Modalità di ingestione: webhooks in tempo reale o polling periodico; i webhooks reagiscono più rapidamente ma richiedono supporto dal sistema sorgente.
• Pulizia dati: filtrare rumore, come canali Slack di chiacchiere; marcare informazioni sensibili; uniformare l’encoding.
• Import iniziale: storico completo o solo nuovi dati. I dati storici possono contenere molti fact obsoleti.

Secondo livello: Fact Schema

KiloClaw - OpenClaw gestito per enterprise: orchestrazione agenti IA e routing intelligente

Inizia →Pubbl.

• Struttura del fact: triple subject-predicate-object, salvate in formato uniforme.
• Timestamp: introduced_at per la prima comparsa + invalidated_at per l’invalidazione. Se manca uno dei due, il ciclo di vita è difficile da valutare.
• Typed edges: almeno derived from per provenance, supersedes per sostituzione e tension per conflitto.
• Strategia conflitti: marcare automaticamente tension per revisione umana, oppure scegliere il newer fact in base al timestamp.

Terzo livello: retrieval

• Combinazione recall: full-text (keyword) + semantico (embedding) + fusione RRF. Il recall solo semantico può perdere query esatte.
• Filtro permessi: access-control tags a livello di fact, ritagliati in base all’identità del chiamante.
• Ranking: combinare recency, relevance e fact validity, filtrando i fact invalidati.
• Obiettivo latenza: risposta di retrieval < 500 ms in test reali, altrimenti le chiamate Agent iniziano a sembrare lente.

Quarto livello: iniezione

• Scelta percorso: hooks per iniezione di contesto in tempo reale vs MCP per chiamate attive dell’Agent. Possono coesistere.
• Compatibilità Agent: Claude Code, Cursor, ChatGPT, Codex devono supportare il percorso scelto.
• Governance: hooks con prompt di installazione trasparenti; MCP con permessi del server controllati dagli admin.
• Controllo quantità dati: limitare la lunghezza del contesto iniettato per non superare i token, dando priorità ai fact ad alta relevance.

Quinto livello: governance

• Ereditarietà permessi: mappare permessi della fonte su visibilità a livello fact. Un fact da un canale Slack privato non deve diventare visibile a tutti.
• Audit log: chi ha iniettato quale fact, quando, e quali fact ha letto l’Agent. Se qualcosa va storto, serve tracciabilità.
• Correzione umana: marcare fact errati, progettare un flusso invalidated, supportare l’aggiunta manuale di fact di chiarimento.
• Export dati: verificare se l’intero fact store può essere esportato in JSON/CSV per valutare il lock-in.

La logica della checklist è semplice. Il livello fonti decide “da dove arriva”. Il livello fact decide “quale struttura salvare”. Il livello retrieval decide “come trovare”. Il livello iniezione decide “come consegnare”. Il livello governance decide “chi gestisce e come correggere”. Se manca un livello, la knowledge base aziendale si bloccherà nella pratica.

Percorso pilot di 7 giorni

Un piccolo team non dovrebbe collegare subito tutto Slack, email o CRM nella prima settimana. I permessi sono complessi e il rumore è alto; nel pilot rischi di vedere prima i problemi di governance che il valore. Parti da fonti a basso rischio, valida recall e correzione, poi espandi.

Day 1-2: scegli fonti dati a basso rischio

• Documenti Notion pubblici, come roadmap prodotto e specifiche tecniche.
• GitHub README e Wiki, come architettura del progetto e documentazione API.
• Escludi: canali Slack privati, email storiche, dati clienti CRM, perché sensibili sui permessi e rumorosi.

Day 3: progetta il Fact Schema

• 3-5 campi: subject, predicate, object, introduced_at, source.
• Non cercare la perfezione: nel pilot conta validare il percorso di retrieval, lo Schema può evolvere dopo.
• Definisci nomi: subject in formato uniforme, per esempio ProjectX, predicate come verbo, per esempio uses.

Day 4-5: testa retrieval e iniezione

• Test retrieval: prepara 5-10 query e controlla se vengono trovati i fact chiave.
• Test iniezione: scegli un Agent, per esempio Claude Code o Cursor, e verifica se legge il contesto iniettato.
• Registra la latenza: la risposta retrieval è < 500 ms? Dopo l’iniezione l’Agent cita correttamente i fact?

Day 6-7: replay e correzione umana

• Ripeti query storiche e controlla se i risultati contengono fact errati o obsoleti.
• Registra errori: elenca i fact da invalidare e progetta il flusso di marcatura.
• Progetta correzione: aggiunta manuale di fact di chiarimento + timestamp invalidated_at sui fact errati.

Cosa non fare nella prima settimana:

• Non collegare Slack, email o CRM: permessi e rumore sono troppo complessi.
• Non inseguire uno Schema perfetto: prima valida il percorso di retrieval, poi itera.
• Non collegare fonti di produzione: usa dati di test o documenti pubblici per validare il flusso.

Alla fine del pilot dovresti avere un flusso retrieval + iniezione funzionante, 5-10 fact verificati e un processo di correzione. Sono i prerequisiti per espandere le fonti: prima verifica che il sistema trovi, legga e corregga; poi collega altri strumenti.

🔥 Non sprecare mesi su prodotti senza domanda! Valida i punti di forza del tuo SaaS con Adsterra e un piccolo budget →

Testa ora →Pubbl.

Tabella dei rischi per la scelta

Quando decidi, controlla sette dimensioni di rischio. Ogni dimensione dovrebbe avere fonte e livello di fiducia.

Tra queste sette dimensioni, export dati e lock-in fornitore sono le più importanti. Nei commenti, il fondatore dice che l’export è supportato, ma non c’è un impegno ufficiale completo verificabile. Questo significa controllare se il formato è strutturato, per esempio JSON/CSV; se può esportare l’intero fact store, inclusi typed edges e timestamp; e se una migrazione verso un altro sistema richiederebbe pulizia aggiuntiva.

La trasparenza degli hooks è un altro rischio facile da sottovalutare. Gli hooks iniettano contesto lato client, e l’utente potrebbe non sapere quali dati sono stati caricati automaticamente nella conversazione dell’Agent. In valutazione, verifica se il prodotto mostra prompt di installazione chiari e se l’utente può vedere e controllare l’ambito dei dati iniettati.

L’ereditarietà dei permessi ha una direzione tecnica pubblica con access-control tags, ma non regole pubbliche. Le domande pratiche sono concrete: come si mappa un fact da un canale Slack privato alla visibilità a livello fact? Come si ritagliano dati clienti CRM per team? Che tu acquisti o costruisca, questa logica di mapping deve essere progettata.

Prossimi passi e letture correlate

Se vuoi approfondire il legame tra Agent e knowledge base, questi articoli BetterLink sono buoni punti di partenza:

• RAG + Agent: architettura di nuova generazione per applicazioni IA — come i risultati di retrieval possono guidare decisioni dell’Agent.
• Sistemi di memoria per AI Agent: aiutare gli agenti a ricordare il contesto — architettura della memoria personale dell’Agent e differenza rispetto alla memoria condivisa aziendale.
• Tutorial Workers AI + Vectorize RAG — dettagli pratici di Cloudflare Vectorize per costruire un piccolo sistema RAG.
• Monitoraggio e auto-recupero degli AI Agent — come collegare memoria ed esecuzione per rilevare e ritentare i fallimenti.
• Agent tool calling nella pratica — dettagli su MCP e tool calling che completano il percorso di iniezione.

Conclusione

Hyper è ancora un prodotto giovane. I dettagli architetturali pubblici, tra cui memoria a due livelli, typed edges, modello di timestamp e doppio percorso hooks/MCP, sono comunque un buon caso per capire come progettare una “memoria aziendale”. Per piccoli team che valutano o costruiscono questo tipo di sistema, i tre controlli principali sono export dati, trasparenza degli hooks e gestione dei conflitti.

Nel pilot, parti da un workflow stretto: documenti Notion pubblici o un README GitHub. Valida recall del retrieval e meccanismo di correzione prima di collegare Slack o email. Non iniziare inseguendo uno Schema perfetto: ciclo di vita dei fact, ereditarietà dei permessi e correzione umana devono iterare con test reali.

Se usi già Claude Code o Cursor, puoi prima provare a iniettare documenti di progetto tramite hooks e osservare se l’Agent cita correttamente i fact. Il passo successivo è chiudere il ciclo tra memoria ed esecuzione: monitoraggio e auto-recupero dell’Agent, così i fallimenti vengono rilevati e ritentati invece di ripetersi in silenzio.