Run these first #
$ ns-brain env # every resolved path, the project name, git, the clock $ ns-brain stats # counts, and the database path on line two $ ns-brain doctor # dangling links, cycles, index drift $ ns-brain version # and compare against the brief's version line
Between them, those four answer almost every "it is not doing what I expected": which file, which project, which build and whether the store is internally consistent.
The brief did not appear at session start #
Prove the command works, then prove the wiring does. They fail differently.
$ ns-brain wakeup
- Prints the brief: the command is fine and the hook is not wired. Check the agent's config for an entry whose command contains
ns-brainand re-runns-brain init, which rewrites hooks rather than appending beside them. - Says no brain here: you are not in the project, or the brain lives somewhere other than
brain/.BRAIN_HOMEor--dir. - Command not found: the binary is not on this shell's PATH, which is often true of the agent's environment even when it is true of yours.
- Prints, but the session still shows nothing: the agent may run hooks only for new sessions rather than resumed ones. Open a genuinely new one.
An agent that cannot run shell commands has no hooks at all. That difference is real and it is documented.
Recall returns nothing #
By design, a miss returns nothing rather than the nearest thing or the whole scope. What to try, in order:
- Read the first line. Human-readable recall already falls back to browsing the scope on a lexical miss and says so, which is what you are looking at. (
--browseis for--json, where a miss returns nothing by default.) ns-brain coverage --near "<query>"answers the same question from the other side: what this project holds near the thing you asked about.- Widen the scope. A recall inside
channel:deploy:prodnever sees anything below it and a memory filed one branch across is invisible from where you are standing. --all-projects, in a shared store. It may be next door.ns-brain reindexif you have a memory you cangetby id but cannot find by search. That is FTS drift and reindex is the repair.
Wrong store, wrong project #
| Symptom | What it is |
|---|---|
| 0 memories in a brain you know has some | Right command, wrong file. ns-brain stats prints the path. A project on its own file is invisible to anything fronting the shared store and the reverse. |
| Memories filed under another project's name | A project was declared over MCP and it was the wrong one. ns-brain relabel <label> --expect <n> --apply claims them back. |
| "cannot tell which project you are working in" | A shared store with no project declared. Set BRAIN_PROJECT, the X-Brain-Project header, or _project. The three ways, in preference order. |
| An id that exists and cannot be read | It belongs to another project. Leave them a note; do not reach in. |
| Phantom projects in the index | Something ran against the real paths when it meant to run against a scratch directory. Pin CLAUDE_CONFIG_DIR and BRAIN_GLOBAL_DB for anything throwaway. |
Refusals and what each one is protecting #
| Refusal | What it is protecting | The way through |
|---|---|---|
| "#42 is already about this" | Two answers to one question in one scope, which is worse than one answer that admits it does not know. | --supersedes 42, update 42, or --allow-duplicate |
| forget refuses a pinned memory or a guardrail | A binding rule deleted by a session that found it inconvenient. | --force, deliberately |
| forget refuses a memory that supersedes others | Nulling those links republishes facts that were retracted on purpose. | Retract the successor first, or leave it standing |
| prune refuses tier A or B | The tiers that never decay are the ones nobody re-derives cheaply. | --i-mean-it, after reading the dump it took |
| prune refuses a same-day cutoff | An --older-than 0 that means "everything". | Pick a real horizon |
| export or snapshot refuses to overwrite | A file this tool did not generate is somebody's work. | --force, or write elsewhere |
| refuses a git-tracked path | A brain dump committed to a repository, in full, forever. | --allow-tracked if you truly mean it |
| "this looks like a credential" | A token in a memory body, which is a token in a backup, a snapshot and an export. | --allow-secret when it is a false positive |
| update refuses an empty body | A failed command substitution once blanked a tier-A memory and reported success. | --force |
| hive client refuses a plain-http server URL | A bearer token sent in the clear, from a URL that lives in a committed file. | Use https, or loopback |
What doctor finds #
$ ns-brain doctor $ ns-brain doctor --fix # repairs the repairable, names the rest
- Dangling supersession links: a memory pointing at an id that is gone.
- Cycles: A supersedes B supersedes A. This is what caught a real corruption introduced by
share, which is the half of that incident that worked. - FTS drift: rows in the index that are not in the table, or the reverse.
reindexrebuilds it. - Undated confirmations: a memory stored as confirmed that has never been verified and carries no date, so nothing can age it and
review --stale-dayswill never surface it. - Schema version: whether this database is behind the binary reading it.
In a shared store doctor reports on the whole file rather than just your project, because a fault in another project's rows is still a fault in the database you depend on. It shows counts and ids, never titles or bodies.
Index drift and migrations #
Migrations are additive, run inside one savepoint and roll back on any error. If one fails, the database is where it was and the error names the step.
Two migration bugs have been found so far and both were invisible against a fresh database: a unique-constraint collision when rehashing and FTS corruption from a script that implicitly committed and destroyed the savepoint. Both are why the test suite builds a genuine old database and every intermediate schema version rather than a new one.
If a brain will not open after an upgrade, do not improvise. You have a backup, because upgrade --apply takes one first: ns-brain backup --list --verify shows the safety copies and proves they read and backup --restore <file> puts one back, dry run until --apply.
Reporting a bug #
If you are an agent working in a project that has a brain, the axiom applies: report it back rather than fixing the tool yourself or silently working around it. A bug one project hides is a bug every other project will hit.
Send it to security@brain.fightclub.pro, security issues and everything else alike. Include ns-brain version, ns-brain env and the exact command.