go-knowledge-core

A local, CLI-first personal knowledge base engine with full-text search, backlinks, and graph traversal capabilities.

Features

• 📝 Markdown Notes: Store notes in Markdown format with YAML frontmatter metadata
• 🔗 Wiki-style Links: Create connections between notes using [[note-title]] syntax
• 🔍 Full-text Search: Fast search across all note content and titles
• ↩️ Backlinks: Automatically track which notes reference each note
• 🕸️ Graph Traversal: Explore connections between notes with BFS/DFS algorithms
• 🏷️ Tags: Organize notes with multiple tags
• 💾 Embedded Database: Uses BBolt (embedded key-value store) for fast indexing
• ⚡ Fast: Written in Go for high performance and low memory usage

Installation

# Clone the repository
git clone https://github.com/BaseMax/go-knowledge-core.git
cd go-knowledge-core

# Build the application
go build

# Or install globally
go install

Quick Start

# Initialize a new knowledge base
./go-knowledge-core init

# Run the interactive demo
./demo.sh

# Create example notes in the notes directory
# See the notes/ folder for examples

# Sync markdown files to the database
./go-knowledge-core sync

# List all notes
./go-knowledge-core list

# Search for notes
./go-knowledge-core search "knowledge management"

# Show a specific note
./go-knowledge-core show getting-started-with-knowledge-core

# View statistics
./go-knowledge-core stats

Demo

Run the included demo script to see all features in action:

./demo.sh

The demo will:

1. Initialize a new knowledge base
2. Create sample notes about programming topics
3. Show full-text search capabilities
4. Demonstrate backlinks tracking
5. Display graph traversal and path finding
6. Show tag-based organization
7. Present knowledge base statistics

Usage

Adding Notes

# Add a note from a file
./go-knowledge-core add notes/my-note.md

# Add a note from stdin
echo "# My Note" | ./go-knowledge-core add

# Add a note with tags
./go-knowledge-core add notes/my-note.md --tags "tag1,tag2"

Searching Notes

# Full-text search
./go-knowledge-core search "machine learning"

# Search is case-insensitive and matches multiple words
./go-knowledge-core search distributed systems

Viewing Notes

# Show a note by ID
./go-knowledge-core show <note-id>

# List all notes
./go-knowledge-core list

Working with Links

# View backlinks (notes that link to this note)
./go-knowledge-core backlinks <note-id>

# Traverse the graph from a note (depth 2 by default)
./go-knowledge-core graph traverse <note-id> 2

# Find path between two notes
./go-knowledge-core graph path <start-id> <end-id>

# Find orphan notes (no links in or out)
./go-knowledge-core graph orphans

Using Tags

# List notes with a specific tag
./go-knowledge-core tags list <tag-name>

# View all tags in statistics
./go-knowledge-core stats

Database Management

# Sync markdown files from notes directory
./go-knowledge-core sync

# Delete a note
./go-knowledge-core delete <note-id>

# Use custom database location
./go-knowledge-core --db /path/to/custom.db list

Markdown Format

Notes should be written in Markdown with YAML frontmatter:

---
title: My Note Title
tags: [tag1, tag2, tag3]
---

# My Note Title

Your note content here.

## Links

You can link to other notes using wiki-style links: [[another-note]]

The link text should match the title of the target note.

Creating Links

Use double brackets to create links to other notes:

Check out my [[project-ideas]] and [[learning-resources]].

Links are automatically:

• Extracted and stored as relationships
• Converted to IDs based on note titles
• Tracked as backlinks in the target notes

Architecture

The application consists of several components:

• Note Parser (note.go): Parses Markdown with YAML frontmatter and extracts links
• Store (store.go): BBolt-based storage with indexing for search, tags, and backlinks
• Graph (graph.go): Graph traversal algorithms (BFS/DFS) for exploring connections
• CLI (main.go): Command-line interface using Cobra

Storage Structure

The BBolt database contains four buckets:

• notes: Stores complete note data (JSON)
• index: Full-text search index (word → note IDs)
• backlinks: Backlink relationships (note ID → linking note IDs)
• tags: Tag index (tag → note IDs)

Example Workflow

# 1. Initialize
./go-knowledge-core init

# 2. Create some notes in the notes/ directory
cat > notes/golang.md << EOF
---
title: Go Programming
tags: [programming, golang]
---

# Go Programming

Go is a statically typed, compiled language. See [[project-ideas]] for Go projects.
EOF

# 3. Sync to database
./go-knowledge-core sync

# 4. Search
./go-knowledge-core search golang

# 5. Explore connections
./go-knowledge-core show go-programming
./go-knowledge-core backlinks go-programming
./go-knowledge-core graph traverse go-programming 2

# 6. View statistics
./go-knowledge-core stats

Performance

• Indexing: O(n*m) where n = number of words, m = number of notes
• Search: O(w) where w = number of words in query
• Graph traversal: O(V + E) where V = vertices, E = edges
• Storage: Uses BBolt's B+tree structure for efficient key-value operations

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Max Base

Related Projects

• Obsidian - A powerful knowledge base that works on local Markdown files
• Roam Research - A note-taking tool for networked thought
• Org-roam - Org-mode based knowledge management system