Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/lekt9/albert-launcher

AI-powered file launcher and semantic search assistant. Like Spotlight/Alfred but with advanced AI capabilities for understanding context and meaning. Features local processing, privacy-first design, and seamless integration with your workflow.
https://github.com/lekt9/albert-launcher

ai alfred desktop document-search electron llm local local-ai macos ollama privacy productivity-tool search-engine semantic-search spotlight typescript vector-search

Last synced: 28 days ago
JSON representation

AI-powered file launcher and semantic search assistant. Like Spotlight/Alfred but with advanced AI capabilities for understanding context and meaning. Features local processing, privacy-first design, and seamless integration with your workflow.

Awesome Lists containing this project

README 

          
# alBERT-launcher



Your AI-powered file launcher and search assistant. Think Spotlight or Alfred, but with the intelligence to understand what you're looking for. Press `Option (⌥) + Space` anywhere to start searching!



![alBERT-launcher Demo](demo.gif)



## Installation



### macOS



1. Download the latest release for your architecture:

   - For Apple Silicon (M1/M2): `albert-launcher-{version}-mac-arm64.dmg`

   - For Intel: `albert-launcher-{version}-mac-x64.dmg`

2. Open the DMG file and drag alBERT to your Applications folder

3. Since the app is not signed with an Apple Developer certificate, you'll need to:

   - Right-click (or Control-click) on alBERT in Applications

   - Select "Open" from the context menu

   - Click "Open" in the security dialog

   - This is only required for the first launch

4. Press `Option (⌥) + Space` anywhere to open alBERT!



### Quick Tips



- 🚀 **Launch**: Press `Option (⌥) + Space` anywhere to open alBERT

- 🔍 **Search**: Just start typing - alBERT understands natural language

- 💡 **Smart Results**: Results are ranked by relevance to your query

- ⌨️ **Navigate**: Use arrow keys to move, Enter to open

- ⚡️ **Quick Exit**: Press Esc to close



## What Makes alBERT Different?



Unlike traditional file search tools that rely on filename matching or basic content indexing, alBERT-launcher uses advanced semantic search and AI capabilities to understand the meaning behind your queries. It maintains a dedicated folder (`~/alBERT`) where it indexes and searches through your important documents, providing:



- **Semantic Search**: Find documents based on meaning, not just keywords

- **AI-Powered Answers**: Get direct answers to questions about your documents

- **Context-Aware Results**: Results are ranked based on relevance to your query context

- **Instant Access**: Global shortcut (`Option (⌥) + Space`) to access from anywhere



## How It Works



```mermaid

graph TD

    A[User Query] --> B[Query Processor]

    B --> C{Query Type}

    C -->|File Search| D[Local Search Engine]

    C -->|Web Search| E[Brave Search API]

    C -->|AI Question| F[Perplexity AI]

    

    D --> G[Document Embeddings]

    D --> H[File Index]

    

    G --> I[Search Results]

    H --> I

    E --> I

    F --> I

    

    I --> J[Result Ranker]

    J --> K[UI Display]



    subgraph "Local Index"

        H

        G

    end



    subgraph "External Services"

        E

        F

    end

```



### Architecture Overview



```mermaid

graph LR

    A[Electron Main Process] --> B[IPC Bridge]

    B --> C[Renderer Process]

    

    subgraph "Main Process"

        A --> D[File Watcher]

        A --> E[Search DB]

        A --> F[Embeddings Service]

    end

    

    subgraph "Renderer Process"

        C --> G[React UI]

        G --> H[Search Bar]

        G --> I[Results View]

        G --> J[Settings Panel]

    end

```



#### Main process lifecycle



The Electron main process is now organised into small lifecycle utilities so contributors can refactor or extend behaviour without digging through a monolithic `index.ts` file:



| Concern | Module | Responsibilities |

| --- | --- | --- |

| Window orchestration | `src/main/lifecycle/window-manager.ts` | Builds the translucent shell window, wires blur/close hooks, and loads the correct renderer URL depending on environment. |

| IPC routing | `src/main/lifecycle/ipc.ts` | Registers the tRPC bridge against the active window so renderer modules can call into the main process. |

| Tray & shortcuts | `src/main/lifecycle/tray.ts`, `src/main/lifecycle/shortcuts.ts` | Sets up the status bar tray menu and keyboard toggle with graceful teardown on quit. |

