Configuration

Kiro Memory works with sensible defaults out of the box. All configuration is done through environment variables and does not require a configuration file.

Environment Variables

Variable	Default	Description
KIRO_MEMORY_DATA_DIR	~/.kiro-memory	Base directory for database, logs, archives, and backups
KIRO_MEMORY_WORKER_HOST	127.0.0.1	Host address the worker HTTP server binds to
KIRO_MEMORY_WORKER_PORT	3001	Port for the worker HTTP server and web dashboard
KIRO_MEMORY_LOG_LEVEL	INFO	Logging verbosity: DEBUG, INFO, WARN, ERROR
KIRO_CONFIG_DIR	~/.kiro	Kiro CLI configuration directory

Setting Environment Variables

Temporary (current session):

export KIRO_MEMORY_WORKER_PORT=3002

Permanent (add to shell profile):

# ~/.bashrc or ~/.zshrc
export KIRO_MEMORY_DATA_DIR="$HOME/.kiro-memory"
export KIRO_MEMORY_WORKER_HOST="127.0.0.1"
export KIRO_MEMORY_WORKER_PORT="3001"
export KIRO_MEMORY_LOG_LEVEL="INFO"

tip

If port 3001 is already in use by another application, change KIRO_MEMORY_WORKER_PORT to an available port. Use lsof -i :3001 to check what is using the port.

Storage Layout

All persistent data lives under KIRO_MEMORY_DATA_DIR (default: ~/.kiro-memory):

~/.kiro-memory/
├── kiro-memory.db        # SQLite database (observations, summaries, knowledge, embeddings)
├── logs/                 # Worker and hook log files
├── archives/             # Archived/rotated data
└── backups/              # Database backups

Database

The SQLite database stores all observations, summaries, sessions, checkpoints, knowledge items, user prompts, and vector embeddings. It uses FTS5 virtual tables for full-text search.

The database is created automatically on first use. No manual setup is required.

warning

Do not modify the database file directly while the worker is running. Use the CLI or SDK for all data operations.

Logs

Log files are written to ~/.kiro-memory/logs/. View them with:

kiro-memory worker:logs     # Recent logs
kiro-memory worker:tail     # Follow in real-time

Set KIRO_MEMORY_LOG_LEVEL=DEBUG for verbose output when troubleshooting.

Worker Management

The Kiro Memory worker is a background HTTP server that handles:

• Database operations via REST API
• Web dashboard serving at the configured host and port
• Real-time event streaming (SSE) for the dashboard
• Vector embedding operations

Worker Commands

Command	Description
kiro-memory worker:start	Start the background worker
kiro-memory worker:stop	Stop the background worker
kiro-memory worker:restart	Restart the worker
kiro-memory worker:status	Check if the worker is running
kiro-memory worker:logs	View recent log output
kiro-memory worker:tail	Follow log output in real-time

Auto-Start Behavior

The worker starts automatically when:

• A coding session begins in a supported editor (via the agentSpawn hook)
• Any CLI command requires the worker API

The startup sequence:

1. Check if the worker is reachable at the configured host and port
2. If not, spawn worker-service.js as a background process
3. Wait up to 3 seconds for the worker to become available
4. Proceed with the operation (graceful degradation if the worker fails to start)

Custom Host and Port

To run the worker on a different address:

export KIRO_MEMORY_WORKER_HOST="0.0.0.0"  # Listen on all interfaces
export KIRO_MEMORY_WORKER_PORT="3002"      # Use port 3002
kiro-memory worker:restart

warning

Setting KIRO_MEMORY_WORKER_HOST to 0.0.0.0 exposes the dashboard on all network interfaces. Only do this in trusted network environments. The worker includes security measures (token auth, rate limiting, Helmet headers, CORS), but it is designed for local development use.

Project Detection

Kiro Memory automatically detects the current project based on your working directory. The project name is derived from the directory name of your repository root.

All observations, summaries, and knowledge are scoped to the detected project. When you switch between projects, Kiro Memory tracks each one independently.

Multi-Project Setup

If you work on multiple projects, each one gets its own namespace in the shared database. You can:

• View all projects from the web dashboard
• Filter CLI commands by project name
• Generate reports for individual projects
• Search across all projects or within a specific one

# Search within a specific project
kiro-memory search "auth" --project=my-app

# Report for a specific project
kiro-memory report --project=my-app --period=weekly

Security Configuration

The worker includes several security layers enabled by default:

Feature	Description
Token authentication	API requests require a valid auth token
Rate limiting	Protects against excessive API calls
Helmet	Sets secure HTTP headers
CORS	Restricts cross-origin requests to localhost

These protections are configured automatically and do not require manual setup. They ensure that even if the worker port is exposed, unauthorized access is mitigated.

Queue Management

Kiro Memory uses an internal queue for processing observations asynchronously. Queue commands are available for advanced troubleshooting:

kiro-memory queue              # View queue status
kiro-memory queue:process      # Force process pending items
kiro-memory queue:clear        # Clear the queue

info

Under normal operation, the queue processes automatically. These commands are only needed for debugging edge cases.