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

Node Types and Relationships

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

KB 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 for errors" Project override: "Use Result + 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]
kb-mcp Server
    ↓ [Rust API]
kb-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 block table 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

Keyboard shortcuts

KOGRAL Documentation