API Reference

This page provides a complete reference for all Kiro Memory interfaces: the CLI, the MCP tools, and the TypeScript SDK.

CLI Reference

Setup Commands

Command	Alias	Description	Options
`install`	--	Set up hooks and MCP server	`--claude-code`, `--cursor`, `--windsurf`, `--cline`
`doctor`	--	Run environment diagnostics	--

Context and Search Commands

Command	Alias	Description	Options
`context`	`ctx`	Show current project context	--
`search <query>`	--	Full-text keyword search (FTS5)	--
`semantic-search <query>`	`sem`	Hybrid vector + keyword search	--
`resume [session-id]`	--	Resume from a checkpoint	Session ID (optional)

Data Retrieval Commands

Command	Alias	Description	Options
`observations [limit]`	`obs`	Show recent observations	Limit (default: 10)
`summaries [limit]`	`sum`	Show recent summaries	Limit (default: 5)

Data Storage Commands

Command	Alias	Description	Options
`add-observation <title> <content>`	`add-obs`	Add a new observation	--
`add-summary <content>`	`add-sum`	Add a session summary	--
`add-knowledge <type> <title> <content>`	`add-k`	Store structured knowledge	`--severity`, `--alternatives`, `--reason`, `--context`, `--confidence`, `--concepts`, `--files`

Report and Analytics Commands

Command	Alias	Description	Options
`report`	--	Generate activity report	`--period=weekly\|monthly`, `--format=text\|md\|json`, `--output=<file>`

Maintenance Commands

Command	Alias	Description	Subcommands
`embeddings`	`emb`	Manage vector embeddings	`stats`, `backfill [batch-size]`
`decay`	--	Memory decay management	`stats`, `detect-stale`, `consolidate [--dry-run]`

Worker Commands

Command	Description
`worker:start`	Start background worker
`worker:stop`	Stop background worker
`worker:restart`	Restart worker
`worker:status`	Check worker status
`worker:logs`	View recent logs
`worker:tail`	Follow logs in real-time

MCP Tools Reference

Kiro Memory exposes 10 tools via the Model Context Protocol. These are available to any MCP-compatible AI assistant.

Tool	Description
`search`	Full-text search across observations and summaries
`semantic_search`	Vector similarity search by meaning
`timeline`	Chronological context around an observation
`get_observations`	Retrieve full observation details by ID
`get_context`	Recent context for a project
`store_observation`	Store a new observation
`store_summary`	Store a session summary
`store_knowledge`	Store structured knowledge
`resume_session`	Resume from a checkpoint
`generate_report`	Generate activity report

For detailed documentation of each tool including parameters, return formats, and examples, see the MCP Server page.

TypeScript SDK

The SDK provides programmatic access to the complete Kiro Memory system. Install it as a dependency:

npm install kiro-memory

Initialization

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

// Using factory function
const km = createKiroMemory({
  dataDir: '~/.kiro-memory',       // optional
  project: 'my-project',           // optional, auto-detected from cwd
  skipMigrations: false,            // optional, skip migration checks
});

// Using class directly
const km = new KiroMemorySDK({
  project: 'my-project',
});

`KiroMemoryConfig`

interface KiroMemoryConfig {
  dataDir?: string;          // Base data directory (default: ~/.kiro-memory)
  project?: string;          // Project name (default: auto-detected)
  skipMigrations?: boolean;  // Skip migration checks for performance
}

Storage Methods

`storeObservation(data)`

Store a new observation.

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'],  // optional
  files: ['src/app.ts'],                      // optional
});

Returns: Promise<number> -- The observation ID.

`storeSummary(data)`

Store a session summary.

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'],
});

Returns: Promise<number> -- The summary ID.

`storeKnowledge(data)`

Store structured knowledge.

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',   // optional
  alternatives: ['MongoDB', 'SQLite'],                        // optional
  severity: 'hard',             // optional, for constraints: hard | soft
  context: 'When processing payments',                        // optional, for heuristics
  confidence: 'high',           // optional, for heuristics: high | medium | low
  concepts: ['database', 'payments'],                         // optional
  files: ['src/db/config.ts'],                                // optional
});

Returns: Promise<number> -- The observation ID.

`storePrompt(contentSessionId, promptNumber, text)`

Store a user prompt for session tracking.

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

Returns: Promise<number> -- The prompt ID.

Retrieval Methods

`getContext()`

Retrieve recent context for the current project.

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

Returns: Promise<ContextContext>

`getSmartContext(options?)`

Retrieve ranked context using the 4-signal scoring model.

const smartCtx = await km.getSmartContext({
  tokenBudget: 2000,   // optional, default: 2000
  query: 'authentication',  // optional, enables semantic ranking
});
// smartCtx.items: ScoredItem[]

