commit 44cd68f2edcd9cea3b990d38ed220f753925c866 Author: Jesús Pérez Date: Fri Jan 23 16:08:43 2026 +0000 chore: init project diff --git a/README.md b/README.md new file mode 100644 index 0000000..510042f --- /dev/null +++ b/README.md @@ -0,0 +1,474 @@ +# 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.