KOGRAL

KOwledge GRAphs, Local-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

┌─────────────────────────────────────────────────────────────┐
│                    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

# 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

# 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

# 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

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:

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:

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

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

# \.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 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 for complete API reference.

NuShell Scripts

Maintenance and automation scripts:

# 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

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

# 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? - Overview and motivation
• Core Concepts - Node types, relationships, multi-graph architecture
• Quick Start Guide - Get up and running in 5 minutes
• Installation Guide - Detailed installation instructions

Architecture & Design

• System Architecture - Complete architecture with diagrams
• Config-Driven Design - Nickel configuration system explained
• Storage Architecture - Hybrid filesystem + SurrealDB strategy
• ADRs - Architectural Decision Records

Configuration

• Configuration Overview - How configuration works
• Setup Guide - Initial setup and deployment
• Nickel Schemas - Type-safe configuration schemas

Usage

• CLI Reference - All kogral-cli commands
• MCP Integration - Claude Code integration (5-minute guide)
• Use Cases - Real-world examples
• Templates - Document templates guide

Advanced

• AI & Embeddings - Semantic search and embedding providers
• Storage Backends - Filesystem, SurrealDB, In-Memory
• API Reference - Developer API documentation
• Contributing - Development guidelines

Visual Guides:

• Architecture Diagram
• Node Types & Relationships
• Config Composition Flow
• Storage Architecture

💡 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:

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

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.