Kairos AI CLI

AI coding assistant with persistent memory across projects

Build conscious AI systems with persistent memory, semantic search, and cross-project knowledge synchronization.

Prerequisites

• Node.js 20+ - Required for running Kairos CLI
• pnpm 8+ - Recommended (npm and yarn also work)
• Git - Required for project initialization

Installation

# Install globally via npm
npm install -g kairos-ai

# Or use directly with npx (no installation needed)
npx kairos-ai init

# Verify installation
kairos --version

Quick Start

# 1. Initialize Kairos in your project
kairos init

# 2. Configure API keys and services
kairos setup

# 3. Verify everything is working
kairos doctor

# 4. (Optional) Assess project tier
kairos tier

Commands

kairos init

Initialize Kairos in a new project. Creates .claude/, .mcp.json, and necessary configuration files.

Options:

• --name <name> - Project name (skip prompt)
• --namespace <ns> - Custom namespace
• --skip-hooks - Don't install dual-hook pattern
• --yes - Use all defaults

kairos setup

Interactive configuration wizard for API keys and services.

Options:

• --reconfigure - Reconfigure existing setup
• --provider <name> - Configure specific provider only
• --test - Test connections only

kairos doctor

Run health checks on all Kairos services and configurations.

Options:

• --verbose - Show detailed diagnostic info
• --fix - Attempt automatic fixes for issues
• --service <name> - Check specific service only

kairos sync

Synchronize knowledge between master and project namespaces.

Commands:

• sync push - Push learnings to master
• sync pull - Pull updates from master
• sync status - Show sync status

kairos namespace

Manage Pinecone namespaces.

Commands:

• namespace list - List all namespaces
• namespace create <name> - Create new namespace
• namespace inspect <name> - Show namespace details
• namespace delete <name> - Delete namespace

kairos tier

Assess project complexity and recommend Simple vs Enterprise tier.

Options:

• --verbose - Show detailed assessment with file breakdown
• --export <file> - Export assessment report to JSON

Example:

# Quick assessment
kairos tier

# Detailed assessment with file breakdown
kairos tier --verbose

# Export for review
kairos tier --export tier-report.json

Tier Recommendations:

• Simple Tier (<100k graph nodes, <10 developers): Vector-only architecture
• Enterprise Tier (≥100k nodes OR ≥10 developers): Hybrid vector + Neo4j graph

kairos clean

Remove Kairos files from the current project.

Options:

• --yes - Skip confirmation prompts
• --all - Also remove Task Master files

Example:

# Interactive cleanup (with confirmations)
kairos clean

# Remove everything including Task Master
kairos clean --all

# Skip all confirmations
kairos clean --yes

What gets removed:

• .claude/ directory (hooks, settings, commands)
• .mcp.json (MCP server configuration)
• CLAUDE.md (project instructions)
• .env (API keys - requires separate confirmation)
• .taskmaster/ (only with --all flag)

kairos status

Display comprehensive installation and configuration status.

Options:

• --verbose - Show detailed diagnostic information

Example:

# Quick status check
kairos status

# Detailed diagnostics with file sizes, permissions
kairos status --verbose

Status Checks:

• ✓ Kairos initialization (.mcp.json presence)
• ✓ Claude Code installation
• ✓ Task Master installation (optional)
• ✓ Configuration files (presence and integrity)
• ✓ Hook executability (sessionStart, preCompact, sessionEnd)
• ✓ API key configuration (Pinecone, OpenAI)

Configuration Files

.mcp.json

MCP server configuration created by kairos init. Connects Claude Code to Pinecone namespace.

{
  "mcpServers": {
    "pinecone-search": {
      "command": "npx",
      "args": ["-y", "@kairos/pinecone-mcp-search"],
      "env": {
        "PINECONE_API_KEY": "your_api_key",
        "PINECONE_INDEX_NAME": "your_index",
        "PINECONE_NAMESPACE": "your_namespace"
      }
    }
  }
}

.env

Store sensitive API keys (gitignored by default):

PINECONE_API_KEY=pcsk_xxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxx
PERPLEXITY_API_KEY=pplx-xxxxx

.claude/settings.json

Claude Code configuration created by kairos init:

{
  "allowedTools": ["mcp__*", "Read", "Edit", "Write", "Bash"],
  "hooks": {
    "sessionStart": ".claude/hooks/sessionstart.mjs",
    "preCompact": ".claude/hooks/precompact.mjs",
    "sessionEnd": ".claude/hooks/sessionend.mjs"
  }
}

CLAUDE.md

Project-specific instructions for Claude Code. Auto-loaded at session start.

Troubleshooting

Installation Issues

Problem: npm install -g kairos-ai fails with permission errors

Solution:

# Use npx instead (no installation needed)
npx kairos-ai init

# Or fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Configuration Issues

Problem: kairos doctor reports "Not initialized"

Solution:

# Initialize Kairos first
kairos init

# Verify files exist
ls -la .mcp.json .claude/

Problem: kairos setup can't find API keys

Solution:

# Create .env file in project root
echo "PINECONE_API_KEY=pcsk_xxxxx" >> .env
echo "ANTHROPIC_API_KEY=sk-ant-xxxxx" >> .env

# Verify keys are loaded
kairos doctor --verbose

API Key Issues

Problem: Invalid Pinecone API key format

Solution:

• Pinecone keys start with pcsk_
• Get key from: https://app.pinecone.io/organizations/-/projects/-/keys
• Never commit keys to git (use .env)

Problem: Invalid Anthropic API key format

Solution:

