kogral/README.md

# KOGRAL

<div align="center"> <img src="assets/kogral-logo.svg" alt="KoGraL Logo" width="600" /> </div>
  
**KO**wledge **GRA**phs, **L**ocal-first

Git-native knowledge graphs for developer teams. Structured knowledge management that scales from solo
projects to organizations. Capture architectural decisions, coding guidelines, and reusable patterns in
version-controlled markdown.

Built for developers who version their knowledge like their code.

## Overview

KOGRAL enables:
- **Bidirectional Knowledge Flow**: AI agents can both contribute to and query structured knowledge
- **Logseq Compatibility**: Uses markdown files with YAML frontmatter and wikilinks for easy editing
- **Config-Driven Architecture**: All behavior defined in Nickel schemas, not hardcoded
- **Hybrid Storage**: Local project graphs (git-friendly) + central shared graph (SurrealDB)
- **MCP Integration**: Model Context Protocol server for Claude Code integration
- **Multiple Interfaces**: CLI tools, MCP server, NuShell scripts for automation

## Key Features

- **6 Node Types**: Notes, Decisions (ADR), Guidelines, Patterns, Journal entries, Execution records
- **6 Relationship Types**: relates_to, depends_on, implements, extends, supersedes, explains
- **Logseq Content Blocks**: Full support for outliner-style blocks with tasks, tags, and properties
- **Multi-Backend Storage**: Filesystem (git-friendly), In-Memory (dev/cache), SurrealDB (scalable)
- **Semantic Search**: Text + vector search with configurable embedding providers
- **Template Engine**: Tera templates for document generation and export
- **Guideline Inheritance**: Project-specific guidelines can override shared base guidelines
- **Logseq Import/Export**: Bidirectional conversion with complete block structure preservation

## Architecture

```text
┌─────────────────────────────────────────────────────────────┐
│                    kogral-core (Rust library)               │
├─────────────────────────────────────────────────────────────┤
│  Config Layer:  Nickel → JSON → serde → Rust structs        │
│  Storage Layer: Filesystem | SurrealDB | In-Memory          │
│  Graph Engine:  Nodes + Edges with multi-graph support      │
│  Parser:        Markdown + YAML frontmatter + wikilinks     │
│  BlockParser:   Logseq outliner ↔ blocks (tasks, tags)      │
│  Embeddings:    rig-core APIs + fastembed local fallback    │
│  Query:         Text + semantic + blocks search             │
└─────────────────────────────────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼───────┐  ┌───────▼───────┐  ┌──────▼──────────┐
│   kogral-cli  │  │   kogral-mcp  │  │    NuShell      │
│   (Commands)  │  │   (Server)    │  │   (Scripts)     │
├───────────────┤  ├───────────────┤  ├─────────────────┤
│ init          │  │ 7 Tools       │  │ kogral-sync     │
│ add           │  │ 6 Resources   │  │ kogral-backup   │
│ search        │  │ 2 Prompts     │  │ kogral-reindex  │
│ link          │  │ JSON-RPC 2.0  │  │ kogral-import   │
│ sync          │  │ stdio         │  │ kogral-export   │
│ serve         │  │               │  │ kogral-stats    │
│ ... 13 total  │  │               │  │ kogral-migrate  │
└───────────────┘  └───────────────┘  └─────────────────┘
```

## Quick Start

### Installation

```bash
# Clone the repository
git clone <repository-url> knowledge-base
cd knowledge-base

# Build the workspace
cargo build --release

# Install CLI tool
cargo install --path crates/kogral-cli

# Verify installation
kogral --version
```

### Initialize a Knowledge Base

```bash
# Create .kogral directory in your project
kogral init

# Add a note
kogral add note "My First Note" --tags rust,architecture

# Search the knowledge base
kogral search "architecture"

# Link two nodes
kogral link note-id-1 note-id-2 relates_to
```

### Start MCP Server

```bash
# Start MCP server for Claude Code integration
kogral serve

# Configure Claude Code to use kogral-mcp server
# Add to ~/.config/claude/config.json
```

## Directory Structure

