Core concepts
A short tour of the building blocks of Loach. Read this once and the rest of the docs will make a lot more sense.
Local-first
Loach is a desktop app, not a web service. There is no account, no telemetry, no required network access. Your chats and content live in a local SQLite file in your app data folder. The OpenAI-compatible API key and the app-lock credentials are kept in your operating system’s credential manager, not in plain text on disk. See Storage & privacy for the full picture, including what a cloud provider receives.
Providers
A provider is where Loach sends a request when you submit a prompt. Loach supports two kinds:
- Ollama - a local Ollama server running on your machine (or elsewhere on your network).
- OpenAI-compatible - any HTTP endpoint speaking the OpenAI Chat Completions protocol: OpenAI itself, llama.cpp, LM Studio, vLLM, LiteLLM, Groq, OpenRouter and so on.
Both are available side-by-side and you switch between them from the chat header. See Providers for setup details.
Chats
A chat is a single conversation. Chats appear in the sidebar and are persisted locally. Each chat remembers:
- The provider and model used.
- Its parameter overrides (see below) and its own instructions.
- Its messages, with their attachments and tool calls.
- The Library sources attached to it, and how they reach the model.
- Its Space, sidebar folder, colour label, pin and archive state, and working folder.
The persona and tone you pick for a chat last until you quit Loach; after a restart the chat goes back to no persona and your default tone.
Keep the sidebar tidy with folders and colour labels, pin a chat to the top, and move chats you no longer want to see to the archive - they’re not deleted, just hidden until you bring them back. Inside a chat, pin a reply to jump back to it later, or fork the conversation to branch a tangent without disturbing the original.
Spaces
A Space groups chats that share context - instructions, reference sources and memory. Use a Space when several chats orbit the same topic: a codebase, a research question, an ongoing piece of writing.
A Space’s default model is the starting point of every new chat created inside it, and each chat can still switch it. Its reference sources - files uploaded to the Space, or items linked from your Library - and its memory go with every chat in it. Its instructions, when set, replace both your global Custom instructions and the chat’s own. The Space’s Settings tab holds its default model, memory auto-save, how its sources reach the model and how images are scaled. See Spaces.
Library
The Library keeps the reference material you want models to use, saved once: texts you write or paste, files (PDF, Word, text and code, images) and links to web pages, which Loach fetches once and keeps as a snapshot. Group items into datasets to attach a whole set in one go. Open it from the sidebar.
Attach items to a chat with + → From Library or by typing # in the message box, or add them to a Space’s sources so every chat in it can use them. Chats and Spaces link to an item rather than copying it, so an edit in the Library reaches every chat using it. Sources that fit go to the model in full text; bigger ones are searched, and only the excerpts most relevant to each message are sent - by keyword out of the box, and by meaning too once you set an embedding model in Settings → Library. Each reply shows which sources it used. See Library.
Memory
Loach can remember lasting facts about you. While memory is on, after each reply it asks the same model, in a second, hidden request, to save new facts and to update or drop ones that no longer hold; every change shows a toast with Undo. There are two lists:
- Space memory - one per Space, on by default for a new Space, and sent with every chat in that Space.
- Global memories - learned in chats outside any Space and sent with every chat, Spaces included. Off by default; turn it on in Settings → Features → Global memories.
You can review, edit and search both lists, or add and remove facts with /remember and /forget. Private Chat never reads or writes memory. See Memory.
Snippets
A Snippet is a saved, reusable prompt. Optionally pin a model to it, then click Run to open a fresh chat pre-filled with the prompt and ready to send. {{PLACEHOLDER}} variables fill in from saved values, and anything left blank is asked for when you run it. Snippets are great for:
- Frequently used templates (“summarize this transcript”, “review this diff”).
- Multi-paragraph prompts you don’t want to re-type.
- Bookmarking a prompt + model pair that gives consistently good results.
Per-chat parameters
Every chat has a parameters panel where you can override sampling and runtime settings without touching the model itself. Its Simple view holds the everyday controls; Advanced adds the sampling and repetition knobs. The most useful ones:
| Parameter | What it does |
|---|---|
| Temperature | Randomness. Lower = more deterministic. |
| Top-K / Top-P / Min-P | Truncate the token distribution at sampling time. |
| Max Tokens | Cap on the length of a single reply. |
| Context Length | The model’s context window - how much of the conversation it can see at once. Sent to Ollama only; an OpenAI-compatible server decides for itself, but Loach still sizes the context bar and Library sources by it (32k when unset). |
| Thinking | Turns a reasoning model’s thinking step on or off (Ollama). |
| Additional instructions | The chat’s own instructions. They take the place of your global Custom instructions for this chat rather than adding to them. |
| Images | How images are scaled down before they’re sent - by default to 1024 px on the longest side. The stored original is untouched. |
Values are layered: a chat’s own setting wins over the model’s Modelfile defaults, which win over Loach’s built-in defaults. Low VRAM mode in Settings → Features, when on, turns Low VRAM on for every Ollama chat, whatever the chat sets.
Personas and tones
A persona is a role the model takes on - Code Reviewer, Writing Editor, Translator, Explain Like I’m 5, and so on. A tone is the delivery style - Direct, Detailed, Casual, Formal, Playful, Skeptical, Socratic, and more. Both wrap around your instructions: the persona goes before them, the tone after. A persona is picked per chat; a tone can be picked per chat or set as the default in Settings → General. See Personas and tones for details.
Custom instructions
Free-text instructions that go into the system prompt. You can set them at three levels, but only one applies to a given chat - the first of these that is set:
- Space - the Space’s instructions, for every chat in that Space.
- Chat - the chat’s own Additional instructions, in the parameters panel or with
/instructions. - Global - Custom instructions in Settings → General, for every chat that has neither.
All three accept template variables such as {{USER_NAME}} and {{CURRENT_DATE}}. See Custom instructions.
Context
The “context” is what Loach sends to the model on each turn: the system prompt, the message history and any sources the chat uses. A context usage bar just below the message box shows how full the model’s window is. You can:
- Attach Library sources, which reach the model in full or as the excerpts most relevant to each message (see source modes).
- Compact it - summarise older turns into the system prompt to free space, without losing your scrollback.
- Export it as Markdown to copy elsewhere, and import exported context - or any text - into another chat to seed it.
- Paste URLs whose pages get fetched and inlined (see Web fetch).
- Have the current date, weekday and timezone added automatically (see Temporal awareness).
- Give the chat a working folder whose
LOACHFILE.mdproject instructions are added to every turn (see Work in folders).
Slash commands
Type / at the start of the composer to open a command palette: /fork, /regenerate, /compact, /model, /persona, /snippet, /remember and more. Tab completes, Enter runs, and destructive commands ask first. /help lists them all. See Slash commands.
Tools and MCP
Models that support tool calls can use tools mid-answer; each call shows up in the reply. Tools come from three places:
- Built-in tools - calculator, date/time, hashing, JSON, unit conversion, text diff, PDF generation and more. They run locally with no network access, and each is off until you switch it on in Settings → Tools or accept the setup wizard’s recommended set.
- Work in folders - add a folder to a chat from the + menu next to the message box (Add directory) and the model can list, find, read, search and edit the files in it. It stays sandboxed to that folder and has no shell, and before anything is written, edited, moved or deleted, Loach shows you the change and asks, unless you’ve allowed that tool for the chat.
- MCP servers - Loach speaks the Model Context Protocol, over HTTP or by running a local program (
npx,uvx,nodeor a full path) that you approve in a native dialog first. Register a server in Settings → MCP, test it and inspect its tools, and the model can use them. Each MCP tool call pauses for your answer - Allow once, Always allow or Deny - unless you switch that off for a server you trust.
Separately, Web fetch downloads the URLs you paste into a prompt and adds their text to it.
Private Chat
Private Chat is an off-the-record overlay for conversations that should leave no trace. Open it from the ghost icon in the title bar or with /private. Nothing is saved: the transcript lives in memory and is wiped when you close the overlay with the × in its header, or when Loach locks. It talks to Ollama only, and gets no tools at all - built-in or MCP - no working folder, no Library sources, no memory and none of your Custom instructions. See Private Chat.