Returns: Promise<SmartContext>

`getRecentObservations(limit?)`

Fetch recent observations.

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

Returns: Promise<Observation[]> -- Default limit: 10.

`getRecentSummaries(limit?)`

Fetch recent summaries.

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

Returns: Promise<Summary[]> -- Default limit: 5.

`getObservationsByIds(ids)`

Batch retrieve observations by ID.

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

Returns: Promise<Observation[]>

Search Methods

`search(query)`

Basic full-text search across observations and summaries.

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

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

`searchAdvanced(query, filters?)`

FTS5-based search with optional filters.

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

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

`hybridSearch(query, options?)`

Combined vector + keyword search.

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

Returns: Promise<SearchResult[]>

`semanticSearch(query, options?)`

Pure vector similarity search.

const results: SearchResult[] = await km.semanticSearch('how to handle retries', {
  limit: 10,        // optional, default: 10
  threshold: 0.3,   // optional, minimum similarity score, default: 0.3
});

Returns: Promise<SearchResult[]>

Timeline and Session Methods

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

Get chronological context around a specific observation.

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

Returns: Promise<TimelineEntry[]> -- Default depths: 5 before, 5 after.

`getOrCreateSession(contentSessionId)`

Create or retrieve a session.

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

Returns: Promise<DBSession>

`completeSession(sessionId)`

Mark a session as completed.

await km.completeSession(42);

Returns: Promise<void>

`createCheckpoint(sessionId, data)`

Save a structured checkpoint for session resumption.

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'],
});

Returns: Promise<number> -- The checkpoint ID.

`getCheckpoint(sessionId)`

Retrieve the latest checkpoint for a session.

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

Returns: Promise<DBCheckpoint | null>

`getLatestProjectCheckpoint()`

Retrieve the latest checkpoint for the current project.

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

Returns: Promise<DBCheckpoint | null>

Report Methods

`generateReport(options?)`

Generate an activity report.

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

Returns: Promise<ReportData>

Embedding Methods

`initializeEmbeddings()`

Initialize the embedding service (lazy loaded).

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

Returns: Promise<boolean> -- Whether embeddings are available.

`backfillEmbeddings(batchSize?)`

Generate embeddings for observations that lack them.

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

Returns: Promise<number> -- Number of embeddings generated.

`getEmbeddingStats()`

Get embedding coverage statistics.

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

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

Maintenance Methods

`detectStaleObservations()`

Flag observations linked to files that have changed.

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

Returns: Promise<number> -- Count of newly stale observations.

`consolidateObservations(options?)`

Merge duplicate observations.

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

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

`getDecayStats()`

Get memory decay statistics.

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

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

Utility Methods

`getProject()`

Get the current project name.

const name: string = km.getProject();

Returns: string

`getDb()`

Get direct database access (for advanced use cases).

const db = km.getDb();

Returns: Database instance.

`close()`

Close the database connection. Call this when done using the SDK.

km.close();

Returns: void

Exported Types

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

Deprecated Aliases

The following aliases are maintained for backward compatibility but should not be used in new code:

Deprecated	Replacement
`ContextKitSDK`	`KiroMemorySDK`
`createContextKit()`	`createKiroMemory()`
`ContextKitConfig`	`KiroMemoryConfig`

CLI Reference​

Setup Commands​

Context and Search Commands​

Data Retrieval Commands​

Data Storage Commands​

Report and Analytics Commands​

Maintenance Commands​

Worker Commands​

MCP Tools Reference​

TypeScript SDK​

Initialization​

KiroMemoryConfig​

Storage Methods​

storeObservation(data)​

storeSummary(data)​

storeKnowledge(data)​

storePrompt(contentSessionId, promptNumber, text)​

Retrieval Methods​

getContext()​

getSmartContext(options?)​

getRecentObservations(limit?)​

getRecentSummaries(limit?)​

getObservationsByIds(ids)​

Search Methods​

search(query)​

searchAdvanced(query, filters?)​

hybridSearch(query, options?)​

semanticSearch(query, options?)​

Timeline and Session Methods​

getTimeline(anchorId, depthBefore?, depthAfter?)​

getOrCreateSession(contentSessionId)​

completeSession(sessionId)​

createCheckpoint(sessionId, data)​

getCheckpoint(sessionId)​

getLatestProjectCheckpoint()​

Report Methods​

generateReport(options?)​

Embedding Methods​

initializeEmbeddings()​

backfillEmbeddings(batchSize?)​

getEmbeddingStats()​

Maintenance Methods​

detectStaleObservations()​

consolidateObservations(options?)​

getDecayStats()​

Utility Methods​

getProject()​

getDb()​

close()​

Exported Types​

Deprecated Aliases​