jesus/kogral

Fork 0

Jesús Pérez 22e9473e69

chore: add docs

2026-01-23 16:11:07 +00:00

16 KiB

Raw Blame History

Changelog

All notable changes to the Knowledge Base project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Changed

BREAKING: MCP Protocol Rebranding

All MCP URIs, tool names, and prompts updated to KOGRAL namespace
- URI Scheme: kb:// → kogral://
  - kb://project/notes → kogral://project/notes
  - kb://project/decisions → kogral://project/decisions
  - kb://project/guidelines → kogral://project/guidelines
  - kb://project/patterns → kogral://project/patterns
  - kb://shared/guidelines → kogral://shared/guidelines
  - kb://shared/patterns → kogral://shared/patterns
- Tool Names: kb/* → kogral/*
  - kb/search → kogral/search
  - kb/add_note → kogral/add_note
  - kb/add_decision → kogral/add_decision
  - kb/link → kogral/link
  - kb/get_guidelines → kogral/get_guidelines
  - kb/list_graphs → kogral/list_graphs
  - kb/export → kogral/export
  - kb/find_blocks → kogral/find_blocks
  - kb/find_todos → kogral/find_todos
  - kb/find_cards → kogral/find_cards
- Prompt Names: kb/* → kogral/*
  - kb/summarize_project → kogral/summarize_project
  - kb/find_related → kogral/find_related
- Server Name: kb-mcp → kogral-mcp
- Migration Required: Users must update ~/.config/claude/config.json:
```
{
  "mcpServers": {
-   "kb-mcp": {
-     "command": "/path/to/kb-mcp",
+   "kogral-mcp": {
+     "command": "/path/to/kogral-mcp",
-       "env": { "KB_DIR": "/path/to/.kb" }
+       "env": { "KOGRAL_DIR": "/path/to/.kogral" }
    }
  }
}
```
- Rationale: Complete branding consistency across all interfaces. Pre-release status (v0.x) allows breaking changes without user pain.
- Files updated:
  - crates/kb-mcp/src/resources.rs: All URI definitions and parsing
  - crates/kb-mcp/src/tools.rs: All tool name definitions and dispatch
  - crates/kb-mcp/src/prompts.rs: All prompt name definitions and dispatch
  - crates/kb-mcp/src/main.rs: Server name registration
  - crates/kb-mcp/tests/integration_test.rs: Test assertions updated
  - docs/apps/mcp-quickguide.md: All examples and references
  - docs/kogral/core-concepts.md: MCP protocol documentation
  - docs/api/mcp-tools.md: API reference documentation
  - README.md: MCP integration examples

Branding

Rebranded to KOGRAL (KOwledge GRAphs, Local-first)
- Updated project name from "Knowledge Base" to "KOGRAL" across all documentation
- New tagline: "Git-native knowledge graphs for developer teams"
- Updated description emphasizing structured knowledge management for developers
- Documentation folder renamed: docs/kb/ → docs/kogral/
- Documentation files renamed:
  - docs/kogral/what-is-kb.md → what-is-kogral.md
  - docs/kogral/why-kb.md → why-kogral.md
- Technical names maintained for compatibility: kb-core, kb-cli, kb-mcp (crate names), kb (CLI binary)
- Hybrid naming strategy: KOGRAL as primary brand, kb.vapora.dev as future alias
- Files updated:
  - README.md: Title, description, and branding
  - Cargo.toml (workspace): Homepage, description, repository metadata
  - crates/kb-core/Cargo.toml: Package description
  - crates/kb-cli/Cargo.toml: Package description
  - crates/kb-mcp/Cargo.toml: Package description
  - crates/kb-core/src/lib.rs: Module documentation comments
  - crates/kb-core/src/models.rs: Type documentation comments
  - crates/kb-cli/src/main.rs: CLI description and messages
  - docs/kogral/what-is-kogral.md: Full KOGRAL branding with acronym explanation
  - docs/kogral/core-concepts.md: All "KB" references replaced with "KOGRAL"
  - docs/README.md: Title and section headers
  - docs/book.toml: mdBook title and description
  - docs/SUMMARY.md: Navigation titles
  - .claude/CLAUDE.md: Project description and documentation links

BREAKING: Filesystem Paths and Environment Variables

Directory structure renamed from .kb/ to .kogral/
- Project directory: .kb/ → .kogral/
- Shared directory: .kb-shared/ → .kogral-shared/
- Configuration paths updated throughout codebase
- All storage paths use .kogral/ prefix
Environment variable renamed from KB_DIR to KOGRAL_DIR
- MCP server configuration requires KOGRAL_DIR environment variable
- CLI tools respect KOGRAL_DIR for custom directory location
Migration Required:
1. Rename existing directory: mv .kb .kogral
2. Update environment variables: KB_DIR → KOGRAL_DIR
3. Update config files referencing .kb/ paths
Rationale: Complete branding consistency across all filesystem operations. Pre-release status allows breaking changes.
Files updated:
- All Rust source files in crates/: Path constants and variable names
- crates/kb-core/src/config/loader.rs: Configuration path discovery
- crates/kb-core/src/storage/filesystem.rs: Storage paths
- crates/kb-cli/src/main.rs: CLI messages and examples
- crates/kb-mcp/src/main.rs: Environment variable handling
- All documentation in docs/: Examples and instructions
- README.md: Setup and usage examples
- .claude/CLAUDE.md: Project configuration paths

Added

Core Infrastructure

Initial project structure with Cargo workspace (kb-core, kb-cli, kb-mcp)
Core graph models (Node, Edge, Graph) with 6 node types and 6 relationship types
Config-driven architecture using Nickel schemas (NCL → JSON → Rust)
Markdown parser with Logseq compatibility (YAML frontmatter + wikilinks)
Storage backends: Filesystem (default), In-Memory, SurrealDB (feature-gated)
Embedding integration via rig-core (OpenAI, Claude, Ollama) + fastembed local fallback
Tera template engine for document generation and export

Logseq Blocks Support (ADR-004)

Block Data Structures (crates/kb-core/src/models.rs):
- TaskStatus enum: TODO, DOING, DONE, LATER, NOW, WAITING, CANCELLED
- BlockProperties struct: tags, task status, custom properties, block/page references
- Block struct: hierarchical content blocks with properties and children
- Node.blocks field: Optional cached block structure (lazy parsing)
BlockParser (crates/kb-core/src/block_parser.rs):
- Bidirectional parser: Markdown outliner ↔ Block structures
- Supports: task markers, #tags, custom properties (key:: value), ((block-refs)), page-refs
- Hierarchical parsing based on indentation
- Round-trip fidelity for Logseq import/export
- 15 comprehensive tests covering parsing, serialization, and round-trips
Block Query API:
- Node::get_blocks(): Lazy parsing from content with caching
- Node::find_blocks_by_tag(): Find blocks with specific tag
- Node::find_all_todos(): Find all task blocks
- Node::find_blocks_by_status(): Find blocks by task status
- Node::find_blocks_by_property(): Find blocks with custom property
- Graph::find_blocks_by_tag(): Search blocks across all nodes
- Graph::find_all_todos(): Find TODOs across entire graph
- 6 integration tests for Node and Graph block queries
SurrealDB Schema (schemas/surrealdb/blocks.surql):
- block table with indexes on node_id, block_id, tags, status, parent_id
- Full-text search index on content
- Support for hierarchical queries and tag-based filtering
- Migration queries and example usage patterns
Logseq Import/Export (crates/kb-core/src/import/logseq.rs, crates/kb-core/src/export/logseq.rs):
- Round-trip import: Logseq markdown → KB Node with blocks
- Property parsing: key:: value format, tags (tag and #tag), references, timestamps
- Export to Logseq page/journal formats with block serialization
- 12 comprehensive tests covering import/export round-trips
MCP Block Tools (crates/kb-mcp/src/tools.rs):
- kb/find_blocks: Search blocks by tag, task status, or custom property
- kb/find_todos: Find all TODO blocks across KB
- kb/find_cards: Find all flashcard blocks (#card tag)
- Fixed borrowing issues with two-phase data collection pattern
Configuration Schema (schemas/kb-config.ncl, config/*.ncl):
- Added BlocksConfig schema with 4 settings:
  - enabled: Enable/disable Logseq blocks parsing (default: false, opt-in)
  - parse_on_import: Auto-parse blocks from Logseq imports (default: true)
  - serialize_on_export: Serialize blocks to outliner format on export (default: true)
  - enable_mcp_tools: Enable block-related MCP tools (default: true)
- Updated all config files (defaults.ncl, production.ncl, minimal.ncl)
- Validated: All configs export to JSON successfully
Documentation:
- Complete technical design: docs/architecture/logseq-blocks-design.md
- Architectural Decision Record: docs/architecture/adrs/004-logseq-blocks-support.md
- 6-phase implementation plan documented
- Use cases and examples for flashcards, task tracking, and block references

Applications

CLI tool (kb-cli) with 13 commands (init, add, search, link, sync, serve, etc.)
MCP server (kb-mcp) with 10 tools (7 core + 3 block tools), 6 resources, 2 prompts for Claude Code integration
NuShell maintenance scripts (6 scripts: sync, backup, reindex, import/export Logseq, stats)

Configuration System (Nickel)

Complete Nickel configuration schema following typedialog/provisioning pattern
Schema contracts (schemas/kb/contracts.ncl) - Type definitions with validation
Default values (schemas/kb/defaults.ncl) - Base configuration values
Composition helpers (schemas/kb/helpers.ncl) - merge_with_override, compose_config
Mode overlays (schemas/kb/modes/{dev,prod,test}.ncl) - Environment-specific tuning
Runtime configurations (.kb-config/core/kb.ncl, .kb-config/platform/*.ncl)
Double validation pattern: Nickel contracts + serde deserialization
Config export to JSON for Rust consumption (.kb-config/targets/*.json)

Templates

Tera templates for 6 document types (note, decision, guideline, pattern, journal, execution)
4 export format templates (Logseq page/journal, summary, JSON)
Customizable template system with frontmatter generation

Documentation (mdBook)

Complete mdBook documentation structure with SUMMARY.md navigation
4 SVG diagrams for visual guides:
- architecture-overview.svg - Complete system architecture
- core-concepts.svg - Node types and relationships
- config-composition.svg - Configuration flow (Schema → Defaults → Mode → User → JSON)
- storage-architecture.svg - Hybrid storage strategy
11 major documentation sections (kb/, guides/, architecture/, setup/, config/, storage/, ai/, templates/, cli/, apps/, api/, contributing/)
ADR documentation (ADR-001: Nickel vs TOML, ADR-002: FastEmbed + AI providers, ADR-003: Hybrid storage)
Use cases documentation (8 real-world scenarios)
MCP quick guide (5-minute setup for Claude Code)
Config-driven architecture deep dive
Storage architecture deep dive with code examples
docs/README.md - Comprehensive guide for using and building documentation

Build System

Modular justfile system (7 modules: build, test, dev, ci, nickel, docs, scripts)
Nickel validation and export recipes (just nickel::validate-all, just nickel::export-all)
mdBook documentation recipes (just docs::serve, just docs::build, just docs::test)
CI/CD pipeline recipes (format, lint, test, build validation)
NuShell script validation and execution recipes

Project Documentation

Enhanced README.md with complete documentation links and visual diagram references
Directory structure documentation with detailed explanations
Quick start guide with MCP integration
Integration guides (Vapora, Logseq, Claude Code)
CHANGELOG.md following Keep a Changelog format

Changed

Updated README.md with comprehensive documentation links (mdBook, guides, architecture, config)
Enhanced directory structure documentation with .kb-config/ and schemas/kb/ details
Improved documentation section with visual diagrams and just recipe references
Blocks Feature Documentation:
- README.md: Added Logseq blocks section with examples, features, and configuration
- README.md: Updated architecture diagram to include BlockParser
- README.md: Added 3 new MCP tools to integration section
- docs/kb/core-concepts.md: Added comprehensive "Logseq Content Blocks" section with examples, use cases, and queries
- docs/api/mcp-tools.md: Added "Block Tools" section documenting kb/find_blocks, kb/find_todos, kb/find_cards
- docs/api/mcp-tools.md: Updated overview from 7 to 10 tools

Infrastructure

Cargo workspace with 3 crates
Feature flags: filesystem (default), surrealdb, fastembed, full
90 tests across workspace (81 kb-core + 5 kb-mcp + 4 kb-cli)
- 15 tests for block parser
- 12 tests for Logseq import/export
- 6 tests for block queries
mdBook integration for documentation (serves on http://localhost:3000)
Nickel → JSON → Rust configuration pipeline
Justfile modules: build, test, dev, ci, nickel, docs, scripts
CI/CD pipeline recipes (format, lint, test, build validation)
mdBook documentation structure with SUMMARY.md
NuShell script validation recipes

[1.0.0] - TBD

Initial release (planned).

Planned Features

Full FilesystemStorage implementation with file watching
Complete Query Engine with semantic search
Guideline inheritance resolution (shared → local override priority)
SurrealDB schema and complete backend implementation
Sync mechanism: bidirectional Filesystem ↔ SurrealDB
FastEmbed local embeddings integration
API provider integrations (OpenAI, Claude, Ollama) for embeddings
Cross-graph queries (project + shared knowledge bases)
Template customization system
Export to multiple formats (Logseq, JSON, Markdown)
Import from Logseq graphs
MCP protocol compliance testing
Production-ready CLI tool
Performance benchmarks
Security audit

Version History

Version Numbering

This project follows semantic versioning (MAJOR.MINOR.PATCH):

MAJOR: Incompatible API changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Release Schedule

Alpha (0.x.x): API unstable, features incomplete
Beta (1.0.0-beta.x): API stable, features complete, testing phase
Stable (1.0.0+): Production ready

Feature Roadmap

Phase 1: Foundation ✅ (Completed)

Core models and graph structure
Nickel configuration system
Markdown parser with Logseq compatibility
Storage trait abstraction
CLI structure with clap
MCP server protocol implementation
NuShell maintenance scripts
Documentation structure

Phase 2: Integration (In Progress)

Full FilesystemStorage with file watching
SurrealDB backend implementation
Query engine with text + semantic search
Embedding provider integrations
Guideline inheritance resolution
Sync mechanism implementation

Phase 3: Polish (Planned)

Performance optimization
Comprehensive error handling
Production testing
Security audit
API stabilization
Release preparation

Migration Guides

Upgrading from 0.x to 1.0

(To be documented when 1.0 is released)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

(To be determined)

16 KiB Raw Blame History

Changelog

[Unreleased]

Changed

BREAKING: MCP Protocol Rebranding

Branding

BREAKING: Filesystem Paths and Environment Variables

Added

Core Infrastructure

Logseq Blocks Support (ADR-004)

Applications

Configuration System (Nickel)

Templates

Documentation (mdBook)

Build System

Project Documentation

Changed

Infrastructure

[1.0.0] - TBD

Planned Features

Version History

Version Numbering

Release Schedule

Feature Roadmap

Phase 1: Foundation ✅ (Completed)

Phase 2: Integration (In Progress)

Phase 3: Polish (Planned)

Migration Guides

Upgrading from 0.x to 1.0

Contributing

License

16 KiB

Raw Blame History