# 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](../diagrams/core-concepts.svg)

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

```yaml
---
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**:

```yaml
---
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**:

```yaml
---
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**:

```yaml
---
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**:

```yaml
---
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**:

```yaml
---
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**:

```text
[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**:

```text
[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**:

```text
[Note: Auth Module Implementation] --implements--> [Pattern: Repository Pattern]
```

### 4. `extends`

**Meaning**: Inheritance/extension relationship.

**Use**: Guideline overrides, pattern variations.

**Example**:

```text
[Guideline: Project Error Handling] --extends--> [Guideline: Shared Error Handling]
```

### 5. `supersedes`

**Meaning**: Replacement relationship. Source replaces target.

**Use**: Track evolution of decisions/patterns.

**Example**:

```text
[Decision: Use GraphQL v2] --supersedes--> [Decision: Use REST]
```

### 6. `explains`

**Meaning**: Documentation/clarification relationship.

**Use**: Connect notes to implementations, executions to rationale.

**Example**:

```text
[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

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

```nickel
{
  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:

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

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

```markdown
---
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**:

```markdown
- 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**:

```markdown
- Learning Rust ownership #rust #learning #card
  - Prevents data races at compile time
  - Borrowing rules enforce safety
```

**Custom Properties**:

```markdown
- Research paper summary
  priority:: high
  reviewed:: 2026-01-17
  source:: https://example.com/paper.pdf
  - Key findings...
```

**Block and Page References**:

```markdown
- Meeting notes from [[2026-01-17]]
  - Discussed architecture ((block-ref-123))
  - Action items: [[Project Roadmap]]
```

**Hierarchical Structure**:

```markdown
- Parent block #top-level
  - Child block 1
    - Nested child
  - Child block 2
```

### Configuration

Blocks support is opt-in via configuration:

```nickel
{
  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**:

```markdown
- TODO Weekly sprint planning #meeting
  - DONE Review last sprint
  - DOING Plan current sprint
  - TODO Assign tasks
```

**2. Flashcards (Spaced Repetition)**:

```markdown
- 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**:

```markdown
- 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**:

```markdown
- 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**:

```json
{
  "tool": "kogral/find_blocks",
  "arguments": { "tag": "card" }
}
```

**Find all TODOs**:

```json
{
  "tool": "kogral/find_todos",
  "arguments": { "limit": 20 }
}
```

**Find flashcards**:

```json
{
  "tool": "kogral/find_cards",
  "arguments": { "limit": 10 }
}
```

**Find blocks by property**:

```json
{
  "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](../architecture/adrs/004-logseq-blocks-support.md)
- [Logseq Blocks Design](../architecture/logseq-blocks-design.md)
- [MCP Block Tools](../api/mcp-tools.md#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?](why-kogral.md)
- **Learn philosophy**: [Design Philosophy](design-philosophy.md)
- **See architecture**: [System Overview](../architecture/overview.md)
- **Start using**: [Quick Start](../guides/quickstart.md)
