# llmbrain

> Persistent, cross-project memory for AI coding agents, served over remote
> MCP. Agents read the brain before starting work and update it before
> stopping — so the next session, on any machine, in any repo, by any agent,
> starts warm instead of blind.

This file is written for AI agents. Humans: see https://llmbrain.dev

## What llmbrain is

Coding agents (Claude Code, Codex CLI) start every session with no memory of
the last one. llmbrain is one hosted place that holds durable context about
all of a user's projects: what each project is, its architecture, data model,
product intent, current status, plus issues and milestones. The repo holds
code; the brain holds everything an agent would otherwise have to be told
twice.

It replaces the `/docs` folder that rots unread in each repo: docs live in
the brain instead — versioned, freshness-tracked, and readable by every agent
in every repo. Orientation at session start costs roughly 400 tokens.
Nothing is ever deleted.

## Features

- **Canonical docs per project** — `status`, `architecture`, `data_model`,
  `product`, plus any custom kebab-case doc. Each carries freshness tracking,
  so agents (and the dashboard) can see what has gone stale.
- **Issues and milestones** — work is tracked as issues grouped under
  milestones (the roadmap). Issues carry real specs, labels, and
  in_progress/done timestamps that tell the next session where work stopped.
- **Cross-project** — one brain spans all of a user's projects. A session in
  `shop-frontend` can read what a session in `shop-api` recorded.
- **Cross-agent** — the same memory is shared by Claude Code, Codex, and
  anything else that speaks MCP.
- **Session hooks** — the CLI installs a SessionStart hook that briefs the
  agent on the current repo's project (status, docs health, open work) and a
  Stop hook that reminds it to record substantial work before ending.
- **Sharing** — projects can be shared with teammates with read or write
  roles, addressed as `owner-handle:slug`.
- **Read-only keys** — a key can be scoped to read; a leaked read key can
  never write, and key management always requires a dashboard session.
- **Dashboard** — humans browse the same brain at https://app.llmbrain.dev

## Connect over MCP

- **Endpoint:** `https://server.llmbrain.dev/mcp` (streamable HTTP)
- **Auth:** `Authorization: Bearer <api-key>` — keys look like `llmb_…`

An account and API key are required. Beta invites:
https://llmbrain.dev/request-access

## Install the CLI

If you are an agent installing llmbrain on the user's machine, follow these
steps:

1. **Prerequisite:** Node.js 20+ with `npm` on PATH.
2. **Get an API key.** Keys look like `llmb_…`. If the user hasn't given you
   one, ask for it — they create keys in the dashboard at
   https://app.llmbrain.dev (no account yet → https://llmbrain.dev/request-access).
3. **Run the install script non-interactively.** Without a key in the
   environment, `llmbrain setup` prompts on `/dev/tty` — which hangs or fails
   in an agent's shell — so always pass the key inline (the env var goes
   before `bash`, not `curl`):

   ```sh
   curl -sSL https://server.llmbrain.dev/install.sh | LLMBRAIN_KEY=llmb_xxx bash
   ```

   Interactive equivalent, for a human at a terminal:

   ```sh
   curl -sSL https://server.llmbrain.dev/install.sh | bash
   ```

   Or skip the script and install the package directly:

   ```sh
   npm install -g llmbrain-cli
   LLMBRAIN_KEY=llmb_xxx llmbrain setup
   ```

4. **Verify** with `llmbrain doctor` — it checks the key, hooks, skill, and
   MCP registrations.
5. **Start a fresh agent session.** Hooks, the skill, and the MCP
   registration are picked up at session start, not mid-session.

Setup is idempotent — re-running updates everything in place and reuses the
key saved in `~/.llmbrain/config.json` (written 0600), so re-runs never
prompt. For every
detected agent (Claude Code, Codex CLI) it installs:

1. the **MCP registration** pointing at the llmbrain server,
2. the **llmbrain skill** (conventions for what to store and when), fetched
   from the server so it never drifts,
3. the **SessionStart and Stop hooks** described above.

### CLI commands

