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"

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

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

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.