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

# 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

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

Layers:

1. kb-core: Core library (models, storage, query)
2. kb-cli: Command-line interface
3. kb-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."