13 KiB
Core Concepts
Understanding the fundamental concepts behind KOGRAL.
The Knowledge Graph
At its core, KOGRAL is a directed graph where:
- Nodes = pieces of knowledge (notes, decisions, guidelines, patterns)
- Edges = typed relationships between concepts
This graph structure enables:
- Discovery: Find related concepts through traversal
- Context: Understand how ideas connect
- Evolution: Track how knowledge changes over time
Node Types
1. Note
Purpose: Capture general observations, learnings, and discoveries.
When to use:
- Documenting a concept you learned
- Recording implementation details
- Capturing meeting notes
- Quick knowledge capture
Example:
---
type: note
title: Async Trait Patterns in Rust
tags: [rust, async, patterns]
---
# Async Trait Patterns in Rust
Using async traits with the async-trait crate...
2. Decision (ADR)
Purpose: Record architectural decisions with full context.
When to use:
- Choosing between alternatives (REST vs GraphQL)
- Major technical decisions (database selection)
- Trade-off analysis
- Explaining "why" for future reference
Structure:
- Context: Background and problem
- Decision: What was chosen
- Consequences: Positive and negative outcomes
- Alternatives: What was considered but rejected
Example:
---
type: decision
title: Use SurrealDB for Storage
status: accepted
---
## Context
Need a graph database that supports our relationship model...
## Decision
Adopt SurrealDB as the primary storage backend.
## Consequences
+ Better graph query performance
+ Native relationship support
- Additional infrastructure dependency
- Team learning curve
3. Guideline
Purpose: Define coding standards, best practices, and conventions.
When to use:
- Code style rules
- Architecture patterns to follow
- Security requirements
- Testing standards
Can be:
- Shared: Organization-wide (in shared KOGRAL)
- Project-specific: Overrides shared guidelines
Example:
---
type: guideline
language: rust
category: error-handling
---
# Rust Error Handling Guidelines
1. Use `thiserror` for custom error types
2. Never use `unwrap()` in production code
3. Always propagate errors with `?`
4. Pattern
Purpose: Document reusable solutions to common problems.
When to use:
- Recurring implementation patterns
- Tested solutions
- Best practice implementations
- Code templates
Structure:
- Problem: What challenge does this solve?
- Solution: The pattern/approach
- Context: When to use/not use
- Example: Working code
Example:
---
type: pattern
title: Repository Pattern for Database Access
tags: [architecture, database, pattern]
---
## Problem
Need consistent database access across modules.
## Solution
Repository pattern with trait abstraction...
## Example
\`\`\`rust
trait UserRepository {
async fn find_by_id(&self, id: Uuid) -> Result<User>;
}
\`\`\`
5. Journal
Purpose: Daily development log for tracking progress and reflections.
When to use:
- End of day summaries
- Daily standup notes
- Progress tracking
- Blocker documentation
Auto-linked: KOGRAL can auto-link journal entries to mentioned concepts.
Example:
---
type: journal
date: 2026-01-17
---
## Progress
- Implemented authentication module
- Fixed cache race condition
## Blockers
- Need API versioning discussion
## Learnings
- tokio::select! perfect for timeouts
6. Execution
Purpose: Record AI agent execution results (from Vapora integration).
When to use:
- Agent task completion
- Execution metrics
- Agent decision history
- Audit trail
Example:
---
type: execution
task_type: code_generation
agent: rust-expert
outcome: success
duration: 45s
---
Generated authentication module following project guidelines.
Relationship Types
1. relates_to
Meaning: General conceptual relationship.
Use: Connect related ideas without specific dependency.
Example:
[Note: Async Patterns] --relates_to--> [Note: Tokio Runtime]
2. depends_on
Meaning: Prerequisite relationship. Source requires target to exist/be understood first.
Use: Learning paths, implementation order.
Example:
[Pattern: Advanced Error Handling] --depends_on--> [Guideline: Basic Errors]
3. implements
Meaning: Concrete implementation of an abstract concept.
Use: Connect code to patterns/guidelines.
Example:
[Note: Auth Module Implementation] --implements--> [Pattern: Repository Pattern]
4. extends
Meaning: Inheritance/extension relationship.
Use: Guideline overrides, pattern variations.
Example:
[Guideline: Project Error Handling] --extends--> [Guideline: Shared Error Handling]
5. supersedes
Meaning: Replacement relationship. Source replaces target.
Use: Track evolution of decisions/patterns.
Example:
[Decision: Use GraphQL v2] --supersedes--> [Decision: Use REST]
6. explains
Meaning: Documentation/clarification relationship.
Use: Connect notes to implementations, executions to rationale.
Example:
[Note: Why We Chose Rust] --explains--> [Decision: Adopt Rust]
Multi-Graph Architecture
KOGRAL supports multiple knowledge graphs:
Local Graph (Project-Specific)
Location: .kogral/ in project directory
Purpose: Project-specific knowledge
- Project decisions
- Implementation notes
- Local patterns
- Daily journals
Storage: Filesystem (git-tracked)
Scope: Single project
Shared Graph (Organization-Wide)
Location: Configurable (e.g., ~/org/.kogral-shared)
Purpose: Shared organizational knowledge
- Coding guidelines
- Standard patterns
- Architecture principles
- Security policies
Storage: SurrealDB (centralized) or filesystem (synced)
Scope: All projects
Inheritance Model
Shared Guidelines (priority: 50)
↓ [inherited by]
Project Guidelines (priority: 100)
↓ [effective]
Combined Guidelines (higher priority wins)
Example:
Shared guideline: "Use Result<T> for errors" Project override: "Use Result<T> + log all errors with tracing" Effective: Both rules apply, project adds requirement
Config-Driven Behavior
Everything is configurable via Nickel schemas:
{
graph = { name = "my-project" }, # Graph metadata
storage = { primary = 'filesystem }, # Where to store
embeddings = { provider = 'fastembed }, # AI provider
templates = { /* ... */ }, # Document templates
query = { similarity_threshold = 0.6 }, # Search behavior
}
No hardcoding: Change behavior without code changes.
Semantic Search
Beyond keyword matching, KOGRAL uses embeddings to find concepts:
Keyword search: "Find 'error handling'"
- Matches exact phrase "error handling"
Semantic search: "How to handle failures gracefully?"
- Finds: error handling, exception patterns, Result types, panic recovery
- Understands: "failures" = errors, "gracefully" = best practices
How it works:
- Text → Embedding (384 or 1536 dimensional vector)
- Similarity search (cosine distance)
- Return nodes above threshold (e.g., 0.6)
Providers:
- fastembed: Local, free, offline (384d)
- OpenAI: Cloud, best quality (1536d)
- Claude: Cloud, excellent (1024d)
- Ollama: Self-hosted (768d)
Templates
Tera templates generate consistent documents:
---
id: {{ id }}
type: {{ type }}
title: {{ title }}
tags: [{% for tag in tags %}"{{ tag }}"{% endfor %}]
---
# {{ title }}
{{ content }}
Customizable: Override templates per project.
Export formats: Logseq, JSON, Markdown.
MCP Integration
Model Context Protocol connects KOGRAL to Claude Code:
Claude Code
↓ [JSON-RPC 2.0]
kogral-mcp Server
↓ [Rust API]
kogral-core Library
↓ [Storage]
Knowledge Graph
Tools: kogral/search, kogral/add_note, kogral/get_guidelines, etc.
Resources: kogral://project/notes, kogral://shared/guidelines
Prompts: kogral/summarize_project, kogral/find_related
Git-Friendly Storage
Markdown + YAML frontmatter = git-tracked knowledge:
---
id: note-123
type: note
title: My Note
---
# Content here
Benefits:
- ✅ Diffs in PRs (reviewable changes)
- ✅ Branches (experiment with knowledge)
- ✅ Merges (combine knowledge from feature branches)
- ✅ History (track evolution over time)
- ✅ Blame (who added this knowledge?)
Logseq Content Blocks
KOGRAL provides full support for Logseq-style outliner blocks with rich metadata and structure.
What are Blocks
Blocks are the fundamental unit of content in Logseq's outliner format:
- Each bullet point is a block
- Blocks can have children (nested blocks)
- Blocks support tasks, tags, and custom properties
- Blocks can reference other blocks or pages
Block Features
Task Status:
- TODO Implement authentication #high-priority
- DOING Write tests
- DONE Deploy to staging
- LATER Consider GraphQL API
- NOW Fix critical bug
- WAITING Code review from @alice
- CANCELLED Old approach
Inline Tags:
- Learning Rust ownership #rust #learning #card
- Prevents data races at compile time
- Borrowing rules enforce safety
Custom Properties:
- Research paper summary
priority:: high
reviewed:: 2026-01-17
source:: https://example.com/paper.pdf
- Key findings...
Block and Page References:
- Meeting notes from [[2026-01-17]]
- Discussed architecture ((block-ref-123))
- Action items: [[Project Roadmap]]
Hierarchical Structure:
- Parent block #top-level
- Child block 1
- Nested child
- Child block 2
Configuration
Blocks support is opt-in via configuration:
{
blocks = {
enabled = true, # Enable blocks parsing
parse_on_import = true, # Auto-parse from Logseq imports
serialize_on_export = true, # Serialize to outliner format
enable_mcp_tools = true, # Enable block-related MCP tools
},
}
Use Cases
1. Task Management:
- TODO Weekly sprint planning #meeting
- DONE Review last sprint
- DOING Plan current sprint
- TODO Assign tasks
2. Flashcards (Spaced Repetition):
- What is Rust's ownership model? #card #rust
- Ownership prevents data races at compile time
- Each value has a single owner
- When owner goes out of scope, value is dropped
3. Knowledge Capture with Metadata:
- Tokio async runtime patterns #rust #async
category:: architecture
difficulty:: intermediate
- Use tokio::select! for concurrent operations
- spawn_blocking() for CPU-intensive work
4. Linked Notes:
- Discussed [[ADR-001]] in architecture meeting
- Decided on SurrealDB
- See ((meeting-notes-block-id)) for details
Block Queries (MCP Tools)
Query blocks across your knowledge base:
Find blocks by tag:
{
"tool": "kogral/find_blocks",
"arguments": { "tag": "card" }
}
Find all TODOs:
{
"tool": "kogral/find_todos",
"arguments": { "limit": 20 }
}
Find flashcards:
{
"tool": "kogral/find_cards",
"arguments": { "limit": 10 }
}
Find blocks by property:
{
"tool": "kogral/find_blocks",
"arguments": {
"property_key": "priority",
"property_value": "high"
}
}
Architecture
Hybrid Model:
- Content stored as markdown string (source of truth)
- Blocks lazily parsed on first access
- Cached block structure for fast queries
- Bidirectional: markdown ↔ blocks
BlockParser:
- Parse outliner markdown → Block structures
- Serialize Block structures → outliner markdown
- Preserve all metadata (tags, status, properties, references)
- Round-trip fidelity for Logseq compatibility
Storage:
- Filesystem: markdown with blocks inline
- SurrealDB: dedicated
blocktable with indexes - Indexes: tags, status, parent_id, full-text search
See Also:
Key Principles
- Capture During Work: Don't wait, document as you go
- Link as You Learn: Connect related concepts immediately
- Query When Needed: AI-assisted discovery of relevant knowledge
- Evolve Over Time: Update decisions, supersede patterns
- Share Wisely: Shared guidelines, local specifics
Next Steps
- Understand motivation: Why KOGRAL?
- Learn philosophy: Design Philosophy
- See architecture: System Overview
- Start using: Quick Start