Usage Guide

Once installed, Kiro Memory works automatically in the background. This guide covers the CLI commands, web dashboard, and key workflows you can use to interact with your memory.

CLI Commands

The kiro-memory CLI provides commands for searching, storing, and managing your memory.

Command	Alias	Description
install	--	Set up hooks and MCP for your editor
context	ctx	Display current project context
search <query>	--	Full-text keyword search (FTS5)
semantic-search <query>	sem	Hybrid vector + keyword search
observations	obs	Show recent observations
summaries	sum	Show recent summaries
add-observation <title> <content>	add-obs	Manually add an observation
add-summary <content>	add-sum	Manually add a session summary
add-knowledge <type> <title> <content>	add-k	Store structured knowledge
resume [session-id]	--	Resume from a previous checkpoint
report	--	Generate an activity report
decay	--	Memory decay management
embeddings	emb	Manage vector embeddings
doctor	--	Run environment diagnostics

Viewing Context

See what Kiro Memory knows about your current project:

kiro-memory context

This displays:

• Recent observations (file writes, commands, research)
• Session summaries
• Active knowledge items (decisions, constraints, heuristics)
• Latest checkpoint information

Searching Memory

Keyword Search

Search using SQLite FTS5 full-text search:

kiro-memory search "authentication middleware"

Results include matching observations and summaries with relevance scores.

Semantic Search

Find memories by meaning using vector embeddings:

kiro-memory semantic-search "how to handle user login errors"
# or use the alias
kiro-memory sem "how to handle user login errors"

Semantic search combines vector similarity with keyword matching (hybrid search) to return the most relevant results even when exact terms do not match.

Web Dashboard

Kiro Memory includes a real-time web dashboard accessible at:

http://localhost:3001

The worker starts automatically when your editor session begins. You can also manage it manually:

kiro-memory worker:start    # Start the worker
kiro-memory worker:stop     # Stop the worker
kiro-memory worker:status   # Check status
kiro-memory worker:logs     # View recent logs
kiro-memory worker:tail     # Follow logs in real-time

Dashboard Features

• Live Feed -- Real-time observation stream via Server-Sent Events (SSE). See file writes, commands, and research as they happen.
• Spotlight Search -- Press Ctrl+K (or Cmd+K on macOS) to open instant search across all observations and summaries.
• Analytics -- Activity timeline, file hotspot analysis, session statistics, and observation type distribution.
• Theme Toggle -- Switch between dark and light themes.
• Project Filtering -- View memory for a specific project or across all projects.

Session Checkpoint and Resume

How Checkpoints Work

When a coding session ends, Kiro Memory automatically creates a checkpoint containing:

• Task: What you were working on
• Progress: What was accomplished
• Next steps: Recommended actions for the next session
• Open questions: Unresolved items
• Relevant files: Files that were modified (up to 20)

Resuming a Session

Resume from the latest checkpoint:

kiro-memory resume

Resume a specific session by ID:

kiro-memory resume 42

The resume output provides a structured summary:

## Session Checkpoint #42

**Task:** Implement payment processing integration
**Progress:** Stripe SDK integrated, webhook handler created
**Next steps:**
  - Add idempotency keys to payment requests
  - Write tests for webhook signature verification
  - Update error handling in checkout flow
**Relevant files:**
  - src/payments/stripe.ts
  - src/webhooks/payment.ts
  - tests/payments/stripe.test.ts

tip

When using Claude Code, the resume_session MCP tool is available to your AI assistant. It can automatically resume context without you running the CLI.

Activity Reports

Generate development activity reports summarizing observations, sessions, and learnings.

Weekly Report

kiro-memory report --period=weekly

Monthly Report

kiro-memory report --period=monthly

Output Formats

kiro-memory report --format=text      # Plain text (default)
kiro-memory report --format=md        # Markdown
kiro-memory report --format=json      # JSON (for programmatic use)

Save to File

kiro-memory report --period=weekly --format=md --output=weekly-report.md

Report Contents

Reports include:

• Overview: Total observations, sessions, and time span
• Sessions: Summary of each coding session
• Learnings: Key insights discovered during the period
• Completed Tasks: What was accomplished
• Next Steps: Pending work items
• File Hotspots: Top 10 most-modified files

Structured Knowledge Storage

Knowledge items are first-class entries that persist independently of sessions. They represent things your team or project "knows."

Knowledge Types

Type	Purpose	Example
decision	Architectural or technical choices	"Use PostgreSQL for relational data"
constraint	Rules that must be followed	"No external API calls in SSR"
heuristic	Soft preferences and guidelines	"Run tests before committing auth changes"
rejected	Approaches tried and abandoned	"Rejected MongoDB due to lack of ACID"

Storing Knowledge

# Basic
kiro-memory add-knowledge decision "Use React Query" \
  "Chose React Query for server state management"

# With metadata
kiro-memory add-knowledge constraint "No Google Fonts" \
  "Must use system fonts for GDPR compliance" \
  --severity=hard \
  --concepts="gdpr,performance,fonts"

# Rejected approach with reason
kiro-memory add-knowledge rejected "Styled Components" \
  "Evaluated styled-components for styling solution" \
  --reason="Runtime CSS-in-JS adds bundle size and hurts LCP" \
  --alternatives="Tailwind CSS,CSS Modules"

Knowledge via MCP

Your AI assistant can store knowledge programmatically using the store_knowledge MCP tool during a session:

"I'll store this architectural decision in Kiro Memory for future reference."

Managing Observations

View Recent Observations

kiro-memory observations         # Last 10
kiro-memory obs 25               # Last 25

Manually Add an Observation

kiro-memory add-observation "Deployed v2.1.0" \
  "Deployed version 2.1.0 to production with auth fixes"

View Summaries

kiro-memory summaries            # Last 5
kiro-memory sum 10               # Last 10

Memory Decay

Over time, observations can become stale as files change. Kiro Memory detects and manages this automatically.

Check Decay Statistics

kiro-memory decay stats

Output:

Memory Decay Statistics
=======================
Total observations:    284
Stale:                  12 (4.2%)
Never accessed:         34 (12.0%)
Recently accessed:     238 (83.8%)

Detect Stale Observations

Flag observations whose linked files have been modified since capture:

kiro-memory decay detect-stale

Consolidate Duplicates

Merge duplicate observations (same file and type), keeping the most recent:

kiro-memory decay consolidate            # Execute
kiro-memory decay consolidate --dry-run  # Preview only

Managing Embeddings

Check Embedding Coverage

kiro-memory embeddings stats

Backfill Missing Embeddings

Generate embeddings for observations that do not have them:

kiro-memory embeddings backfill        # Default batch of 50
kiro-memory embeddings backfill 200    # Custom batch size

info

Embeddings are generated locally using the built-in embedding model. No API keys or external services are required.