FloatMemo

A lightweight, always-on-top sticky notes app for macOS with Markdown support, rich text editing, and seamless workspace integration.

Overview

FloatMemo is a macOS desktop application that brings floating memo windows to your workspace. Create quick notes with Markdown formatting, syntax-highlighted code blocks, and customizable appearance. Memos stay on top of other windows, sync across spaces, and persist automatically to your filesystem.

Built with Swift 6, SwiftUI, and AppKit, FloatMemo requires only the Swift toolchain to build and run—no Xcode needed.

Features

Core Features

• Floating Windows: Memos stay on top of all other applications
• Rich Text Editing: NSTextView-based editor with line numbering support
• Markdown Preview: Render and preview Markdown with real-time syntax highlighting
• Code Syntax Highlighting: Supports 180+ languages via Highlightr
• Auto-Save: Changes persist automatically (500ms debounce)
• Menu Bar Integration: Minimize to menu bar, no dock icon by default
• Global Hotkeys:
  • Cmd+Shift+N: Create new memo
  • Cmd+Shift+M: Toggle visibility of all memos

Customization

• 8 Color Schemes: Yellow, Blue, Green, Pink, Purple, Orange, Gray, White (light and dark variants)
• Opacity Control: 20-100% per memo
• Window Size Presets: Small (250x300), Medium (350x450), Large (500x650)
• Light/Dark/System Themes: Override system appearance for the app
• Line Numbers: Toggle line numbers in editor (Settings)
• Font Size: Configurable per-memo (14pt default)

Window Management

• Pin/Compact Mode: Double-click title bar to toggle compact view
• Space Behavior:
  • All Spaces: Memo appears on every space
  • Follow User: Memo appears on current space only
  • Stay on Space: Memo stays on the space where created
• Multi-Display Support: Automatically relocates memos when displays disconnect/reconnect
• Position & Size Persistence: Remembers window positions and dimensions across restarts

Organization

• Folder Organization: Create, rename, and delete folders to organize memos
• Folder Management: Drag memos into folders for better workspace organization

Search & Export

• Full-Text Search: Search across all memo content and titles
• Export Options: Export memos as Markdown (.md), plain text (.txt), or PDF (.pdf)
• Right-Click Context Menu: Quick access to export, resize, pin, and color options

System Integration

• Launch at Login: Optional system preference via SMAppService
• Multi-Display Tracking: Memos remember which screen they were created on
• Settings Window: Dedicated UI for General, Appearance, and Shortcuts configuration

Requirements

• macOS 14.0 (Sonoma) or later
• Swift 6.0 toolchain
• Apple Silicon or Intel Mac

Installation

Build from Source

Clone the repository and build with Swift Package Manager:

git clone <repository-url> floatmemo
cd floatmemo
swift build
.build/debug/FloatMemo

Or build optimized release version:

swift build -c release
.build/release/FloatMemo

Running the App

After building, the executable is available at .build/debug/FloatMemo or .build/release/FloatMemo. You can:

• Run directly from the terminal
• Move the executable to /Applications for system integration
• Create an alias or shell script for easier access

Project Structure

The project uses a modular architecture organized by domain:

