ML Notes

A powerful command-line note-taking application with semantic vector search capabilities, powered by SQLite and lil-rag for intelligent search.

✨ Features

📝 Complete Note Management - Create, edit, delete, and organize notes with powerful CLI tools
🌐 Website Import - Import web pages as notes with headless browser support and image URL preservation
🌐 Modern Web Interface - Beautiful, responsive web UI with real-time markdown preview and graph visualization
🏷️ Smart Tagging System - Organize notes with tags, search by tags, and manage tag collections
🔍 Triple Search Methods - Semantic vector search, traditional text search, and tag-based search
📊 Interactive Graph Visualization - Explore relationships between notes with D3.js-powered graph views
🚀 Fast & Lightweight - Built with Go and SQLite for maximum performance
🔌 Lil-Rag Integration - Advanced semantic search with project-aware namespacing
📊 Smart Search Isolation - Project-scoped search prevents cross-contamination between different note collections
🧠 AI-Powered Analysis - Deep analysis with custom prompts and reasoning visibility
✏️ Advanced Editor Features - Split-pane markdown editor with synchronized scrolling and focus-based behavior
🛠️ Highly Configurable - Customize everything from storage paths to AI models
🐛 Debug Support - Built-in debugging for troubleshooting and development
🤖 MCP Server - Model Context Protocol server for LLM integration (Claude Desktop)
🔄 Smart Reindexing - Automatic vector index management and optimization

📋 Table of Contents

Installation
Quick Start
Configuration
Web Interface
CLI Usage
MCP Server
- Claude Desktop Integration
- Available Tools
Development
Contributing
License

🚀 Installation

Prerequisites

Go 1.22 or higher
CGO support (for SQLite integration)
(Optional) Lil-Rag service for enhanced semantic search
(Optional) Ollama for AI-powered features

From Source

# Clone the repository
git clone https://github.com/streed/ml-notes.git
cd ml-notes

# Build the application
make build

# Install to your PATH
sudo make install

Pre-built Binaries

Download the latest release from the Releases page.

# Download and extract (Linux/macOS example)
wget https://github.com/streed/ml-notes/releases/latest/download/ml-notes-linux-amd64.tar.gz
tar -xzf ml-notes-linux-amd64.tar.gz
sudo mv ml-notes /usr/local/bin/

Using Make

# Build for current platform
make build

# Install to /usr/local/bin (requires sudo)
make install

# Build and install in one step
make all

# Clean build artifacts
make clean

# Run tests
make test

# Development build with race detector
make dev

Cross-Platform Builds

ML Notes supports building for multiple platforms:

# Build for all platforms (Linux, macOS, Windows)
make build-all

# Build for specific platforms
make build-linux    # Linux AMD64
make build-darwin   # macOS (Intel & Apple Silicon)
make build-windows  # Windows AMD64

# Create release packages
make release

Platform Support:

✅ Linux AMD64 - Full native support
✅ macOS Intel (AMD64) - Native and cross-compilation support
✅ macOS Apple Silicon (ARM64) - Native and cross-compilation support
✅ Windows AMD64 - Native and cross-compilation support

Cross-Compilation Notes:

Cross-compilation requires appropriate toolchains (clang for macOS, mingw for Windows)
For best results, build natively on target platforms
CGO is required for sqlite-vec support
Use make build-native for automatic platform detection

🎯 Quick Start

Initialize configuration:

# Interactive setup (recommended for first-time users)
ml-notes init --interactive

# Or quick setup with defaults
ml-notes init

# Or custom setup with flags
ml-notes init \
  --data-dir ~/my-notes \
  --ollama-endpoint http://localhost:11434 \
  --summarization-model llama3.2:latest \
  --enable-summarization

Add your first note:

ml-notes add -t "My First Note" -c "This is the content of my first note"

# Or add a note with tags
ml-notes add -t "Project Ideas" -c "Some great ideas for the next project" --tags "ideas,projects,todo"

List your notes:

ml-notes list

Search with vector similarity:

ml-notes search --vector "machine learning concepts"

Search by tags:

ml-notes search --tags "projects,ideas"

Start the web interface:

ml-notes serve
# Open http://localhost:21212 in your browser

⚙️ Configuration

ML Notes stores its configuration in ~/.config/ml-notes/config.json.

Initial Setup

Run the interactive setup:

ml-notes init -i

Or configure with flags:

ml-notes init \
  --data-dir ~/.local/share/ml-notes \
  --ollama-endpoint http://localhost:11434 \
  --summarization-model llama3.2:latest \
  --enable-summarization

