# KOGRAL
KoGraL Logo
**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 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 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.