# What is KOGRAL

KOGRAL (**KO**wledge **GRA**phs, **L**ocal-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:

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

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

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

```text
┌─────────────────────────────────────────────────────┐
│                    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](../guides/installation.md)
- **Ready to start?** → [Quick Start](../guides/quickstart.md)
- **Want examples?** → [Use Cases](../guides/use-cases.md)
- **Understand design?** → [Architecture Overview](../architecture/overview.md)

---

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