Configuration Options

Option	Description	Default
`data-dir`	Where notes database is stored	`~/.local/share/ml-notes`
`ollama-endpoint`	Ollama API endpoint	`http://localhost:11434`
`lilrag-url`	Lil-Rag service endpoint	`http://localhost:12121`
`summarization-model`	Model for AI analysis	`llama3.2:latest`
`enable-summarization`	Enable/disable analysis features	`true`
`enable-auto-tagging`	Enable/disable AI auto-tagging	`true`
`max-auto-tags`	Maximum auto-generated tags	`5`
`editor`	Default editor for note editing	Auto-detect
`debug`	Enable debug logging	`false`

Lil-Rag Integration

ML Notes uses Lil-Rag for advanced semantic search with project-aware namespacing:

Project Isolation: Each project directory gets its own search namespace (e.g., ml-notes-myproject), preventing search results from mixing between different projects.

Setup Lil-Rag Service:

# Install and run lil-rag service
go install github.com/stillmatic/lil-rag@latest
lil-rag serve --port 12121

# Configure ML Notes to use lil-rag
ml-notes config set lilrag-url http://localhost:12121

Benefits:

Project Scoping: Search only within your current project's notes
Cross-Project Isolation: Notes from different projects don't contaminate search results
Automatic Namespacing: Project directory name automatically determines search scope
Fallback Support: Gracefully falls back to text search when lil-rag is unavailable

Managing Configuration

# View current configuration
ml-notes config show

# Update settings
ml-notes config set ollama-endpoint http://localhost:11434
ml-notes config set lilrag-url http://localhost:12121
ml-notes config set summarization-model llama3.2:latest
ml-notes config set enable-auto-tagging true
ml-notes config set max-auto-tags 5
ml-notes config set editor "code --wait"
ml-notes config set debug true

🌐 Web Interface

ML Notes includes a modern, responsive web interface that provides an intuitive way to manage your notes, visualize relationships, and edit content with a powerful markdown editor.

Starting the Web Server

# Start the web server on default port (21212)
ml-notes serve

# Start on specific host and port
ml-notes serve --host 0.0.0.0 --port 3000

# Access the web interface
open http://localhost:21212

Web UI Features

📝 Smart Markdown Editor

Focus-Based Split Pane: Editor automatically appears when you focus on editing areas
Real-Time Preview: Live markdown rendering with synchronized scrolling
Auto-Scroll: Preview automatically follows your cursor when typing extends the editor
Smooth Transitions: Elegant animations for pane resizing and focus changes

🏷️ Tag Management

Visual tag display with removal capabilities
Tag input with comma-separated support
Filter notes by tags using the sidebar dropdown
Auto-tagging integration with AI-powered suggestions

🔍 Integrated Search

Real-time search as you type
Vector search integration for semantic similarity
Tag-based filtering
Search results with content previews

📊 Note Organization

Sidebar with all notes and metadata
Chronological organization with creation dates
Active note highlighting
Quick navigation between notes

🎨 Theme Support

Light and dark theme toggle
Consistent theming across all components
Paper-like texture for comfortable reading
Responsive design for all screen sizes

🤖 AI Integration

One-click auto-tagging for notes
AI-powered note analysis with custom prompts
Integration with Ollama for local AI processing
Analysis results with thinking process visibility

Graph Visualization

📊 Interactive Note Graph

D3.js-Powered Visualization: Smooth, interactive graph showing note relationships
Smart Node Positioning: Isolated notes stay near center, connected notes spread outward
Connection-Based Sizing: Node size reflects number of connections to other notes
Tag-Based Relationships: Notes connected by shared tags with weighted connections
Color-Coded Groups: Different colors for different note clusters/topics

🎮 Interactive Features

Zoom and Pan: Scroll to zoom, drag to pan around the graph
Node Interaction: Click nodes to navigate directly to notes
Hover Tooltips: See note titles, tags, and connection counts
Drag Nodes: Manually position nodes by dragging
Filter Controls: Filter by tag, minimum connections, and maximum nodes displayed

🎯 Graph Controls

Filter Panel:
- Filter by specific tags
- Set minimum connection threshold
- Limit maximum nodes displayed
Zoom Controls: Zoom in/out buttons and fit-to-view
View Options: Toggle between full graph view and embedded preview
Reset View: Return to optimal view with one click

📱 Responsive Design

