Passa al contenuto principale

Contribuire

Grazie per il tuo interesse a contribuire a Kiro Memory. Questa guida copre la configurazione dell'ambiente di sviluppo, i test, gli standard del codice e gli scenari di risoluzione dei problemi piu comuni.

Prima di iniziare​

  1. Apri prima una issue -- Discuti la modifica che intendi apportare prima di scrivere codice. Questo previene sforzi duplicati e garantisce l'allineamento con la direzione del progetto.
  2. Una modifica per PR -- Mantieni le pull request focalizzate su una singola questione per facilitare la revisione.

Configurazione dell'ambiente di sviluppo​

Prerequisiti​

  • Node.js >= 18.0.0
  • npm (incluso con Node.js)
  • Strumenti di compilazione (Linux/WSL): sudo apt-get install -y build-essential python3

Clone e build​

git clone https://github.com/auriti-web-design/kiro-memory.git
cd kiro-memory
npm install
npm run build

Flusso di lavoro di sviluppo​

Il comando dev compila e sincronizza in un solo passaggio:

npm run dev

Dopo la compilazione, collega la versione locale per i test:

npm run install:kiro

Questo installa la versione compilata localmente come comando globale kiro-memory.

Gestione del worker durante lo sviluppo​

npm run worker:start    # Avvia il worker manualmente
npm run worker:stop     # Ferma il worker
npm run worker:logs     # Visualizza i log del worker
npm run worker:tail     # Segui i log in tempo reale

Struttura del progetto​

kiro-memory/
├── src/
│   ├── cli/                  # Definizioni dei comandi CLI
│   │   └── contextkit.ts     # Tutti i comandi CLI e handler
│   ├── hooks/                # Implementazioni degli hooks per editor
│   │   ├── agentSpawn.ts     # Iniezione contesto all'avvio sessione
│   │   ├── postToolUse.ts    # Cattura esecuzione strumenti
│   │   ├── userPromptSubmit.ts  # Archiviazione prompt
│   │   ├── stop.ts           # Riepilogo/checkpoint fine sessione
│   │   ├── hook-definitions.ts  # Registro degli hooks
│   │   ├── kiro-hooks.ts     # Sistema hooks CLI Kiro
│   │   └── utils.ts          # Utilita per gli hooks
│   ├── sdk/
│   │   └── index.ts          # TypeScript SDK (classe KiroMemorySDK)
│   ├── servers/
│   │   └── mcp-server.ts     # Definizioni e handler degli strumenti MCP
│   ├── services/
│   │   ├── search/           # Sottosistema di ricerca
│   │   │   ├── EmbeddingService.ts   # Generazione embedding locale
│   │   │   ├── VectorSearch.ts       # Ricerca per similarita vettoriale
│   │   │   ├── HybridSearch.ts       # Combinata vettoriale + FTS5
│   │   │   ├── ScoringEngine.ts      # Ranking a 4 segnali
│   │   │   └── ChromaManager.ts      # Integrazione Chroma
│   │   ├── sqlite/            # Livello database
│   │   │   ├── Database.ts           # Connessione DB e migrazioni
│   │   │   ├── Observations.ts       # CRUD osservazioni
│   │   │   ├── Summaries.ts          # CRUD riepiloghi
│   │   │   ├── Sessions.ts           # Gestione sessioni
│   │   │   ├── Checkpoints.ts        # CRUD checkpoint
│   │   │   ├── Search.ts             # Query di ricerca FTS5
│   │   │   ├── Analytics.ts          # Query di analisi
│   │   │   ├── Prompts.ts            # Archiviazione prompt
│   │   │   └── Reports.ts            # Generazione report
│   │   ├── worker-service.ts  # Server HTTP Express
│   │   └── report-formatter.ts  # Formattazione output report
│   ├── types/
│   │   └── worker-types.ts    # Tipi TypeScript condivisi
│   ├── ui/
│   │   ├── viewer.html        # Punto di ingresso della dashboard
│   │   └── viewer/            # App React della dashboard
│   │       ├── App.tsx
│   │       ├── components/    # Feed, Analytics, Search, ecc.
│   │       ├── hooks/         # React hooks (SSE, tema, impostazioni)
│   │       └── utils/         # Utilita per formattazione e dati
│   ├── utils/
│   │   └── logger.ts          # Utilita di logging
│   ├── shared/
│   │   └── paths.ts           # Risoluzione dei percorsi
│   └── index.ts               # Punto di ingresso del pacchetto
├── tests/
│   └── sqlite/                # Test del livello database
│       ├── database.test.ts
│       ├── observations.test.ts
│       └── sdk.test.ts
├── scripts/
│   ├── build-plugin.js        # Script di compilazione
│   ├── install-kiro.sh        # Script di installazione
│   └── sync-kiro.cjs          # Script di sincronizzazione
├── kiro-agent/                # Configurazione agente CLI Kiro
│   ├── contextkit.json
│   └── steering.md
├── package.json
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE

Test​

Eseguire tutti i test​

npm test

Eseguire suite di test specifiche​

npm run test:sqlite    # Test del livello database
npm run test:search    # Funzionalita di ricerca
npm run test:context   # Operazioni sul contesto
npm run test:server    # Test degli endpoint server
npm run test:agents    # Test di integrazione agenti
npm run test:infra     # Test dell'infrastruttura

Scrivere test​

  • Posiziona i file di test nella directory tests/, rispecchiando la struttura dei sorgenti
  • Usa nomi di test descrittivi che spieghino il comportamento atteso
  • Testa sia i casi di successo che di errore
  • Mantieni i test isolati -- ogni test deve ripulire dopo se stesso