Sources/FloatMemo/
├── App/                          # Application entry point and configuration
│   ├── AppConstants.swift        # Constants (window sizes, defaults, etc.)
│   ├── AppDelegate.swift         # macOS app delegate, lifecycle management
│   └── FloatMemoApp.swift        # SwiftUI app root, menu bar integration
│
├── Models/                       # Data models
│   ├── Memo.swift                # Memo data structure (Codable)
│   ├── Folder.swift              # Folder organization structure
│   ├── MemoColor.swift           # Color enumeration with light/dark variants
│   ├── SpaceBehavior.swift       # Space behavior enumeration
│   └── WindowSizePresets.swift   # Window size preset definitions
│
├── Panels/                       # Window and UI layer management
│   ├── MemoPanel.swift           # Custom NSPanel subclass (always-on-top)
│   ├── MemoPanelController.swift # Window lifecycle and state management
│   └── PanelHostingView.swift    # SwiftUI view wrapper for NSPanel
│
├── Services/                     # Business logic and utilities
│   ├── DataStore.swift           # JSON persistence, memo CRUD
│   ├── WindowManager.swift       # Window lifecycle and display tracking
│   ├── HotkeyManager.swift       # Global hotkey registration (Carbon API)
│   ├── DisplayTracker.swift      # Multi-display support and screen tracking
│   ├── AutoSaveManager.swift     # Automatic save coordination via Combine
│   ├── ExportService.swift       # Markdown, text, and PDF export
│   └── MarkdownTheme.swift       # Markdown rendering configuration
│
├── TextEditor/                   # Rich text editing
│   ├── MemoTextView.swift        # NSTextView integration via NSViewRepresentable
│   ├── MemoTextViewCoordinator.swift  # Text delegate and event handling
│   ├── MemoTextStorage.swift     # Custom NSTextStorage for syntax highlighting
│   ├── CodeHighlighter.swift     # Highlightr integration
│   └── LineNumberRulerView.swift # Line number ruler UI
│
├── ViewModels/                   # MVVM view state management
│   ├── MemoViewModel.swift       # Single memo state and actions
│   ├── MemoListViewModel.swift   # Memo list and window coordination
│   └── SettingsViewModel.swift   # Settings and preferences
│
├── Views/                        # SwiftUI UI components
│   ├── MemoView.swift            # Main memo window UI
│   ├── MemoTitleBar.swift        # Custom title bar with controls
│   ├── MemoListView.swift        # Menu bar memo list
│   ├── MemoPreviewView.swift     # Markdown preview rendering
│   ├── SettingsView.swift        # Settings/preferences window
│   │
│   └── Components/               # Reusable UI components
│       ├── ColorPickerView.swift # Color selection UI
│       ├── OpacitySlider.swift   # Opacity control slider
│       ├── MarkdownToggle.swift  # Editor/preview mode toggle
│       └── HighlightedCodeBlock.swift  # Code block with syntax highlighting
│
└── Extensions/                   # Swift extensions
    ├── Color+MemoColors.swift    # Color scheme utilities
    ├── NSScreen+Identifier.swift # Screen identification for multi-display support
    └── View+ConditionalModifier.swift  # SwiftUI modifier helpers

Architecture

Design Patterns

• MVVM (Model-View-ViewModel): UI state separated from business logic
• Coordinator Pattern: WindowManager coordinates memo lifecycle and display
• Observable Macro: Swift 6's @Observable for reactive state management
• NSViewRepresentable: Bridges AppKit components into SwiftUI

Key Technologies

• SwiftUI: Modern declarative UI framework
• AppKit (NSPanel): Native macOS floating window implementation
• NSTextView: Rich text editing with delegates and custom storage
• Carbon API: Global hotkey registration via RegisterEventHotKey
• Combine: Reactive programming for auto-save coordination
• MarkdownUI: Markdown parsing and rendering
• Highlightr: Code syntax highlighting (180+ languages)

Data Flow

1. DataStore (observable): Maintains in-memory memo and folder state
2. WindowManager: Creates and manages memo windows via MemoPanel
3. MemoPanelController: Bridges NSPanel with SwiftUI views
4. ViewModels: Expose state and mutations to SwiftUI components
5. AutoSaveManager: Debounces changes and triggers DataStore persistence

Usage

Creating and Managing Memos

New Memo

• Press Cmd+Shift+N or use menu bar "Create" button
• Memos appear at random positions on screen
• Click to start typing immediately

Edit Mode

• Type or paste content into the editor
• Switch between editor and preview with "Markdown" toggle
• Changes auto-save after 500ms inactivity

Colors & Appearance

• Right-click memo for context menu
• Select color, or open color picker in title bar
• Adjust opacity slider (20-100%)
• All changes persist automatically

Window Controls