Desktop Experience: Full-featured graph with all controls and interactions
Mobile Friendly: Simplified interface optimized for touch devices
Embedded Mode: Compact graph view for the main dashboard
Performance Optimized: Efficient rendering for large note collections

🔗 Graph Navigation

Direct Navigation: Click any node to jump to that note
Context Preservation: Graph remembers position when returning
Visual Feedback: Selected and hovered nodes are highlighted
Breadcrumb Integration: Easy return to main interface

Web Interface Keyboard Shortcuts

Shortcut	Action
`Ctrl/Cmd + S`	Save current note
`Ctrl/Cmd + N`	Create new note
`Ctrl/Cmd + /`	Toggle theme
`Escape`	Close modals

Web Server Configuration

The web server supports additional configuration options:

# Enable custom CSS
ml-notes config set webui-custom-css true

# Set default theme
ml-notes config set webui-theme dark

API Endpoints

The web server also exposes REST API endpoints:

GET /api/v1/notes - List all notes
POST /api/v1/notes - Create new note
GET /api/v1/notes/{id} - Get specific note
PUT /api/v1/notes/{id} - Update note
DELETE /api/v1/notes/{id} - Delete note
POST /api/v1/notes/search - Search notes
GET /api/v1/tags - List all tags
GET /api/v1/graph - Get graph data for visualization
POST /api/v1/auto-tag/suggest/{id} - Get AI tag suggestions

📚 CLI Usage

Managing Notes

Add a Note

# Interactive mode (opens your editor)
ml-notes add -t "Title"

# With content directly
ml-notes add -t "Title" -c "Content"

# With tags
ml-notes add -t "Project Notes" -c "Important project details" --tags "project,important,todo"

# From stdin
echo "Content" | ml-notes add -t "Title"

# Use specific editor
ml-notes add -t "Code Review" --editor-cmd "code --wait"

List Notes

# List recent notes
ml-notes list

# With pagination
ml-notes list --limit 10 --offset 20

# Short format (ID and title only)
ml-notes list --short

Get a Note

ml-notes get <note-id>

Edit a Note

# Edit note in your default editor (includes tags)
ml-notes edit 123

# Edit title only
ml-notes edit -t 123

# Edit content only
ml-notes edit -c 123

# Use a specific editor
ml-notes edit -e "code --wait" 123

Note: When editing in your editor, the note format includes tags:

Title: Your Note Title
Tags: tag1, tag2, tag3
---
Your note content goes here

Delete Notes

# Delete a single note
ml-notes delete 123

# Delete multiple notes
ml-notes delete 123 456 789

# Skip confirmation prompt
ml-notes delete -f 123

# Delete all notes (use with extreme caution!)
ml-notes delete --all

Import Website Content

# Import a website as a new note
ml-notes import-url https://blog.example.com/article

# Import with custom tags
ml-notes import-url https://docs.example.com/guide --tags "docs,reference,tutorial"

# Import with AI auto-tagging
ml-notes import-url https://example.com/post --auto-tag

# Import with custom timeout for slow-loading sites
ml-notes import-url https://heavy-site.com --timeout 60s

Features:

Headless Browser: Uses Chrome to render JavaScript and dynamic content
Smart Content Extraction: Prioritizes main content areas (article, main) while filtering out navigation, ads, and sidebars
Image URL Preservation: Converts relative image URLs to absolute URLs while maintaining external/CDN links
Markdown Conversion: Clean HTML-to-markdown conversion with proper formatting
Security-First: Uses secure browser settings with SSL validation for live websites

Tag Management

Managing Tags

# List all tags in the system
ml-notes tags list

# Add tags to an existing note
ml-notes tags add 123 --tags "urgent,important"

# Remove specific tags from a note
ml-notes tags remove 123 --tags "old,outdated"

# Replace all tags for a note
ml-notes tags set 123 --tags "research,ai,final"

# Remove all tags from a note
ml-notes tags set 123 --tags ""

Tag Search

# Search for notes with specific tags
ml-notes search --tags "project,important"

# Search for notes with any of the specified tags
ml-notes search --tags "research,ai,ml"

# Combine with other search options
ml-notes search --tags "project" --limit 5 --short

Searching

Text Search

# Search in titles and content
ml-notes search "golang"

# Limit results
ml-notes search --limit 5 "machine learning"

# Short format showing only IDs and titles
ml-notes search --short "programming"

Vector Search

# Semantic similarity search (returns most similar note by default)
ml-notes search --vector "neural networks and deep learning"

