mnemo

mnemo records a voice note from your default microphone, transcribes it with ElevenLabs, and stores the resulting text in Hindsight.

Requirements

• A working macOS microphone input
• An ElevenLabs API key with Speech-to-Text access
• A running Hindsight API endpoint

Rust and Cargo are only required if you build from source or install the latest development build with brew install --HEAD mnemo.

Platform Support

mnemo currently publishes prebuilt releases for macOS Apple Silicon only.

Supported target:

• aarch64-apple-darwin

Other platforms may work from source, but are not currently tested or packaged.

Usage

Start recording a voice note:

mnemo record

Press Enter in that terminal when you are done. mnemo will stop recording, transcribe the audio, and retain the transcript in Hindsight.

Stream Decks And External Triggers

As an alternative to pressing Enter, you can stop an active recording from another process:

mnemo stop

This is useful for external triggers like a Stream Deck button. Start recording with mnemo record, then have the button run mnemo stop to signal that recording process to finish.

Installation

Install with Homebrew:

brew tap Toady00/tap
brew install mnemo

To install the latest development build from the default branch instead:

brew install --HEAD mnemo

Or install from a GitHub release by downloading the mnemo-aarch64-apple-darwin.tar.gz asset, extracting it, and moving mnemo to a directory on your PATH.

Configuration

The default config file location is:

~/.config/mnemo/config.toml

Create a starter config:

mnemo init

Or create it from the example:

mkdir -p ~/.config/mnemo
cp config.example.toml ~/.config/mnemo/config.toml

All configuration lives under a named profile. The default profile is default, and it is used when no profile is specified.

Supported config keys:

[profiles.default]
hindsight_url = "https://your-hindsight-api.example.com"
bank = "personal"
language = "eng"
model = "scribe_v2"
context = "user recorded voice memo"

# Optional Hindsight retain fields. Leave unset to send null.
# metadata = { source = "mnemo" }
# tags = ["voice-note"]
# strategy = "append"

# Defaults to ~/.local/state/mnemo/mnemo.sock
# socket_path = "/Users/you/.local/state/mnemo/mnemo.sock"

# Prefer macOS Keychain or environment variables for secrets, but config keys are supported.
# elevenlabs_api_key = "..."
# hindsight_api_key = "..."

Config precedence is:

built-in defaults < config.toml < environment variables < CLI flags

hindsight_url is required for mnemo record. Set it in the config file, MNEMO_HINDSIGHT_API_URL, or --hindsight-url.

bank and an ElevenLabs API key are also required for mnemo record. Set bank in the selected profile, MNEMO_BANK_ID, or --bank.

API key precedence for ElevenLabs and Hindsight keys is:

CLI flag > MNEMO_* environment variable > macOS Keychain > config.toml

In practice, prefer macOS Keychain for normal use and MNEMO_ELEVENLABS_API_KEY or MNEMO_HINDSIGHT_API_KEY for one-time setup or development overrides.

macOS Keychain

mnemo can store API keys in macOS Keychain so GUI wrappers and plugin-launched processes do not need shell environment variables.

First-time setup:

export MNEMO_ELEVENLABS_API_KEY="your-elevenlabs-key"
export MNEMO_HINDSIGHT_API_KEY="your-hindsight-key"
mnemo keychain sync
unset MNEMO_ELEVENLABS_API_KEY
unset MNEMO_HINDSIGHT_API_KEY

For a named profile:

export MNEMO_ELEVENLABS_API_KEY="your-business-elevenlabs-key"
export MNEMO_HINDSIGHT_API_KEY="your-business-hindsight-key"
mnemo keychain sync --profile business
unset MNEMO_ELEVENLABS_API_KEY
unset MNEMO_HINDSIGHT_API_KEY

List API keys stored in Keychain:

mnemo keychain list

Remove selected Keychain entries interactively:

mnemo keychain remove

Remove all mnemo API keys with confirmation:

mnemo keychain remove --all

Remove all mnemo API keys without confirmation:

mnemo keychain remove --all --force

Keychain entries use service mnemo-secrets and account names scoped by profile and key name:

profile:default:elevenlabs-api-key
profile:default:hindsight-api-key
profile:business:elevenlabs-api-key
profile:business:hindsight-api-key

Keychain operations shell out to /usr/bin/security so access is tied to Apple's stable system tool rather than mnemo's binary signature.

Profiles

Profiles let you keep separate Hindsight destinations and retain settings in one config file. Each profile lives under [profiles.<name>].

Example:

[profiles.default]
hindsight_url = "https://your-hindsight-api.example.com"
bank = "personal"
context = "user recorded voice memo"

