chore: init project
This commit is contained in:
Jesús Pérez
commit
44cd68f2ed
474
README.md
Normal file
474
README.md
Normal 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.
|
||||||
Loading…
x
Reference in New Issue
Block a user