# Get top 5 most similar notes
ml-notes search --vector --limit 5 "machine learning concepts"

# Finds related notes even without exact matches
ml-notes search --vector "AI concepts"

Tag Search

# Search by single tag
ml-notes search --tags "research"

# Search by multiple tags (finds notes with ANY of these tags)
ml-notes search --tags "project,important,urgent"

# Combine tag search with limits and formatting
ml-notes search --tags "ai,ml" --limit 10 --short

# Tag-only search (no text query needed)
ml-notes search --tags "todo"

Advanced Features

Project-Scoped Search

ML Notes automatically isolates search results by project directory:

# In /home/user/project1
ml-notes search --vector "machine learning"  # Searches ml-notes-project1 namespace

# In /home/user/project2  
ml-notes search --vector "machine learning"  # Searches ml-notes-project2 namespace

Debug Mode

# Enable for current command
ml-notes --debug search --vector "test"

# Enable persistently
ml-notes config set debug true

AI-Powered Analysis

Basic Analysis

# Analyze a single note
ml-notes analyze 123

# Analyze multiple notes together
ml-notes analyze 1 2 3

# Analyze all notes
ml-notes analyze --all

# Analyze recent notes
ml-notes analyze --recent 10

Custom Analysis Prompts

# Focus on technical aspects
ml-notes analyze 123 -p "Focus on technical implementation details"

# Analyze all notes with a specific tag
ml-notes search --tags "research" --analyze -p "Summarize research findings"

# Extract insights and patterns
ml-notes analyze --all -p "What are the recurring themes and patterns?"

# Comparative analysis
ml-notes analyze 1 2 3 -p "Compare and contrast these approaches"

# Business-focused analysis
ml-notes analyze --recent 5 -p "What business opportunities are mentioned?"

Search with Analysis

# Analyze search results
ml-notes search --analyze "machine learning"

# Custom analysis of search results
ml-notes search --analyze -p "Focus on practical applications" "algorithms"

# Show both analysis and detailed results
ml-notes search --analyze --show-details "python"

Analysis Features

Reasoning Visibility: See the AI's thought process with formatted thinking sections
Custom Prompts: Target analysis with specific questions or focus areas
Multi-Note Analysis: Analyze relationships and patterns across multiple notes
Search Integration: Analyze search results for deeper insights

Configuration

# Enable/disable analysis features
ml-notes config set enable-summarization true

# Set the analysis model
ml-notes config set summarization-model llama3.2:latest

# View current settings
ml-notes config show

🤖 MCP Server

ML Notes includes a Model Context Protocol (MCP) server that allows LLMs like Claude to interact with your notes programmatically.

Claude Desktop Integration

Add ML Notes to your Claude Desktop configuration:

Open your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/claude/claude_desktop_config.json
Add the ML Notes MCP server:

{
  "mcpServers": {
    "ml-notes": {
      "command": "ml-notes",
      "args": ["mcp"]
    }
  }
}

Restart Claude Desktop

Available Tools

The MCP server provides the following tools to LLMs:

Note Management

add_note - Create a new note with title, content, and optional tags
get_note - Retrieve a specific note by ID (includes tags)
update_note - Modify existing note title, content, or tags
delete_note - Remove a note from the database
list_notes - List notes with pagination support (shows tags)

Tag Management

list_tags - List all tags in the system
update_note_tags - Update tags for a specific note

Search Capabilities

search_notes - Search using vector similarity, text matching, or tag search
- Supports semantic vector search, keyword search, and tag-based search
- Configurable result limits
- Automatically uses best search method
- Tag search with comma-separated tag lists

Resources

The MCP server exposes these resources:

notes://recent - Get the most recently created notes
notes://stats - Database statistics and configuration
notes://config - Current ML Notes configuration
notes://note/{id} - Access specific note by ID

Prompts

Pre-configured prompts for common tasks:

search_notes - Structured search prompt with query parameters
analyze_notes - Generate AI-powered analysis of your note collection

Starting the MCP Server

# Start MCP server (for use with LLM clients)
ml-notes mcp

# The server communicates via stdio for Claude Desktop integration

🔧 Development

Project Structure

