Riferimento API

Questa pagina fornisce un riferimento completo per tutte le interfacce di Kiro Memory: la CLI, gli strumenti MCP e il TypeScript SDK.

Riferimento CLI

Comandi di configurazione

Comando	Alias	Descrizione	Opzioni
`install`	--	Configura hooks e server MCP	`--claude-code`, `--cursor`, `--windsurf`, `--cline`
`doctor`	--	Esegui diagnostica dell'ambiente	--

Comandi di contesto e ricerca

Comando	Alias	Descrizione	Opzioni
`context`	`ctx`	Mostra il contesto del progetto corrente	--
`search <query>`	--	Ricerca full-text per parole chiave (FTS5)	--
`semantic-search <query>`	`sem`	Ricerca ibrida vettoriale + parole chiave	--
`resume [session-id]`	--	Riprendi da un checkpoint	Session ID (opzionale)

Comandi di recupero dati

Comando	Alias	Descrizione	Opzioni
`observations [limit]`	`obs`	Mostra le osservazioni recenti	Limite (predefinito: 10)
`summaries [limit]`	`sum`	Mostra i riepiloghi recenti	Limite (predefinito: 5)

Comandi di archiviazione dati

Comando	Alias	Descrizione	Opzioni
`add-observation <title> <content>`	`add-obs`	Aggiungi una nuova osservazione	--
`add-summary <content>`	`add-sum`	Aggiungi un riepilogo di sessione	--
`add-knowledge <type> <title> <content>`	`add-k`	Archivia conoscenza strutturata	`--severity`, `--alternatives`, `--reason`, `--context`, `--confidence`, `--concepts`, `--files`

Comandi di report e analisi

Comando	Alias	Descrizione	Opzioni
`report`	--	Genera report di attivita	`--period=weekly\|monthly`, `--format=text\|md\|json`, `--output=<file>`

Comandi di manutenzione

Comando	Alias	Descrizione	Sottocomandi
`embeddings`	`emb`	Gestione degli embedding vettoriali	`stats`, `backfill [batch-size]`
`decay`	--	Gestione del decadimento della memoria	`stats`, `detect-stale`, `consolidate [--dry-run]`

Comandi del worker

Comando	Descrizione
`worker:start`	Avvia il worker in background
`worker:stop`	Ferma il worker in background
`worker:restart`	Riavvia il worker
`worker:status`	Verifica lo stato del worker
`worker:logs`	Visualizza i log recenti
`worker:tail`	Segui i log in tempo reale

Riferimento strumenti MCP

Kiro Memory espone 10 strumenti tramite il Model Context Protocol. Questi sono disponibili per qualsiasi assistente AI compatibile con MCP.

Strumento	Descrizione
`search`	Ricerca full-text tra osservazioni e riepiloghi
`semantic_search`	Ricerca per similarita vettoriale per significato
`timeline`	Contesto cronologico attorno a un'osservazione
`get_observations`	Recupera i dettagli completi di un'osservazione tramite ID
`get_context`	Contesto recente per un progetto
`store_observation`	Archivia una nuova osservazione
`store_summary`	Archivia un riepilogo di sessione
`store_knowledge`	Archivia conoscenza strutturata
`resume_session`	Riprendi da un checkpoint
`generate_report`	Genera report di attivita

Per la documentazione dettagliata di ogni strumento, inclusi parametri, formati di ritorno ed esempi, consulta la pagina Server MCP.

TypeScript SDK

L'SDK fornisce accesso programmatico al sistema completo di Kiro Memory. Installalo come dipendenza:

npm install kiro-memory

Inizializzazione

import { createKiroMemory, KiroMemorySDK } from 'kiro-memory';

// Usando la funzione factory
const km = createKiroMemory({
  dataDir: '~/.kiro-memory',       // opzionale
  project: 'my-project',           // opzionale, rilevato automaticamente da cwd
  skipMigrations: false,            // opzionale, salta i controlli di migrazione
});

// Usando la classe direttamente
const km = new KiroMemorySDK({
  project: 'my-project',
});

`KiroMemoryConfig`

interface KiroMemoryConfig {
  dataDir?: string;          // Directory base dei dati (predefinito: ~/.kiro-memory)
  project?: string;          // Nome del progetto (predefinito: rilevamento automatico)
  skipMigrations?: boolean;  // Salta i controlli di migrazione per le prestazioni
}

Metodi di archiviazione

`storeObservation(data)`

Archivia una nuova osservazione.

const id: number = await km.storeObservation({
  type: 'file-write',      // file-write | command | research | tool-use | constraint | decision | heuristic | rejected
  title: 'Written: src/app.ts',
  content: 'Refactored main application entry point',
  concepts: ['refactoring', 'architecture'],  // opzionale
  files: ['src/app.ts'],                      // opzionale
});

Ritorna: Promise<number> -- L'ID dell'osservazione.

`storeSummary(data)`

Archivia un riepilogo di sessione.

const id: number = await km.storeSummary({
  request: 'Implement user authentication',
  learned: 'JWT refresh tokens need rotation logic',
  completed: ['Login flow', 'Session persistence'],
  nextSteps: ['Add refresh token rotation', 'Write auth tests'],
});

