Architettura

Questa pagina illustra l'architettura interna di Kiro Memory, coprendo il flusso dei dati, il sistema di hooks, gli algoritmi di ricerca e ranking, la progettazione dello storage e la sicurezza.

Panoramica del sistema

┌──────────────────────────────────────────────────────────┐
│                    AI Coding Editor                       │
│         (Claude Code / Cursor / Windsurf / Cline)        │
├──────────────────────────────────────────────────────────┤
│                                                          │
│   ┌─────────────┐              ┌──────────────────┐     │
│   │   Hooks /    │              │   MCP Server     │     │
│   │   Rules      │              │   (10 strumenti) │     │
│   │              │              │                  │     │
│   │  Cattura:    │              │  Ricerca, Arch., │     │
│   │  - File      │              │  Ripresa, Report │     │
│   │  - Comandi   │              │                  │     │
│   │  - Decisioni │              │                  │     │
│   └──────┬───────┘              └────────┬─────────┘     │
│          │                               │               │
└──────────┼───────────────────────────────┼───────────────┘
           │            HTTP               │
           v                               v
     ┌─────────────────────────────────────────────┐
     │           Kiro Memory Worker                │
     │           (port 3001)                       │
     │                                             │
     │   ┌───────────┐  ┌────────────────────┐    │
     │   │  REST API  │  │  Web Dashboard     │    │
     │   │  Endpoints │  │  (SSE feed live)   │    │
     │   └─────┬──────┘  └────────────────────┘    │
     │         │                                    │
     │   ┌─────┴──────────────────────────────┐    │
     │   │         Livello di servizio        │    │
     │   │                                    │    │
     │   │  ┌──────────┐  ┌───────────────┐  │    │
     │   │  │  SQLite   │  │ Ricerca       │  │    │
     │   │  │  + FTS5   │  │ vettoriale    │  │    │
     │   │  └──────────┘  └───────────────┘  │    │
     │   └────────────────────────────────────┘    │
     └─────────────────────────────────────────────┘
                        │
                        v
              ~/.kiro-memory/kiro-memory.db

Sistema di hooks

Hooks di Claude Code

Claude Code fornisce hooks del ciclo di vita che Kiro Memory utilizza per catturare e iniettare contesto automaticamente. Vengono registrati quattro hooks:

Inizio sessione                           Fine sessione
     │                                          │
     v                                          v
 ┌──────────┐    ┌──────────────┐    ┌──────────────┐
 │ PreTool  │    │  PostTool    │    │    Stop      │
 │ Use      │    │  Use         │    │              │
 │          │    │              │    │  - Riepilogo │
 │ Iniezione│    │  Cattura:    │    │  - Checkpoint│
 │ contesto │    │  - Scritture │    │              │
 └──────────┘    │  - Comandi   │    └──────────────┘
                 │  - Ricerche  │
                 └──────────────┘
                        │
                 ┌──────────────┐
                 │ Notification │
                 │              │
                 │ Archivia     │
                 │ prompt utente│
                 └──────────────┘

Dettagli degli hooks

PreToolUse (agentSpawn)

• Si attiva all'inizio della sessione
• Recupera il contesto intelligente dall'SDK usando il ranking a 4 segnali
• Inietta riepiloghi recenti e osservazioni rilevanti nella sessione
• Garantisce che il worker in background sia in esecuzione (lo avvia se necessario)
• Attende fino a 3 secondi per la disponibilita del worker
• Degrada gradualmente se il worker non e raggiungibile

PostToolUse (postToolUse)

• Si attiva dopo ogni esecuzione di strumento
• Normalizza gli eventi degli strumenti da diverse fonti editor
• Classifica le osservazioni per tipo:
  • file-write -- Creazione o modifica di file
  • command -- Esecuzione di comandi shell
  • research -- Ricerca nel codice, grep, lettura di file
  • tool-use -- Altre invocazioni di strumenti
  • delegation -- Eventi di delega tra agenti
• Filtra gli strumenti non informativi (introspect, thinking, todo)
• Traccia gli strumenti di sola lettura (glob, grep, read) solo con i percorsi dei file
• Limita il contenuto a 500 caratteri per campo
• Invia notifica in tempo reale alla dashboard

Notification (userPromptSubmit)

• Si attiva quando l'utente invia un prompt
• Archivia il testo del prompt con l'associazione alla sessione
• Abilita lo storico dei prompt per la ricostruzione del contesto

Stop

• Si attiva quando l'agente completa la sua risposta
• Recupera fino a 50 osservazioni recenti (per sessione o finestra di 4 ore)
• Genera un riepilogo della sessione contenente:
  • Attivita completate (fino a 10, dai titoli delle osservazioni)
  • File modificati (deduplicati)
  • Intuizioni apprese (fino a 5, dalle osservazioni di ricerca)
• Crea un checkpoint strutturato con attivita, progresso, prossimi passi e file rilevanti (fino a 20)
• Invia notifiche in tempo reale sia per la creazione del riepilogo che del checkpoint