| Search database lifecycle | `src/main/lifecycle/search-service.ts` | Lazily initialises the embedded vector index, streams progress updates to the renderer, and persists/shuts down cleanly. |



These modules keep the bootstrap logic declarative inside `src/main/index.ts` while still exposing focused hooks for new background services or observability.



#### Renderer state toolkit



To keep the liquid-glass UI responsive, the renderer has been decomposed into focused utilities instead of one monolithic `App.tsx`:



| Concern | Module | Responsibilities |

| --- | --- | --- |

| Smithery connectors | `src/renderer/src/hooks/useSmitheryContext.ts` | Debounced MCP fetching with cancellation, error surfacing, and manual refresh support. |

| Context scoring | `src/renderer/src/hooks/useContextScoring.ts` | Reranks merged local/MCP documents and tracks cosine similarity maps without blocking the UI thread. |

| Prompt assembly | `src/renderer/src/lib/context-builder.ts` | Normalises sticky notes, Smithery snippets, and search results into a bounded context string for the LLM middleware. |

| Shared search types | `src/renderer/src/types/search.ts` | Source of truth for search result, cache, and sticky note shapes reused across components. |



These modules let feature components subscribe to just the slices of data they need, improving readability while reducing redundant network requests and state churn.



> **Secrets stay local.** Configuration lives in `.env` (ignored by git) with safe defaults documented in `.env.example`; never commit API keys to the repo.



### Search Flow



```mermaid

sequenceDiagram

    participant U as User

    participant UI as UI Layer

    participant S as Search Engine

    participant DB as Search DB

    participant AI as AI Services

    

    U->>UI: Enter Query

    UI->>S: Process Query

    S->>DB: Search Local Index

    S->>AI: Get AI Answer

    par Local Results

        DB-->>S: Document Matches

    and AI Response

        AI-->>S: Generated Answer

    end

    S->>S: Rank & Merge Results

    S->>UI: Display Results

    UI->>U: Show Results

```



## Features



- 🚀 Lightning-fast local file search

- 🤖 AI-powered answers using Perplexity

- 🔍 Semantic search capabilities

- 🌐 Web search integration with Brave Search

- ⌨️ Global keyboard shortcuts (`Option (⌥) + Space`)

- 💾 Smart caching system

- 🎯 Context-aware search results

- 🫧 Liquid glass interface inspired by macOS Sonoma

- 📱 Modern, responsive UI



### Liquid Glass Interface



The renderer has been refreshed to echo Apple's latest "liquid glass" design language:



- Layered frosted panels with animated gradient orbs and a soft grid backdrop keep the workspace calm yet dynamic.

- A sculpted header surfaces key stats (pinned notes, surfaced results, conversations) so you can gauge context at a glance.

- Search, chat, and notes live inside glass panels with softened borders, luminous highlights, and adaptive blur so focus stays on your content.

- Sticky notes inherit the same frosted aesthetic and can be spawned instantly from the header or via ⌘/Ctrl + N.



To tweak the visuals, inspect `src/renderer/src/assets/index.css` for theme tokens and glass utilities, and adjust the panel layout inside `src/renderer/src/App.tsx`.



### Smithery MCP connectors