Ritorna: Promise<number> -- L'ID del riepilogo.

`storeKnowledge(data)`

Archivia conoscenza strutturata.

const id: number = await km.storeKnowledge({
  knowledgeType: 'decision',    // decision | constraint | heuristic | rejected
  title: 'Use PostgreSQL',
  content: 'Chose PostgreSQL over MongoDB for relational data integrity',
  project: 'my-project',
  reason: 'Need ACID transactions for payment processing',   // opzionale
  alternatives: ['MongoDB', 'SQLite'],                        // opzionale
  severity: 'hard',             // opzionale, per vincoli: hard | soft
  context: 'When processing payments',                        // opzionale, per euristiche
  confidence: 'high',           // opzionale, per euristiche: high | medium | low
  concepts: ['database', 'payments'],                         // opzionale
  files: ['src/db/config.ts'],                                // opzionale
});

Ritorna: Promise<number> -- L'ID dell'osservazione.

`storePrompt(contentSessionId, promptNumber, text)`

Archivia un prompt dell'utente per il tracciamento della sessione.

const id: number = await km.storePrompt('session-123', 1, 'Fix the auth bug in login.ts');

Ritorna: Promise<number> -- L'ID del prompt.

Metodi di recupero

`getContext()`

Recupera il contesto recente per il progetto corrente.

const context = await km.getContext();
// context.observations: Observation[]
// context.summaries: Summary[]
// context.prompts: UserPrompt[]

Ritorna: Promise<ContextContext>

`getSmartContext(options?)`

Recupera il contesto classificato usando il modello di punteggio a 4 segnali.

const smartCtx = await km.getSmartContext({
  tokenBudget: 2000,   // opzionale, predefinito: 2000
  query: 'authentication',  // opzionale, abilita il ranking semantico
});
// smartCtx.items: ScoredItem[]

Ritorna: Promise<SmartContext>

`getRecentObservations(limit?)`

Recupera le osservazioni recenti.

const observations: Observation[] = await km.getRecentObservations(10);

Ritorna: Promise<Observation[]> -- Limite predefinito: 10.

`getRecentSummaries(limit?)`

Recupera i riepiloghi recenti.

const summaries: Summary[] = await km.getRecentSummaries(5);

Ritorna: Promise<Summary[]> -- Limite predefinito: 5.

`getObservationsByIds(ids)`

Recupero batch di osservazioni tramite ID.

const observations: Observation[] = await km.getObservationsByIds([1, 5, 12]);

Ritorna: Promise<Observation[]>

Metodi di ricerca

`search(query)`

Ricerca full-text di base tra osservazioni e riepiloghi.

const results = await km.search('authentication middleware');
// results.observations: Observation[]
// results.summaries: Summary[]

Ritorna: Promise<{ observations: Observation[]; summaries: Summary[] }>

`searchAdvanced(query, filters?)`

Ricerca basata su FTS5 con filtri opzionali.

const results = await km.searchAdvanced('auth', {
  project: 'my-app',
  type: 'file-write',
  // dateRange: { start: '2025-01-01', end: '2025-12-31' }
});

Ritorna: Promise<{ observations: Observation[]; summaries: Summary[] }>

`hybridSearch(query, options?)`

Ricerca combinata vettoriale + parole chiave.

const results: SearchResult[] = await km.hybridSearch('error handling patterns', {
  limit: 10,   // opzionale, predefinito: 10
});

Ritorna: Promise<SearchResult[]>

`semanticSearch(query, options?)`

Ricerca per pura similarita vettoriale.

const results: SearchResult[] = await km.semanticSearch('how to handle retries', {
  limit: 10,        // opzionale, predefinito: 10
  threshold: 0.3,   // opzionale, punteggio di similarita minimo, predefinito: 0.3
});

Ritorna: Promise<SearchResult[]>

Metodi di timeline e sessione

`getTimeline(anchorId, depthBefore?, depthAfter?)`

Ottieni il contesto cronologico attorno a una specifica osservazione.

const entries: TimelineEntry[] = await km.getTimeline(42, 5, 5);

Ritorna: Promise<TimelineEntry[]> -- Profondita predefinite: 5 prima, 5 dopo.

`getOrCreateSession(contentSessionId)`

Crea o recupera una sessione.

const session: DBSession = await km.getOrCreateSession('session-abc-123');

Ritorna: Promise<DBSession>

`completeSession(sessionId)`

Contrassegna una sessione come completata.

await km.completeSession(42);

Ritorna: Promise<void>

`createCheckpoint(sessionId, data)`

Salva un checkpoint strutturato per la ripresa della sessione.

const id: number = await km.createCheckpoint(42, {
  task: 'Implement payment flow',
  progress: 'Stripe SDK integrated',
  nextSteps: ['Add idempotency keys', 'Write webhook tests'],
  openQuestions: ['Which webhook events to handle?'],
  relevantFiles: ['src/payments/stripe.ts', 'src/webhooks/payment.ts'],
});

Ritorna: Promise<number> -- L'ID del checkpoint.

`getCheckpoint(sessionId)`