[profiles.business]
hindsight_url = "https://your-hindsight-api.example.com"
bank = "business"
context = "user recorded business voice memo"
tags = ["business", "voice-note"]
strategy = "append"

[profiles.family]
hindsight_url = "https://your-hindsight-api.example.com"
bank = "family"
context = "user recorded family voice memo"
metadata = { source = "mnemo", category = "family" }

Use the default profile:

mnemo record

Use a named profile:

mnemo record --profile business

Or select a profile with an environment variable:

export MNEMO_PROFILE="business"
mnemo record

Profile values can still be overridden by MNEMO_* environment variables or CLI flags. For example, this records to the business profile but overrides the bank for one run:

mnemo record --profile business --bank temporary-business-notes

Supported environment variables:

export MNEMO_ELEVENLABS_API_KEY="your-elevenlabs-key"
export MNEMO_HINDSIGHT_API_KEY="your-hindsight-key-if-needed"
export MNEMO_HINDSIGHT_API_URL="https://hindsight-api.example.com"
export MNEMO_PROFILE="default"
export MNEMO_BANK_ID="personal"
export MNEMO_ELEVENLABS_LANGUAGE="eng"
export MNEMO_ELEVENLABS_MODEL="scribe_v2"
export MNEMO_SOCKET_PATH="$HOME/.local/state/mnemo/mnemo.sock"
export MNEMO_CONTEXT="user recorded voice memo"
export MNEMO_TAGS="voice-note,personal"
export MNEMO_STRATEGY="append"
export MNEMO_METADATA='{"source":"mnemo"}'

Development

Check that the project builds:

cargo check

Format the code:

cargo fmt

Run the app in development mode:

cargo run -- record

mnemo defaults to record, so this is equivalent:

cargo run

Override config from the CLI:

cargo run -- --bank personal --language auto

Use a named profile:

cargo run -- record --profile business

Or with the installed binary:

mnemo record --profile business

Set the Hindsight URL from the CLI:

cargo run -- --hindsight-url https://your-hindsight-api.example.com

Use a different config file:

cargo run -- --config /path/to/config.toml

When running record, mnemo starts recording immediately. Press Enter to stop recording, then it will transcribe and retain the note.

You can also stop a running recording from another shell:

cargo run -- stop

record opens a Unix socket at:

~/.local/state/mnemo/mnemo.sock

Only one mnemo record process can run at a time. If the socket belongs to a live process, a second record command exits instead of trying to record from the microphone at the same time. If the socket is stale, mnemo removes it and continues.

The socket stays open for the full mnemo record lifecycle and uses newline-delimited JSON. New clients receive the current status immediately after connecting, and connected clients receive future status changes.

Status messages look like:

{"type":"status","state":"recording","startedAt":"2026-05-09T19:24:18.248Z"}
{"type":"status","state":"processing","startedAt":"2026-05-09T19:24:18.248Z"}
{"type":"status","state":"complete","startedAt":"2026-05-09T19:24:18.248Z"}
{"type":"status","state":"error","startedAt":"2026-05-09T19:24:18.248Z","message":"failed to call ElevenLabs STT"}

Clients can request the current status or stop an active recording:

{"type":"status"}
{"type":"stop"}

No socket means mnemo is idle. recording means stop is valid. processing, complete, and error are terminal or near-terminal states where the socket will close shortly after the final status is published.

Release Process

mnemo releases are currently built locally for macOS Apple Silicon and published through GitHub Releases.

Before releasing, verify the project:

cargo fmt --check
cargo test
cargo clippy -- -D warnings

Build the release binary:

cargo build --release

Package the release asset:

mkdir -p dist
cp target/release/mnemo dist/mnemo
tar -czf dist/mnemo-aarch64-apple-darwin.tar.gz -C dist mnemo
shasum -a 256 dist/mnemo-aarch64-apple-darwin.tar.gz

Create and push a signed release tag:

git tag -s vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

Create the GitHub release:

gh release create vX.Y.Z \
  dist/mnemo-aarch64-apple-darwin.tar.gz \
  --title "mnemo vX.Y.Z" \
  --notes-file CHANGELOG.md

After the release asset is published, update the Homebrew formula in Toady00/homebrew-tap with the new version URL and SHA-256 checksum.

Build A Local Binary

Build an optimized local macOS binary:

cargo build --release

The binary will be created at:

target/release/mnemo

Install it somewhere on your PATH, for example:

mkdir -p ~/.local/bin
cp target/release/mnemo ~/.local/bin/mnemo

Then run it from anywhere:

mnemo

Make sure ~/.local/bin is on your PATH if the command is not found.

macOS Notes

The first time you run mnemo, macOS may ask for microphone permission for your terminal app. Approve microphone access, then run the command again if the first attempt fails.