A markdown file can only grow. Here are six things it cannot do.
Open a session and your agent already has the brief: today's date and time (no more good morning at 11pm), where git stands, your project's rules and how you like to work. Then every prompt you type pulls in the memories that match it. It keeps what you type too (here is what it stores). Nothing depends on the agent remembering to look.
What arrives and in what order →Ask a question and the memories that answer most of it come first. Old news sinks. The part of the project you are working in counts more than the rest. Importance only breaks a tie: when we let it do more, the right answer dropped by up to twelve places.
The scoring model →"TLS terminates at nginx on 8443" stays true for years. "The box is rebooting" matters for an afternoon. Your agent gives each memory a type when it saves it and the type sets how fast it fades. Two weeks later the reboot is buried. Nothing gets deleted.
Types and tiers →When something changes, your agent saves the new fact as a replacement and the old one stops coming back, even if you ask in the old words. Try to save the same thing twice and the brain stops you, shows what it already has and asks which you meant.
How corrections work →A bug, an incident or a "right now" fact is stamped with the commit it was true at. When it comes back, the brain says whether the code has moved since. Nothing changed: use it. Fourteen commits later: check it first.
Provenance and verification →If it cannot tell what you meant, it stops and says so instead of guessing. A script that searches and finds nothing gets nothing back, not the closest thing. Anything that deletes in bulk shows you the list first and waits for a yes.
What each guard protects →Ask an agent without a brain "why do migrations run before 7am?" and watch it dig. It greps for "migration", reads every markdown file, opens the deploy scripts looking for a comment and scrolls the git log for the commit that changed the time. The real reason (a 40-second table lock somebody measured in March) was never written in the code. After all that reading, it may still guess.
With a brain it is one recall and next to zero tokens. The answer comes back with where it came from and the last line says the code has not changed since, so your agent just answers.
$ ns-brain recall "why do migrations run before 7am" #31 [deploy/gotcha] (score 0.333) Migrations lock the invoices table, so they run before 7am [confirmed] Measured 2026-03-04: migration 0042 held a table lock for 40 seconds on the deploy box. Run migrations before the first billing job at 7am. (bench/migrate-0042.log) tree unchanged since stored (a41f22c9)
Memories are filed in nested areas such as deploy:prod. A search there also sees deploy and anything global, never the other way round.
It never does the biggest thing it could. Before any command ships we check three cases: nothing matches, the filter is empty, you made a typo. In each one it stops and tells you what happened.
On the right, your agent tried to save something the brain already knows. Rather than keep two answers to one question, it asks which one is right.
$ ns-brain remember --type gotcha \ --title "staging deploy needs the vault unsealed" #42 in deploy:staging is already about this (86% title overlap): stored: the staging deploy needs the vault unsealed first yours: staging deploy needs the vault unsealed Storing both would put two answers to one question in the brain. Pick one: the fact CHANGED --supersedes 42 same fact, better words ns-brain update 42 --body ... genuinely separate --allow-duplicate
prune always shows the list first and backs up the whole brain before it deletes anything. It stops at 25 unless you add --yes and leaves facts that never fade alone unless you add --i-mean-it.--apply --i-mean-it. A backup of that project is written before anything goes.--allow-secret. The brain file can only be read by you and never goes into git.Free for one developer. Any number of projects and machines, for as long as you like.
$ curl -fsSL https://brain.fightclub.pro/install.sh | sh $ cd ~/projects/yours && ns-brain init