Mnemosyne

A command-line tool to instantly find and open any of your files from anywhere — search by content or browse your full index, and jump straight to the result in your configured IDE. It also manages workspaces: named sets of apps, files, and URLs you can launch all at once.

mn add thesis.pdf
mn search "simplex algorithm"
mn open                       # pick a workspace and launch everything in it

Named after the Greek goddess of memory.

---

Contents

• Install
• Documentation
• Building from source
  • Linux
  • macOS
  • Windows
  • Enabling GUI IDE launchers
  • Enabling PDF support
  • Uninstalling
• Quick Start

Install

Windows — download Mnemosyne-Setup-<version>.exe from the latest release and run it. No admin rights needed, no separate PDF setup — poppler is bundled. The installer adds mn to your user PATH; open a new terminal afterwards.

macOS and Linux installers aren't available yet — build from source below.

Documentation

• System Architecture — component diagram, module descriptions, source and data layouts
• Command Reference — all commands with examples
• Supported File Types — .txt, .md, .tex, .pdf parsing details
• Roadmap — v1 direct match → v4 semantic search

Building from source

make        # build the binary
make clean  # remove the binary

Installing (so you can type mn from anywhere)

Prerequisites — gcc and make (usually pre-installed; otherwise install via your distro's package manager).

Build and install:

sudo make install                      # installs to /usr/local/bin
make install PREFIX=$HOME/.local       # no-sudo alternative (~/.local/bin)

Add to PATH (no-sudo path only) — ~/.local/bin may not be on PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc   # or ~/.zshrc

Open a new terminal afterwards.

macOS

Prerequisites — Apple Command Line Tools (not the full Xcode IDE):

xcode-select --install

gcc on macOS is aliased to Apple Clang — the build works as-is.

Build and install:

sudo make install                      # installs to /usr/local/bin
make install PREFIX=$HOME/.local       # no-sudo alternative (~/.local/bin)

Add to PATH (no-sudo path only) — ~/.local/bin is not on PATH by default:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Open a new terminal afterwards.

Windows

Prerequisites — MSYS2 with the MinGW toolchain (provides gcc and make):

1. Download and run the installer from msys2.org.
2. In the MSYS2 UCRT64 shell, install the build tools:

   pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-make

3. Add MSYS2 to your Windows PATH (run in PowerShell, then open a new terminal):

   [Environment]::SetEnvironmentVariable('PATH', $env:PATH+';C:\msys64\ucrt64\bin', 'User')

Build and install (PowerShell, from the project directory):

mingw32-make
mingw32-make install

On Windows the binary is mingw32-make, not make. Use it wherever this README says make.

This copies mnemosyne.exe to %USERPROFILE%\bin\.

Copies mn.exe to %USERPROFILE%\bin\. If that folder is not yet on your PATH, run this once then open a new terminal:

[Environment]::SetEnvironmentVariable('PATH', $env:PATH+";$env:USERPROFILE\bin", 'User')

Open a new terminal afterwards.

Do not use setx to add to PATH — it truncates paths longer than 1024 characters, which can silently break other tools.

Enabling GUI IDE launchers

For mnemosyne to open files in code, cursor, or idea, the matching CLI launcher must be on your PATH. Windows and Linux installers usually handle this automatically. On macOS, it's a manual step:

IDE key	How to enable on macOS
code	Open VS Code → Cmd+Shift+P → run Shell Command: Install 'code' command in PATH
cursor	Open Cursor → Cmd+Shift+P → run Shell Command: Install 'cursor' command in PATH
idea	Open IntelliJ IDEA → Tools → Create Command-Line Launcher (or use JetBrains Toolbox → Settings → Generate shell scripts)

Open a new terminal afterwards, then verify with code --version, cursor --version, or idea --version.

nvim, vim, and nano are installed via package managers and are on PATH automatically.

Enabling PDF support

Mnemosyne extracts text from .pdf files via pdftotext (from poppler-utils). Without it, mn add on a PDF prints an error and skips the file — all other file types work normally.

Linux:

sudo apt install poppler-utils       # Debian/Ubuntu
sudo dnf install poppler-utils       # Fedora

macOS:

brew install poppler

Windows — fetch a bundled copy and install it alongside mn.exe. No system PATH changes, no separate poppler install:

mingw32-make fetch-poppler           # one-time, downloads ~50 MB into vendor/
mingw32-make install                 # copies pdftotext.exe + DLLs next to mn.exe

fetch-poppler downloads a pinned poppler-windows release into vendor/poppler-windows/ (gitignored) and normalizes the layout. install then copies it to %USERPROFILE%\bin\poppler\bin\ so mn.exe finds it as a sibling.

To pin a different release:

mingw32-make fetch-poppler POPPLER_VERSION=25.07.0-0

On Windows, mn resolves pdftotext.exe in this order: (1) next to mn.exe, (2) poppler\bin\ next to mn.exe, (3) PATH. So you can also drop a manually-downloaded poppler folder in either location instead of using fetch-poppler.

Uninstalling

If you used the Windows installer, uninstall via Settings → Apps → Mnemosyne (or Add/Remove Programs) — this also removes it from PATH.

If you built from source:

sudo make uninstall          # Linux/macOS if installed to /usr/local/bin
make uninstall               # Linux/macOS no-sudo install
mingw32-make uninstall       # Windows

Quick Start

On first run, Mnemosyne prompts you for a storage location and a default IDE. You can press Enter to accept the default storage path; the IDE is chosen from an interactive picker (arrow keys or type a number to jump to an option).

# add some files (or a whole folder — recurses into subfolders)
mn add notes.txt
mn add ~/Documents/thesis.md
mn add ~/Documents/notes      # indexes every supported file under notes/

# search (case-insensitive)
mn search simplex
# search (case-sensitive)
mn search Chapter -c
mn search -c Chapter

# change your default IDE later (opens a picker)
mn config ide

# or set it directly by name
mn config ide nvim

# browse all indexed files interactively
mn list

# remove a file, or a whole folder's worth in one shot
mn remove notes.txt
mn remove ~/Documents/notes

# create a workspace, then add/remove apps & links in it (code/cursor, or a full path to any .exe/app)
mn open create work
mn open edit

# or snapshot the apps you already have open into a new workspace
mn open snap

# launch everything in a workspace (interactive picker)
mn open

Supported IDE keys: code, cursor, nvim, vim, nano, idea. See Enabling GUI IDE launchers if code/cursor/idea aren't found on macOS.

Moved files are tracked automatically. When mn search or mn reindex notices an indexed file is no longer at its recorded path, it scans the file's git repo (and other indexed repos) for a file with the same name. A single match is re-indexed at its new location; zero or multiple matches drop the entry. Files not originally inside a git repo are dropped on first miss — re-add them with mn add.

After you open a file (mn search / mn list) or launch a workspace (mn open), Mnemosyne closes the terminal window it was launched from, leaving just the opened apps. Cancelling a picker with Esc opens nothing and leaves the terminal open. See the Command Reference for full details.