ml-notes/
├── cmd/              # CLI commands
│   ├── root.go      # Root command
│   ├── add.go       # Add note command
│   ├── list.go      # List notes command
│   ├── get.go       # Get note command
│   ├── search.go    # Search command
│   ├── serve.go     # Web server command
│   ├── init.go      # Init configuration
│   ├── config.go    # Config management
│   ├── reindex.go   # Reindex embeddings
│   ├── detect.go    # Detect dimensions
│   └── mcp.go       # MCP server command
├── internal/         # Internal packages
│   ├── api/         # Web server and API endpoints
│   ├── autotag/     # AI-powered auto-tagging
│   ├── config/      # Configuration management
│   ├── database/    # Database operations
│   ├── embeddings/  # Embedding generation
│   ├── logger/      # Logging utilities
│   ├── mcp/         # MCP server implementation
│   ├── models/      # Data models
│   ├── search/      # Search implementation
│   └── summarize/   # AI analysis features
├── web/              # Web interface assets
│   ├── templates/   # HTML templates
│   │   ├── index.html    # Main web interface
│   │   └── graph.html    # Graph visualization page
│   └── static/      # Static web assets
│       ├── css/     # Stylesheets
│       │   ├── styles.css    # Main styles
│       │   └── themes.css    # Theme definitions
│       └── js/      # JavaScript
│           └── app.js        # Main web application
├── main.go          # Entry point
├── go.mod           # Go modules
├── Makefile         # Build automation
└── README.md        # Documentation

Building from Source

# Get dependencies
go mod download

# Build with CGO
CGO_ENABLED=1 go build -o ml-notes

# Run tests
go test ./...

# Run with race detector
go build -race -o ml-notes-dev

Testing

# Run all tests
make test

# Run with coverage
make test-coverage

# Run specific package tests
go test ./internal/embeddings/...

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🐛 Troubleshooting

Common Issues

Lil-Rag Connection:

# Check lil-rag service is running
curl http://localhost:12121/health

# Update endpoint if needed
ml-notes config set lilrag-url http://your-lilrag:12121

# Service falls back to text search if lil-rag unavailable

Ollama Connection:

# Check Ollama is running  
curl http://localhost:11434/api/tags

# Update endpoint if needed
ml-notes config set ollama-endpoint http://your-ollama:11434

Debug Information:

# Enable debug mode to see namespace usage
ml-notes --debug search --vector "test"
ml-notes --debug <command>

📄 License

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

🙏 Acknowledgments

Lil-Rag - Advanced semantic search service
Ollama - Local LLM inference
SQLite - Reliable embedded database
Cobra - CLI framework

📮 Support

Made with ❤️ by the ML Notes community

Name		Name	Last commit message	Last commit date
Latest commit History 67 Commits
.github/workflows		.github/workflows
cmd		cmd
docs		docs
examples		examples
internal		internal
web		web
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
PROJECT_STRUCTURE.md		PROJECT_STRUCTURE.md
README.md		README.md
RELEASES.md		RELEASES.md
assets.go		assets.go
debug-test.html		debug-test.html
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh
main.go		main.go
mcp-config.example.json		mcp-config.example.json
test-upload.txt		test-upload.txt

License

streed/ml-notes

Folders and files

Latest commit

History

Repository files navigation

ML Notes

✨ Features

📋 Table of Contents

🚀 Installation

Prerequisites

From Source

Pre-built Binaries

Using Make

Cross-Platform Builds

🎯 Quick Start

⚙️ Configuration

Initial Setup

Configuration Options

Lil-Rag Integration

Managing Configuration

🌐 Web Interface

Starting the Web Server

Web UI Features

📝 Smart Markdown Editor

🏷️ Tag Management

🔍 Integrated Search

📊 Note Organization

🎨 Theme Support

🤖 AI Integration

Graph Visualization

📊 Interactive Note Graph

🎮 Interactive Features

🎯 Graph Controls

📱 Responsive Design

🔗 Graph Navigation

Web Interface Keyboard Shortcuts

Web Server Configuration

API Endpoints

📚 CLI Usage

Managing Notes

Add a Note

List Notes

Get a Note

Edit a Note

Delete Notes

Import Website Content

Tag Management

Managing Tags

Tag Search

Searching

Text Search

Vector Search

Tag Search

Advanced Features

Project-Scoped Search

Debug Mode

AI-Powered Analysis

Basic Analysis

Custom Analysis Prompts

Search with Analysis

Analysis Features

Configuration

🤖 MCP Server

Claude Desktop Integration

Available Tools

Note Management

Tag Management

Search Capabilities

Resources

Prompts

Starting the MCP Server

🔧 Development

Project Structure

Building from Source

Testing

🤝 Contributing

🐛 Troubleshooting

Common Issues

📄 License

Packages