Skip to main content

Contributing

Thank you for your interest in contributing to Kiro Memory. This guide covers development setup, testing, code standards, and common troubleshooting scenarios.

Before You Start​

  1. Open an issue first -- Discuss your planned change before writing code. This prevents duplicated effort and ensures alignment with the project direction.
  2. One change per PR -- Keep pull requests focused on a single concern for easier review.

Development Setup​

Prerequisites​

  • Node.js >= 18.0.0
  • npm (bundled with Node.js)
  • Build tools (Linux/WSL): sudo apt-get install -y build-essential python3

Clone and Build​

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

Development Workflow​

The dev command builds and syncs in one step:

npm run dev

After building, link the local version for testing:

npm run install:kiro

This installs the locally built version as the global kiro-memory command.

Worker Management During Development​

npm run worker:start    # Start the worker manually
npm run worker:stop     # Stop the worker
npm run worker:logs     # View worker logs
npm run worker:tail     # Follow logs in real-time

Project Structure​

kiro-memory/
├── src/
│   ├── cli/                  # CLI command definitions
│   │   └── contextkit.ts     # All CLI commands and handlers
│   ├── hooks/                # Editor hook implementations
│   │   ├── agentSpawn.ts     # Session start context injection
│   │   ├── postToolUse.ts    # Tool execution capture
│   │   ├── userPromptSubmit.ts  # Prompt storage
│   │   ├── stop.ts           # Session end summary/checkpoint
│   │   ├── hook-definitions.ts  # Hook registry
│   │   ├── kiro-hooks.ts     # Kiro CLI hook system
│   │   └── utils.ts          # Hook utilities
│   ├── sdk/
│   │   └── index.ts          # TypeScript SDK (KiroMemorySDK class)
│   ├── servers/
│   │   └── mcp-server.ts     # MCP tool definitions and handlers
│   ├── services/
│   │   ├── search/           # Search subsystem
│   │   │   ├── EmbeddingService.ts   # Local embedding generation
│   │   │   ├── VectorSearch.ts       # Vector similarity search
│   │   │   ├── HybridSearch.ts       # Combined vector + FTS5
│   │   │   ├── ScoringEngine.ts      # 4-signal ranking
│   │   │   └── ChromaManager.ts      # Chroma integration
│   │   ├── sqlite/            # Database layer
│   │   │   ├── Database.ts           # Core DB connection/migrations
│   │   │   ├── Observations.ts       # Observation CRUD
│   │   │   ├── Summaries.ts          # Summary CRUD
│   │   │   ├── Sessions.ts           # Session management
│   │   │   ├── Checkpoints.ts        # Checkpoint CRUD
│   │   │   ├── Search.ts             # FTS5 search queries
│   │   │   ├── Analytics.ts          # Analytics queries
│   │   │   ├── Prompts.ts            # Prompt storage
│   │   │   └── Reports.ts            # Report generation
│   │   ├── worker-service.ts  # Express HTTP server
│   │   └── report-formatter.ts  # Report output formatting
│   ├── types/
│   │   └── worker-types.ts    # Shared TypeScript types
│   ├── ui/
│   │   ├── viewer.html        # Dashboard entry point
│   │   └── viewer/            # React dashboard app
│   │       ├── App.tsx
│   │       ├── components/    # Feed, Analytics, Search, etc.
│   │       ├── hooks/         # React hooks (SSE, theme, settings)
│   │       └── utils/         # Formatting and data utilities
│   ├── utils/
│   │   └── logger.ts          # Logging utility
│   ├── shared/
│   │   └── paths.ts           # Path resolution
│   └── index.ts               # Package entry point
├── tests/
│   └── sqlite/                # Database layer tests
│       ├── database.test.ts
│       ├── observations.test.ts
│       └── sdk.test.ts
├── scripts/
│   ├── build-plugin.js        # Build script
│   ├── install-kiro.sh        # Installation script
│   └── sync-kiro.cjs          # Sync script
├── kiro-agent/                # Kiro CLI agent configuration
│   ├── contextkit.json
│   └── steering.md
├── package.json
├── CONTRIBUTING.md
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── LICENSE

