kogral/docs/guides/installation.md

# Installation

This guide covers installing and setting up the KOGRAL.

## Prerequisites

### Required

- **Rust** 1.70 or later

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

- **Nickel** CLI for configuration management

  ```bash
  cargo install nickel-lang-cli
  ```

### Optional

- **NuShell** for maintenance scripts

  ```bash
  cargo install nu
  ```

- **SurrealDB** for scalable storage backend

  ```bash
  # macOS
  brew install surrealdb/tap/surreal

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

## Installation Methods

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

```bash
# 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/kogral-cli

# Verify installation
kogral --version
```

### Method 2: Build Specific Crates

```bash
# Build only kogral-core library
cargo build --package kogral-core --release

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

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

### Method 3: Build with Features

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

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

## Feature Flags

kogral-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:

```bash
# Enable SurrealDB backend
cargo build --features surrealdb

# Enable all features
cargo build --features full
```

## Environment Setup

### 1. Initialize a Knowledge Base

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

# Initialize .kogral directory
kogral init

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

This creates:

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

### 2. Configure Nickel Schemas (Optional)

If you want advanced configuration:

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

# Edit configuration
$EDITOR .kogral/config.ncl

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

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

For shared guidelines and patterns across projects:

```bash
# Create shared KOGRAL location
mkdir -p ~/Tools/.kogral-shared
cd ~/Tools/.kogral-shared

# Initialize shared KOGRAL
kogral init --name "Shared Knowledge" --description "Cross-project guidelines"

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

## Verify Installation

### Test CLI

```bash
# Check version
kogral --version

# Show help
kogral --help

# Test initialization (dry-run)
kogral init --dry-run
```

### Test MCP Server

```bash
# Start MCP server in test mode
kogral serve --transport stdio

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

### Run Tests

```bash
# Run all tests
cargo test --workspace

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

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

## SurrealDB Setup (Optional)

If using SurrealDB backend:

### Start SurrealDB Server

```bash
# 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 kogral-core

Edit `.kogral/config.ncl`:

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

### Initialize Schema

```bash
# Run migration script
nu scripts/kogral-migrate.nu --target latest

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

## Embedding Provider Setup (Optional)

### Local fastembed

```bash
# Build with fastembed feature
cargo build --package kogral-core --features fastembed

# Models will be downloaded on first use
```

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

Set environment variables:

```bash
# 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`:

```nickel
{
  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 kogral-mcp with Claude Code:

### 1. Build MCP Server

```bash
cargo build --package kogral-mcp --release
```

### 2. Configure Claude Code

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

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

### 3. Test Connection

Start Claude Code and verify:

```text
> kogral/search "test"
```

## Troubleshooting

### Nickel Not Found

```bash
# 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

```bash
# Update Rust
rustup update stable

# Clean and rebuild
cargo clean
cargo build --workspace
```

### SurrealDB Connection Failed

```bash
# 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

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

# Check logs
kogral serve --log-level debug
```

## Next Steps

- [Quick Start Guide](user-guide/quickstart.md) - Create your first knowledge base
- [Configuration Reference](user-guide/configuration.md) - Customize behavior
- [MCP Tools](api/mcp-tools.md) - Integrate with Claude Code

## Uninstallation

```bash
# Remove installed binary
cargo uninstall kogral-cli

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

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