Your notes and meetings

Heya can work with your personal notes vault: read it to ground answers, add to it without ever rewriting anything, turn meeting transcripts into notes, and listen along on a call to remind you of things your vault already knows.

This page walks through the whole setup, from an empty config to live listening. Each step works on its own; stop wherever you have what you need.

Step 1: point Heya at your vault

A vault is a folder of markdown notes. An Obsidian vault is exactly that, so if you use Obsidian, point Heya at the same folder. Add to ~/.config/heya/config.toml:

[vault]
path = "~/Notes"

That is the only required line. Restart Heya and ask something your notes can answer:

> what do my notes say about Alex?

Heya searches the vault (notes show up in the knowledge base under vault/ names), reads the matching notes, and cites them by name.

Optional settings, with their defaults:

[vault]
path = "~/Notes"
daily_dir = ""              # folder for daily notes ("" = vault root)
daily_format = "%Y-%m-%d"   # daily-note filename (.md added)
inbox = "Inbox.md"          # where quick captures go
meetings_dir = "Meetings"   # where meeting notes go

What Heya can and cannot do to your notes

Two write tools exist, and both ask for approval every time:

vault_append adds lines to the END of a note (today's daily note, the inbox, or any note by path). It creates the note when missing.
vault_create_note creates a new note and refuses to touch an existing one.

There is no edit tool. Heya cannot rewrite, reorder, or delete anything in your vault; that is enforced in code, not by a polite instruction. The general file tools cannot reach the vault folder at all.

So this works, and is safe to say yes to:

> add a task to my daily note: review the migration PR

Step 2: turn a meeting into a note

/meeting takes a transcript and writes one grounded note to your meetings folder:

/meeting @transcript.md

You can also paste the transcript right after typing /meeting, with no file. Either way, Heya:

extracts the decisions, action items, and commitments (not a transcript dump),
checks every person and date against your vault, cites the notes it used, and warns you when the meeting contradicts them (a follow-up scheduled with someone your vault says is away, for example),
writes Meetings/2026-07-22 <title>.md with your approval.

Links and tasks are gated in code: [[wikilinks]] to notes that do not exist are turned into plain text, a filename collision picks a numbered variant instead of overwriting, and action items already open anywhere in your vault are dropped instead of duplicated.

No pasting: pull the transcript from Granola

If you run Granola on your calls, connect its MCP server and Heya fetches the meeting itself:

[mcp.servers.granola]
transport = "http"
url = "https://mcp.granola.ai/mcp"
auth = "oauth"

Restart Heya, approve the browser sign-in once, then:

/meeting

With no file and no paste, Heya asks Granola for your latest meeting. Two Granola caveats: only finished meetings are available (nothing mid-call), and fetching full transcripts needs a paid Granola plan.

Step 3: listen live

/listen records your microphone, transcribes locally in ~20 second chunks, and speaks up only when the conversation touches something your vault knows:

/listen
  listening: recording from the microphone (local transcription only; ...)
...
  vault hint: People/Alex: AFK from Jul 30, per your note
...
/listen stop

/listen stop ends the recording and feeds the whole transcript into the /meeting flow above, so you get the same grounded note and tasks.

How the live loop works

Audio streams in continuously and is transcribed locally in ~20 second chunks. Each chunk goes through three gates, so silence costs nothing:

Plain code checks whether a vault note's name was just said, or was said in the last few chunks (about a minute and a half at the default 20 second chunk size) while the current chunk carries a commitment (a weekday, "next week", "follow up", "deadline", leave words). No match, nothing happens; no model is consulted.
On a match, one small-model call reads the chunk, the recent conversation, the matched notes' actual content, and the notes they [[link]] to (one hop), and picks one of three answers: stay silent (the usual case), warn you from the vault ("vault hint: People/Alex: AFK from Jul 30"), or capture a moment that was just agreed ("noted: Alex to send the migration plan by Friday").
Each vault note warns at most once per DAY across calls (the reminder you saw on the morning standup stays quiet on the afternoon sync; set hint_memory = false under [voice] for once per call instead), and captured moments are shown as they happen, kept, and handed to the meeting note at /listen stop, so a long call cannot lose its early decisions.

Type /listen again mid-call to see how many transcript lines and live notes Heya has so far.

Setup, once, with one command:

heya voice

The wizard does everything: installs the audio packages into Heya's own environment (works the same for pip, pipx, and Homebrew installs), lets you pick a speech model from a short list (Parakeet v3 is the suggested default: fast, accurate, 25 European languages; the Whisper family covers about 100 languages), downloads it with a progress bar so nothing surprises you mid-call, and tests the microphone so macOS asks for permission during setup instead of during a meeting.

Local transcription currently needs an Apple Silicon Mac (the models run on the Metal GPU). One thing to know: upgrading Heya with pipx or Homebrew rebuilds its environment, so if /listen stops finding the engine after an upgrade, run heya voice once more.

Hearing both sides of the call

By default /listen hears only your microphone. The wizard offers one more step: a tiny audio helper (built from source Heya ships, or downloaded checksum-verified from a Heya release) that taps SYSTEM audio, so the other side of a Slack huddle or a call is transcribed too. With it on, transcript lines carry [me] and [them] labels, and the meeting note knows who said what without any voice-recognition guesswork.

It needs macOS 14.2 or newer, and macOS asks once for the "System Audio Recording" permission (the wizard triggers that prompt during setup; a few terminals, iTerm among them, may need the permission granted by hand under System Settings, Privacy & Security). Turn it off any time with system_audio = false under [voice].

What to know before using it on a real call:

Audio never leaves your machine; transcription is fully local. The transcribed TEXT is another matter: it goes to whatever model you configured, for the live hints and the meeting note. On a confidential call, use a local model profile so nothing leaves the machine at all.
Tell the people you are talking to that you are taking notes. Recording laws in many places require everyone's consent, and that matters even more once both sides are captured.
Hints are deliberately rare: a vault note's name has to come up, and a small model then checks whether the note actually matters. Silence is normal.
Transcripts are saved under ~/.config/heya/transcripts/. Set keep_transcripts = false under [voice] to delete them once the note is written.

Tuning, all optional (heya voice writes engine and model for you):

[voice]
engine = "auto"          # auto | mlx-whisper | parakeet
model = ""               # a specific model repo, engine default when empty
chunk_seconds = 20       # smaller = faster hints, more compute
language = ""            # force a language, auto-detect when empty
keep_transcripts = true
system_audio = true      # hear the other side too, once set up

Troubleshooting

"/meeting needs a vault": add the [vault] block above and restart.
"no local speech-to-text engine is available": run heya voice; on anything other than an Apple Silicon Mac, local STT is not supported yet.
/listen broke after upgrading Heya: pipx and Homebrew rebuild Heya's environment on upgrade. Run heya voice again; the model itself stays cached, so this takes seconds.
Heya (or the terminal) died mid-call: nothing is lost. The transcript is written to disk as the call happens, and the next /listen points at the unfinished session's file with the exact /meeting @path command to turn it into a note.
No hints during a call: that usually means your vault has nothing to say. Check that the people you talk about have notes (a People/ folder with one note per person works well), and that facts like leave dates are in them.
The model heard nonsense: whisper-family models sometimes invent text during silence. Dead-air chunks are skipped before transcription (silence_threshold under [voice]; useful values sit between 0 and about 0.1, raise it in a noisy room, set 0 to turn the gate off), and the meeting note step filters what matters.