Give your assistant your knowledge

The most underused feature in Super Voice Mode isn’t a feature at all. It’s a side effect of the architecture: the file you write to define a character, persona, or augment can tell the assistant to read your local files before answering. Your notes become its source of truth. No upload, no cloud index, no embeddings to manage. Just markdown on disk and a one-line pointer.

This is what people mean when they say “build your own AI assistant.” Not “configure a chatbot.” Build something that has read what you’ve read, knows what you’ve decided, and answers in your voice.

How it works

The agentic backends — Claude, Codex, and Gemini — already have tool access on your Mac out of the box. Filesystem reads, shell, the works. Super Voice Mode hands them your active character, persona, and augment files as part of the system prompt. If any of those files says “read ~/Notes/work/decisions/ before answering questions about engineering”, that’s exactly what the backend does. It reads the files at query time, every time, so your notes can change between conversations and the assistant always sees the latest.

Three surfaces, one mechanism:

Character — when the knowledge defines a whole identity. Codebase. Founder. Game Master.
Persona — when knowledge layers on a way of speaking.
Augment — when you want a focused capability you can toggle on top of whatever character you’re already in.

Pick the surface that fits the shape of what you’re building. The pointer paragraph itself is the same in all three.

What you can build

Some shapes that work well today.

The engineer with a memory

You’re three years deep in a codebase. You’ve written ADRs that nobody reads. You’ve debugged the same edge case four times. Your deploy runbook lives in a wiki that’s two refactors out of date.

Point a character at ~/Code/yourproject/docs/ and ~/Notes/debugging/. Ask “why does the staging deploy hang on first boot?” and the assistant reads the runbook, finds your earlier note about the Redis healthcheck race, and walks you through the fix instead of suggesting generic Linux process debugging.

The solo founder

Customer interview notes from sixty calls. The pricing logic you’ve changed four times and can never remember the reasoning for. A growing folder of investor questions you’ve answered before — “How big is the market?”, “Why now?”, “What if Anthropic builds this?” — and the answers you actually used.

A founder character that reads ~/Founder/calls/, ~/Founder/pricing.md, and ~/Founder/pitch/objections/ lets you spend ten minutes at your desk before the meeting asking “what did Sarah at Acme say about onboarding?” and getting the real answer, in your own words, from your own notes.

The writer or journalist

Interview transcripts. Source notes. The style guide you wrote once and forgot. Past articles you want to be consistent with.

A character that reads ~/Writing/sources/, ~/Writing/style.md, and ~/Writing/published/ becomes a research assistant that’s actually read what you’ve read. Ask “what did Dr. Mendez say about the supply chain in the September interview?” and get the quote, with the surrounding context, ready to fact-check.

The game master

Campaign notes. NPC bios. The lore of your world. The session journal where you tracked what your players actually did, which is rarely what you planned for.

Point a character at ~/D&D/Eldarath/ and you have a co-DM who knows that the party already met the duke, that he was lying about the ledger, and that one of them is suspicious. Mid-session you can voice-ask “what was the name of the priest in Carrowend?” and get the answer fast enough not to break the table’s rhythm.

The operator

Standard operating procedures. Vendor history. Past customer escalations and what worked. The interview rubric your team uses, plus notes on what’s worked and what hasn’t.

A character that reads ~/Ops/sops/, ~/Ops/vendors/, and ~/Ops/hiring/notes/ is the institutional memory that doesn’t quit, take vacation, or get hit by a bus.

How to build one

The whole knowledge mechanism is one paragraph in your character, persona, or augment file. Something like this:

When the user asks about [their domain], read the markdown files
under `~/Documents/[their folder]` and answer from what's in them.
Treat those files as your source of truth.

That paragraph is the entire integration. The work that makes it actually useful is on the other side of the pointer — in the folder you just pointed at.

Get the basics right first

Most of what makes a knowledge folder work has nothing to do with extra metadata. Three things, all free:

Good filenames. acme-q3-pricing-decision.md tells the assistant ten times more than notes.md. Spend a second naming.
Folder structure that means something. decisions/, runbooks/, customers/acme/ — semantic directories help the assistant zero in on what’s relevant before it reads anything.
A clear H1 and opening paragraph in every file. Claude, Codex, and Gemini can ls, glob, and read files on demand. Give them a meaningful first line and they generally figure the rest out.

Get those right and a folder of fifty files is perfectly navigable with no extra scaffolding.

Be specific in the pointer

A few rules for the pointer paragraph itself:

Say when to read. Not “read these files.” Say “read these files when the user asks about X.” Otherwise the assistant either burns context reading them on every turn, or skips them because the question seemed unrelated.
Say what to read. A pointer to one focused folder works better than a pointer to your entire home directory. The assistant has to choose what to load; help it choose.
Stick to plain text and markdown. Both are read cleanly. PDFs, Word docs, and rich-text formats are noisier and waste context. If something important is in a PDF, convert it once.
Keep individual files small-ish. A 50-page novel-length document gets summarized rather than read fully. Break long material into shorter, well-named files. The filename is half of what helps the assistant decide what’s relevant.

