ahai Documentation

ahai finds the core ideas scattered across your markdown files—in Obsidian vaults, repo READMEs, clipped content, and more. Everything runs locally on your Apple Silicon Mac using MLX.

Installation

Download the app

Get the DMG file from ahai.app.

Install

Open the DMG file and drag ahai to your Applications folder.

Launch

Open ahai from your Applications folder or Spotlight.

First Launch

When you first open ahai, the app will request permission to access folders on your Mac. Grant this permission so ahai can scan your markdown files. Your data never leaves your machine—all processing happens locally.

Starting a Session

1. Click "New Session"

Find this button in the main window.

2. Select a folder

Choose any folder containing markdown files—an Obsidian vault, a GitHub repo, exported notes, or any collection of .md files.

3. Processing begins

ahai automatically scans all markdown files in the folder and its subfolders. Progress is displayed in real-time.

Understanding Results

Discovered ideas are displayed in a list. Each item shows the source file path, an excerpt from your note, and a confidence indicator showing how strongly the AI believes this is a forward-looking concept.

Session Management

Sessions are saved automatically as you work. Resume any session from the session list in the sidebar. Each session tracks which files were processed and preserves your organization choices.

Drag-Drop Organization

Reorder discovered ideas by dragging them to new positions. Your custom order is preserved across sessions, letting you prioritize what matters most.

Hide Items

Right-click any idea to hide it from view. Hidden items aren't deleted—restore them anytime from the View menu by selecting "Show Hidden Items."

Use the search box at the top of the results list to filter ideas by keyword. Search matches against both the excerpt text and the source file path.

Export

Export your organized ideas in three formats:

JSON — structured data for programmatic use
CSV — spreadsheet-compatible format
Markdown — human-readable list, ideal for pasting into notes

Find export options in the File menu or use the keyboard shortcut ⌘E.

Settings

Open Preferences (⌘,) to configure the default output folder location and other options.

Frequently Asked Questions

What is a forward-looking concept?

Ideas captured for future action: features to build, content to write, questions to research, improvements to make. These are the seeds of future work scattered throughout your notes.

What file types does ahai scan?

Markdown files with the .md extension. This includes Obsidian vaults, GitHub repositories, Bear exports, Notion exports, and any other markdown files.

Does my data leave my Mac?

No. All processing happens locally using Apple's MLX framework. There are no cloud services, no API calls, no data transmission. Your notes stay on your machine.

What are the system requirements?

An Apple Silicon Mac (M1, M2, M3, or M4) with minimum 16GB RAM, running macOS 13 Ventura or later. Intel Macs are not supported.

How long does scanning take?

Processing time depends on the number of files. A few hundred files typically complete in 1–5 minutes. Progress is shown in real-time so you can monitor the scan.

Can I disagree with what ahai found?

Absolutely. Hide any item you don't consider actionable. The AI surfaces candidates; you decide what matters. Your judgment is the final filter.

Where are sessions stored?

In ~/Library/Application Support/ahai/

What AI models can I use?

ahai works with any mlx_lm compatible model that fits on your machine. Models are downloaded to your configured HuggingFace cache location. For good performance, the model should be roughly ≤ half your system RAM. If you're not familiar with mlx models, a default model is downloaded automatically.

Is the output 100% accurate?

ahai contains AI-generated content, so use with caution. The AI surfaces candidates; you decide what matters. Your judgment is the final filter.

Troubleshooting

App won't launch

Verify you're running an Apple Silicon Mac (M1/M2/M3/M4) with minimum 16GB RAM and macOS 13 Ventura or later. Intel Macs are not supported.

When Gatekeeper blocks the app, right-click the ahai icon and select "Open" from the context menu. Confirm the dialog to allow the app to run.

Processing seems stuck

Large folders with thousands of files take time to process. Check the progress indicator to confirm scanning is still active. You can cancel the current session and resume later—progress is saved automatically.