| Command | Purpose |
|---|---|
| `llmbrain setup` | Install everything: MCP registration, skill, and hooks for every agent |
| `llmbrain update` | Re-run setup with the saved key: refresh skill, hooks, MCP registration |
| `llmbrain login` | Verify an API key and save it to `~/.llmbrain/config.json` |
| `llmbrain logout` | Remove the saved credentials |
| `llmbrain search "…"` | Search docs and issues across every project, ranked, from a terminal |
| `llmbrain skills list \| push \| pull` | Your skills in the brain, and installing them on this machine |
| `llmbrain skills browse` | The public gallery — published skills any account can pull |
| `llmbrain skills publish \| withdraw` | Submit one of your skills for review, or take it back out |
| `llmbrain doctor` | Check the installation: key, hooks, skill, MCP registrations |
| `llmbrain uninstall` | Remove hooks, skills, and MCP registrations from every agent |

## MCP tools

| Tool | Purpose |
|---|---|
| `start_session` | The whole session bootstrap in one call — card, status, open issues, roadmap |
| `list_projects` | All projects you can reach, with the exact ref and your role for each |
| `get_project` | Project card, docs health, and what setup is still missing |
| `create_project` / `update_project` | Create a project; set description, repo URL, status |
| `get_doc` / `save_doc` / `list_docs` | Read and write docs; `save_doc` replaces the whole body |
| `search` | Find docs and issues across every project — ranked hits with snippets |
| `list_issues` / `get_issue` | Open work and full issue specs |
| `create_issue` / `update_issue` | File work worth doing later; move status as you work |
| `add_comment` | Append a handoff note to one issue — what you tried, where to resume |
| `list_milestones` / `create_milestone` / `update_milestone` | The roadmap grouping issues |

## Session protocol

At task start, before planning, call `start_session(project)` once. It returns
the project card and docs health, the status doc saying where the last session
left off, the open and in-progress issues, and the roadmap — read its `brief`
first, and use the structured fields under it when you need to act on one.

`project` takes a ref or the repo's git remote URL, so `git remote get-url
origin` is enough to identify the project. Call `list_projects` first only when
you do not know which project you are in.

It answers "where were we" — never make the user restate it.

While working:

- Store durable things in the brain, not the repo: docs via `save_doc`,
  decisions, conventions, and work worth doing later as issues — not TODO
  comments. Only write repo markdown when the user explicitly asks for a
  repo file (`README.md`, `CLAUDE.md`, `AGENTS.md` are the exception — they
  are part of the repo and stay there).
- Set issue `status=in_progress` when you start one and `status=done` when
  you finish — the brain derives the active issue and where work stopped
  from those timestamps; a stale status makes it lie to the next session.
- Stopping mid-issue: `add_comment` on that issue with what you tried, what
  is blocked, and where the next session should start. Issue-level progress
  belongs on the issue; comments are append-only and come back with
  `get_issue`.
- Read a doc before overwriting it; `save_doc` does not merge.
- Labels are created on first use — use them freely.

Before stopping: rewrite the `status` doc whole — what was done, current
state, what's next. It is a snapshot, not a changelog, and the inner life of
one issue goes in a comment on it rather than here.

## Writing docs

Canonical docs are `status`, `architecture`, `data_model`, `product` — one of
each per project. Any other kebab-case name creates a custom doc, the right
move for a topic that fits none of the four. Write the current state, not the
diff: the reader is a session with no memory of this one. Concise markdown —
prose for reasoning, tables for facts.

## Project refs

A bare slug addresses one of the account's own projects; `owner-handle:slug`
one shared with it. Slugs are unique per account, not globally, so an
ambiguous bare slug is rejected rather than guessed — `list_projects` gives
the exact ref to use for each.

## Keys and permissions

Keys are read-only or read-write. If `save_doc` and `create_issue` are
missing from your tool list, the key cannot write: read freely, and when
asked to record something say plainly that a write key or a write grant is
needed — never describe an update as saved when it was not. Individual
projects can also be read-only even with a write key; `list_projects` gives
the role for each, and a write to a read-only project returns an error, not
a silent no-op.

Never store secrets, credentials, tokens, or machine-specific local paths in
the brain.

## Links

- Website: https://llmbrain.dev
- Dashboard: https://app.llmbrain.dev
- MCP endpoint: https://server.llmbrain.dev/mcp
- Install script: https://server.llmbrain.dev/install.sh
- CLI on npm: https://www.npmjs.com/package/llmbrain-cli
- Beta access: https://llmbrain.dev/request-access