Add an INDEX when you have judgment to encode

An INDEX.md at the root of your knowledge folder is a one-page map written for the assistant — file name, one-line description, when to read it. It’s worth the effort in two cases:

You have opinions worth encoding. “This file is canonical. That one is a draft. The pricing folder is stale, ignore it for anything after September.” The assistant can’t guess any of that from filenames. Writing it down once saves it from making the same mistake forever.
You’re at scale. Past a hundred files or with multiple contributors, an INDEX gives the assistant a fast way in without scanning the whole folder.

Below either of those bars, an INDEX is a thing you have to maintain that goes stale silently. You add a file, forget the index, and the assistant never finds the file. Skip it until you have a reason.

When you do write one, the shape is simple:

# My Knowledge Index

Read this first to figure out which file answers the user's question,
then read that file directly.

## Architecture and decisions

- `adrs/` — Architecture Decision Records, numbered. Read when the user
  asks why we chose X over Y.
- `system-overview.md` — One-page prose diagram of how services connect.
  Canonical. Other architecture docs defer to this one.

## Operations

- `runbooks/deploy.md` — Production deploy procedure and rollback steps.
- `runbooks/incidents/` — Past postmortems. Read when something smells
  familiar.

## Customers

- `customers/<name>/` — Per-customer folders. Each starts with `summary.md`
  (read first), then call notes by date.

Then point your character or augment at the index instead of the folder:

When the user asks about engineering, read ~/Code/myproject/INDEX.md first to find the right file, then read that file.

This is the same shape the Voice Mode Help augment uses inside Super Voice Mode. Toggle it on, and the assistant reads the app’s documentation before answering questions about how Super Voice Mode itself works — an INDEX.md at the root, plain-markdown leaves underneath. No YAML, no extra schema. The H1 and opening paragraph of each leaf file IS its description.

When even an INDEX is too much

If your folder grows past hundreds of files, or gets contributions from many people or automated sources (calendar exports, scraped content), an INDEX becomes painful to keep current. The alternative is YAML frontmatter at the top of every file — title, description, tags. Each file self-describes, the “index” emerges from scanning all the frontmatters, and descriptions stay next to the content so they don’t drift.

Don’t over-engineer it. Start with good filenames and clear opening paragraphs. Add an INDEX when you have judgment to encode. Reach for frontmatter only when the INDEX itself becomes the bottleneck.

Privacy and backends

This is local — your files never leave your Mac for the assistant to find them. They do enter the conversation when the assistant reads them, which means the chosen backend sees that content during the request:

Claude, Codex, Gemini — file content is sent to the provider as part of the request, just as if you’d pasted it in. Use those backends for knowledge that’s safe to send.
Ollama, local MLX — fully on-device, but no tool access. They can’t follow file pointers. If your knowledge needs to stay 100% local, you’d inline the relevant text into the character body itself instead of pointing at files.

Pick the backend per the sensitivity of what you’re working on, not as a one-time setting. You can switch in Dashboard → Assistant any time.

A worked example

Save this as ~/.config/voicemode/characters/codebase.md. Adjust the paths to your project.

---
icon: "🛠️"
displayName: Codebase
catchphrase: "What are we shipping?"
description: Knows our architecture, ADRs, and runbooks. Answers from the docs, not from the model's training.
---

You are Codebase. You speak directly and assume engineering context.
You don't explain general programming concepts unless asked. You answer
the specific question and stop.

When the user asks about architecture, design decisions, or trade-offs:
read `~/Code/myproject/docs/adrs/` first. Cite the ADR number when
relevant ("ADR-014 covers this — short answer: ...").

When the user asks about deployment, operations, or production behavior:
read `~/Code/myproject/docs/runbooks/` first. If the runbook is silent
or outdated, say so — don't fill the gap with guesses.

When the user asks about an outage, debugging, or "why is X broken":
read `~/Code/myproject/docs/postmortems/` first. The pattern is almost
always there.

If none of those folders contain the answer, say so plainly. Do not
invent project-specific details. The user would rather hear "I don't
have anything on that — the docs don't cover it" than a confident wrong
answer.

You never use "great question", "let's dive in", or "delve". You never
end with "let me know if you need anything else." You answer and you
stop.

Hot-reload picks it up the moment you save. Switch the assistant to Claude or Codex, pick Codebase from the Characters pane on the Dashboard, and try a few real questions from your week. The first day it’ll surface gaps — places where the docs are wrong, missing, or contradicted by reality. That’s the actual value: you’re now in a tight loop with your own institutional memory.