Brain - the closet where compaction cannot reach

Connecting to the brain server… if this stays, start it with ./brain/brain serve.

Start here

Browse

Visualizer →

Every entry as a card. Filter by project, type or tag. Add and edit without touching a file.

Reference

API →

Every route this server answers, with a link that runs it.

Catalogue

INDEX.md →

The whole brain as one readable page: every project, every entry, every tag with a count.

Conventions

House rules →

The rules that keep it readable, and the mistake each one exists to prevent.

The four commands that matter

./brain/brain search "build command"        # find something
./brain/brain add --scope myproject --type knowledge "Title" "Body"
./brain/brain list --scope myproject         # everything about a project
./brain/brain doctor                         # is this brain healthy?

On Windows use brain\brain.cmd instead. The launcher finds Node by itself, so it works whether or not Node is on your PATH. Every command takes --json if something else is reading the output.

Every command

Command	What it does
`add`	Write an entry. `--title --body --type --tags --scope --source`. `--body @file` reads a long body from a file, which is far easier than escaping quotes in a shell.
`search`	Full text across title, tags and body. Combine with `--tag`, `--type`, `--scope`.
`list`	Everything, newest first. Same filters, plus `--limit N`.
`get`	One entry in full.
`update`	Change any field of an entry. Use this instead of writing a near-duplicate.
`delete`	Remove an entry.
`tags`	Every tag in use, with counts. Check here before inventing one.
`scopes`	The project registry, with entry counts.
`index`	Rebuild `INDEX.md` and `index.json`. `--dry` to see what it would write.
`doctor`	Check the corpus. Exits non-zero when something is actually wrong.
`serve`	Start the HTTP API and this site. `--port` to move it.
`info`	Where this brain lives, its name and its port.

What lives where

Path	What it is
`entries/`	One Markdown file per entry, with a frontmatter block. This is the source of truth. Hand-editable.
`lib/vocab.js`	The project registry. Add a project here and run `index`. This is the only place to register one.
`lib/store.js`	Reads and writes entries. Atomic writes, so two agents never corrupt one.
`lib/index.js`	Builds the catalogue.
`lib/doctor.js`	The health checks.
`lib/config.js`	This brain's own port and name, so several brains can run at once.
`ui/`	This homepage, the visualizer and the export page.
`tools/`	`normalise.js` tidies old entries (dry run by default) and `test-normalise.js` tests its rules.
`templates/`	Entry templates. They are not entries and do not appear in search.
`INDEX.md`, `index.json`	Generated. Read them, never edit them; `brain index` rewrites both.

Types

Four, and the choice matters because it is how a reader decides whether to trust a line.

Type	Means
`knowledge`	A durable fact, established by evidence.
`memory`	What happened: a session outcome, current state, an open thread.
`decision`	A choice, with the reason. The reason is the part nobody can re-derive.
`note`	Everything else.

When an agent should write here

Read the brain before starting work on a project, and write to it after learning something. The test is simple: if a future session would have to rediscover this, it belongs in the closet. If the product needs it at runtime, it belongs on the desk.

The house rules

The short list. Each of these exists because it was broken once, not because it reads well.

Every entry has a frontmatter block. An entry without one is indexed silently, with no title and no tags, which makes it invisible to everything.
A title is a name, not a sentence. Keep it under about 90 characters and put the detail in the body.
Register a project before filing anything under it. Add it to lib/vocab.js and run index, or its entries render with no name or colour.
global means workspace-wide. Project facts go under the project, even the internal ones.
An entry carries its own scope as a tag. So --scope and --tag agree.
Reuse a tag before inventing one. A tag used once is a detail, not navigation.
Plain hyphens, never long dashes. No em or en dashes anywhere. It reads better and it is a house rule.
Templates live in templates/. Anything in entries/ is an entry, and will show up as one.
Update before you duplicate. Two entries that disagree are worse than one that is vague.
Never overwrite another agent's entry. Read, merge, write. Several agents share this folder.
Run doctor before you trust it. It catches what you cannot see by reading: empty titles, unregistered scopes, dangling references.
Generated files are not yours to edit. INDEX.md and index.json are built by brain index; never hand-edit them or the next rebuild silently destroys your changes.
Em dashes and en dashes prohibited. No U+2014, U+2013, or dash-like characters (~, ~~, - used as substitute). Use `node -e "process.stdout.write('—'.charCodeAt(0))"` to check. `normalise` will fix them, but it is easier not to type them.
Keep secrets out, keep their locations in. Where a key lives, yes. The key itself, no. Entries are copied into exports, zips and other people's machines. Never commit secrets or platform tokens.
Record a decision with its reason. A decision entry says what was chosen and why the alternative lost. The reason is the part nobody can re-derive. Six months later someone will ask why, and "because it seemed right" is not an answer.
Total detail wipe resets the brain. `./brain/brain reindex --wipe` clears `entries/`, `index.json`, `INDEX.md`, and all generated reports, leaving only `lib/vocab.js`, `lib/config.js`, and the `entries/` folder structure. No entries, no scope registry, no tags — a clean slate for a fresh brain.

The full rules, with the reason behind each one →

Quick reference

15 rules, the essentials:

Frontmatter block. Every entry needs --- block with id, type, title, scope.
Title as name. Keep under 90 characters; detail in body.
Register project. Add to lib/vocab.js, then run index.
global = workspace. Project facts under project scope, not global.
Scope as tag. Entry's scope must also be in its tags.
Reuse tags. Check existing before inventing new; prevents vocabulary bloat.
Plain hyphens only. No em dashes (—), en dashes (–), or dash substitutes.
Templates in templates/. Never in entries/ or they become phantom entries.
Update before duplicate. Use update rather than creating near-duplicates.
No overwrite. Read, merge, write. Several agents share this folder.
Run doctor. Catches empty titles, unregistered scopes, dangling refs.
No em dashes. Explicitly prohibited; check with char code test.
Total detail wipe. `brain reindex --wipe` resets to zero for fresh start.

Read the full rules with incidents →

HTTP API

For other tools and webviews. CORS is open and it binds to localhost only.

Route	Purpose
`GET /api/index`	Everything in one object: counts, projects, tag frequencies, every entry. Add `?entries=0` for just the shape.
`GET /api/scopes`	The project registry, for building a picker.
`GET /api/entries`	List, filtered by `type`, `tag`, `scope`.
`GET /api/entries/:id`	One entry.
`POST /api/entries`	Create.
`PATCH /api/entries/:id`	Update.
`DELETE /api/entries/:id`	Delete.
`GET /api/search`	Search.
`GET /api/tags`	Every tag with a count.

checking…
Plain text, one file per entry, no database. Everything here is in entries/ and can be read with any tool that opens Markdown.

🧠 The brain

📄 The desk

🧠 The closet