kogral/docs/guides/installation.md

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/kogral-cli

# Verify installation
kogral --version

Method 2: Build Specific Crates

# 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

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

# 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 .kogral directory
kogral init

# Or initialize with custom name
kogral 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 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:

# 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

# Check version
kogral --version

# Show help
kogral --help

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

Test MCP Server

# 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

# 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

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

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

Initialize Schema

# 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

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

# 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 kogral-mcp with Claude Code:

1. Build MCP Server

cargo build --package kogral-mcp --release

2. Configure Claude Code

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

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

3. Test Connection

Start Claude Code and verify:

> kogral/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"}' | kogral serve

# Check logs
kogral 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 kogral-cli

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

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