Standard del codice​

TypeScript​

  • La modalita strict e attiva -- non sono ammessi tipi any
  • Scrivi funzioni pure per calcoli e logica
  • Mantieni gli effetti collaterali (I/O, database, rete) ai confini del sistema
  • Preferisci nomi chiari ai commenti esplicativi

Linee guida di stile​

  • Usa nomi descrittivi per variabili e funzioni
  • Evita l'astrazione prematura -- una semplice duplicazione e preferibile a helper non necessari
  • Mantieni le funzioni piccole e focalizzate
  • Gestisci gli errori esplicitamente; non sopprimere le eccezioni

Messaggi di commit​

Segui le Conventional Commits:

feat(hooks): add retry logic to postToolUse
fix(search): handle empty query in hybrid search
refactor(sdk): extract scoring into ScoringEngine
docs: update installation instructions
test(sqlite): add edge case for concurrent writes
chore: bump dependencies

Formato: type(scope): description

Tipi: feat, fix, refactor, docs, test, chore, perf, ci

Processo di pull request​

  1. Forka il repository e crea un branch da main
  2. Scrivi test per qualsiasi nuova funzionalita o correzione di bug
  3. Verifica che npm test e npm run build passino entrambi
  4. Invia la tua PR con:
    • Un titolo chiaro nel formato conventional commit
    • Un riepilogo di 1-3 punti su cosa e cambiato e perche
    • Un piano di test che descrive come le modifiche sono state verificate

Revisione della PR​

  • Le PR richiedono almeno un'approvazione prima del merge
  • La CI deve passare (test + build)
  • I maintainer potrebbero richiedere modifiche o porre domande di chiarimento

Risoluzione dei problemi​

Invalid ELF Header (WSL)​

Error: invalid ELF header

Causa: Stai eseguendo Node.js installato su Windows all'interno di WSL. I moduli nativi compilati per Windows non possono funzionare su Linux.

Soluzione: Installa Node.js nativamente all'interno di WSL usando nvm:

# All'interno di WSL
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm use 20
npm install -g kiro-memory

Problema di prefisso npm (Windows/WSL)​

npm ERR! Error: EACCES: permission denied

Causa: npm sta cercando di installare in una directory Windows da WSL.

Soluzione: Configura npm per usare un prefisso nativo Linux:

mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'

# Aggiungi a ~/.bashrc o ~/.zshrc:
export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.bashrc
npm install -g kiro-memory

Strumenti di compilazione mancanti (Linux/WSL)​

Error: Could not find any Python installations
gyp ERR! find Python

Causa: I moduli nativi (better-sqlite3) richiedono strumenti di compilazione C++ e Python.

Soluzione:

sudo apt-get update
sudo apt-get install -y build-essential python3
npm install -g kiro-memory

Conflitti di porta​

Error: listen EADDRINUSE: address already in use :::3001

Causa: La porta 3001 e gia in uso da un altro processo.

Soluzione:

# Trova cosa sta usando la porta 3001
lsof -i :3001

# Opzione 1: Termina il processo in conflitto
kill -9 <PID>

# Opzione 2: Usa una porta diversa
export KIRO_MEMORY_WORKER_PORT=3002
kiro-memory worker:restart

Configurazione agent/hook non trovata​

Error: agent configuration not found

Causa: Il passaggio di installazione non e stato eseguito o non e stato completato.

Soluzione:

kiro-memory install              # Rilevamento automatico dell'editor
# oppure
kiro-memory install --claude-code  # Editor specifico

Database bloccato​

Error: SQLITE_BUSY: database is locked

Causa: Piu processi stanno cercando di scrivere nel database contemporaneamente.

Soluzione:

# Ferma il worker
kiro-memory worker:stop

# Attendi un momento, poi riavvia
kiro-memory worker:start

Eseguire la diagnostica​

Il comando doctor verifica l'intero ambiente:

kiro-memory doctor

Questo valida:

  • Compatibilita della versione di Node.js
  • Installazione del pacchetto globale
  • Configurazione degli hook/regole dell'editor
  • Registrazione del server MCP
  • Disponibilita del worker
  • Accessibilita del database
  • Stato del servizio di embedding

Output di esempio:

Kiro Memory Doctor
==================
[OK]   Node.js v20.11.0 (>= 18 required)
[OK]   kiro-memory v1.7.1 installed globally
[OK]   Claude Code hooks configured
[OK]   MCP server entry found
[OK]   Worker reachable at http://127.0.0.1:3001
[OK]   Database: ~/.kiro-memory/kiro-memory.db (284 observations)
[OK]   Embeddings: 94% coverage (267/284)
[WARN] Windsurf rules not found (not installed for this editor)
suggerimento

Quando segnali problemi, includi l'output completo di kiro-memory doctor e tutti i file di log rilevanti da ~/.kiro-memory/logs/.

Segnalazione dei problemi​

Quando presenti una segnalazione di bug, includi:

  1. Comportamento effettivo -- Cosa e successo
  2. Comportamento atteso -- Cosa avrebbe dovuto succedere
  3. Passaggi per la riproduzione -- Passaggi minimi per riprodurre il problema
  4. Ambiente -- Sistema operativo, versione di Node.js, editor, output di kiro-memory doctor
  5. Log -- Voci rilevanti da ~/.kiro-memory/logs/
Vulnerabilita di sicurezza

Non segnalare vulnerabilita di sicurezza attraverso issue pubbliche su GitHub. Segui il processo di divulgazione descritto in SECURITY.md.

Licenza​

Contribuendo a Kiro Memory, accetti che i tuoi contributi saranno rilasciati sotto la Licenza AGPL-3.0.