Recupera l'ultimo checkpoint per una sessione.

const checkpoint: DBCheckpoint | null = await km.getCheckpoint(42);

Ritorna: Promise<DBCheckpoint | null>

`getLatestProjectCheckpoint()`

Recupera l'ultimo checkpoint per il progetto corrente.

const checkpoint: DBCheckpoint | null = await km.getLatestProjectCheckpoint();

Ritorna: Promise<DBCheckpoint | null>

Metodi di report

`generateReport(options?)`

Genera un report di attivita.

const report: ReportData = await km.generateReport({
  period: 'weekly',         // opzionale: weekly | monthly
  startDate: '2025-01-01',  // opzionale
  endDate: '2025-01-31',    // opzionale
});

Ritorna: Promise<ReportData>

Metodi per gli embedding

`initializeEmbeddings()`

Inizializza il servizio di embedding (caricamento lazy).

const available: boolean = await km.initializeEmbeddings();

Ritorna: Promise<boolean> -- Se gli embedding sono disponibili.

`backfillEmbeddings(batchSize?)`

Genera gli embedding per le osservazioni che ne sono prive.

const count: number = await km.backfillEmbeddings(50);  // predefinito: 50

Ritorna: Promise<number> -- Numero di embedding generati.

`getEmbeddingStats()`

Ottieni le statistiche di copertura degli embedding.

const stats = km.getEmbeddingStats();
// stats.total: number
// stats.embedded: number
// stats.percentage: number

Ritorna: { total: number; embedded: number; percentage: number }

Metodi di manutenzione

`detectStaleObservations()`

Segnala le osservazioni collegate a file che sono cambiati.

const staleCount: number = await km.detectStaleObservations();

Ritorna: Promise<number> -- Conteggio delle osservazioni appena segnalate come obsolete.

`consolidateObservations(options?)`

Unisci le osservazioni duplicate.

const result = await km.consolidateObservations({ dryRun: false });
// result.merged: number
// result.removed: number

Ritorna: Promise<{ merged: number; removed: number }>

`getDecayStats()`

Ottieni le statistiche di decadimento della memoria.

const stats = await km.getDecayStats();
// stats.total: number
// stats.stale: number
// stats.neverAccessed: number
// stats.recentlyAccessed: number

Ritorna: Promise<{ total: number; stale: number; neverAccessed: number; recentlyAccessed: number }>

Metodi di utilita

`getProject()`

Ottieni il nome del progetto corrente.

const name: string = km.getProject();

Ritorna: string

`getDb()`

Ottieni l'accesso diretto al database (per casi d'uso avanzati).

const db = km.getDb();

Ritorna: Istanza del database.

`close()`

Chiudi la connessione al database. Richiama questo metodo quando hai finito di usare l'SDK.

km.close();

Ritorna: void

Tipi esportati

import type {
  Observation,
  Summary,
  UserPrompt,
  DBSession,
  DBCheckpoint,
  ContextContext,
  SearchFilters,
  TimelineEntry,
  ScoredItem,
  SmartContext,
  StoreKnowledgeInput,
  KnowledgeType,
  KnowledgeMetadata,
  ReportData,
  SearchResult,
  KiroMemoryConfig,
} from 'kiro-memory';

Alias deprecati

I seguenti alias sono mantenuti per compatibilita con le versioni precedenti ma non dovrebbero essere usati nel nuovo codice:

Deprecato	Sostituzione
`ContextKitSDK`	`KiroMemorySDK`
`createContextKit()`	`createKiroMemory()`
`ContextKitConfig`	`KiroMemoryConfig`

Riferimento CLI​

Comandi di configurazione​

Comandi di contesto e ricerca​

Comandi di recupero dati​

Comandi di archiviazione dati​

Comandi di report e analisi​

Comandi di manutenzione​

Comandi del worker​

Riferimento strumenti MCP​

TypeScript SDK​

Inizializzazione​

KiroMemoryConfig​

Metodi di archiviazione​

storeObservation(data)​

storeSummary(data)​

storeKnowledge(data)​

storePrompt(contentSessionId, promptNumber, text)​

Metodi di recupero​

getContext()​

getSmartContext(options?)​

getRecentObservations(limit?)​

getRecentSummaries(limit?)​

getObservationsByIds(ids)​

Metodi di ricerca​

search(query)​

searchAdvanced(query, filters?)​

hybridSearch(query, options?)​

semanticSearch(query, options?)​

Metodi di timeline e sessione​

getTimeline(anchorId, depthBefore?, depthAfter?)​

getOrCreateSession(contentSessionId)​

completeSession(sessionId)​

createCheckpoint(sessionId, data)​

getCheckpoint(sessionId)​

getLatestProjectCheckpoint()​

Metodi di report​

generateReport(options?)​

Metodi per gli embedding​

initializeEmbeddings()​

backfillEmbeddings(batchSize?)​

getEmbeddingStats()​

Metodi di manutenzione​

detectStaleObservations()​

consolidateObservations(options?)​

getDecayStats()​

Metodi di utilita​

getProject()​

getDb()​

close()​

Tipi esportati​

Alias deprecati​