## 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

# 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

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<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:

1. Text → Embedding (384 or 1536 dimensional vector)
2. Similarity search (cosine distance)
3. 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:

- ADR-004: Logseq Blocks Support
- Logseq Blocks Design
- MCP Block Tools

## Key Principles

1. Capture During Work: Don't wait, document as you go
2. Link as You Learn: Connect related concepts immediately
3. Query When Needed: AI-assisted discovery of relevant knowledge
4. Evolve Over Time: Update decisions, supersede patterns
5. Share Wisely: Shared guidelines, local specifics

## Next Steps

- Understand motivation: Why KOGRAL?
- Learn philosophy: Design Philosophy
- See architecture: System Overview
- Start using: Quick Start