Editor basati su regole (Cursor, Windsurf, Cline)

Gli editor senza supporto nativo per gli hooks utilizzano file di regole/istruzioni che indirizzano l'assistente AI a richiamare gli strumenti MCP nei momenti appropriati:

• Inizio sessione: Richiamare get_context o resume_session
• Durante la sessione: Richiamare store_observation e store_knowledge quando necessario
• Fine sessione: Richiamare store_summary con apprendimenti e prossimi passi

Ricerca vettoriale

Kiro Memory fornisce ricerca semantica utilizzando embedding vettoriali generati localmente. Non sono necessarie chiavi API esterne.

Pipeline degli embedding

Testo dell'osservazione
      │
      v
┌─────────────────┐
│ Modello di       │    Inferenza locale
│ embedding        │    Nessuna chiave API
│ (fastembed o     │
│  transformers)   │
└────────┬─────────┘
         │
         v
   Vettore a 384 dimensioni
         │
         v
┌─────────────────┐
│ Archiviazione    │    Archiviato insieme
│ SQLite           │    ai dati dell'osservazione
│ (colonna emb.)   │
└─────────────────┘

Provider di embedding

Kiro Memory supporta due provider di embedding locali (elencati come dipendenze opzionali):

1. fastembed -- Generazione di embedding nativa ad alta velocita
2. @huggingface/transformers -- Modelli transformer di HuggingFace

Il servizio di embedding viene inizializzato in modo lazy al primo utilizzo e funziona interamente in locale.

Modalita di ricerca

Modalita	Metodo	Come funziona
Parole chiave	search()	Ricerca full-text SQLite FTS5 con ranking BM25
Semantica	semanticSearch()	Similarita del coseno tra query e embedding delle osservazioni
Ibrida	hybridSearch()	Combina punteggi FTS5 per parole chiave con punteggi di similarita vettoriale

La ricerca ibrida offre i migliori risultati intercettando sia le corrispondenze esatte per parole chiave sia i contenuti semanticamente simili.

Ranking a 4 segnali

Il sistema di contesto intelligente classifica ogni elemento di memoria utilizzando quattro segnali per far emergere il contesto piu rilevante:

┌──────────────────────────────────────────────┐
│             Punteggio di ranking             │
│                                              │
│   Score = w1 * Recency                       │
│         + w2 * Frequency                     │
│         + w3 * Similarita semantica          │
│         + w4 * Penalita di decay             │
│                                              │
└──────────────────────────────────────────────┘

Definizione dei segnali

1. Recency

Quanto e recente la creazione dell'osservazione. Le osservazioni recenti ricevono punteggi piu alti, con decadimento esponenziale nel tempo.

recency_score = exp(-age_hours / half_life)

2. Frequency

Quanto spesso i file o i concetti associati all'osservazione appaiono nella memoria. Gli elementi referenziati frequentemente hanno maggiore probabilita di essere rilevanti.

3. Similarita semantica

Quando viene fornita una query (ad esempio durante getSmartContext con un parametro query), le osservazioni vengono valutate per similarita del coseno tra il loro vettore embedding e l'embedding della query.

4. Penalita di decay

Le osservazioni collegate a file che sono stati modificati dopo la cattura vengono penalizzate. Questo impedisce che informazioni obsolete emergano. Anche le osservazioni mai consultate ricevono un punteggio inferiore col tempo.

Budget di token

Il metodo getSmartContext() accetta un parametro tokenBudget (predefinito: 2000 token) che limita la quantita di contesto iniettato. Gli elementi vengono classificati per punteggio composito e inclusi fino a esaurimento del budget. Questo previene l'overflow del contesto negli editor con finestre di prompt limitate.

Architettura dello storage

SQLite con FTS5

Tutti i dati sono archiviati in un singolo database SQLite in ~/.kiro-memory/kiro-memory.db. SQLite e stato scelto per:

• Configurazione zero
• Portabilita in un singolo file
• Eccellenti prestazioni di lettura per carichi di lavoro locali
• Estensione FTS5 per la ricerca full-text

Schema del database

Il database contiene le seguenti tabelle principali:

┌─────────────────┐     ┌─────────────────┐
│  observations   │     │   summaries     │
│                 │     │                 │
│  id (PK)        │     │  id (PK)        │
│  type           │     │  project        │
│  title          │     │  session_id     │
│  content        │     │  request        │
│  project        │     │  learned        │
│  session_id     │     │  completed      │
│  concepts       │     │  next_steps     │
│  files          │     │  created_at     │
│  embedding      │     └─────────────────┘
│  stale           │
│  access_count   │     ┌─────────────────┐
│  last_accessed  │     │  checkpoints    │
│  created_at     │     │                 │
└─────────────────┘     │  id (PK)        │
                        │  session_id     │
