# ns-brain > Persistent, scoped, decay-tiered memory for coding agents. One static Go binary over > SQLite. No daemon, no runtime and nothing sent on its own beyond a > once-a-day version check (NS_BRAIN_NO_UPDATE_CHECK=1 turns it off); `ns-brain feedback` > sends only when someone runs it. 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 -s -- --user # ~/.local/bin, no sudo cd ns-brain init --agent # brain + hooks, idempotent ns-brain bootstrap # only if the project has history ``` Use `--user`. Without it the installer targets /usr/local/bin and needs sudo, which you cannot answer; with no terminal it refuses and names `--user`. `--dir ` installs anywhere else. Check that ~/.local/bin is on PATH. `init` writes `brain/brain.json`, `brain/brain.db` (mode 600), `brain/HOWTO.md`, `brain/BEST-PRACTICES.md`, `brain/autoexec.sh`, `.gitignore` entries for the store and its dumps and the hooks for the agent you name (or for each agent it detects). At a terminal it asks which agent to wire (Claude Code, Codex CLI, Cursor, Gemini CLI, OpenCode, Copilot CLI, Devin CLI, Qwen Code, Hermes Agent, Continue CLI, Kilo or "I will do it myself", which wires nothing and prints each agent's block). With no terminal, which is your case, it wires the agent named by `--agent ` (claude, codex, cursor, gemini, opencode, copilot, devin, qwen, hermes, continue, kilo), or detects agents from their config directory in the project or home: `.claude/ .codex/ .cursor/ .gemini/ .opencode/ .copilot/ .devin/ .qwen/ .hermes/ .continue/ .kilo/`. Pass `--agent` for the agent you are. It does not edit CLAUDE.md. It is idempotent: run it again to migrate an older install in place. It never overwrites `brain.db`. Tell the user one thing it wires: the per-message hook stores each prompt verbatim (clipped at 8000 characters, credential-shaped text refused), kept 30 days (`utterance_days` in brain.json). `ns-brain utterances` lists them; `init --no-auto-recall` is the only off switch. 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 ""`: ranked retrieval. Before you grep. - `ns-brain remember --title "..." --body "..." --type `: store a durable fact. - `ns-brain prefer "" --why ""`: how the user wants to be worked with. - `ns-brain log ""`: 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 --help`. ## Docs - [Install and first hour](https://brain.fightclub.pro/install.md): the full procedure, the checks, the failure modes. - [How it works](https://brain.fightclub.pro/how-it-works.html): the six mechanisms (context before the first turn, bounded ranking, decay by type, supersession, provenance, failing closed), what a recall returns and what each guard refuses. - [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): the CLI's commands as tools, over stdio or HTTP (a bearer token on every HTTP request, TLS off loopback). Read this before wiring a client: a shared store REFUSES a call that does not name its project (BRAIN_PROJECT, an X-Brain-Project header or _project). - [Coding agents](https://brain.fightclub.pro/agents.html): per agent (Claude Code, Cursor, Gemini CLI, OpenCode, Kilo, Cline CLI, Copilot CLI, Qwen Code, Hermes Agent, Continue CLI, Aider, Goose, Codex CLI, Devin CLI), the hook and MCP files to write and which channels that agent cannot carry. Claude Code carries every channel: `init --agent claude` writes SessionStart, UserPromptSubmit, PostToolUse, Stop and SessionEnd hooks into .claude/settings.json, named through $CLAUDE_PROJECT_DIR, plus slash commands in .claude/commands/. Cursor's per-prompt hook cannot add context: give it `.cursor/mcp.json` as well as `init --agent cursor`. Gemini CLI carries every channel through `init --agent gemini`; OpenCode and Kilo through the plugin `init --agent opencode` / `--agent kilo` writes. Cline CLI discards hook output: MCP only and its MCP server must be given BRAIN_HOME (or BRAIN_PROJECT) or it refuses. Copilot CLI runs .claude/settings.json: `init --agent copilot` writes that file; headless runs need GITHUB_COPILOT_PROMPT_MODE_REPO_HOOKS=true. Qwen Code reads .qwen/settings.json: `init --agent qwen`. Hermes hooks are user-level in ~/.hermes/config.yaml: `init --agent hermes` prints the hooks block to paste; the MCP entry is added by hand. Continue CLI never fires hooks: MCP in ~/.continue/config.yaml, printed by `init --agent continue`. Aider has no hooks or MCP: a shell wrapper passes the brief with --read. Goose: a shell wrapper adds --system with the brief and --with-extension for MCP. Codex: `init --agent codex`; headless codex exec needs --dangerously-bypass-hook-trust. Devin CLI reads .claude/settings.json: `init --agent devin`. - [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. - [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.