Install

Install

Run it: one command, then the first ten minutes.

You need git and Python 3.11 or newer. The model comes during setup.

curl -fsSL https://raw.githubusercontent.com/ezapmar/brainless-public/main/install.sh | bash

Yes, that is curl piped into bash, on a page with a whole section about trust. The script is short enough to read first, and I would. It sets up Python and the brainless command in ~/brainless (--vault <dir> for another place), then hands over to brainless init, which asks a handful of questions.

1. Your name, and the language it should write in. The folders follow the language, so a Turkish vault keeps its notes in Notlar and its inbox in Gelen.
2. Notes you already have somewhere else, an old Obsidian vault for instance. Those folders are linked in and read, never written to. Obsidian itself is optional.
3. The model. Ollama on your own machine (it asks before installing it), a cloud API with a key, or a command-line tool you are already signed in to. Keys go to the macOS Keychain, or libsecret on Linux, and never into the folder.
4. Whether it may run in the background. One scheduler entry, every 15 minutes. If the laptop slept through the evening, the evening's work runs when it wakes.

Before it finishes, it makes one test call, so you find out now that the key had a typo. Every answer lands in brainless.toml, which you can edit by hand, and brainless doctor tells you what is broken, one line per check. Running it again is safe.

bash install.sh --profile full --schedule installs my three-machine setup instead. The Lite page has the model table, the flags for an unattended install and the limits I know about.

Optional inputs. Documents need nothing more: markitdown is installed with its PDF, DOCX, XLSX and PPTX extras, so a dropped file becomes Markdown with nothing more to install. The other doors need something extra on the machine that runs the capture:

• Voice needs ffmpeg and whisper.cpp with a model file (this vault runs large-v3-turbo). Transcription stays on the machine; only the cleaned text reaches a model. Without them, voice notes are kept as audio and not transcribed.

• Photographs are read by the vision lane of whichever backend you configured (capture-photo in tools/llm.py), so a backend without vision means no OCR. A local OCR option is on the list in Local Inference.

• YouTube and podcasts need yt-dlp for captions, plus the same ffmpeg and whisper.cpp for episodes without them. Share an episode link, not a show link.

• Backups need age. Put the public key in PROFILE.md and keep the private one in your password manager.

None is required to start: text, links, documents and the whole compile loop work without them. How each door is wired is in Capture Flow.

Search by meaning (optional). brainless search ranks by words out of the box. For the questions that share no words with the page (a synonym, the other language, a thing described without its name), add the embedding index once:

cd ~/brainless && .venv/bin/python -m pip install -r requirements-search.txt
.venv/bin/python tools/semantic_index.py build

The model, about 2 GB, downloads once and runs on the CPU; no note leaves the machine. Search turns hybrid by itself when the index exists, the nightly compile keeps it current, and link suggestions and dreaming read it. Without it everything still works on words alone. See Scripts Reference.

Other agents (optional). tools/mcp_server.py serves the compiled wiki read-only to any MCP client: search, one page, the index. It never serves a page git ignores. To give every Claude Code session on the machine your vault:

claude mcp add --scope user brainless-wiki -- ~/brainless/.venv/bin/python ~/brainless/tools/mcp_server.py

To run the script with options instead of piping it:

git clone https://github.com/ezapmar/brainless-public.git ~/brainless
bash ~/brainless/install.sh --vault ~/brainless

The first ten minutes

brainless add "the thing you keep thinking about"   # a note, where the digest reads
brainless add ~/Downloads/some-report.pdf        # a document into the inbox
brainless tick                                   # run what is due now
brainless compile --dry-run                      # what would be compiled
brainless compile                                # build .wiki/
brainless search "the thing you keep thinking about"
brainless dialectic "We should hire before we have the revenue"
brainless calibrate                              # decisions due for grading

That is the start. The whole shell command, from brainless help:

init       set up this vault: language, folders, model, background runs
doctor     check the setup, one line per check (--probe calls the model)
add        capture a note, or copy a document into the inbox
tick       run what is due from the queue (the background entry calls this)
queue      what ran, what waits, what failed; retry
schedule   install or remove the one background entry
concepts   decide concept proposals (review, decide)
config     what brainless.toml sets; keys in the OS keychain (secret set)
profile    lite or full; enable a hidden command
compile    build .wiki/ from your notes (--dry-run, --full-rebuild, --only <phase>)
search     search the compiled wiki
dialectic  six personas argue a thesis; --scorecard prints the rolling 30 day scorecard
lint       wiki integrity checks and repairs (--fix, --fix-links)
calibrate  decisions due for grading, decisions missing a prediction
today      preview, save (--build) or send (--send) the three-item Today queue
closeout   evening close-out: one seed, one decision, one contradiction
digest     nightly digest of Thinking/Daily, archives the raw captures
dashboard  rebuild the projects view from every notes.md
health     refresh and print _Agent-Context/HEALTH.md
file       file a result into .wiki/digests/queries/ so the wiki compounds
media      queue YouTube and podcast links, work the transcript queue
backup     monthly encrypted archive, restore test, status
graph      the link graph as a Gephi file
eval       ask the golden questions and score the search
chats      bring Claude or ChatGPT history in, filtered
export     produce the public engine tree from a private vault
update     git pull and refresh dependencies

On the lite profile, today, closeout, dashboard, health, media, backup, graph, eval,
chats and export are hidden until `brainless profile enable <command>`.
vault      print the vault path
version    print the engine version

The personas are only as good as what they have to argue with, so give them something. Open _Templates/. Copy Belief.md into Thinking/Beliefs/ and write one thing you believe about your work. Copy Decision.md into Thinking/Decisions/ for the last real decision you made, with a prediction and a date. One belief and one decision are enough to start a fight.

Inside Claude Code or Gemini CLI, from the vault root, the thinking tools are slash commands. Fifteen of them, in three groups:

• Deciding: /decide, /dialectic, /contradict, /calibrate
• Thinking: /ideas, /pollinate, /trace, /connect, /weekly, /context
• Tending the vault: /graduate, /backlog, /sync, /lint, /recompile

Their definitions live in .wiki/_commands/, one Markdown prompt each, and the .claude/commands/ and .gemini/commands/ wrappers only point back there, so they work with any agent that can read files. What each one asks, and the thinking error it is built against: Commands.

Next

• Lite · one computer, any model: the details of what init sets up
• Configuration · brainless.toml, keys, choosing a model
• Syncing across devices · git, Google Drive or Obsidian Sync
• Capture Flow · start feeding it notes
• Reference Deployment · run it unattended on a second machine