384 lines
7.4 KiB
Markdown
384 lines
7.4 KiB
Markdown
# 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](../installation.md))
|
|
|
|
## Step 1: Initialize Your Knowledge Base
|
|
|
|
Navigate to your project directory and initialize:
|
|
|
|
```bash
|
|
cd /path/to/your/project
|
|
kogral init
|
|
```
|
|
|
|
This creates a `.kogral/` directory with the following structure:
|
|
|
|
```text
|
|
.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:
|
|
|
|
```bash
|
|
kogral add note "Getting Started with Rust" \
|
|
--tags rust,programming,learning \
|
|
--content "Key concepts for learning Rust effectively."
|
|
```
|
|
|
|
Or create interactively:
|
|
|
|
```bash
|
|
kogral add note
|
|
# Follow the prompts to enter title, tags, and content
|
|
```
|
|
|
|
## Step 3: Create a Decision Record
|
|
|
|
Document an architectural decision:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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):
|
|
|
|
```bash
|
|
# Semantic search finds conceptually related content
|
|
kogral search "memory safety" --semantic --threshold 0.7
|
|
```
|
|
|
|
## Step 6: View Node Details
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# Open in your editor
|
|
$EDITOR .kogral/notes/getting-started-with-rust.md
|
|
|
|
# Or use your favorite markdown editor
|
|
code .kogral/notes/
|
|
```
|
|
|
|
Document format:
|
|
|
|
```markdown
|
|
---
|
|
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:
|
|
|
|
```bash
|
|
kogral add journal "Today's Progress" \
|
|
--content "Learned about trait objects and dynamic dispatch in Rust."
|
|
```
|
|
|
|
Or open today's journal directly:
|
|
|
|
```bash
|
|
$EDITOR .kogral/journal/$(date +%Y-%m-%d).md
|
|
```
|
|
|
|
## Step 9: Export to Logseq (Optional)
|
|
|
|
If you use Logseq, export your knowledge base:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# Quick note
|
|
kogral add note "Remember to check error handling in parser module" --tags todo,parser
|
|
```
|
|
|
|
### Document Architectural Decisions
|
|
|
|
```bash
|
|
# Create ADR
|
|
kogral add decision "Adopt Async Rust for I/O Operations" \
|
|
--status accepted \
|
|
--tags architecture,async
|
|
```
|
|
|
|
### Build a Pattern Library
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```nickel
|
|
{
|
|
graph = {
|
|
name = "My Project",
|
|
version = "1.0.0",
|
|
},
|
|
|
|
embeddings = {
|
|
enabled = true,
|
|
provider = 'fastembed,
|
|
},
|
|
|
|
templates = {
|
|
templates_dir = "templates",
|
|
},
|
|
}
|
|
```
|
|
|
|
See [Configuration Reference](configuration.md) for all options.
|
|
|
|
### Set Up Shared Guidelines
|
|
|
|
Create a shared knowledge base for organization-wide standards:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```markdown
|
|
See [[getting-started-with-rust]] for basics.
|
|
Related decision: [[use-surrealdb-for-storage]].
|
|
```
|
|
|
|
### Reference Code
|
|
|
|
Link to specific code locations:
|
|
|
|
```markdown
|
|
Error handling implementation: @src/parser.rs:42
|
|
```
|
|
|
|
### Tag Consistently
|
|
|
|
Use consistent tagging for better searchability:
|
|
|
|
```bash
|
|
# Good tagging
|
|
--tags rust,error-handling,pattern
|
|
|
|
# Avoid
|
|
--tags Rust,ErrorHandling,patterns
|
|
```
|
|
|
|
### Leverage Templates
|
|
|
|
Customize templates for your workflow:
|
|
|
|
```bash
|
|
# 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"
|
|
|
|
```bash
|
|
# Make sure you initialized
|
|
kogral init
|
|
|
|
# Or specify KB directory
|
|
kogral --kogral-dir /path/to/.kb search "query"
|
|
```
|
|
|
|
### "Node not found"
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
---
|
|
id: my-note
|
|
type: note
|
|
title: My Note
|
|
---
|
|
```
|
|
|
|
## Further Reading
|
|
|
|
- [Configuration Reference](configuration.md) - Full configuration options
|
|
- [CLI Commands](cli-commands.md) - All available commands
|
|
- [Document Format](document-format.md) - Markdown and frontmatter details
|
|
- [MCP Tools](../api/mcp-tools.md) - Claude Code integration
|
|
|
|
## 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.
|