• Double-click title bar: Toggle compact view
• Resize: Drag corner or use size presets (Small/Medium/Large)
• Pin: Click pin icon to keep memo on top of other memos
• Close: Click close button (memo is archived, not deleted)

Organizing with Folders

1. Open menu bar > "New Folder"
2. Name the folder
3. Drag memos into folder
4. Right-click folder to rename or delete

Searching Memos

1. Open menu bar > "Search"
2. Type search term to find content across all memos
3. Click result to open memo

Exporting Memos

1. Right-click memo
2. Select "Export as..."
3. Choose format: Markdown (.md), Text (.txt), or PDF (.pdf)

Settings

Open FloatMemo > Settings (Cmd+,) to configure:

General Tab

• Launch at Login toggle
• Default window size preference

Appearance Tab

• Light/Dark/System theme override
• Show line numbers toggle
• Default font size

Shortcuts Tab

• View and customize global hotkey bindings
• Cmd+Shift+N: New memo
• Cmd+Shift+M: Toggle all memos visibility

Dependencies

• swift-markdown-ui (2.4.0+): Markdown rendering
• Highlightr (2.2.1+): Code syntax highlighting

Dependencies are automatically resolved via Swift Package Manager (SPM).

Data Storage

Memos and settings are stored in:

~/Library/Application Support/FloatMemo/
├── memos.json          # Array of memo objects
├── folders.json        # Array of folder objects
└── settings.json       # User preferences and hotkey configuration

Files use standard JSON encoding. Manual editing is supported but not recommended.

Memo JSON Structure

{
  "id": "UUID",
  "title": "Optional title",
  "content": "Markdown content",
  "color": "yellow",
  "positionX": 100,
  "positionY": 100,
  "width": 300,
  "height": 400,
  "screenID": "screen-identifier",
  "isPinned": false,
  "isCompact": false,
  "opacity": 0.95,
  "fontSize": 14,
  "spaceBehavior": "allSpaces",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z",
  "folderID": null
}

Development

Building

# Debug build
swift build

# Release build (optimized)
swift build -c release

# Run tests
swift test

# Build and run in one command
swift run FloatMemo

Key Development Files

• AppConstants.swift: Window sizes, UI constants, auto-save debounce timing
• HotkeyManager.swift: Global hotkey registration and event handling
• DataStore.swift: Persistence logic and data mutations
• WindowManager.swift: Window lifecycle and multi-display coordination
• MemoPanel.swift: NSPanel configuration for floating behavior

Adding Features

1. New Memo Property: Update Memo.swift model, DataStore persistence, and ViewModels
2. New UI Control: Create in Components folder, integrate into MemoView
3. New Service: Add to Services folder, integrate with WindowManager or AppDelegate
4. New Settings Option: Update SettingsView and SettingsViewModel

Code Style

• Type Annotations: Used for clarity in complex contexts
• Access Control: Private by default, public only when necessary
• Separation of Concerns: Services handle business logic, ViewModels manage state
• SwiftUI Modifiers: Prefer environment and state over prop drilling

Known Limitations

• Global hotkeys require accessibility permissions (granted on first use)
• Line numbers are optional due to performance considerations in rich text views
• Markdown preview doesn't support embedded images (files only)
• PDF export quality depends on system PDF rendering

Keyboard Shortcuts

Action	Shortcut
New Memo	Cmd+Shift+N
Toggle All Memos	Cmd+Shift+M
Settings	Cmd+,
Find in Memo	Cmd+F
Toggle Compact	Double-click title bar

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit with clear messages
4. Submit a pull request

Support

For bugs, feature requests, or questions:

• Open an issue on GitHub
• Check existing issues for similar problems

Future Enhancements

Potential features for future versions:

• Cloud synchronization
• Rich text formatting toolbar
• Memo tagging and advanced search
• Custom keyboard shortcuts configuration (UI)
• Dark mode color schemes
• Notification/reminder system
• Collaborative editing

---

Version: 1.0.0 Last Updated: February 2026 Maintainer: FloatMemo Contributors Swift Version: 6.0+ macOS Version: 14.0+ (Sonoma)