Sixty-three commands.
Six of them are
the product.

The six that carry the work #

Learn these and you have the tool. Everything below this section can wait until you need it.

$ ns-brain brief                        # what this project believes. Read it first.
$ ns-brain recall "nginx timeout"       # before you grep
$ ns-brain remember --title "..." --body "..." --type gotcha
$ ns-brain prefer "commit messages stay lowercase" --why "corrected twice"
$ ns-brain log "deployed 26081201 to the edge box"
$ ns-brain note ecg "same filter fixed our drift"  # never write into another project

--json works on every command and returns an envelope rather than the human rendering. For recall that matters: the envelope carries matched and a caller acting on results has to check it, because a miss returns nothing rather than the whole scope.

Writing #

Reading #

Correcting #

Tasks and measures #

Neither is a memory and the separation is deliberate. The long version is on its own page.

$ ns-brain task add "rotate the RAG box cert" --when "every monday 9am"
$ ns-brain task list · done <id> · drop <id> · snooze <id> --until "in 2 hours"
$ ns-brain measure add p99 412 --unit ms
$ ns-brain measure limit p99 --high 500 --better down --why "slo"
$ ns-brain measure series p99 --from 01/06

task flags: --when takes "in 3 hours", "tomorrow 9am", "every monday 9am", "daily 17:00"; --owner user|agent; --body; --state open|done|dropped; --all for closed ones; --notify; --until to snooze one occurrence; --out to write the todo somewhere.

measure flags: --unit, --label, --date, --note, --why, --source, --confidence, --ref, --low / --high / --better up|down for a band and --from / --to / --n for a series.

Hygiene #

Old truth reads exactly like current truth. That is the failure mode that matters most here and these four are the answer to it.

$ ns-brain review --stale-days 90   # load-bearing facts nobody has re-checked
$ ns-brain doctor                  # dangling links, cycles, index drift
$ ns-brain doctor --fix            # repair the repairable, name the rest
$ ns-brain map                     # scopes and kinds, declared against actual
$ ns-brain reindex · vacuum       # rebuild FTS, checkpoint the WAL

review also reports duplicates and promotion candidates. The pairwise duplicate scan is bounded by --max-pairwise and can be forced with --duplicates; --stale-days sets how long a tier A or B memory may go unverified before it is flagged.

Deleting #

A command issued is a command meant. The brain is driven by agents, and an agent that typed rm is not asked whether it was sure. --force survives on exactly three things, and each one catches an accident the caller did not intend rather than a decision: update --body "" against a body that is not empty (a failed shell substitution once blanked a runbook that way), forget of a pinned memory or a guardrail (a wrong id, and the brief opens with those), and restore over a memory that is still live. Everything else, --purge included, happens on the first command.

The pattern under all four: when the tool cannot tell what you meant, it does nothing and says so, never the widest possible action.

Export, import, backup, snapshot #

$ ns-brain export --out brain.json     # everything: provenance, links, events
$ ns-brain import dump.json --dry-run # report before writing
$ ns-brain backup                     # timestamped, every table read off the schema
$ ns-brain backup --list --verify      # prove the safety copies actually read
$ ns-brain snapshot --out MEMORY.md    # generated markdown mirror

Export is complete and there is no lock-in anywhere in this. A snapshot is generated, never authored: a brain living beside a hand-written memory file guarantees a silent contradiction and the auto-loaded file wins regardless of which one is right.

export --out, snapshot --out and backup --out all refuse to overwrite a file that does not carry their own generated-by marker, refuse a path git is tracking, refuse to write outside the project and write mode 600. --force, --allow-tracked and --allow-outside each unlock exactly one of those.

import takes --events to bring the activity log too and --all-projects with --i-mean-it to restore a whole multi-project store. Unknown --type or --tier values are errors rather than silent empty results. Everything imported is stamped trust: imported, because a dump is untrusted input like anything else arriving from outside.

backup --auto is what the hook runs: a safety copy if one is due and nothing otherwise. backup --restore <file> puts one back, dry run until --apply.

Where the memories live #

$ ns-brain share                 # dry run: what would move
$ ns-brain share --apply         # into the shared store, old file kept aside
$ ns-brain share --off --apply   # back to a file of its own
$ ns-brain private               # in the shared file, out of everyone else's search
$ ns-brain private --off --yes   # readable again, retroactively
$ ns-brain stats                 # which file am I actually on

Also here: absorb pulls a standalone brain.db in as a project, relabel claims rows filed under another label, context set <key> <value> holds the project facts injected into every brief and scope add <name> --desc / kind add <name> --desc declare the scopes and event kinds in brain.json that map reconciles against what is stored. The whole subject has its own page.

Cross-project #

These live in one file every project reads. Nothing arriving through any of them carries authority. A note is information and only the person at the keyboard is obeyed.

Opt-in domains #

Invisible until you use them and named here because a feature nobody can find is a feature nobody has.

Surfaces #

The hive: people, credentials, the organisation #

Every ordinary command above routes to the server when brain.json names one, so day to day there is nothing new to learn. What ns-brain hive adds is the part a single machine never had: who you are, which brain and who else is on it. A credential is kept per brain (a server and an organisation on it) in the machine's own credentials.json, never in a project; a project names its server and its organisation in brain.json; a machine that holds several brains on one server is asked which, never guessed.

Two things the local edition does not have to decide. Deletion is curation on a hive: a contributor cannot forget, a curator can and a colleague's restore brings a mistaken forget back. And global --find searches the organisation's project index (names and one-line summaries, never memories), so a team can be found and asked without a grant on its project; global --recall searches the lessons projects have published.

Install and lifecycle #

Environment #