kogral/docs/kogral/what-is-kogral.md

What is KOGRAL

KOGRAL (KOwledge GRAphs, Local-first) is a git-native knowledge graph system designed for developer teams to capture, connect, and query structured knowledge.

Purpose

KOGRAL solves the problem of knowledge fragmentation in software development:

• 📝 Notes scattered across tools
• 🤔 Decisions lost in chat histories
• 📚 Guidelines buried in wikis
• 🔄 Patterns rediscovered repeatedly
• 🤖 AI agents lacking project context

Solution

KOGRAL provides a unified, queryable knowledge graph that:

1. Captures knowledge in structured, git-friendly markdown
2. Connects concepts through typed relationships
3. Queries via text and semantic similarity
4. Integrates with AI tools (Claude Code via MCP)
5. Syncs across local (filesystem) and shared (SurrealDB) storage

Core Philosophy

Config-Driven

Behavior defined in Nickel schemas, not hardcoded:

{
  graph = { name = "my-project" },
  storage = { primary = 'filesystem },
  embeddings = { provider = 'fastembed },
  templates = { templates_dir = "templates" },
}

Every aspect configurable: storage, embeddings, templates, query behavior.

Git-Friendly

Knowledge stored as markdown files with YAML frontmatter:

---
id: note-123
type: note
title: Error Handling Patterns
tags: [rust, error-handling]
---

# Error Handling Patterns

Use `thiserror` for custom error types...

Changes tracked via git, reviewable in PRs, mergeable across branches.

AI-Native

Built for agent collaboration:

• MCP Protocol: Native integration with Claude Code
• Semantic Search: Find concepts, not just keywords
• Auto-Linking: Suggest relationships based on content
• Context Injection: Agents query relevant guidelines before coding

Key Concepts

Nodes

6 types of knowledge nodes:

Type	Purpose	Example
Note	General observations	"Rust ownership patterns"
Decision	ADRs (Architectural Decision Records)	"Use SurrealDB for storage"
Guideline	Code standards	"Error handling with thiserror"
Pattern	Reusable solutions	"Repository pattern for DB access"
Journal	Daily reflections	"2026-01-17 progress notes"
Execution	Agent task records	"Implemented auth module"

Relationships

6 typed edges connecting nodes:

Relation	Meaning	Example
relates_to	Conceptual link	Note ↔ Note
depends_on	Prerequisite	Pattern → Guideline
implements	Concrete realization	Code → Pattern
extends	Inheritance	ProjectGuideline → BaseGuideline
supersedes	Replacement	DecisionV2 → DecisionV1
explains	Documentation	Note → Execution

Multi-Graph Architecture

Local Graph (per project):

• Stored in .kogral/ directory
• Git-tracked for version control
• Project-specific knowledge

Shared Graph (organization-wide):

• Centralized guidelines and patterns
• SurrealDB for scalability
• Inherited by projects

Inheritance Resolution:

Shared Guidelines (priority: 50)
    ↓
Project Guidelines (priority: 100)
    ↓
Effective Guidelines (higher priority wins)

Use Cases

For Developers

• Capture decisions as you make them (ADRs)
• Document patterns for future reference
• Track daily progress in journal entries
• Query past decisions before new implementations

For Teams

• Share guidelines across projects
• Standardize patterns organization-wide
• Onboard new members with searchable knowledge
• Review decisions in context with git history

For AI Agents

• Query guidelines before generating code
• Check past decisions for context
• Document executions for audit trails
• Suggest related patterns during implementation

Comparison with Other Tools

vs. Logseq

Feature	KOGRAL	Logseq
Storage	Git-friendly markdown + DB	Local markdown
AI Integration	Native MCP protocol	Plugin-based
Config	Type-safe Nickel schemas	JSON files
Multi-Backend	Filesystem + SurrealDB	Filesystem only
Semantic Search	Multiple AI providers	Local only
Graph Queries	SurrealDB graph queries	Block references

Compatibility: KOGRAL can import/export Logseq graphs for visual editing.

vs. Obsidian

Feature	KOGRAL	Obsidian
Target Audience	Developers + AI agents	Knowledge workers
Focus	Structured knowledge graph	Flexible note-taking
Configuration	Config-driven (Nickel)	Settings UI
CLI	Full CLI + MCP server	Limited CLI
Version Control	Git-native	Git plugin

Use Case: KOGRAL for developer knowledge, Obsidian for personal notes.

vs. Notion/Confluence

Feature	KOGRAL	Notion/Confluence
Storage	Local-first	Cloud-only
Format	Plain markdown	Proprietary
AI Access	Programmatic API	Web scraping
Offline	Full functionality	Limited
Privacy	Self-hosted	Third-party servers

Advantage: KOGRAL keeps sensitive knowledge on-premises.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                    kogral-core                          │
│  (Rust library: graph, storage, config, query)     │
└──────────────┬─────────────┬────────────────────────┘
               │             │
     ┌─────────┴──────┐  ┌──┴─────────┐
     │                │  │            │
┌────▼─────┐  ┌──────▼──▼───┐  ┌─────▼─────┐
│  kogral-cli  │  │   kogral-mcp     │  │  NuShell  │
│ (13 cmds)│  │ (MCP server) │  │ (scripts) │
└──────────┘  └──────────────┘  └───────────┘

Layers:

1. kogral-core: Core library (models, storage, query)
2. kogral-cli: Command-line interface
3. kogral-mcp: MCP server for AI integration
4. Scripts: NuShell automation (sync, backup, etc.)

When to Use KOGRAL

✅ Good fit:

• Developer teams building software
• Projects with architectural decisions
• Organizations standardizing patterns
• AI-assisted development workflows
• Knowledge requiring version control

❌ Not ideal for:

• Personal journaling (use Obsidian)
• Team wikis (use Notion)
• Customer documentation (use mdBook)
• Simple note-taking (use Logseq)

Next Steps

• New to KOGRAL? → Installation Guide
• Ready to start? → Quick Start
• Want examples? → Use Cases
• Understand design? → Architecture Overview

---

"Knowledge is only valuable when it's accessible, connected, and queryable."