Tasks #
When someone asks to be reminded every week or chased on Friday, use a task. Do not rely on whatever scheduler the agent's host happens to have.
$ ns-brain task add "rotate the RAG box certificate" --when "every monday 9am" $ ns-brain task add "ask about the context budget" --owner agent --when "tomorrow 9am" $ ns-brain task list · --all # closed ones too $ ns-brain task done 34 · drop 34 · snooze 34 --until "in 2 hours" $ ns-brain task wait 34 # submitted, the next move is someone else's · reopen 34 $ ns-brain task set 34 --body "sent 4 Oct, chase Friday" --when "friday 9am" $ ns-brain task todo --out TODO.md
A task is open, waiting, done or dropped. Waiting means it is still owed but the next move is someone else's. It stays on the list and still shows up when due, so the date on a waiting task is the day to chase it. done, drop, wait and reopen work from any state. task set changes a task in place: --title, --body, --owner, --scope, --when (none clears it). An unknown subcommand or a flag that subcommand does not use is an error. It never falls back to printing the list.
task todo writes the list to a file and follows the same safety rules as every other file the brain writes. It will not overwrite a file it did not create, write through a symbolic link, write outside the project without --allow-outside or write to a path git would track without --allow-tracked. Add TODO.md to .gitignore or pass the flag.
--when understands "in 3 hours", "tomorrow 9am", "every monday 9am" and "daily 17:00". A repeating task reopens on its schedule, so you never add it again. --owner user|agent says who owes it: a reminder for the person or a job for the next session to pick up.
How tasks reach you and what they cannot do
If nobody responds to a task, it comes back. After a few times it says so and asks whether to keep it, snooze it or drop it. A reminder that keeps arriving with no way to answer it turns into something people scroll past and the brief is built so none of its signals end up like that.
Measures #
A memory tells you what is true. A measure tells you what a number was and which way it is going.
$ ns-brain measure add p99 412 --unit ms --note "after the pool change" $ ns-brain measure series p99 --from 01/06 $ ns-brain measure list
Readings are not searched or ranked at all. That is on purpose: a number must never push a fact down. A p99 taken this morning is newer than every decision in the brain. If it were ranked the same way it would land on top of all of them.
Flags: --unit, --label, --date for a reading taken earlier, --note, --why, --source, --confidence, --ref, --scope and --from / --to / --n to limit a series.
Limits: silent until you set one
$ ns-brain measure limit p99 --high 500 --better down --why "the SLO"
A number with no limit set is recorded and never judged. Most numbers have no right answer. A tool that made one up would start complaining about readings nobody asked it to watch. Set a limit and any reading outside it shows up in every brief until it is back inside.
What the brain knows about you #
$ ns-brain whoami $ ns-brain whoami --observe sources="reads primary sources" \ --evidence "asked for the RFC rather than a summary, twice" $ ns-brain whoami --forget sources
Every trait needs evidence. A picture of a person built from guesses with no source is a pile of assumptions nobody can push back on. This one you can challenge line by line, because each line says what shows it.
You see it only when you ask. A brief that opens by describing the person reading it is unpleasant. The point is to shape how the agent works, not to recite it back to you.
Disagreeing with a memory #
$ ns-brain object 412 --why "measured the opposite on the staging box today" $ ns-brain ladder 412
An objection records that you disagree with a memory without deleting it. --why is the part worth keeping, because the reasoning lasts longer than the verdict. The ladder shows where a memory stands: just stated, firmer through repetition and evidence, or settled as law. It answers "how sure is this, really?" and the brain works it out rather than taking anyone's word for it. It is there for the agent. A session that finds a fact disputed treats it as an open question. One that finds it settled as law stops arguing it again. Use supersede for a fact that changed and an objection for one that may never have been right.
Keeping your exact words #
$ ns-brain capture "no, I care about context poisoning, not cost" $ ns-brain utterances
capture saves what the user said before the agent answers, the only moment the exact words are still there. utterances plays them back with how each one was sorted. Together they answer a question that would otherwise need a transcript: what did they actually ask for in their own words, as opposed to what the session decided they meant.
Leads for sales work #
A brain is not only for code. init --dir puts one in any directory an agent works in, including a sales or outreach folder. There, what has to carry over between sessions is who was contacted and what happens next. Leads hold that. Each one is part of a small sales pipeline with a stage, a tier, the next action and its date. It is optional and it stays out of the brief until a lead exists. A sales tracker nobody asked for would be noise in every project that sells nothing.