{"id":"5b90a08e-7938-48b7-999b-7fc6bc00c6db","slug":"ml-notes","kind":"mcp","name":"ml-notes","summary":"Notes with a little ml sprinkled on top.","owner":"streed","repoUrl":"https://github.com/streed/ml-notes","license":"GPL-3.0","licenseTier":"strong-copyleft","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-08-13T01:55:08.000Z","addedAt":"2026-10-21T15:42:07.116Z","logoUrl":"https://avatars.githubusercontent.com/u/805140?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["productivity"],"tags":[],"runtime":"go","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T11:27:12.319Z","sample":false,"url":"https://conduits.dev/tools/ml-notes","language":"Go","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# ML Notes\n\n[![Go Version](https://img.shields.io/badge/Go-1.22%2B-blue.svg)](https://golang.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n\nA powerful command-line note-taking application with semantic vector search capabilities, powered by SQLite and lil-rag for intelligent search.\n\n## ✨ Features\n\n- 📝 **Complete Note Management** - Create, edit, delete, and organize notes with powerful CLI tools\n- 🌐 **Website Import** - Import web pages as notes with headless browser support and image URL preservation\n- 🌐 **Modern Web Interface** - Beautiful, responsive web UI with real-time markdown preview and graph visualization\n- 🏷️ **Smart Tagging System** - Organize notes with tags, search by tags, and manage tag collections\n- 🔍 **Triple Search Methods** - Semantic vector search, traditional text search, and tag-based search\n- 📊 **Interactive Graph Visualization** - Explore relationships between notes with D3.js-powered graph views\n- 🚀 **Fast & Lightweight** - Built with Go and SQLite for maximum performance\n- 🔌 **Lil-Rag Integration** - Advanced semantic search with project-aware namespacing\n- 📊 **Smart Search Isolation** - Project-scoped search prevents cross-contamination between different note collections\n- 🧠 **AI-Powered Analysis** - Deep analysis with custom prompts and reasoning visibility\n- ✏️ **Advanced Editor Features** - Split-pane markdown editor with synchronized scrolling and focus-based behavior\n- 🛠️ **Highly Configurable** - Customize everything from storage paths to AI models\n- 🐛 **Debug Support** - Built-in debugging for troubleshooting and development\n- 🤖 **MCP Server** - Model Context Protocol server for LLM integration (Claude Desktop)\n- 🔄 **Smart Reindexing** - Automatic vector index management and optimization\n\n## 📋 Table of Contents\n\n- [Installation](#installation)\n  - [From Source](#from-source)\n  - [Pre-built Binaries](#pre-built-binaries)\n  - [Using Make](#using-make)\n- [Quick Start](#quick-start)\n- [Configuration](#configuration)\n- [Web Interface](#web-interface)\n  - [Starting the Web Server](#starting-the-web-server)\n  - [Web UI Features](#web-ui-features)\n  - [Graph Visualization](#graph-visualization)\n- [CLI Usage](#cli-usage)\n  - [Managing Notes](#managing-notes)\n  - [Tag Management](#tag-management)\n  - [Searching](#searching)\n  - [AI-Powered Analysis](#ai-powered-analysis)\n- [MCP Server](#mcp-server)\n  - [Claude Desktop Integration](#claude-desktop-integration)\n  - [Available Tools](#available-tools)\n- [Development](#development)\n- [Contributing](#contributing)\n- [License](#license)\n\n## 🚀 Installation\n\n### Prerequisites\n\n- Go 1.22 or higher\n- CGO support (for SQLite integration)\n- (Optional) [Lil-Rag](https://github.com/stillmatic/lil-rag) service for enhanced semantic search\n- (Optional) [Ollama](https://ollama.ai) for AI-powered features\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/streed/ml-notes.git\ncd ml-notes\n\n# Build the application\nmake build\n\n# Install to your PATH\nsudo make install\n```\n\n### Pre-built Binaries\n\nDownload the latest release from the [Releases](https://github.com/streed/ml-notes/releases) page.\n\n```bash\n# Download and extract (Linux/macOS example)\nwget https://github.com/streed/ml-notes/releases/latest/download/ml-notes-linux-amd64.tar.gz\ntar -xzf ml-notes-linux-amd64.tar.gz\nsudo mv ml-notes /usr/local/bin/\n```\n\n### Using Make\n\n```bash\n# Build for current platform\nmake build\n\n# Install to /usr/local/bin (requires sudo)\nmake install\n\n# Build and install in one step\nmake all\n\n# Clean build artifacts\nmake clean\n\n# Run tests\nmake test\n\n# Development build with race detector\nmake dev\n```\n\n### Cross-Platform Builds\n\nML Notes supports building for multiple platforms:\n\n```bash\n# Build for all platforms (Linux, macOS, Windows)\nmake build-all\n\n# Build for specific platforms\nmake build-linux    # Linux AMD64\nmake build-darwin   # macOS (Intel & Apple Silicon)\nmake build-windows  # Windows AMD64\n\n# Create release packages\nmake release\n```\n\n**Platform Support:**\n- ✅ **Linux AMD64** - Full native support\n- ✅ **macOS Intel (AMD64)** - Native and cross-compilation support\n- ✅ **macOS Apple Silicon (ARM64)** - Native and cross-compilation support  \n- ✅ **Windows AMD64** - Native and cross-compilation support\n\n**Cross-Compilation Notes:**\n- Cross-compilation requires appropriate toolchains (clang for macOS, mingw for Windows)\n- For best results, build natively on target platforms\n- CGO is required for sqlite-vec support\n- Use `make build-native` for automatic platform detection\n\n## 🎯 Quick Start\n\n1. **Initialize configuration:**\n```bash\n# Interactive setup (recommended for first-time users)\nml-notes init --interactive\n\n# Or quick setup with defaults\nml-notes init\n\n# Or custom setup with flags\nml-notes init \\\n  --data-dir ~/my-notes \\\n  --ollama-endpoint http://localhost:11434 \\\n  --summarization-model llama3.2:latest \\\n  --enable-summarization\n```\n\n2. **Add your first note:**\n```bash\nml-notes add -t \"My First Note\" -c \"This is the content of my first note\"\n\n# Or add a note with tags\nml-notes add -t \"Project Ideas\" -c \"Some great ideas for the next project\" --tags \"ideas,projects,todo\"\n```\n\n3. **List your notes:**\n```bash\nml-notes list\n```\n\n4. **Search with vector similarity:**\n```bash\nml-notes search --vector \"machine learning concepts\"\n```\n\n5. **Search by tags:**\n```bash\nml-notes search --tags \"projects,ideas\"\n```\n\n6. **Start the web interface:**\n```bash\nml-notes serve\n# Open http://localhost:21212 in your browser\n```\n\n## ⚙️ Configuration\n\nML Notes stores its configuration in `~/.config/ml-notes/config.json`.\n\n### Initial Setup\n\nRun the interactive setup:\n```bash\nml-notes init -i\n```\n\nOr configure with flags:\n```bash\nml-notes init \\\n  --data-dir ~/.local/share/ml-notes \\\n  --ollama-endpoint http://localhost:11434 \\\n  --summarization-model llama3.2:latest \\\n  --enable-summarization\n```\n\n### Configuration Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `data-dir` | Where notes database is stored | `~/.local/share/ml-notes` |\n| `ollama-endpoint` | Ollama API endpoint | `http://localhost:11434` |\n| `lilrag-url` | Lil-Rag service endpoint | `http://localhost:12121` |\n| `summarization-model` | Model for AI analysis | `llama3.2:latest` |\n| `enable-summarization` | Enable/disable analysis features | `true` |\n| `enable-auto-tagging` | Enable/disable AI auto-tagging | `true` |\n| `max-auto-tags` | Maximum auto-generated tags | `5` |\n| `editor` | Default editor for note editing | Auto-detect |\n| `debug` | Enable debug logging | `false` |\n\n### Lil-Rag Integration\n\nML Notes uses [Lil-Rag](https://github.com/stillmatic/lil-rag) for advanced semantic search with project-aware namespacing:\n\n**Project Isolation**: Each project directory gets its own search namespace (e.g., `ml-notes-myproject`), preventing search results from mixing between different projects.\n\n**Setup Lil-Rag Service**:\n```bash\n# Install and run lil-rag service\ngo install github.com/stillmatic/lil-rag@latest\nlil-rag serve --port 12121\n\n# Configure ML Notes to use lil-rag\nml-notes config set lilrag-url http://localhost:12121\n```\n\n**Benefits**:\n- **Project Scoping**: Search only within your current project's notes\n- **Cross-Project Isolation**: Notes from different projects don't contaminate search results  \n- **Automatic Namespacing**: Project directory name automatically determines search scope\n- **Fallback Support**: Gracefully falls back to text search when lil-rag is unavailable\n\n### Managing Configuration\n\n```bash\n# View current configuration\nml-notes config show\n\n# Update settings\nml-notes config set ollama-endpoint http://localhost:11434\nml-notes config set lilrag-url http://localhost:12121\nml-notes config set summarization-model llama3.2:latest\nml-notes config set enable-auto-tagging true\nml-notes config set max-auto-tags 5\nml-notes config set editor \"code --wait\"\nml-notes config set debug true\n```\n\n## 🌐 Web Interface\n\nML 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.\n\n### Starting the Web Server\n\n```bash\n# Start the web server on default port (21212)\nml-notes serve\n\n# Start on specific host and port\nml-notes serve --host 0.0.0.0 --port 3000\n\n# Access the web interface\nopen http://localhost:21212\n```\n\n### Web UI Features\n\n#### 📝 **Smart Markdown Editor**\n- **Focus-Based Split Pane**: Editor automatically appears when you focus on editing areas\n- **Real-Time Preview**: Live markdown rendering with synchronized scrolling\n- **Auto-Scroll**: Preview automatically follows your cursor when typing extends the editor\n- **Smooth Transitions**: Elegant animations for pane resizing and focus changes\n\n#### 🏷️ **Tag Management**\n- Visual tag display with removal capabilities\n- Tag input with comma-separated support\n- Filter notes by tags using the sidebar dropdown\n- Auto-tagging integration with AI-powered suggestions\n\n#### 🔍 **Integrated Search**\n- Real-time search as you type\n- Vector search integration for semantic similarity\n- Tag-based filtering\n- Search results with content previews\n\n#### 📊 **Note Organization**\n- Sidebar with all notes and metadata\n- Chronological organization with creation dates\n- Active note highlighting\n- Quick navigation between notes\n\n#### 🎨 **Theme Support**\n- Light and dark theme toggle\n- Consistent theming across all components\n- Paper-like texture for comfortable reading\n- Responsive design for all screen sizes\n\n#### 🤖 **AI Integration**\n- One-click auto-tagging for notes\n- AI-powered note analysis with custom prompts\n- Integration with Ollama for local AI processing\n- Analysis results with thinking process visibility\n\n### Graph Visualization\n\n#### 📊 **Interactive Note Graph**\n- **D3.js-Powered Visualization**: Smooth, interactive graph showing note relationships\n- **Smart Node Positioning**: Isolated notes stay near center, connected notes spread outward\n- **Connection-Based Sizing**: Node size reflects number of connections to other notes\n- **Tag-Based Relationships**: Notes connected by shared tags with weighted connections\n- **Color-Coded Groups**: Different colors for different note clusters/topics\n\n#### 🎮 **Interactive Features**\n- **Zoom and Pan**: Scroll to zoom, drag to pan around the graph\n- **Node Interaction**: Click nodes to navigate directly to notes\n- **Hover Tooltips**: See note titles, tags, and connection counts\n- **Drag Nodes**: Manually position nodes by dragging\n- **Filter Controls**: Filter by tag, minimum connections, and maximum nodes displayed\n\n#### 🎯 **Graph Controls**\n- **Filter Panel**: \n  - Filter by specific tags\n  - Set minimum connection threshold\n  - Limit maximum nodes displayed\n- **Zoom Controls**: Zoom in/out buttons and fit-to-view\n- **View Options**: Toggle between full graph view and embedded preview\n- **Reset View**: Return to optimal view with one click\n\n#### 📱 **Responsive Design**\n- **Desktop Experience**: Full-featured graph with all controls and interactions\n- **Mobile Friendly**: Simplified interface optimized for touch devices\n- **Embedded Mode**: Compact graph view for the main dashboard\n- **Performance Optimized**: Efficient rendering for large note collections\n\n#### 🔗 **Graph Navigation**\n- **Direct Navigation**: Click any node to jump to that note\n- **Context Preservation**: Graph remembers position when returning\n- **Visual Feedback**: Selected and hovered nodes are highlighted\n- **Breadcrumb Integration**: Easy return to main interface\n\n### Web Interface Keyboard Shortcuts\n\n| Shortcut | Action |\n|----------|--------|\n| `Ctrl/Cmd + S` | Save current note |\n| `Ctrl/Cmd + N` | Create new note |\n| `Ctrl/Cmd + /` | Toggle theme |\n| `Escape` | Close modals |\n\n### Web Server Configuration\n\nThe web server supports additional configuration options:\n\n```bash\n# Enable custom CSS\nml-notes config set webui-custom-css true\n\n# Set default theme\nml-notes config set webui-theme dark\n```\n\n### API Endpoints\n\nThe web server also exposes REST API endpoints:\n\n- `GET /api/v1/notes` - List all notes\n- `POST /api/v1/notes` - Create new note\n- `GET /api/v1/notes/{id}` - Get specific note\n- `PUT /api/v1/notes/{id}` - Update note\n- `DELETE /api/v1/notes/{id}` - Delete note\n- `POST /api/v1/notes/search` - Search notes\n- `GET /api/v1/tags` - List all tags\n- `GET /api/v1/graph` - Get graph data for visualization\n- `POST /api/v1/auto-tag/suggest/{id}` - Get AI tag suggestions\n\n## 📚 CLI Usage\n\n### Managing Notes\n\n#### Add a Note\n```bash\n# Interactive mode (opens your editor)\nml-notes add -t \"Title\"\n\n# With content directly\nml-notes add -t \"Title\" -c \"Content\"\n\n# With tags\nml-notes add -t \"Project Notes\" -c \"Important project details\" --tags \"project,important,todo\"\n\n# From stdin\necho \"Content\" | ml-notes add -t \"Title\"\n\n# Use specific editor\nml-notes add -t \"Code Review\" --editor-cmd \"code --wait\"\n```\n\n#### List Notes\n```bash\n# List recent notes\nml-notes list\n\n# With pagination\nml-notes list --limit 10 --offset 20\n\n# Short format (ID and title only)\nml-notes list --short\n```\n\n#### Get a Note\n```bash\nml-notes get <note-id>\n```\n\n#### Edit a Note\n```bash\n# Edit note in your default editor (includes tags)\nml-notes edit 123\n\n# Edit title only\nml-notes edit -t 123\n\n# Edit content only\nml-notes edit -c 123\n\n# Use a specific editor\nml-notes edit -e \"code --wait\" 123\n```\n\n**Note**: When editing in your editor, the note format includes tags:\n```\nTitle: Your Note Title\nTags: tag1, tag2, tag3\n---\nYour note content goes here\n```\n\n#### Delete Notes\n```bash\n# Delete a single note\nml-notes delete 123\n\n# Delete multiple notes\nml-notes delete 123 456 789\n\n# Skip confirmation prompt\nml-notes delete -f 123\n\n# Delete all notes (use with extreme caution!)\nml-notes delete --all\n```\n\n#### Import Website Content\n```bash\n# Import a website as a new note\nml-notes import-url https://blog.example.com/article\n\n# Import with custom tags\nml-notes import-url https://docs.example.com/guide --tags \"docs,reference,tutorial\"\n\n# Import with AI auto-tagging\nml-notes import-url https://example.com/post --auto-tag\n\n# Import with custom timeout for slow-loading sites\nml-notes import-url https://heavy-site.com --timeout 60s\n```\n\n**Features:**\n- **Headless Browser**: Uses Chrome to render JavaScript and dynamic content\n- **Smart Content Extraction**: Prioritizes main content areas (article, main) while filtering out navigation, ads, and sidebars\n- **Image URL Preservation**: Converts relative image URLs to absolute URLs while maintaining external/CDN links\n- **Markdown Conversion**: Clean HTML-to-markdown conversion with proper formatting\n- **Security-First**: Uses secure browser settings with SSL validation for live websites\n\n### Tag Management\n\n#### Managing Tags\n```bash\n# List all tags in the system\nml-notes tags list\n\n# Add tags to an existing note\nml-notes tags add 123 --tags \"urgent,important\"\n\n# Remove specific tags from a note\nml-notes tags remove 123 --tags \"old,outdated\"\n\n# Replace all tags for a note\nml-notes tags set 123 --tags \"research,ai,final\"\n\n# Remove all tags from a note\nml-notes tags set 123 --tags \"\"\n```\n\n#### Tag Search\n```bash\n# Search for notes with specific tags\nml-notes search --tags \"project,important\"\n\n# Search for notes with any of the specified tags\nml-notes search --tags \"research,ai,ml\"\n\n# Combine with other search options\nml-notes search --tags \"project\" --limit 5 --short\n```\n\n### Searching\n\n#### Text Search\n```bash\n# Search in titles and content\nml-notes search \"golang\"\n\n# Limit results\nml-notes search --limit 5 \"machine learning\"\n\n# Short format showing only IDs and titles\nml-notes search --short \"programming\"\n```\n\n#### Vector Search\n```bash\n# Semantic similarity search (returns most similar note by default)\nml-notes search --vector \"neural networks and deep learning\"\n\n# Get top 5 most similar notes\nml-notes search --vector --limit 5 \"machine learning concepts\"\n\n# Finds related notes even without exact matches\nml-notes search --vector \"AI concepts\"\n```\n\n#### Tag Search\n```bash\n# Search by single tag\nml-notes search --tags \"research\"\n\n# Search by multiple tags (finds notes with ANY of these tags)\nml-notes search --tags \"project,important,urgent\"\n\n# Combine tag search with limits and formatting\nml-notes search --tags \"ai,ml\" --limit 10 --short\n\n# Tag-only search (no text query needed)\nml-notes search --tags \"todo\"\n```\n\n### Advanced Features\n\n#### Project-Scoped Search\nML Notes automatically isolates search results by project directory:\n```bash\n# In /home/user/project1\nml-notes search --vector \"machine learning\"  # Searches ml-notes-project1 namespace\n\n# In /home/user/project2  \nml-notes search --vector \"machine learning\"  # Searches ml-notes-project2 namespace\n```\n\n#### Debug Mode\n```bash\n# Enable for current command\nml-notes --debug search --vector \"test\"\n\n# Enable persistently\nml-notes config set debug true\n```\n\n### AI-Powered Analysis\n\n#### Basic Analysis\n```bash\n# Analyze a single note\nml-notes analyze 123\n\n# Analyze multiple notes together\nml-notes analyze 1 2 3\n\n# Analyze all notes\nml-notes analyze --all\n\n# Analyze recent notes\nml-notes analyze --recent 10\n```\n\n#### Custom Analysis Prompts\n```bash\n# Focus on technical aspects\nml-notes analyze 123 -p \"Focus on technical implementation details\"\n\n# Analyze all notes with a specific tag\nml-notes search --tags \"research\" --analyze -p \"Summarize research findings\"\n\n# Extract insights and patterns\nml-notes analyze --all -p \"What are the recurring themes and patterns?\"\n\n# Comparative analysis\nml-notes analyze 1 2 3 -p \"Compare and contrast these approaches\"\n\n# Business-focused analysis\nml-notes analyze --recent 5 -p \"What business opportunities are mentioned?\"\n```\n\n#### Search with Analysis\n```bash\n# Analyze search results\nml-notes search --analyze \"machine learning\"\n\n# Custom analysis of search results\nml-notes search --analyze -p \"Focus on practical applications\" \"algorithms\"\n\n# Show both analysis and detailed results\nml-notes search --analyze --show-details \"python\"\n```\n\n#### Analysis Features\n- **Reasoning Visibility**: See the AI's thought process with formatted thinking sections\n- **Custom Prompts**: Target analysis with specific questions or focus areas  \n- **Multi-Note Analysis**: Analyze relationships and patterns across multiple notes\n- **Search Integration**: Analyze search results for deeper insights\n\n#### Configuration\n```bash\n# Enable/disable analysis features\nml-notes config set enable-summarization true\n\n# Set the analysis model\nml-notes config set summarization-model llama3.2:latest\n\n# View current settings\nml-notes config show\n```\n\n## 🤖 MCP Server\n\nML Notes includes a Model Context Protocol (MCP) server that allows LLMs like Claude to interact with your notes programmatically.\n\n### Claude Desktop Integration\n\nAdd ML Notes to your Claude Desktop configuration:\n\n1. Open your Claude Desktop config file:\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n   - Linux: `~/.config/claude/claude_desktop_config.json`\n\n2. Add the ML Notes MCP server:\n```json\n{\n  \"mcpServers\": {\n    \"ml-notes\": {\n      \"command\": \"ml-notes\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\n3. Restart Claude Desktop\n\n### Available Tools\n\nThe MCP server provides the following tools to LLMs:\n\n#### Note Management\n- **add_note** - Create a new note with title, content, and optional tags\n- **get_note** - Retrieve a specific note by ID (includes tags)\n- **update_note** - Modify existing note title, content, or tags\n- **delete_note** - Remove a note from the database\n- **list_notes** - List notes with pagination support (shows tags)\n\n#### Tag Management\n- **list_tags** - List all tags in the system\n- **update_note_tags** - Update tags for a specific note\n\n#### Search Capabilities\n- **search_notes** - Search using vector similarity, text matching, or tag search\n  - Supports semantic vector search, keyword search, and tag-based search\n  - Configurable result limits\n  - Automatically uses best search method\n  - Tag search with comma-separated tag lists\n\n### Resources\n\nThe MCP server exposes these resources:\n- `notes://recent` - Get the most recently created notes\n- `notes://stats` - Database statistics and configuration\n- `notes://config` - Current ML Notes configuration\n- `notes://note/{id}` - Access specific note by ID\n\n### Prompts\n\nPre-configured prompts for common tasks:\n- **search_notes** - Structured search prompt with query parameters\n- **analyze_notes** - Generate AI-powered analysis of your note collection\n\n### Starting the MCP Server\n\n```bash\n# Start MCP server (for use with LLM clients)\nml-notes mcp\n\n# The server communicates via stdio for Claude Desktop integration\n```\n\n## 🔧 Development\n\n### Project Structure\n```\nml-notes/\n├── cmd/              # CLI commands\n│   ├── root.go      # Root command\n│   ├── add.go       # Add note command\n│   ├── list.go      # List notes command\n│   ├── get.go       # Get note command\n│   ├── search.go    # Search command\n│   ├── serve.go     # Web server command\n│   ├── init.go      # Init configuration\n│   ├── config.go    # Config management\n│   ├── reindex.go   # Reindex embeddings\n│   ├── detect.go    # Detect dimensions\n│   └── mcp.go       # MCP server command\n├── internal/         # Internal packages\n│   ├── api/         # Web server and API endpoints\n│   ├── autotag/     # AI-powered auto-tagging\n│   ├── config/      # Configuration management\n│   ├── database/    # Database operations\n│   ├── embeddings/  # Embedding generation\n│   ├── logger/      # Logging utilities\n│   ├── mcp/         # MCP server implementation\n│   ├── models/      # Data models\n│   ├── search/      # Search implementation\n│   └── summarize/   # AI analysis features\n├── web/              # Web interface assets\n│   ├── templates/   # HTML templates\n│   │   ├── index.html    # Main web interface\n│   │   └── graph.html    # Graph visualization page\n│   └── static/      # Static web assets\n│       ├── css/     # Stylesheets\n│       │   ├── styles.css    # Main styles\n│       │   └── themes.css    # Theme definitions\n│       └── js/      # JavaScript\n│           └── app.js        # Main web application\n├── main.go          # Entry point\n├── go.mod           # Go modules\n├── Makefile         # Build automation\n└── README.md        # Documentation\n```\n\n### Building from Source\n\n```bash\n# Get dependencies\ngo mod download\n\n# Build with CGO\nCGO_ENABLED=1 go build -o ml-notes\n\n# Run tests\ngo test ./...\n\n# Run with race detector\ngo build -race -o ml-notes-dev\n```\n\n### Testing\n\n```bash\n# Run all tests\nmake test\n\n# Run with coverage\nmake test-coverage\n\n# Run specific package tests\ngo test ./internal/embeddings/...\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n**Lil-Rag Connection:**\n```bash\n# Check lil-rag service is running\ncurl http://localhost:12121/health\n\n# Update endpoint if needed\nml-notes config set lilrag-url http://your-lilrag:12121\n\n# Service falls back to text search if lil-rag unavailable\n```\n\n**Ollama Connection:**\n```bash\n# Check Ollama is running  \ncurl http://localhost:11434/api/tags\n\n# Update endpoint if needed\nml-notes config set ollama-endpoint http://your-ollama:11434\n```\n\n**Debug Information:**\n```bash\n# Enable debug mode to see namespace usage\nml-notes --debug search --vector \"test\"\nml-notes --debug <command>\n```\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [Lil-Rag](https://github.com/stillmatic/lil-rag) - Advanced semantic search service\n- [Ollama](https://ollama.ai) - Local LLM inference\n- [SQLite](https://sqlite.org) - Reliable embedded database\n- [Cobra](https://github.com/spf13/cobra) - CLI framework\n\n## 📮 Support\n\n- 🐛 [Report bugs](https://github.com/streed/ml-notes/issues)\n- 💡 [Request features](https://github.com/streed/ml-notes/issues)\n- 📖 [Documentation](https://github.com/streed/ml-notes/wiki)\n\n---\n\nMade with ❤️ by the ML Notes community"}