Tuning What fai Remembers
fai keeps your work as searchable context. Two settings shape how well it does that: the embedding model it uses to understand your files, and how often it captures the files you're actively editing. Good defaults ship out of the box — this page is for when you want to tune them.
Choose an embeddings provider
Recall is how fai finds relevant context by meaning rather than by file name. It works by turning your captures into an index with an embeddings provider, and it only works if that provider does. Without one, recall comes back empty. Your captures still save, they just aren't searchable.
You choose the provider when you run fai synthesize (or pick Manage
Synthesis from the session menu). Right after you pick a synthesis provider,
fai asks for an embeddings provider:
| Option | What it is |
|---|---|
A detected model, e.g. ollama - nomic-embed-text (768-dim) | An embedding model fai found on your installed providers. The best choice when one is listed. |
Local ONNX (offline, last resort) | A small model that runs on your machine with no provider at all. |
Custom OpenAI-compatible endpoint | Any /v1/embeddings endpoint. fai checks it returns a vector before saving it. If it doesn't, you can try again or skip to Local ONNX. |
Local ONNX needs nothing installed. It downloads about 22 MB to
~/.fai/models/ the first time it's used, then runs offline. It's also what
fai uses until you choose something else. The trade-off is quality: it's a
small model with a short context window, so recall is less precise than with a
dedicated embedding model like nomic-embed-text. See the next section.
"No embedding-capable model found on your providers." fai looked at the
providers it detected and none of them offer an embedding model. This is
common when synthesis runs on a chat-only or custom endpoint. Pull one (for
example ollama pull nomic-embed-text) and run fai synthesize again, or
choose Local ONNX or a custom embeddings endpoint from the same menu.
If your provider goes down, fai pauses embedding, warns you, and retries every few minutes. Recall stays empty until the provider is back or you choose a different one.
Pick a longer-context embedding model
fai turns your captured content into a searchable index using an embedding model. The model's context window decides how big a slice of a file fai can understand at once. A small-window model has to chop a long file into thousands of tiny fragments — which fills up storage fast and makes recall noisier. A longer-window model keeps each slice large and coherent.
If you're on all-minilm, switch to nomic-embed-text (via Ollama). It has
a much larger context window and better recall quality. Pick it when you run
fai synthesize. Changing models triggers a one-time re-index of your existing
context, so the first session afterward spends a little time catching up.
Advanced: some models report a smaller context than they actually support, and
some hosted models report none at all. You can set the real value yourself in a
small model-info.json override so fai uses larger, cleaner slices.
Keep capture focused on what's settled
fai watches your rules, plans, and memory files and captures them as they change, so your assistant always knows what you're working on. But a file you're actively editing — a plan you're writing right now — shouldn't be captured on every single save. fai debounces the fast-changing files: it waits until a file has been idle for a couple of minutes before capturing it, so it keeps the version that matters instead of every keystroke. If you keep editing for a long stretch, it still captures periodically so nothing is lost.
Slow-changing files (your rules and skills) are captured immediately, as always. The result: your real work gets remembered, and a busy planning session doesn't crowd it out.