jesus/kogral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: init project

Browse Source
This commit is contained in:
Jesús Pérez 2026-01-23 16:08:43 +00:00
commit 44cd68f2ed
1 changed files with 474 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

474
README.md Normal file
View File

@ -0,0 +1,474 @@
# 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.