jesus/kogral
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
kogral/CHANGELOG.md
Jesús Pérez 22e9473e69
chore: add docs
2026-01-23 16:11:07 +00:00

337 lines
16 KiB
Markdown
Raw Permalink 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](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [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`:
```diff
{
"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** (**KO**wledge **GRA**phs, **L**ocal-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](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)
- [x] Core models and graph structure
- [x] Nickel configuration system
- [x] Markdown parser with Logseq compatibility
- [x] Storage trait abstraction
- [x] CLI structure with clap
- [x] MCP server protocol implementation
- [x] NuShell maintenance scripts
- [x] 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](docs/contributing/development.md) for development setup and guidelines.
---
## License
(To be determined)
Reference in New Issue View Git Blame Copy Permalink