## Keyboard shortcuts

Press `←` or `→` to navigate between chapters

Press `S` or `/` to search in the book

Press `?` to show this help

Press `Esc` to hide this help

# Installation

This guide covers installing and setting up the KOGRAL.

## Prerequisites

### Required

- Rust 1.70 or later

      curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

- Nickel CLI for configuration management

      cargo install nickel-lang-cli

### Optional

- NuShell for maintenance scripts

      cargo install nu

- SurrealDB for scalable storage backend

      # macOS
      brew install surrealdb/tap/surreal

      # Linux/Windows
      curl -sSf https://install.surrealdb.com | sh

## Installation Methods

### Method 1: Install from Source (Recommended)

    # Clone the repository
    git clone <repository-url> knowledge-base
    cd knowledge-base

    # Build the workspace
    cargo build --release

    # Install CLI tool
    cargo install --path crates/kb-cli

    # Verify installation
    kb --version

### Method 2: Build Specific Crates

    # Build only kb-core library
    cargo build --package kb-core --release

    # Build only kb-cli
    cargo build --package kb-cli --release

    # Build only kogral-mcp server
    cargo build --package kb-mcp --release

### Method 3: Build with Features

    # Build with all features (filesystem + SurrealDB + fastembed)
    cargo build --workspace --all-features --release

    # Build with specific features
    cargo build --package kb-core --features "surrealdb,fastembed" --release

## Feature Flags

kb-core supports optional features:

Feature | Description | Default
--- | --- | ---
`filesystem` | Filesystem storage backend | ✅ Yes
`surrealdb` | SurrealDB storage backend | ❌ No
`fastembed` | Local embedding generation | ❌ No
`full` | All features enabled | ❌ No

Example usage:

    # Enable SurrealDB backend
    cargo build --features surrealdb

    # Enable all features
    cargo build --features full

## Environment Setup

### 1. Initialize a Knowledge Base

    # Navigate to your project
    cd /path/to/your/project

    # Initialize .kb directory
    kb init

    # Or initialize with custom name
    kb init --name "My Project" --description "Project knowledge base"

This creates:

    your-project/
    └── .kogral/
        ├── config.toml
        ├── notes/
        ├── decisions/
        ├── guidelines/
        ├── patterns/
        └── journal/

### 2. Configure Nickel Schemas (Optional)

If you want advanced configuration:

    # Copy default config
    cp /path/to/knowledge-base/config/defaults.ncl .kogral/config.ncl

    # Edit configuration
    $EDITOR .kogral/config.ncl

    # Export to TOML (for kb-cli compatibility)
    nickel export --format json .kogral/config.ncl | kb config import

### 3. Set Up Shared Knowledge Base (Optional)

For shared guidelines and patterns across projects:

    # Create shared KB location
    mkdir -p ~/Tools/.kogral-shared
    cd ~/Tools/.kogral-shared

    # Initialize shared KB
    kb init --name "Shared Knowledge" --description "Cross-project guidelines"

    # Configure inheritance in project
    kb config set inheritance.base ~/Tools/.kogral-shared

## Verify Installation

### Test CLI

    # Check version
    kb --version

    # Show help
    kb --help

    # Test initialization (dry-run)
    kb init --dry-run

### Test MCP Server

    # Start MCP server in test mode
    kb serve --transport stdio

    # In another terminal, test with echo
    echo '{"jsonrpc":"2.0","id":1,"method":"kogral/search","params":{"query":"test"}}' | kb serve

### Run Tests

    # Run all tests
    cargo test --workspace

    # Run integration tests
    cargo test --package kb-core --test '*'

    # Run with all features
    cargo test --workspace --all-features

## SurrealDB Setup (Optional)

If using SurrealDB backend:

### Start SurrealDB Server

    # Start server
    surreal start --log trace --user root --pass root file://data.db

    # Or use memory backend for testing
    surreal start --log trace --user root --pass root memory

### Configure kb-core

Edit `.kogral/config.ncl`:

    {
      storage = {
        primary = 'filesystem,
        secondary = {
          enabled = true,
          type = 'surrealdb,
          url = "ws://localhost:8000",
          namespace = "kb",
          database = "default",
          username = "root",
          password = "root",
        },
      },
    }

### Initialize Schema

    # Run migration script
    nu scripts/kb-migrate.nu --target latest

    # Or manually import schema
    surreal import --conn ws://localhost:8000 --user root --pass root --ns kb --db default schema.surql

## Embedding Provider Setup (Optional)

### Local fastembed

    # Build with fastembed feature
    cargo build --package kb-core --features fastembed

    # Models will be downloaded on first use

### API Providers (OpenAI, Claude, Ollama)

Set environment variables:

    # OpenAI
    export OPENAI_API_KEY="sk-..."

    # Claude (Anthropic)
    export ANTHROPIC_API_KEY="sk-ant-..."

    # Ollama (local)
    export OLLAMA_API_BASE="http://localhost:11434"

Configure provider in `.kogral/config.ncl`:

    {
      embeddings = {
        enabled = true,
        provider = 'openai,  # or 'claude, 'ollama, 'fastembed
        model = "text-embedding-3-small",
        api_key_env = "OPENAI_API_KEY",
      },
    }

## Claude Code Integration

To use kb-mcp with Claude Code:

### 1. Build MCP Server

    cargo build --package kb-mcp --release

### 2. Configure Claude Code

Add to `~/.config/claude/config.json`:

    {
      "mcpServers": {
        "kogral-mcp": {
          "command": "/path/to/knowledge-base/target/release/kb-mcp",
          "args": ["serve"],
          "env": {}
        }
      }
    }

### 3. Test Connection

Start Claude Code and verify:

    > kb/search "test"

## Troubleshooting

### Nickel Not Found

    # Verify nickel is installed
    nickel --version

    # If not, install
    cargo install nickel-lang-cli

    # Add cargo bin to PATH
    export PATH="$HOME/.cargo/bin:$PATH"

### Compilation Errors

    # Update Rust
    rustup update stable

    # Clean and rebuild
    cargo clean
    cargo build --workspace

### SurrealDB Connection Failed

    # Check SurrealDB is running
    curl http://localhost:8000/health

    # Start SurrealDB with correct settings
    surreal start --bind 0.0.0.0:8000 --user root --pass root memory

### MCP Server Not Responding

    # Test stdio communication
    echo '{"jsonrpc":"2.0","id":1,"method":"ping"}' | kb serve

    # Check logs
    kb serve --log-level debug

## Next Steps

- Quick Start Guide - Create your first knowledge base
- Configuration Reference - Customize behavior
- MCP Tools - Integrate with Claude Code

## Uninstallation

    # Remove installed binary
    cargo uninstall kb-cli

    # Remove project knowledge base
    rm -rf /path/to/project/.kogral

    # Remove shared knowledge base
    rm -rf ~/Tools/.kogral-shared