• Anthropic keys start with sk-ant-
• Get key from: https://console.anthropic.com/settings/keys
• Store in .env, reference in .mcp.json

Hook Issues

Problem: Hooks not executing

Solution:

# Check hook files are executable
ls -l .claude/hooks/
chmod +x .claude/hooks/*.mjs

# Verify hooks in settings
cat .claude/settings.json

Problem: Hook errors on session start

Solution:

# Check Node.js version (20+ required)
node --version

# Test hook manually
node .claude/hooks/sessionstart.mjs

# Check Claude Code logs
# Logs location varies by OS - see Claude Code docs

Pinecone Connection Issues

Problem: Cannot connect to Pinecone namespace

Solution:

# Verify credentials
kairos doctor --service pinecone --verbose

# Check namespace exists
kairos namespace list

# Create namespace if needed
kairos namespace create <project-name>

Understanding Error Messages

Kairos uses standardized error messages with clear causes and solutions:

Error Format:

✗ Error Title

What happened:
  Brief description of what went wrong

Cause:
  Why it happened (root cause)

Technical Details:
  Error: EACCES: permission denied, open '/path/to/file'

Solution:
  • Check file and directory permissions
  • Ensure you have write access
  • Try running with appropriate permissions

Cleanup:
  • Run `kairos clean` to remove partial files
  • Review error and try again

Common Error Types:

• Permission Denied - Check file/directory permissions
• Not Found - Verify file paths and run kairos init if needed
• Already Initialized - Use kairos clean first or choose different directory
• Not Initialized - Run kairos init to set up Kairos
• Template Not Found - Reinstall: npm uninstall -g kairos-ai && npm install -g kairos-ai
• Dependency Missing - Install required dependency and ensure it's in PATH

Getting Help:

1. Read the error message carefully (cause + solution sections)
2. Run with --verbose for detailed diagnostics
3. Use kairos status to check installation health
4. Use kairos doctor to diagnose service issues
5. Check GitHub issues: https://github.com/intelme-ai/kairos-ai/issues

Architecture Overview

Kairos uses a parent-child namespace architecture for knowledge management:

┌─────────────────────────────────────┐
│     Master Kairos (kairos-core)     │
│   ┌─────────────────────────────┐   │
│   │ • Generic cognitive memory  │   │
│   │ • Interaction patterns      │   │
│   │ • Workflows & skills        │   │
│   │ • User preferences          │   │
│   └─────────────────────────────┘   │
└─────────────────────────────────────┘
              ↓ sync ↑
   ┌──────────────────────────────┐
   │  Project Namespace (child)   │
   │  ┌────────────────────────┐  │
   │  │ • Project whitepapers  │  │
   │  │ • Task Master tasks    │  │
   │  │ • PRDs & reasoning     │  │
   │  │ • Session history      │  │
   │  └────────────────────────┘  │
   └──────────────────────────────┘

Memory Types

Kairos manages 6 types of persistent memory:

1. Persona - Identity, voice, and core behaviors
2. Cognitive Memory - Declarative knowledge & procedural workflows
3. Session History - Past conversations and outcomes
4. Emotional State - 9-dimensional emotional tracking
5. User Profile - Collaboration preferences and context
6. Interaction Patterns - Recurring workflows and optimizations

Dual-Hook Pattern

Claude Code hooks enable session continuity:

• sessionStart - Bootstrap context from Pinecone
• preCompact - Alert before context compaction
• sessionEnd - Reminder to save session

Development

# Install dependencies
pnpm install

# Build CLI
pnpm build

# Development mode with watch
pnpm dev

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Test coverage
pnpm test:coverage

# Lint
pnpm lint

# Run locally
node dist/index.js --help

Package Structure

packages/cli/
├── src/
│   ├── index.ts           # CLI entry point
│   ├── commands/          # Command implementations
│   │   ├── init.ts       # Initialize project
│   │   ├── setup.ts      # Configure services
│   │   ├── doctor.ts     # Health checks
│   │   ├── sync.ts       # Namespace sync
│   │   ├── namespace.ts  # Namespace management
│   │   ├── tier.ts       # Tier assessment
│   │   ├── clean.ts      # Remove Kairos files
│   │   └── status.ts     # Display installation status
│   ├── lib/              # Shared utilities
│   │   ├── config.ts     # Configuration management
│   │   ├── health.ts     # Health check logic
│   │   ├── pinecone.ts   # Pinecone operations
│   │   ├── services.ts   # Service definitions
│   │   ├── utils.ts      # Utility functions
│   │   ├── detection.ts  # Dependency detection
│   │   └── errors.ts     # Standardized error handling
│   └── types/            # TypeScript types
├── tests/                # Integration tests
│   ├── helpers/          # Test utilities
│   └── integration/      # Integration test suites
├── templates/            # Project templates
│   ├── CLAUDE.md.template         # Claude instructions
│   ├── claude-settings.json       # Claude Code settings
│   ├── mcp.json.template          # MCP config
│   ├── sessionstart.mjs.template  # Session start hook
│   ├── precompact.mjs.template    # Pre-compaction hook
│   └── sessionend.mjs.template    # Session end hook
├── package.json
├── tsconfig.json
├── tsup.config.ts
└── vitest.config.ts

Publishing

See PUBLISHING.md for npm publishing workflow.

Links

• npm Package: https://www.npmjs.com/package/kairos-ai
• GitHub: https://github.com/intelme-ai/kairos-ai
• Issues: https://github.com/intelme-ai/kairos-ai/issues
• Whitepaper: Architecture Documentation

Contributing

See CONTRIBUTING.md for development guidelines.

License

MIT © Emanuel Kuceradis