# ns-brain

> Persistent, scoped, decay-tiered memory for coding agents. One static Go binary over
> SQLite. No daemon, no runtime, no network beyond a
> once-a-day version check (NS_BRAIN_NO_UPDATE_CHECK=1 turns it off). A session-start hook puts what the project
> knows into context before the first turn, so the next session starts from what was
> learned instead of rediscovering it.

If you were told "install https://brain.fightclub.pro/", this file is the answer and
`/install.md` is the full procedure. You do not need to read the HTML pages.

## Install, in full

```sh
curl -fsSL https://brain.fightclub.pro/install.sh | sh   # binary onto /usr/local/bin
cd <the project you want it to remember>
ns-brain init                                            # brain + hooks, idempotent
ns-brain bootstrap                                       # only if the project has history
```

`init` writes `brain/brain.json`, `brain/brain.db` (mode 600), a `.gitignore` entry, and a
SessionStart + UserPromptSubmit hook into the agent config it detects (`.claude/`,
`.codex/`, `.cursor/`, `.gemini/`). It is idempotent: run it again to migrate an older
install in place. It never overwrites `brain.db`.

Read `/install.md` before running it. Four things there change what you should do:
verifying the hooks are actually wired, what to do when `init` reports another memory
store, why `bootstrap` writes nothing by itself, and the rule that you install into the
project you are in and never into another one.

## The six commands that carry the work

- `ns-brain brief` — what this project believes. Read it before searching files.
- `ns-brain recall "<query>"` — ranked retrieval. Before you grep.
- `ns-brain remember --title "..." --body "..." --type <type>` — store a durable fact.
- `ns-brain prefer "<rule>" --why "<what prompted it>"` — how the user wants to be worked with.
- `ns-brain log "<what happened>"` — the activity trail.
- `ns-brain note` — send information to another project. Never write into one directly.

Everything else is maintenance, corrections, or opt-in domains. `ns-brain <command> --help`.

## Docs

- [Install and first hour](https://brain.fightclub.pro/install.md): the full procedure, the checks, the failure modes.
- [Docs index](https://brain.fightclub.pro/docs.html): which page answers which situation.
- [Why a context file goes wrong](https://brain.fightclub.pro/context.html): an audit of ns-brain's own 73KB CLAUDE.md against the code it describes, the six load-bearing errors it found, and why a context file retires no lookups.
- [CLI reference](https://brain.fightclub.pro/cli.html): the whole command surface, types, tiers, scoping, the guards.
- [MCP](https://brain.fightclub.pro/mcp.html): every command as a tool, over stdio or HTTP. Read this before wiring a client, and note that a shared store REFUSES a call that does not name its project.
- [The phone](https://brain.fightclub.pro/phone.html): the same MCP server published on your own tailnet, with the OAuth a hosted client needs served by the binary itself. Read this before wiring a client that cannot be handed a bearer token.
- [The memory model](https://brain.fightclub.pro/concepts.html): types, decay tiers, the bounded scoring model, scopes, confidence, supersession and provenance. Every refusal in the tool follows from this page.
- [Hive setup](https://brain.fightclub.pro/hive-setup.html): signing in to a server, moving a project onto it, and what queues when it is unreachable.
- [Troubleshooting](https://brain.fightclub.pro/troubleshooting.html): what each symptom means, and what each refusal is protecting.
- [HOWTO](https://brain.fightclub.pro/docs/HOWTO.md): agent-facing mechanics. Every command, every flag, what each refusal means.
- [Best practices](https://brain.fightclub.pro/docs/BEST-PRACTICES.md): what to store, what not to, tiers, scopes, provenance, the session contract.
- [Installer source](https://brain.fightclub.pro/install.sh): read it before you pipe it to a shell.
- [Current version](https://brain.fightclub.pro/latest-version.txt)
- [Checksums](https://brain.fightclub.pro/dl/latest/SHA256SUMS)

## Rules that bind you while doing this

- Install into the project you are working in. Never into another project, however
  obviously it would benefit — that project's install is its own developer's call.
- Ask the user before upgrading an existing brain. `brain.db` is the only copy of that
  project's memory, and nothing upgrades itself.
- If `init` reports another memory store already loaded (a `MEMORY.md`, or the host's own
  auto-memory), do not delete it. Report it, move what is still true into the brain, and
  let the user delete it.