710 lines
30 KiB
HTML
710 lines
30 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="rust sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Core Concepts - KOGRAL Documentation</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="Complete documentation for KOGRAL - Git-native knowledge graphs for developer teams">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="../favicon.svg">
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|
<link rel="stylesheet" href="../css/general.css">
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "../";
|
|
const default_light_theme = "rust";
|
|
const default_dark_theme = "navy";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="mdbook-help-container">
|
|
<div id="mdbook-help-popup">
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|
<div>
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('rust')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
}
|
|
sidebar_toggle.checked = sidebar === 'visible';
|
|
html.classList.remove('sidebar-visible');
|
|
html.classList.add("sidebar-" + sidebar);
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">KOGRAL Documentation</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
<a href="https://github.com/your-org/knowledge-base" title="Git repository" aria-label="Git repository">
|
|
<i id="git-repository-button" class="fa fa-github"></i>
|
|
</a>
|
|
<a href="https://github.com/your-org/knowledge-base/edit/main/docs/./kogral/core-concepts.md" title="Suggest an edit" aria-label="Suggest an edit">
|
|
<i id="git-edit-button" class="fa fa-edit"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="core-concepts"><a class="header" href="#core-concepts">Core Concepts</a></h1>
|
|
<p>Understanding the fundamental concepts behind KOGRAL.</p>
|
|
<h2 id="the-knowledge-graph"><a class="header" href="#the-knowledge-graph">The Knowledge Graph</a></h2>
|
|
<p>At its core, KOGRAL is a <strong>directed graph</strong> where:</p>
|
|
<ul>
|
|
<li><strong>Nodes</strong> = pieces of knowledge (notes, decisions, guidelines, patterns)</li>
|
|
<li><strong>Edges</strong> = typed relationships between concepts</li>
|
|
</ul>
|
|
<p><img src="../diagrams/core-concepts.svg" alt="Node Types and Relationships" /></p>
|
|
<p>This graph structure enables:</p>
|
|
<ul>
|
|
<li><strong>Discovery</strong>: Find related concepts through traversal</li>
|
|
<li><strong>Context</strong>: Understand how ideas connect</li>
|
|
<li><strong>Evolution</strong>: Track how knowledge changes over time</li>
|
|
</ul>
|
|
<h2 id="node-types"><a class="header" href="#node-types">Node Types</a></h2>
|
|
<h3 id="1-note"><a class="header" href="#1-note">1. Note</a></h3>
|
|
<p><strong>Purpose</strong>: Capture general observations, learnings, and discoveries.</p>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul>
|
|
<li>Documenting a concept you learned</li>
|
|
<li>Recording implementation details</li>
|
|
<li>Capturing meeting notes</li>
|
|
<li>Quick knowledge capture</li>
|
|
</ul>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-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...
|
|
</code></pre>
|
|
<h3 id="2-decision-adr"><a class="header" href="#2-decision-adr">2. Decision (ADR)</a></h3>
|
|
<p><strong>Purpose</strong>: Record architectural decisions with full context.</p>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul>
|
|
<li>Choosing between alternatives (REST vs GraphQL)</li>
|
|
<li>Major technical decisions (database selection)</li>
|
|
<li>Trade-off analysis</li>
|
|
<li>Explaining "why" for future reference</li>
|
|
</ul>
|
|
<p><strong>Structure</strong>:</p>
|
|
<ul>
|
|
<li><strong>Context</strong>: Background and problem</li>
|
|
<li><strong>Decision</strong>: What was chosen</li>
|
|
<li><strong>Consequences</strong>: Positive and negative outcomes</li>
|
|
<li><strong>Alternatives</strong>: What was considered but rejected</li>
|
|
</ul>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-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
|
|
</code></pre>
|
|
<h3 id="3-guideline"><a class="header" href="#3-guideline">3. Guideline</a></h3>
|
|
<p><strong>Purpose</strong>: Define coding standards, best practices, and conventions.</p>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul>
|
|
<li>Code style rules</li>
|
|
<li>Architecture patterns to follow</li>
|
|
<li>Security requirements</li>
|
|
<li>Testing standards</li>
|
|
</ul>
|
|
<p><strong>Can be</strong>:</p>
|
|
<ul>
|
|
<li><strong>Shared</strong>: Organization-wide (in shared KOGRAL)</li>
|
|
<li><strong>Project-specific</strong>: Overrides shared guidelines</li>
|
|
</ul>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-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 `?`
|
|
</code></pre>
|
|
<h3 id="4-pattern"><a class="header" href="#4-pattern">4. Pattern</a></h3>
|
|
<p><strong>Purpose</strong>: Document reusable solutions to common problems.</p>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul>
|
|
<li>Recurring implementation patterns</li>
|
|
<li>Tested solutions</li>
|
|
<li>Best practice implementations</li>
|
|
<li>Code templates</li>
|
|
</ul>
|
|
<p><strong>Structure</strong>:</p>
|
|
<ul>
|
|
<li><strong>Problem</strong>: What challenge does this solve?</li>
|
|
<li><strong>Solution</strong>: The pattern/approach</li>
|
|
<li><strong>Context</strong>: When to use/not use</li>
|
|
<li><strong>Example</strong>: Working code</li>
|
|
</ul>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-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>;
|
|
}
|
|
\`\`\`
|
|
</code></pre>
|
|
<h3 id="5-journal"><a class="header" href="#5-journal">5. Journal</a></h3>
|
|
<p><strong>Purpose</strong>: Daily development log for tracking progress and reflections.</p>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul>
|
|
<li>End of day summaries</li>
|
|
<li>Daily standup notes</li>
|
|
<li>Progress tracking</li>
|
|
<li>Blocker documentation</li>
|
|
</ul>
|
|
<p><strong>Auto-linked</strong>: KOGRAL can auto-link journal entries to mentioned concepts.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-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
|
|
</code></pre>
|
|
<h3 id="6-execution"><a class="header" href="#6-execution">6. Execution</a></h3>
|
|
<p><strong>Purpose</strong>: Record AI agent execution results (from Vapora integration).</p>
|
|
<p><strong>When to use</strong>:</p>
|
|
<ul>
|
|
<li>Agent task completion</li>
|
|
<li>Execution metrics</li>
|
|
<li>Agent decision history</li>
|
|
<li>Audit trail</li>
|
|
</ul>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code class="language-yaml">---
|
|
type: execution
|
|
task_type: code_generation
|
|
agent: rust-expert
|
|
outcome: success
|
|
duration: 45s
|
|
---
|
|
|
|
Generated authentication module following project guidelines.
|
|
</code></pre>
|
|
<h2 id="relationship-types"><a class="header" href="#relationship-types">Relationship Types</a></h2>
|
|
<h3 id="1-relates_to"><a class="header" href="#1-relates_to">1. <code>relates_to</code></a></h3>
|
|
<p><strong>Meaning</strong>: General conceptual relationship.</p>
|
|
<p><strong>Use</strong>: Connect related ideas without specific dependency.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>[Note: Async Patterns] --relates_to--> [Note: Tokio Runtime]
|
|
</code></pre>
|
|
<h3 id="2-depends_on"><a class="header" href="#2-depends_on">2. <code>depends_on</code></a></h3>
|
|
<p><strong>Meaning</strong>: Prerequisite relationship. Source requires target to exist/be understood first.</p>
|
|
<p><strong>Use</strong>: Learning paths, implementation order.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>[Pattern: Advanced Error Handling] --depends_on--> [Guideline: Basic Errors]
|
|
</code></pre>
|
|
<h3 id="3-implements"><a class="header" href="#3-implements">3. <code>implements</code></a></h3>
|
|
<p><strong>Meaning</strong>: Concrete implementation of an abstract concept.</p>
|
|
<p><strong>Use</strong>: Connect code to patterns/guidelines.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>[Note: Auth Module Implementation] --implements--> [Pattern: Repository Pattern]
|
|
</code></pre>
|
|
<h3 id="4-extends"><a class="header" href="#4-extends">4. <code>extends</code></a></h3>
|
|
<p><strong>Meaning</strong>: Inheritance/extension relationship.</p>
|
|
<p><strong>Use</strong>: Guideline overrides, pattern variations.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>[Guideline: Project Error Handling] --extends--> [Guideline: Shared Error Handling]
|
|
</code></pre>
|
|
<h3 id="5-supersedes"><a class="header" href="#5-supersedes">5. <code>supersedes</code></a></h3>
|
|
<p><strong>Meaning</strong>: Replacement relationship. Source replaces target.</p>
|
|
<p><strong>Use</strong>: Track evolution of decisions/patterns.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>[Decision: Use GraphQL v2] --supersedes--> [Decision: Use REST]
|
|
</code></pre>
|
|
<h3 id="6-explains"><a class="header" href="#6-explains">6. <code>explains</code></a></h3>
|
|
<p><strong>Meaning</strong>: Documentation/clarification relationship.</p>
|
|
<p><strong>Use</strong>: Connect notes to implementations, executions to rationale.</p>
|
|
<p><strong>Example</strong>:</p>
|
|
<pre><code>[Note: Why We Chose Rust] --explains--> [Decision: Adopt Rust]
|
|
</code></pre>
|
|
<h2 id="multi-graph-architecture"><a class="header" href="#multi-graph-architecture">Multi-Graph Architecture</a></h2>
|
|
<p>KB supports <strong>multiple knowledge graphs</strong>:</p>
|
|
<h3 id="local-graph-project-specific"><a class="header" href="#local-graph-project-specific">Local Graph (Project-Specific)</a></h3>
|
|
<p><strong>Location</strong>: <code>.kogral/</code> in project directory</p>
|
|
<p><strong>Purpose</strong>: Project-specific knowledge</p>
|
|
<ul>
|
|
<li>Project decisions</li>
|
|
<li>Implementation notes</li>
|
|
<li>Local patterns</li>
|
|
<li>Daily journals</li>
|
|
</ul>
|
|
<p><strong>Storage</strong>: Filesystem (git-tracked)</p>
|
|
<p><strong>Scope</strong>: Single project</p>
|
|
<h3 id="shared-graph-organization-wide"><a class="header" href="#shared-graph-organization-wide">Shared Graph (Organization-Wide)</a></h3>
|
|
<p><strong>Location</strong>: Configurable (e.g., <code>~/org/.kogral-shared</code>)</p>
|
|
<p><strong>Purpose</strong>: Shared organizational knowledge</p>
|
|
<ul>
|
|
<li>Coding guidelines</li>
|
|
<li>Standard patterns</li>
|
|
<li>Architecture principles</li>
|
|
<li>Security policies</li>
|
|
</ul>
|
|
<p><strong>Storage</strong>: SurrealDB (centralized) or filesystem (synced)</p>
|
|
<p><strong>Scope</strong>: All projects</p>
|
|
<h3 id="inheritance-model"><a class="header" href="#inheritance-model">Inheritance Model</a></h3>
|
|
<pre><code>Shared Guidelines (priority: 50)
|
|
↓ [inherited by]
|
|
Project Guidelines (priority: 100)
|
|
↓ [effective]
|
|
Combined Guidelines (higher priority wins)
|
|
</code></pre>
|
|
<p><strong>Example</strong>:</p>
|
|
<p>Shared guideline: "Use Result<T> for errors"
|
|
Project override: "Use Result<T> + log all errors with tracing"
|
|
Effective: Both rules apply, project adds requirement</p>
|
|
<h2 id="config-driven-behavior"><a class="header" href="#config-driven-behavior">Config-Driven Behavior</a></h2>
|
|
<p><strong>Everything is configurable</strong> via Nickel schemas:</p>
|
|
<pre><code class="language-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
|
|
}
|
|
</code></pre>
|
|
<p><strong>No hardcoding</strong>: Change behavior without code changes.</p>
|
|
<h2 id="semantic-search"><a class="header" href="#semantic-search">Semantic Search</a></h2>
|
|
<p>Beyond keyword matching, KOGRAL uses <strong>embeddings</strong> to find concepts:</p>
|
|
<p><strong>Keyword search</strong>: "Find 'error handling'"</p>
|
|
<ul>
|
|
<li>Matches exact phrase "error handling"</li>
|
|
</ul>
|
|
<p><strong>Semantic search</strong>: "How to handle failures gracefully?"</p>
|
|
<ul>
|
|
<li>Finds: error handling, exception patterns, Result types, panic recovery</li>
|
|
<li>Understands: "failures" = errors, "gracefully" = best practices</li>
|
|
</ul>
|
|
<p><strong>How it works</strong>:</p>
|
|
<ol>
|
|
<li>Text → Embedding (384 or 1536 dimensional vector)</li>
|
|
<li>Similarity search (cosine distance)</li>
|
|
<li>Return nodes above threshold (e.g., 0.6)</li>
|
|
</ol>
|
|
<p><strong>Providers</strong>:</p>
|
|
<ul>
|
|
<li><strong>fastembed</strong>: Local, free, offline (384d)</li>
|
|
<li><strong>OpenAI</strong>: Cloud, best quality (1536d)</li>
|
|
<li><strong>Claude</strong>: Cloud, excellent (1024d)</li>
|
|
<li><strong>Ollama</strong>: Self-hosted (768d)</li>
|
|
</ul>
|
|
<h2 id="templates"><a class="header" href="#templates">Templates</a></h2>
|
|
<p><strong>Tera templates</strong> generate consistent documents:</p>
|
|
<pre><code class="language-jinja2">---
|
|
id: {{ id }}
|
|
type: {{ type }}
|
|
title: {{ title }}
|
|
tags: [{% for tag in tags %}"{{ tag }}"{% endfor %}]
|
|
---
|
|
|
|
# {{ title }}
|
|
|
|
{{ content }}
|
|
</code></pre>
|
|
<p><strong>Customizable</strong>: Override templates per project.</p>
|
|
<p><strong>Export formats</strong>: Logseq, JSON, Markdown.</p>
|
|
<h2 id="mcp-integration"><a class="header" href="#mcp-integration">MCP Integration</a></h2>
|
|
<p><strong>Model Context Protocol</strong> connects KOGRAL to Claude Code:</p>
|
|
<pre><code>Claude Code
|
|
↓ [JSON-RPC 2.0]
|
|
kb-mcp Server
|
|
↓ [Rust API]
|
|
kb-core Library
|
|
↓ [Storage]
|
|
Knowledge Graph
|
|
</code></pre>
|
|
<p><strong>Tools</strong>: <code>kogral/search</code>, <code>kogral/add_note</code>, <code>kogral/get_guidelines</code>, etc.</p>
|
|
<p><strong>Resources</strong>: <code>kogral://project/notes</code>, <code>kogral://shared/guidelines</code></p>
|
|
<p><strong>Prompts</strong>: <code>kogral/summarize_project</code>, <code>kogral/find_related</code></p>
|
|
<h2 id="git-friendly-storage"><a class="header" href="#git-friendly-storage">Git-Friendly Storage</a></h2>
|
|
<p><strong>Markdown + YAML frontmatter</strong> = git-tracked knowledge:</p>
|
|
<pre><code class="language-markdown">---
|
|
id: note-123
|
|
type: note
|
|
title: My Note
|
|
---
|
|
|
|
# Content here
|
|
</code></pre>
|
|
<p><strong>Benefits</strong>:</p>
|
|
<ul>
|
|
<li>✅ Diffs in PRs (reviewable changes)</li>
|
|
<li>✅ Branches (experiment with knowledge)</li>
|
|
<li>✅ Merges (combine knowledge from feature branches)</li>
|
|
<li>✅ History (track evolution over time)</li>
|
|
<li>✅ Blame (who added this knowledge?)</li>
|
|
</ul>
|
|
<h2 id="logseq-content-blocks"><a class="header" href="#logseq-content-blocks">Logseq Content Blocks</a></h2>
|
|
<p>KOGRAL provides full support for <strong>Logseq-style outliner blocks</strong> with rich metadata and structure.</p>
|
|
<h3 id="what-are-blocks"><a class="header" href="#what-are-blocks">What are Blocks?</a></h3>
|
|
<p>Blocks are the fundamental unit of content in Logseq's outliner format:</p>
|
|
<ul>
|
|
<li>Each bullet point is a block</li>
|
|
<li>Blocks can have children (nested blocks)</li>
|
|
<li>Blocks support tasks, tags, and custom properties</li>
|
|
<li>Blocks can reference other blocks or pages</li>
|
|
</ul>
|
|
<h3 id="block-features"><a class="header" href="#block-features">Block Features</a></h3>
|
|
<p><strong>Task Status</strong>:</p>
|
|
<pre><code class="language-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
|
|
</code></pre>
|
|
<p><strong>Inline Tags</strong>:</p>
|
|
<pre><code class="language-markdown">- Learning Rust ownership #rust #learning #card
|
|
- Prevents data races at compile time
|
|
- Borrowing rules enforce safety
|
|
</code></pre>
|
|
<p><strong>Custom Properties</strong>:</p>
|
|
<pre><code class="language-markdown">- Research paper summary
|
|
priority:: high
|
|
reviewed:: 2026-01-17
|
|
source:: https://example.com/paper.pdf
|
|
- Key findings...
|
|
</code></pre>
|
|
<p><strong>Block and Page References</strong>:</p>
|
|
<pre><code class="language-markdown">- Meeting notes from [[2026-01-17]]
|
|
- Discussed architecture ((block-ref-123))
|
|
- Action items: [[Project Roadmap]]
|
|
</code></pre>
|
|
<p><strong>Hierarchical Structure</strong>:</p>
|
|
<pre><code class="language-markdown">- Parent block #top-level
|
|
- Child block 1
|
|
- Nested child
|
|
- Child block 2
|
|
</code></pre>
|
|
<h3 id="configuration"><a class="header" href="#configuration">Configuration</a></h3>
|
|
<p>Blocks support is opt-in via configuration:</p>
|
|
<pre><code class="language-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
|
|
},
|
|
}
|
|
</code></pre>
|
|
<h3 id="use-cases"><a class="header" href="#use-cases">Use Cases</a></h3>
|
|
<p><strong>1. Task Management</strong>:</p>
|
|
<pre><code class="language-markdown">- TODO Weekly sprint planning #meeting
|
|
- DONE Review last sprint
|
|
- DOING Plan current sprint
|
|
- TODO Assign tasks
|
|
</code></pre>
|
|
<p><strong>2. Flashcards (Spaced Repetition)</strong>:</p>
|
|
<pre><code class="language-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
|
|
</code></pre>
|
|
<p><strong>3. Knowledge Capture with Metadata</strong>:</p>
|
|
<pre><code class="language-markdown">- Tokio async runtime patterns #rust #async
|
|
category:: architecture
|
|
difficulty:: intermediate
|
|
- Use tokio::select! for concurrent operations
|
|
- spawn_blocking() for CPU-intensive work
|
|
</code></pre>
|
|
<p><strong>4. Linked Notes</strong>:</p>
|
|
<pre><code class="language-markdown">- Discussed [[ADR-001]] in architecture meeting
|
|
- Decided on SurrealDB
|
|
- See ((meeting-notes-block-id)) for details
|
|
</code></pre>
|
|
<h3 id="block-queries-mcp-tools"><a class="header" href="#block-queries-mcp-tools">Block Queries (MCP Tools)</a></h3>
|
|
<p>Query blocks across your knowledge base:</p>
|
|
<p><strong>Find blocks by tag</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"tool": "kogral/find_blocks",
|
|
"arguments": { "tag": "card" }
|
|
}
|
|
</code></pre>
|
|
<p><strong>Find all TODOs</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"tool": "kogral/find_todos",
|
|
"arguments": { "limit": 20 }
|
|
}
|
|
</code></pre>
|
|
<p><strong>Find flashcards</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"tool": "kogral/find_cards",
|
|
"arguments": { "limit": 10 }
|
|
}
|
|
</code></pre>
|
|
<p><strong>Find blocks by property</strong>:</p>
|
|
<pre><code class="language-json">{
|
|
"tool": "kogral/find_blocks",
|
|
"arguments": {
|
|
"property_key": "priority",
|
|
"property_value": "high"
|
|
}
|
|
}
|
|
</code></pre>
|
|
<h3 id="architecture"><a class="header" href="#architecture">Architecture</a></h3>
|
|
<p><strong>Hybrid Model</strong>:</p>
|
|
<ul>
|
|
<li>Content stored as markdown string (source of truth)</li>
|
|
<li>Blocks lazily parsed on first access</li>
|
|
<li>Cached block structure for fast queries</li>
|
|
<li>Bidirectional: markdown ↔ blocks</li>
|
|
</ul>
|
|
<p><strong>BlockParser</strong>:</p>
|
|
<ul>
|
|
<li>Parse outliner markdown → Block structures</li>
|
|
<li>Serialize Block structures → outliner markdown</li>
|
|
<li>Preserve all metadata (tags, status, properties, references)</li>
|
|
<li>Round-trip fidelity for Logseq compatibility</li>
|
|
</ul>
|
|
<p><strong>Storage</strong>:</p>
|
|
<ul>
|
|
<li>Filesystem: markdown with blocks inline</li>
|
|
<li>SurrealDB: dedicated <code>block</code> table with indexes</li>
|
|
<li>Indexes: tags, status, parent_id, full-text search</li>
|
|
</ul>
|
|
<p><strong>See Also</strong>:</p>
|
|
<ul>
|
|
<li><a href="../architecture/adrs/004-logseq-blocks-support.html">ADR-004: Logseq Blocks Support</a></li>
|
|
<li><a href="../architecture/logseq-blocks-design.html">Logseq Blocks Design</a></li>
|
|
<li><a href="../api/mcp-tools.html#block-tools">MCP Block Tools</a></li>
|
|
</ul>
|
|
<h2 id="key-principles"><a class="header" href="#key-principles">Key Principles</a></h2>
|
|
<ol>
|
|
<li><strong>Capture During Work</strong>: Don't wait, document as you go</li>
|
|
<li><strong>Link as You Learn</strong>: Connect related concepts immediately</li>
|
|
<li><strong>Query When Needed</strong>: AI-assisted discovery of relevant knowledge</li>
|
|
<li><strong>Evolve Over Time</strong>: Update decisions, supersede patterns</li>
|
|
<li><strong>Share Wisely</strong>: Shared guidelines, local specifics</li>
|
|
</ol>
|
|
<h2 id="next-steps"><a class="header" href="#next-steps">Next Steps</a></h2>
|
|
<ul>
|
|
<li><strong>Understand motivation</strong>: <a href="why-kogral.html">Why KOGRAL?</a></li>
|
|
<li><strong>Learn philosophy</strong>: <a href="design-philosophy.html">Design Philosophy</a></li>
|
|
<li><strong>See architecture</strong>: <a href="../architecture/overview.html">System Overview</a></li>
|
|
<li><strong>Start using</strong>: <a href="../guides/quickstart.html">Quick Start</a></li>
|
|
</ul>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../kogral/what-is-kogral.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../kogral/why-kogral.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="../kogral/what-is-kogral.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../kogral/why-kogral.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="../elasticlunr.min.js"></script>
|
|
<script src="../mark.min.js"></script>
|
|
<script src="../searcher.js"></script>
|
|
|
|
<script src="../clipboard.min.js"></script>
|
|
<script src="../highlight.js"></script>
|
|
<script src="../book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|