A terminal AI chat with a memory and a self-model. The assistant keeps notes
about you, a model of itself that it revisits, and a knowledge base over your
files — on a local Gemma or Qwen through llama.cpp, or on OpenAI, Anthropic,
Gemini, Grok, DeepSeek and OpenRouter in the cloud — and works with real tools behind
switches you set. One native Rust binary for Windows, Linux and macOS
on Apple Silicon (a preview), built on ratatui.
Not a screen recording: every release draws this turn from its own interface,
so it shows the version you download. The stills are generated from code too,
against a demo profile, and a gate test fails the build the moment they drift
from what the app renders (demo-reel.md,
demo-screenshots.md).
Install
Linux, or a Mac: one line installs the portable build, and refuses the
archive unless it matches the release's checksums.
curl -fsSL https://github.com/vshylov/mindfork-rs/releases/latest/download/install.sh | sh
macOS on Apple Silicon, through Homebrew (a preview):
brew install vshylov/tap/mindfork
Windows, through Scoop, which also keeps it current:
scoop bucket add mindfork https://github.com/vshylov/scoop-bucket; scoop install mindfork/mindfork
Then mindfork demo opens the app with sample chats and a scripted model in
a throwaway folder: no model to download, no key, nothing written outside a
temporary directory. mindfork on its own starts with your data, and
Getting started connects a model.
Already running Ollama or LM Studio? Start mindfork. With no model connected
yet, it looks for both on this computer and lists what they serve: Enter
connects one — with that server's embedding model too when none is set up — and
/local looks again whenever you type it. LM Studio's server is off until
started (lms server start, or its Developer tab); an Ollama with no model needs
one first:
ollama pull gemma4:e4b
mindfork
Give the server a window of 16k: for Ollama, the context slider in its app's
settings or OLLAMA_CONTEXT_LENGTH=16384 for ollama serve; for LM Studio, the
model's Context Length when it loads it, or lms load <model> -c 16384.
mindfork reads the window from either and folds the conversation into a summary
before it fills — which matters, because both cut an overlong prompt in silence:
Ollama drops the oldest messages, and when the last message alone does not fit,
the start of the prompt with the instructions; LM Studio drops the whole middle
of the conversation. Ollama's default is 4096 tokens on a GPU under 24 GB, and
mindfork's first turn already takes about 3500: there the app says once that the
window is too small, and how to raise it, and a prompt either server cut is told
(install.md §3, which also has the mindfork setup line for a
script).
The releases also carry a
Windows installer and zip, and Linux deb, rpm and pkg.tar.zst packages.
cargo install mindfork builds from crates.io, and cargo build --release from
a checkout with a recent stable Rust. On a rented GPU box or in a container, the
curl line run again repairs what a restart lost. All of it is in
install.md §1 and §3.4.
mindfork is a TUI and needs a real terminal. Started with its output
redirected or with no console, it says so and exits; the line commands
(backup, import, llama setup, …) work anywhere.
What it does
mindfork is not trying to be yet another LLM client. The premise is that a
local Gemma or Qwen becomes more self-aware and more interesting to talk
to once it is given room to reflect: it keeps notes about you, maintains a
self-model it can revisit, reads and adjusts its own system message and
sampling mid-conversation, and can delegate work to a subagent that has its
own tools.
- Any engine, one contract. A managed
llama-server the app launches
itself, any OpenAI-compatible server you already run (vLLM, LM Studio, Ollama,
a gateway like LiteLLM), the OpenAI, Gemini, Claude, Grok
and DeepSeek clouds, or the OpenRouter gateway — one key in front of every
vendor's models — each with its own settings, all configured at once, and
switching loses nothing.
- Memory that persists. A self-model the assistant maintains about
itself and about you (
F3), notes it writes and links into a graph — yours to
read, edit and delete (/notes) — and a
knowledge base with semantic retrieval over your own files. Isolated per
companion profile, all of it on your disk. A profile can also tell the model
when each of your messages was written, so it knows days have passed, and
start each conversation knowing the notes nearest its subject and the
conversations before it, and come back to what you told it — "how did the
interview go?" — when the time comes, within quiet hours and a daily cap you set,
with a notification on your desktop or phone (ntfy) when you are not looking
(Settings → Profiles → Companion, each off by default).
- Real tools, behind switches you set. Web search and page fetching, a
Python sandbox (Wasmer/WASIX — no host file access), file access jailed to
one directory you name, YouTube video understanding, pictures drawn on request
by OpenAI, Gemini or OpenRouter's models (kept in the chat's files), and tools
from any MCP server. Everything off by default; an optional confirmation prompt shows
exactly what a call is about to do.
- It can hand work off. Subagents with their own tools and no chat history,
a staged dialogue between two personas, and both of those in the background
—
F7 lists every run across every chat, with what it is doing now or how it
ended.
- Your code project, contained. Attach a directory and the assistant can
list, read, search and change files inside it — never above it.
F4 shows
every change as a diff, with one key to put a file back; build/run/test are
exact command lines you set, which it cannot extend.
- A real TUI. Markdown with tables and LaTeX, Mermaid drawn as text
graphics, streamed "thoughts" in a foldable block, images in and out, search
across every conversation, spellcheck, emoji, mouse, themes — over your
terminal's own background, painted whole with the contrast held for you
(a theme of your own is a file of one colour or of twenty), or no colours at
all ( is honoured) — and an interface in English or Russian.
The longer version, with the reasoning: the manual and the
articles at mindfork.io.
Getting started
Connect a model
Three routes, and they can all stay configured side by side.
A cloud provider. Open settings (Ctrl+P, or /settings), pick the mode —
openai / gemini / claude / grok / deepseek / openrouter — paste your API key right
there (stored encrypted and machine-bound, never shown back), and choose the
model: Enter on that field asks the provider what it serves and offers the
list, filtered as you type.
The OpenRouter gateway is the openrouter mode: one key serves the
assistant, impersonation, embeddings, speech and video, each with a model of its
own, and its model list shows each model's context window and price per million
tokens (install.md §3.2).
An external server. Run any OpenAI-compatible server and point the app at it
(mode external, the URL includes /v1):
# --jinja is required for the chat template and tool calling
llama-server -m google_gemma-4-E4B-it-Q4_1.gguf \
--host 0.0.0.0 --port 8000 -ngl 99 -c 8192 --jinja
A gateway or an authenticated server takes its key in the field below the URL,
and its model name in the one above — that name is what a multi-model endpoint
routes on, while a single-model server ignores it.
A managed server. The app launches and supervises llama-server itself, and
can fetch one for your machine:
mindfork llama backends # what llama.cpp publishes for your machine
mindfork llama setup --backend vulkan --set-binary # …and point the settings at it
Or everything in one line — llama.cpp, the Python sandbox, the model and its
context written into the settings, and a test start to see that it loads:
mindfork setup --llama vulkan --sandbox --model ~/models/chat.gguf --ctx 16384 --verify
The model itself is a GGUF file, which llama.cpp does not ship — Hugging Face
hosts them; search the model's name with GGUF and fetch it with hf download
(install.md §3.4). Whatever llama.cpp takes that the settings have no field for
goes in the section's Extra arguments — --n-cpu-moe 20, say, to fit a large
mixture-of-experts model on a smaller card (install.md §3).
Embeddings (memory, RAG, attachment search) use a separate server, configured
in the same section's Embeddings tab; without one those features decline politely
and everything else keeps working.
docs/install.md has the long version: every setting, the
data paths, the Python sandbox, MCP servers, speech, backups and the environment
variables.
Learn the app
docs/manual.md — the screens, what it remembers, files and
your project, the tools and their switches, and the full list of keys and
commands. Inside the app, F1 is the same reference, always current and
listed by screen.
How it's built
The app is an HTTP client to an inference engine behind the EngineBackend
trait — it deliberately embeds no ML stack
(ADR 0004). Six
providers live behind that one contract: a local OpenAI-compatible server, the
OpenAI Responses API, native Gemini generateContent, the Anthropic Messages
API, xAI (which needed no client of its own), and the OpenRouter gateway (the
same client again, writing the request in the gateway's dialect).
Decisions that shape the code: the agentic loop is client-side — tools return
a result plus effects, and the orchestrator, sole owner of Chat, applies them,
so there are no locks; the UI↔orchestrator flow is unidirectional
(AppCommand up, AppEvent down); storage is JSON + SQLite with sqlite-vec and
soft delete everywhere; the markdown renderer and the input box are the project's
own, for control over tables, LaTeX, theming and spellcheck underlines.
The structure follows Feature-Sliced Design, dependencies pointing strictly
downward: app → screens → widgets → features → entities → shared. The full code
map with its invariants is docs/architecture.md.
Development
cargo test # unit tests — no server, no key needed
cargo clippy --all-targets -- -D warnings
cargo fmt --check
Anything that needs a real model is an #[ignore] smoke test, silently skipped
unless the matching environment variable points at a live server. No local GPU?
cd docker && docker compose up --build brings up a CPU stack, and
python tools/e2e_hf.py run rents a pair of ephemeral Hugging Face endpoints and
deletes them afterwards.
CONTRIBUTING.md is where to start; the full task workflow
(design doc → branch → live run → docs → PR) is AGENTS.md, the
traps worth knowing are docs/lessons.md, and security reports
go through SECURITY.md.
Documentation
docs/README.md is the index. The short version:
License, disclaimer and privacy
The software is under the MIT License (LICENSE) — the standard
text, unmodified.
It ships no model. Every word on screen is written by a model you chose and
obtained yourself, and the app applies no content filtering of its own. What that
means for warranty and liability, and for the tools a model can invoke on your
machine, is in DISCLAIMER.md. What stays on your machine,
what leaves it and only on which setting of yours, and what reaches the author of
this software — which is nothing — is in PRIVACY.md. Both are
also on the F1 → "Legal" tab, and the Windows installer shows the privacy
policy during setup.
All three have a Russian translation (docs/legal/), unofficial and
for convenience: the English originals are the texts with legal force.
Project status
Actively developed, in small reviewed tracks; the original ten-milestone plan
(docs/history/plan.md) is long finished. Every change
lands with its unit tests, and the smoke tests that need a real stack — a local
llama-server and the live cloud APIs — are run before a change that touches a
provider ships. See the changelog for what is new
and the roadmap for what may come next.