Testing​

Run All Tests​

npm test

Run Specific Test Suites​

npm run test:sqlite    # Database layer tests
npm run test:search    # Search functionality
npm run test:context   # Context operations
npm run test:server    # Server endpoint tests
npm run test:agents    # Agent integration tests
npm run test:infra     # Infrastructure tests

Writing Tests​

  • Place test files in the tests/ directory, mirroring the source structure
  • Use descriptive test names that explain the expected behavior
  • Test both success and error cases
  • Keep tests isolated -- each test should clean up after itself

Code Standards​

TypeScript​

  • Strict mode is enforced -- no any types allowed
  • Write pure functions for calculation and logic
  • Keep side effects (I/O, database, network) at system boundaries
  • Prefer clear naming over explanatory comments

Style Guidelines​

  • Use descriptive variable and function names
  • Avoid premature abstraction -- simple duplication is preferable to unnecessary helpers
  • Keep functions small and focused
  • Handle errors explicitly; do not swallow exceptions

Commit Messages​

Follow 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

Format: type(scope): description

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

Pull Request Process​

  1. Fork the repository and create a branch from main
  2. Write tests for any new features or bug fixes
  3. Verify that npm test and npm run build both pass
  4. Submit your PR with:
    • A clear title following conventional commit format
    • 1--3 bullet summary of what changed and why
    • Test plan describing how the changes were verified

PR Review​

  • PRs require at least one approval before merging
  • CI must pass (tests + build)
  • Maintainers may request changes or ask clarifying questions

Troubleshooting​

Invalid ELF Header (WSL)​

Error: invalid ELF header

Cause: You are running the Windows-installed Node.js inside WSL. Native modules compiled for Windows cannot run on Linux.

Fix: Install Node.js natively inside WSL using nvm:

# Inside 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

npm Prefix Issue (Windows/WSL)​

npm ERR! Error: EACCES: permission denied

Cause: npm is trying to install to a Windows directory from WSL.

Fix: Configure npm to use a Linux-native prefix:

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

# Add to ~/.bashrc or ~/.zshrc:
export PATH="$HOME/.npm-global/bin:$PATH"
source ~/.bashrc
npm install -g kiro-memory

Missing Build Tools (Linux/WSL)​

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

Cause: Native modules (better-sqlite3) require C++ build tools and Python.

Fix:

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

Port Conflicts​

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

Cause: Port 3001 is already in use by another process.

Fix:

# Find what is using port 3001
lsof -i :3001

# Option 1: Kill the conflicting process
kill -9 <PID>

# Option 2: Use a different port
export KIRO_MEMORY_WORKER_PORT=3002
kiro-memory worker:restart

Agent/Hook Configuration Not Found​

Error: agent configuration not found

Cause: The installation step was not run or did not complete.

Fix:

kiro-memory install              # Auto-detect editor
# or
kiro-memory install --claude-code  # Specific editor

Database Locked​

Error: SQLITE_BUSY: database is locked

Cause: Multiple processes are trying to write to the database simultaneously.

Fix:

# Stop the worker
kiro-memory worker:stop

# Wait a moment, then restart
kiro-memory worker:start

Running Diagnostics​

The doctor command checks your entire environment:

kiro-memory doctor

This validates:

  • Node.js version compatibility
  • Global package installation
  • Editor hook/rules configuration
  • MCP server registration
  • Worker availability
  • Database accessibility
  • Embedding service status

Example output:

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)
tip

When reporting issues, include the full output of kiro-memory doctor and any relevant log files from ~/.kiro-memory/logs/.

Reporting Issues​

When filing a bug report, include:

  1. Actual behavior -- What happened
  2. Expected behavior -- What should have happened
  3. Reproduction steps -- Minimal steps to reproduce
  4. Environment -- OS, Node.js version, editor, kiro-memory doctor output
  5. Logs -- Relevant entries from ~/.kiro-memory/logs/
Security Vulnerabilities

Do not report security vulnerabilities through public GitHub issues. Follow the disclosure process described in SECURITY.md.

License​

By contributing to Kiro Memory, you agree that your contributions will be licensed under the AGPL-3.0 License.