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

# Quick Start Guide

Get up and running with the KOGRAL in 5 minutes.

## Prerequisites

- Rust 1.70+ installed
- Nickel CLI installed (`cargo install nickel-lang-cli`)
- kb-cli installed (see Installation)

## Step 1: Initialize Your Knowledge Base

Navigate to your project directory and initialize:

    cd /path/to/your/project
    kb init

This creates a `.kogral/` directory with the following structure:

    .kogral/
    ├── config.toml       # Configuration
    ├── notes/            # General notes
    ├── decisions/        # Architectural decisions
    ├── guidelines/       # Project guidelines
    ├── patterns/         # Reusable patterns
    └── journal/          # Daily journal entries

## Step 2: Create Your First Note

Add a note to your knowledge base:

    kb add note "Getting Started with Rust" \
      --tags rust,programming,learning \
      --content "Key concepts for learning Rust effectively."

Or create interactively:

    kb add note
    # Follow the prompts to enter title, tags, and content

## Step 3: Create a Decision Record

Document an architectural decision:

    kb add decision "Use SurrealDB for Storage" \
      --context "Need scalable storage for knowledge graph" \
      --decision "Adopt SurrealDB for its graph capabilities" \
      --consequence "Better query performance" \
      --consequence "Additional infrastructure dependency"

## Step 4: Link Nodes Together

Create relationships between nodes:

    # Find node IDs
    kb list

    # Create a relationship
    kb link <note-id> <decision-id> relates_to

Available relationship types:

- `relates_to` - General conceptual link
- `depends_on` - Dependency relationship
- `implements` - Implementation of a concept
- `extends` - Inheritance/extension
- `supersedes` - Replaces older version
- `explains` - Documentation/clarification

## Step 5: Search Your Knowledge Base

Search by text:

    # Simple search
    kb search "rust"

    # Filter by type
    kb search "architecture" --type decision

    # Limit results
    kb search "error handling" --limit 5

Search semantically (requires embeddings):

    # Semantic search finds conceptually related content
    kb search "memory safety" --semantic --threshold 0.7

## Step 6: View Node Details

    # Show node by ID
    kb show <node-id>

    # Show node with relationships
    kb show <node-id> --with-relationships

## Step 7: Edit Documents Directly

All knowledge base documents are markdown files you can edit:

    # Open in your editor
    $EDITOR .kogral/notes/getting-started-with-rust.md

    # Or use your favorite markdown editor
    code .kogral/notes/

Document format:

    ---
    id: unique-id
    type: note
    title: Getting Started with Rust
    created: 2026-01-17T10:30:00Z
    modified: 2026-01-17T10:30:00Z
    tags: [rust, programming, learning]
    status: active
    ---

    # Getting Started with Rust

    Content goes here with [[wikilinks]] to other nodes.

    ## Key Concepts

    - Ownership
    - Borrowing
    - Lifetimes

## Step 8: Create a Daily Journal Entry

Start journaling your development progress:

    kb add journal "Today's Progress" \
      --content "Learned about trait objects and dynamic dispatch in Rust."

Or open today's journal directly:

    $EDITOR .kogral/journal/$(date +%Y-%m-%d).md

## Step 9: Export to Logseq (Optional)

If you use Logseq, export your knowledge base:

    nu scripts/kb-export-logseq.nu /path/to/logseq-graph

This creates a Logseq-compatible graph you can open in Logseq for visual editing.

## Step 10: Start MCP Server for Claude Code

Integrate with Claude Code for AI-assisted knowledge management:

    # Start MCP server
    kb serve

    # Configure in ~/.config/claude/config.json
    # Then use in Claude Code:
    # > kb/search "rust ownership"

## Common Workflows

### Capture Quick Notes

    # Quick note
    kb add note "Remember to check error handling in parser module" --tags todo,parser

### Document Architectural Decisions

    # Create ADR
    kb add decision "Adopt Async Rust for I/O Operations" \
      --status accepted \
      --tags architecture,async

### Build a Pattern Library

    # Add a pattern
    kb add pattern "Error Handling with thiserror" \
      --tags rust,error-handling \
      --content "Standard pattern for error types in this project."

### Track Daily Progress

    # Add journal entry
    kb add journal --content "Implemented search functionality. Need to add semantic search next."

## Next Steps

### Customize Configuration

Edit `.kogral/config.ncl` for advanced configuration:

    {
      graph = {
        name = "My Project",
        version = "1.0.0",
      },

      embeddings = {
        enabled = true,
        provider = 'fastembed,
      },

      templates = {
        templates_dir = "templates",
      },
    }

See Configuration Reference for all options.

### Set Up Shared Guidelines

Create a shared knowledge base for organization-wide standards:

    # Create shared KB
    mkdir -p ~/Tools/.kogral-shared
    cd ~/Tools/.kogral-shared
    kb init --name "Shared Guidelines"

    # Add guidelines
    kb add guideline "Rust Error Handling" \
      --language rust \
      --category error-handling

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

### Automate with NuShell Scripts

    # Backup regularly
    nu scripts/kb-backup.nu --compress

    # Sync with SurrealDB
    nu scripts/kb-sync.nu --direction bidirectional

    # Generate statistics
    nu scripts/kb-stats.nu --show-tags

### Integrate with Git

    # Add to version control
    git add .kogral/
    git commit -m "docs: Add knowledge base"

    # Add to .gitignore (optional: exclude certain types)
    echo ".kogral/journal/" >> .gitignore

## Tips and Tricks

### Use Wikilinks

Link to other nodes naturally in markdown:

    See [[getting-started-with-rust]] for basics.
    Related decision: [[use-surrealdb-for-storage]].

### Reference Code

Link to specific code locations:

    Error handling implementation: @src/parser.rs:42

### Tag Consistently

Use consistent tagging for better searchability:

    # Good tagging
    --tags rust,error-handling,pattern

    # Avoid
    --tags Rust,ErrorHandling,patterns

### Leverage Templates

Customize templates for your workflow:

    # Copy template
    cp templates/note.md.tera templates/meeting-notes.md.tera

    # Edit for meeting notes format
    $EDITOR templates/meeting-notes.md.tera

## Troubleshooting

### "KB directory not found"

    # Make sure you initialized
    kb init

    # Or specify KB directory
    kb --kb-dir /path/to/.kb search "query"

### "Node not found"

    # List all nodes to find ID
    kb list

    # Search for node
    kb search "partial title"

### "Failed to parse frontmatter"

Check your markdown file has valid YAML frontmatter:

    ---
    id: my-note
    type: note
    title: My Note
    ---

## Further Reading

- Configuration Reference - Full configuration options
- CLI Commands - All available commands
- Document Format - Markdown and frontmatter details
- MCP Tools - Claude Code integration

## Getting Help

- Check `kb --help` for command usage
- Read inline help: `kb add --help`
- Report issues on GitHub
- Join community discussions

Congratulations! You've created your first knowledge base. Start capturing knowledge and building connections.