┌─────────────────┐     │  project        │
│  sessions       │     │  task           │
│                 │     │  progress       │
│  id (PK)        │     │  next_steps     │
│  content_id     │     │  questions      │
│  project        │     │  files          │
│  status         │     │  created_at     │
│  created_at     │     └─────────────────┘
│  completed_at   │
└─────────────────┘     ┌─────────────────┐
                        │  user_prompts   │
┌─────────────────┐     │                 │
│ observations_fts│     │  id (PK)        │
│ (FTS5 virtuale) │     │  session_id     │
│                 │     │  prompt_number  │
│  title          │     │  text           │
│  content        │     │  created_at     │
│  concepts       │     └─────────────────┘
└─────────────────┘

Tabelle virtuali FTS5

La ricerca full-text e alimentata dalle tabelle virtuali SQLite FTS5 che indicizzano titoli, contenuti e concetti delle osservazioni. FTS5 offre:

• Ranking di rilevanza BM25
• Query con prefisso
• Operatori booleani (AND, OR, NOT)
• Corrispondenza di frasi
• Ricerca specifica per colonna

Archiviazione vettoriale

I vettori embedding vengono archiviati direttamente nella tabella delle osservazioni come blob binari. Questo evita l'overhead di un database vettoriale separato pur supportando la ricerca per similarita del coseno. L'indice vettoriale viene ricostruito in memoria quando il servizio di embedding si inizializza.

Architettura del worker

Meccanismo di avvio automatico

Il worker e un processo Node.js autonomo che viene eseguito in background:

Inizio sessione editor
        │
        v
  Hook: agentSpawn
        │
        v
  Il worker e raggiungibile?  ──── Si ───> Inietta contesto
        │
        No
        │
        v
  Avvia worker-service.js
  (processo in background)
        │
        v
  Attendi fino a 3s
        │
        v
  Worker pronto? ──── No ───> Degradazione graduale
        │                     (continua senza worker)
        Si
        │
        v
  Inietta contesto

Responsabilita del worker

Il processo worker gestisce:

1. API HTTP -- Endpoint RESTful per tutte le operazioni CRUD
2. Dashboard web -- Serve l'interfaccia dashboard basata su React
3. Streaming SSE -- Streaming di eventi in tempo reale per il feed live della dashboard
4. Operazioni sugli embedding -- Inizializzazione lazy ed elaborazione batch degli embedding vettoriali
5. Gestione del database -- Connection pooling e gestione delle migrazioni

Endpoint API

Il worker espone endpoint REST sotto http://127.0.0.1:3001/api/:

Endpoint	Metodo	Descrizione
/api/context/:project	GET	Contesto del progetto
/api/search	GET	Ricerca full-text
/api/hybrid-search	GET	Ricerca ibrida vettoriale + parole chiave
/api/timeline	GET	Timeline cronologica
/api/observations/batch	POST	Recupero batch di osservazioni
/api/observations	POST	Archivia osservazione
/api/summaries	POST	Archivia riepilogo
/api/knowledge	POST	Archivia conoscenza
/api/checkpoint	GET	Ultimo checkpoint del progetto
/api/sessions/:id/checkpoint	GET	Checkpoint della sessione
/api/report	GET	Report di attivita
/api/embeddings/stats	GET	Statistiche degli embedding
/api/events	GET	Flusso eventi SSE

Sicurezza

Kiro Memory e progettato per l'uso in sviluppo locale ma include diversi livelli di sicurezza:

Autenticazione con token

Le richieste API al worker richiedono un token di autenticazione valido. Il token viene generato durante l'installazione e archiviato nella configurazione locale. Gli hooks e il server MCP includono il token automaticamente.

Rate limiting

Il worker basato su Express utilizza express-rate-limit per proteggere da chiamate API eccessive. Questo impedisce che cicli incontrollati negli hooks sovraccarichino il sistema.

Helmet

Il middleware Helmet imposta header HTTP sicuri:

• Content-Security-Policy -- Limita il caricamento delle risorse
• X-Content-Type-Options: nosniff -- Previene lo sniffing MIME
• X-Frame-Options: DENY -- Previene il clickjacking
• Strict-Transport-Security -- Impone HTTPS (quando applicabile)

CORS

Il Cross-Origin Resource Sharing e limitato alle origini localhost. La dashboard web viene servita dalla stessa origine dell'API, e le richieste esterne vengono rifiutate.

Validazione degli input

Tutti gli input API vengono validati utilizzando schema Zod. I payload non validi vengono rifiutati prima di raggiungere il livello database. I campi contenuto vengono sanitizzati con DOMPurify per prevenire XSS nella dashboard web.

Progettazione locale

Per impostazione predefinita, il worker si lega a 127.0.0.1 (solo localhost). Tutti i dati rimangono sulla tua macchina. Nessuna telemetria, nessun servizio cloud, nessuna chiamata API esterna. La generazione degli embedding avviene localmente utilizzando modelli integrati.