jesus/kogral

Fork 0

Jesús Pérez 22e9473e69

chore: add docs

2026-01-23 16:11:07 +00:00

7.4 KiB

Raw Blame History

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)
kogral-cli installed (see Installation)

Step 1: Initialize Your Knowledge Base

Navigate to your project directory and initialize:

cd /path/to/your/project
kogral 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:

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

Or create interactively:

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

Step 3: Create a Decision Record

Document an architectural decision:

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

# Create a relationship
kogral 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
kogral search "rust"

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

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

Search semantically (requires embeddings):

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

Step 6: View Node Details

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

# Show node with relationships
kogral 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:

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

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

Common Workflows

Capture Quick Notes

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

Document Architectural Decisions

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

Build a Pattern Library

# Add a pattern
kogral 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
kogral 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 KOGRAL
mkdir -p ~/Tools/.kogral-shared
cd ~/Tools/.kogral-shared
kogral init --name "Shared Guidelines"

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

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

Automate with NuShell Scripts

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

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

# Generate statistics
nu scripts/kogral-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
kogral init

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

"Node not found"

# List all nodes to find ID
kogral list

# Search for node
kogral search "partial title"

"Failed to parse frontmatter"

Check your markdown file has valid YAML frontmatter:

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

Getting Help

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

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

7.4 KiB Raw Blame History