```text
knowledge-base/
├── crates/
│   ├── kogral-core/             # Core library (models, storage, parser, query)
│   ├── kogral-cli/              # Command-line interface (13 commands)
│   └── kogral-mcp/              # MCP server (7 tools, 6 resources, 2 prompts)
├── schemas/              # Nickel configuration schemas (config-driven)
│   ├── contracts.ncl        # Type contracts (validation)
│   ├── defaults.ncl         # Base default values
│   ├── helpers.ncl          # Composition utilities
│   └── modes/               # Mode overlays (dev/prod/test)
├── .kogral-config/              # Runtime configuration
│   ├── core/kogral.ncl          # User customization
│   ├── platform/            # Platform-specific configs (dev/prod/test)
│   └── targets/             # Exported JSON configs (generated)
├── templates/               # Tera templates
│   ├── note.md.tera         # Document templates (6 types)
│   ├── decision.md.tera
│   └── export/              # Export templates (4 formats)
├── scripts/                 # NuShell maintenance scripts
│   ├── kogral-sync.nu           # Filesystem ↔ SurrealDB sync
│   ├── kogral-backup.nu         # Backup knowledge base
│   ├── kogral-reindex.nu        # Rebuild embeddings
│   └── kogral-import-logseq.nu  # Import from Logseq
├── docs/                    # Documentation (mdBook)
│   ├── README.md            # How to use docs
│   ├── book.toml            # mdBook configuration
│   ├── SUMMARY.md           # Navigation structure
│   ├── diagrams/            # SVG diagrams (4 visual guides)
│   ├── kb/                  # KB definition
│   ├── guides/              # User guides
│   ├── architecture/        # Architecture + ADRs
│   ├── setup/               # Setup guides
│   ├── config/              # Configuration reference
│   ├── storage/             # Storage backends
│   ├── ai/                  # Embeddings & semantic search
│   ├── templates/           # Template system
│   ├── cli/                 # CLI reference
│   ├── apps/                # Integrations (MCP, Logseq)
│   ├── api/                 # API reference
│   └── contributing/        # Development guides
├── justfiles/               # Modular just recipes
│   ├── build.just           # Build commands
│   ├── test.just            # Test commands
│   ├── docs.just            # Documentation (mdBook)
│   ├── nickel.just          # Nickel validation & export
│   └── scripts.just         # NuShell script runners
├── justfile                 # Main just orchestrator
├── CHANGELOG.md             # Version history
└── README.md                # This file
```

## Project Knowledge Base Structure

Each project can have a `\.kogral/` directory with the following structure:

```text
project-root/
└── \.kogral/
    ├── config.toml       # Graph configuration
    ├── notes/            # General notes
    ├── decisions/        # Architectural Decision Records (ADR)
    ├── guidelines/       # Project-specific guidelines
    ├── patterns/         # Reusable patterns
    └── journal/          # Daily journal entries
```

## Document Format

Knowledge base documents use markdown with YAML frontmatter:

```markdown
---
id: unique-id
type: note
title: Example Note
created: 2026-01-17T10:30:00Z
modified: 2026-01-17T10:30:00Z
tags: [rust, architecture]
status: active
relates_to:
  - other-note-id
  - decision-0001
---

# Example Note

Content with [[wikilinks]] to other nodes.

## Section

More content referencing @path/to/file.rs:42 for code links.
```

### Logseq Blocks Support

When blocks are enabled, documents can use Logseq's outliner format with full support for tasks, tags, and properties:

```markdown
---
id: project-tasks
type: note
title: Project Tasks
tags: [tasks, project]
---

- TODO Implement feature A #high-priority
  - DONE Research approaches
  - DOING Write implementation
  - TODO Add tests
- Learning Rust patterns #learning #card
  priority:: high
  reviewed:: 2026-01-17
  - Ownership model prevents data races
  - Borrowing rules checked at compile time
- Meeting notes from [[2026-01-17]]
  - Discussed architecture decisions
  - Action items: ((block-ref-id))
```

**Block Features**:
- Task status: `TODO`, `DOING`, `DONE`, `LATER`, `NOW`, `WAITING`, `CANCELLED`
- Inline tags: `#tag` for quick categorization
- Custom properties: `key:: value` for metadata
- Block references: `((block-id))` for linking specific blocks
- Page references: `[[page-name]]` for wiki-style links
- Hierarchical nesting: Indentation creates parent-child relationships

## Configuration

Knowledge base behavior is fully configurable via Nickel schemas:

```nickel
# \.kogral/config.ncl
{
  graph = {
    name = "my-project",
    version = "1.0.0",
  },

  storage = {
    primary = 'filesystem,
    secondary = {
      enabled = true,
      type = 'surrealdb,
      url = "ws://localhost:8000",
    },
  },

  embeddings = {
    enabled = true,
    provider = 'fastembed,
    model = "BAAI/bge-small-en-v1.5",
  },

  blocks = {
    enabled = true,                # Enable Logseq blocks support
    parse_on_import = true,        # Auto-parse blocks from imports
    serialize_on_export = true,    # Serialize blocks on export
    enable_mcp_tools = true,       # Enable block-related MCP tools
  },
}
```

See [docs/user-guide/configuration.md](docs/user-guide/configuration.md) for complete configuration reference.

## MCP Integration

The MCP server provides Claude Code with access to your knowledge base:

**Tools**:
- `kb/search` - Search knowledge base
- `kb/add_note` - Add new notes
- `kb/add_decision` - Create ADRs
- `kb/link` - Create relationships
- `kb/get_guidelines` - Query guidelines with inheritance
- `kb/list_graphs` - List available graphs
- `kb/export` - Export to various formats
- `kb/find_blocks` - Find blocks by tag, status, or property
- `kb/find_todos` - Find all TODO blocks
- `kb/find_cards` - Find flashcard blocks (#card)

**Resources**:
- `kogral://project/notes` - Project notes
- `kogral://project/decisions` - Project decisions
- `kogral://shared/guidelines` - Shared guidelines
- `kogral://shared/patterns` - Shared patterns

See [docs/api/mcp-tools.md](docs/api/mcp-tools.md) for complete API reference.

## NuShell Scripts

Maintenance and automation scripts:

```bash
# Sync filesystem with SurrealDB
nu scripts/kogral-sync.nu --direction bidirectional

# Backup knowledge base
nu scripts/kogral-backup.nu --format tar --compress

# Rebuild embeddings index
nu scripts/kogral-reindex.nu --provider fastembed --batch-size 10

# Import from Logseq
nu scripts/kogral-import-logseq.nu /path/to/logseq-graph

# Export to Logseq
nu scripts/kogral-export-logseq.nu /path/to/output

# Show statistics
nu scripts/kogral-stats.nu --format summary --show-tags
```

## Development

### Build and Test

```bash
# Build workspace
cargo build --workspace

# Run tests
cargo test --workspace

# Run linter
cargo clippy --workspace -- -D warnings

# Format code
cargo fmt --all

# Generate documentation
cargo doc --no-deps --open
```

### Quality Standards

This project follows strict Rust standards:
- ✅ Zero unsafe code (`#![forbid(unsafe_code)]`)
- ✅ No unwrap() in production code
- ✅ 100% documented public APIs
- ✅ Comprehensive test coverage (100+ tests)
- ✅ Idiomatic Rust patterns
- ✅ Configuration-driven design

## Documentation

**📚 Full documentation available as mdBook:**

```bash
# Install mdBook (one-time setup)
cargo install mdbook

# Serve documentation locally at http://localhost:3000
just docs::serve

# Or build static HTML
just docs::build
```

**Quick Links:**

### Getting Started
- [What is KOGRAL?](docs/kogral/what-is-kogral.md) - Overview and motivation
- [Core Concepts](docs/kogral/core-concepts.md) - Node types, relationships, multi-graph architecture
- [Quick Start Guide](docs/guides/quickstart.md) - Get up and running in 5 minutes
- [Installation Guide](docs/guides/installation.md) - Detailed installation instructions

### Architecture & Design
- [System Architecture](docs/architecture/overview.md) - Complete architecture with diagrams
- [Config-Driven Design](docs/architecture/config-driven.md) - Nickel configuration system explained
- [Storage Architecture](docs/storage/overview.md) - Hybrid filesystem + SurrealDB strategy
- [ADRs](docs/architecture/adrs/) - Architectural Decision Records

### Configuration
- [Configuration Overview](docs/config/overview.md) - How configuration works
- [Setup Guide](docs/setup/) - Initial setup and deployment
- [Nickel Schemas](schemas/) - Type-safe configuration schemas

### Usage
- [CLI Reference](docs/cli/) - All kogral-cli commands
- [MCP Integration](docs/apps/mcp-quickguide.md) - Claude Code integration (5-minute guide)
- [Use Cases](docs/guides/use-cases.md) - Real-world examples
- [Templates](docs/templates/) - Document templates guide

### Advanced
- [AI & Embeddings](docs/ai/) - Semantic search and embedding providers
- [Storage Backends](docs/storage/) - Filesystem, SurrealDB, In-Memory
- [API Reference](docs/api/) - Developer API documentation
- [Contributing](docs/contributing/) - Development guidelines

**Visual Guides:**
- [Architecture Diagram](docs/diagrams/architecture-overview.svg)
- [Node Types & Relationships](docs/diagrams/core-concepts.svg)
- [Config Composition Flow](docs/diagrams/config-composition.svg)
- [Storage Architecture](docs/diagrams/storage-architecture.svg)

> 💡 **Tip**: For the best reading experience, use `just docs::serve` to browse the full mdBook
> documentation with navigation, search, and interactive examples.

## Integration

### With Vapora (AI Agent Orchestration)

Deep integration with Vapora's agent system for AI-assisted development workflows:

**How It Works:**
- **Agent Executions → Knowledge Nodes**: Every agent task becomes an `Execution` node with full audit trail
- **Guidelines Inform Agents**: Vapora agents query KOGRAL guidelines before generating code
- **Patterns Guide Implementations**: Reusable patterns from KOGRAL drive automated code generation
- **Bidirectional Knowledge Flow**: Agents both read from and contribute to the knowledge graph

**Execution Node Example:**

```yaml
---
type: execution
task_type: code_generation
agent: rust-expert
outcome: success
context:
  - guideline-rust-errors
  - pattern-result-handling
---

# Agent Execution: Implement Error Handling

Agent: rust-expert
Task: Refactor error handling in kogral-core/parser.rs
Outcome: Success

Applied guidelines:
- [[guideline-rust-errors]] - Prefer Result<T, E> over panic!()
- [[pattern-result-handling]] - Use ? operator for propagation

Changes: @crates/kogral-core/src/parser.rs:42-67
```

[Learn more about Vapora](https://vapora.dev)

### With Logseq

Import/export compatibility with Logseq graphs:
- Bidirectional markdown format
- Wikilinks preserved
- YAML frontmatter conversion
- Journal entries support

### With Claude Code

Native MCP integration for seamless knowledge capture during development sessions.

## License

[License details to be added]

## Contributing

[Contributing guidelines to be added]

## Acknowledgments

Inspired by Logseq, Obsidian, and the Zettelkasten method. Built with modern Rust tooling and configuration management practices.