alBERT now speaks the [Model Context Protocol (MCP)](https://smithery.ai/mcp) so you can stream structured knowledge packs straight from [Smithery](https://smithery.ai) into every search and chat turn.



1. **Open Settings → Smithery MCP** and (optionally) drop in your Smithery API key if you need private connectors.

2. Paste a Smithery slug (for example `notion-notes`) or a manifest URL to link a connector. You can also pick from the built-in directory and click **Link connector**.

3. Toggle connectors on/off, refresh their metadata, or remove them entirely without editing config files.



Once linked, context cards from each connector show up beneath search results. The retrieved snippets are automatically blended into the conversation context so the assistant can cite them alongside your local documents. Everything is stored in local preferences—no Smithery secrets are shipped with the repo.



For deeper integrations—hosting your own MCP servers, enabling OAuth, or wiring Smithery connectors into other runtimes—see [`docs/smithery-mcp.md`](docs/smithery-mcp.md) for a protocol primer and official SDK references.



## Core Concepts



### The alBERT Folder

The `~/alBERT` folder is your personal knowledge base. Any files placed here are:

- Automatically indexed for semantic search

- Processed for quick retrieval

- Analyzed for contextual understanding

- Accessible through natural language queries



### Semantic Search

alBERT uses advanced embedding techniques to understand the meaning of your documents:

1. Documents are split into meaningful chunks

2. Each chunk is converted into a high-dimensional vector

3. Queries are matched against these vectors for semantic similarity

4. Results are ranked based on relevance and context



### AI Integration

- **Query Understanding**: Natural language processing to understand user intent

- **Context Awareness**: Maintains conversation context for follow-up queries

- **Smart Answers**: Generates answers by combining local knowledge with AI capabilities



### OpenRouter Integration



alBERT-launcher uses OpenRouter to access powerful language models for enhanced search capabilities:



> **Note:** The app does not include an OpenRouter API key. Provide your own key via the in-app **Settings → Public AI** section or by setting `OPENROUTER_API_KEY` in `.env` before enabling cloud responses.



```mermaid

graph TD

    A[User Query] --> B[Query Analyzer]

    B --> C{Query Type}

    C -->|Direct Question| D[OpenRouter API]

    C -->|Document Analysis| E[Local Processing]

    

    D --> F[Perplexity/LLaMA Model]

    F --> G[AI Response]

    

    E --> H[Document Vectors]

    H --> I[Semantic Search]

    

    G --> J[Result Merger]

    I --> J

    J --> K[Final Response]



    subgraph "OpenRouter Service"

        D

        F

    end



    subgraph "Local Processing"

        E

        H

        I

    end

```



#### OpenRouter Features

- **Model Selection**: Uses Perplexity's LLaMA-3.1-Sonar-Small-128k model for optimal performance

- **Context Integration**: Combines AI responses with local document context

- **Source Attribution**: AI responses include relevant source URLs

- **Streaming Responses**: Real-time response streaming for better UX

- **Fallback Handling**: Graceful degradation when API is unavailable



Example OpenRouter configuration:

```typescript

const openRouterConfig = {

  model: "perplexity/llama-3.1-sonar-small-128k-online",

  temperature: 0.7,

  maxTokens: 500,

  systemPrompt: "You are a search engine api that provides answers to questions with as many links to sources as possible."

}

```



### Privacy-First: Local AI with Ollama



alBERT-launcher puts your privacy first by supporting local AI processing through Ollama integration. Switch between cloud and local AI with a single click:



```mermaid

graph TD

    A[Your Query] --> B{Privacy Mode}

    B -->|Private| C[Local AI]

    B -->|Public| D[Cloud AI]

    C --> E[Private Results]

    D --> F[Cloud Results]

```



#### Features



- 🔒 **Privacy Mode**: Switch between local and cloud AI instantly

- 💻 **Local Processing**: Keep your data on your machine

- 🌐 **Flexible Choice**: Use cloud AI when you need more power

- ⚡ **Fast Response**: No internet latency in local mode

- 💰 **Cost-Free**: No API costs when using local models

- 🔌 **Offline Support**: Work without internet connection



#### Quick Setup



1. Install Ollama from [ollama.ai](https://ollama.ai)

2. Enable "Private Mode" in alBERT settings

3. Start searching with complete privacy!



#### Available Models



Choose from various powerful local models:

- Llama 2

- CodeLlama

- Mistral

- And more from Ollama's model library



#### Why Local AI?



- **Complete Privacy**: Your queries never leave your computer

- **No API Costs**: Use AI features without subscription fees

- **Always Available**: Work offline without interruption

- **Full Control**: Choose and customize your AI models



### File System Integration



alBERT-launcher implements a sophisticated file system monitoring and indexing system:



```mermaid

graph TD

    A[File System Events] --> B[Event Watcher]

    B --> C{Event Type}

    C -->|Create| D[Index New File]

    C -->|Modify| E[Update Index]

    C -->|Delete| F[Remove from Index]

    

    D --> G[File Processor]

    E --> G

    

    G --> H[Content Extractor]

    H --> I[Text Chunker]

    I --> J[Vector Database]

    

    subgraph "File Processing Pipeline"

        G

        H

        I

    end



    subgraph "Search Index"

        J

    end

```



#### File System Features



1. **Automatic Monitoring**

   - Real-time file change detection

   - Efficient delta updates

   - Handles file moves and renames

   - Supports symbolic links



2. **Content Processing**

   ```typescript

   // Example content processing pipeline

   async function processFile(filePath: string) {

     const content = await readContent(filePath)

     const chunks = splitIntoChunks(content)

     const vectors = await vectorizeChunks(chunks)

     await updateSearchIndex(filePath, vectors)

   }

   ```



3. **Supported File Types**

   - Text files (.txt, .md, .json)

   - Documents (.pdf, .doc, .docx)

   - Code files (.js, .py, .ts, etc.)

   - Configuration files (.yaml, .toml)

   - And more...



4. **Smart Indexing**

   - Incremental updates

   - Content deduplication

   - Metadata extraction

   - File type detection



5. **Search Capabilities**

   - Full-text search

   - Fuzzy matching

   - Regular expressions

   - Metadata filters



#### File Organization



The `~/alBERT` directory structure:

```

~/alBERT/

├── documents/           # General documents

├── notes/              # Quick notes and thoughts

├── code/               # Code snippets and examples

├── configuration/      # Config files and settings

└── .alBERT/           # Internal index and metadata

    ├── index/         # Search indices

    ├── vectors/       # Document vectors

    ├── cache/         # Query cache

    └── metadata/      # File metadata

```



#### Performance Optimizations



1. **Indexing**

   - Batch processing for multiple files

   - Parallel processing when possible

   - Priority queue for important files

   - Delayed processing for large files



2. **Search**

   ```mermaid

   graph LR

       A[Query] --> B[Vector]

       B --> C{Search Type}

       C -->|ANN| D[Approximate Search]

       C -->|KNN| E[Exact Search]

       D --> F[Results]

       E --> F

   ```



3. **File Monitoring**

   - Debounced file system events

   - Coalescence of multiple events

   - Selective monitoring based on file size

   - Resource-aware processing



## Vector Database Implementation



alBERT-launcher uses Weaviate Embedded as its vector database engine, providing efficient storage and retrieval of document embeddings:



```mermaid

graph TD

    A[Document] --> B[Content Extractor]

    B --> C[Text Chunks]

    C --> D[Embedding Model]

    D --> E[Vector Embeddings]

    E --> F[Weaviate DB]

    

    G[Search Query] --> H[Query Vectorizer]

    H --> I[Query Vector]

    I --> J[Vector Search]

    F --> J

    J --> K[Ranked Results]



    subgraph "Embedding Pipeline"

        B

        C

        D

        E

    end



    subgraph "Vector Store"

        F

    end



    subgraph "Search Pipeline"

        H

        I

        J

    end

```



#### Vector Database Architecture



1. **Document Processing**

   ```typescript

   interface WeaviateDocument {

     content: string

     path: string

     lastModified: number

     extension: string

   }

   ```



2. **Schema Definition**

   ```typescript

   const schema = {

     class: 'File',

     properties: [

       { name: 'path', dataType: ['string'] },

       { name: 'content', dataType: ['text'] },

       { name: 'filename', dataType: ['string'] },

       { name: 'extension', dataType: ['string'] },

       { name: 'lastModified', dataType: ['number'] },

       { name: 'hash', dataType: ['string'] }

     ],

     vectorizer: 'none'  // Custom vectorization

   }

   ```



#### Embedding System



1. **Worker-based Processing**

   - Dedicated worker threads for vectorization

   - Parallel processing of document batches

   - Automatic resource management

   - Error handling and recovery



2. **Batch Processing**

   ```typescript

   // Example batch processing

   export const embed = async (

     text: string | string[],

     batch_size: number = 15

   ): Promise => {

     // Process in batches for optimal performance

   }

   ```



3. **Reranking System**

   - Cross-encoder for accurate result ranking

   - Contextual similarity scoring

   - Optional document return with scores



#### Performance Features



1. **Efficient Storage**

   - Incremental updates

   - Document hashing for change detection

   - Optimized vector storage

   - Automatic garbage collection



2. **Fast Retrieval**

   ```mermaid

   graph LR

       A[Query] --> B[Vector]

       B --> C{Search Type}

       C -->|ANN| D[Approximate Search]

       C -->|KNN| E[Exact Search]

       D --> F[Results]

       E --> F

   ```



3. **Optimization Techniques**

   - Approximate Nearest Neighbor (ANN) search

   - Vector quantization

   - Dimension reduction

   - Caching strategies



#### Advanced Features



1. **Hybrid Search**

   - Combined keyword and semantic search

   - Weighted scoring system

   - Metadata filtering

   - Context-aware ranking



2. **Vector Operations**

   ```typescript

   interface RankResult {

     corpus_id: number

     score: number

     text?: string

   }

   ```



## Open Source Readiness



This repository is set up for collaborative development:



- Environment variables are documented in `.env.example`. Provide your own API keys during local development; none are committed to source control.

- The renderer and main process read configuration through the validated helpers in `src/main/config.ts`, ensuring secrets never live in the UI bundle.

- Prefer `npm` for dependency management (`package-lock.json` is authoritative). After cloning, run:



  ```bash

  npm install

  npm run dev

  npm run lint

  npm run typecheck

  ```



- Secret scanning is encouraged for contributors (e.g., `git secrets --scan`) before submitting pull requests.

- UI components follow the frosted-glass design tokens declared in `src/renderer/src/assets/index.css`—please align new work with these utilities for consistency.



3. **Quality Assurance**

   - Automated consistency checks

   - Vector space analysis

   - Performance monitoring

   - Error detection



#### System Integration



```mermaid

sequenceDiagram

    participant App as Application

    participant VDB as Vector DB

    participant Worker as Worker Thread

    participant Storage as File Storage

    

    App->>VDB: Index Request

    VDB->>Worker: Vectorize Content

    Worker->>Worker: Process Batch

    Worker-->>VDB: Return Vectors

    VDB->>Storage: Store Vectors

    Storage-->>VDB: Confirm Storage

    VDB-->>App: Index Complete

    

    App->>VDB: Search Request

    VDB->>Worker: Vectorize Query

    Worker-->>VDB: Query Vector

    VDB->>Storage: Vector Search

    Storage-->>VDB: Search Results

    VDB-->>App: Ranked Results

```



## Prerequisites



- Node.js (v18 or higher recommended)

- npm 9+ (ships with Node.js and matches the repository lockfile)

- Brave Search API key (optional)

- OpenRouter API key (optional)



## Development



```bash

# Install dependencies

npm install



# Start the development server

npm run dev

```



## Building for Production



```bash

# For macOS

npm run build:mac



# For Windows

npm run build:win



# For Linux

npm run build:linux

```



## Configuration



Copy `.env.example` to `.env` in the project root and populate any API keys you intend to use:



```bash

cp .env.example .env

```



The application validates its environment variables at startup and will surface an error if required

values are malformed. Both `BRAVE_API_KEY` and `OPENROUTER_API_KEY` are optional—features that depend on

them will simply be skipped when the keys are not provided.



## Project Structure



```

alBERT-launcher/

├── src/

│   ├── main/                 # Electron main process

│   │   ├── api.ts           # tRPC API endpoints

│   │   ├── db.ts            # Search database management

│   │   ├── embeddings.ts    # Text embedding functionality

│   │   └── utils/           # Utility functions

│   ├── renderer/            # React frontend

│   │   ├── components/      # UI components

│   │   ├── lib/            # Utility functions

│   │   └── App.tsx         # Main application component

│   └── preload/            # Electron preload scripts

├── public/                 # Static assets

└── electron-builder.json5  # Build configuration

```



## API Documentation



### Search API

The search API supports various query types:

- Basic text search

- Semantic search

- Natural language questions

- File metadata queries



Example queries:

```

"find documents about react hooks"

"what are the key points from my meeting notes?"

"show me python files modified last week"

```



### File Monitoring

alBERT automatically monitors the `~/alBERT` folder for:

- New files

- File modifications

- File deletions

- File moves



Changes are automatically indexed and available for search immediately.



## Contributing



We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.



## License



This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.



## Acknowledgments



- [Electron](https://www.electronjs.org/)

- [React](https://reactjs.org/)

- [tRPC](https://trpc.io/)

- [Brave Search](https://brave.com/search/)

- [OpenRouter](https://openrouter.ai/)



## Support



If you encounter any issues or have questions, please file an issue on our [GitHub Issues](https://github.com/lekt9/alBERT-launcher/issues) page.