<!-- Generated by scripts/build-agents-md.mjs. Do not edit.
     Wrapper: apps/website/content/agents.md
     Conventions below: apps/api/src/llmbrain/assets/skill.md (#23) -->

# 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.ai

## 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` and `preferences`, plus any custom kebab-case doc. Each carries
  freshness tracking, so agents (and the dashboard) can see what has gone
  stale.
- **Docs link to each other** — `[[architecture]]` inside a doc body names
  another doc, `[[project/slug]]` one in another project. Links are
  clickable in the dashboard, every doc read comes back with its `links`
  and `backlinks`, and the dashboard draws a project's docs as a graph.
- **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://llmbrain.ai/app

## Connect over MCP

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

An account and API key are required. Beta invites:
https://llmbrain.ai/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://llmbrain.ai/app (no account yet → https://llmbrain.ai/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.ai/install.sh | LLMBRAIN_KEY=llmb_xxx bash
   ```

   Interactive equivalent, for a human at a terminal:

   ```sh
   curl -sSL https://server.llmbrain.ai/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.


The tool list and the CLI's own commands are deliberately not enumerated here.
`llmbrain --help` is the CLI's truth, and an MCP client is handed the live tool
list the moment it connects — a table on this page could only ever be a copy
that goes stale between releases, which is the failure this page was rebuilt to
stop (#23).

## Conventions

Everything below is the llmbrain skill verbatim — the same text `llmbrain setup`
installs on the machine and the same text the server hands out at
`/api/v1/install/skill`. It is the conventions an agent follows once it is
connected: what belongs in the brain, which doc holds it, and when to write it.

The brain is memory that survives the session, the machine, and the agent.
The repo holds code; the brain holds everything you would otherwise have to
be told twice.

### At task start

One call: `start_session(project)`. It returns the project card and docs
health, the status doc saying where the last session left off, the
`preferences` doc when the user has written one, the open and in-progress
issues, and the roadmap. Read its `brief` first — the structured
fields under it carry the same facts 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 find the project. If you do not know
which project this is, `list_projects` first.

A project is a product and may span several repos — `zenve3d-website` is
usually another repo of `zenve3d`, not a project of its own. When a remote is
untracked, the error says what to do: ask the user whether this repo belongs
to an existing project, and if so attach it with `update_project(add_repo=<remote url>)`
— never create a twin project for a satellite repo without asking.

Do this before planning, not after. It answers "where were we", so never make
the user restate it.

### Finding something

`search(query, project=None, owner=None)` covers docs, issues, decisions and
memories in every project you can reach, ranked, with a snippet of the matching
text. It is the answer to "where did we decide X?" and "have we solved this
before?" — reach for it before asking the user to restate something they
already told an earlier session.

Bare words are ANDed, "quoted phrases" match in order, a leading `-` excludes.
Write the query precisely; nothing rewrites it for you. Each hit carries a
project ref plus a doc slug, issue number, decision id or memory id, which is
exactly what `get_doc` / `get_issue` / `get_decision` take next — the snippet
is a pointer, not the passage.

A team's projects are in your reach the moment you are a member, so they turn
up unasked. `owner=<handle>` is how you ask for **only** that account's brain —
a team handle to search the team's, and it narrows what you can already reach
rather than opening anything new.

### What belongs in the brain

| Store | Where |
|---|---|
| Any doc you are asked to write | `save_doc` — a canonical name if one fits, otherwise a new kebab-case one |
| A change to a doc that already exists | `patch_doc` — never `save_doc` with the body retyped |
| A doc's title or folder, nothing else | `update_doc` — the metadata without the body |
| A design or data-model change | `architecture` / `data_model`, in the same session as the code |
| A choice and why: "chose X over Y", "won't do X" | `add_decision` — never an overwriteable doc |
| A reversal of an earlier decision | `add_decision(supersedes=…)` — never an edit |
| One small durable fact about the project | `remember` — not a line in `status` |
| How this codebase is worked on | a `conventions` doc |
| A preference or a fact about the user | the `preferences` doc |
| Work worth doing later | `create_issue` — not a TODO comment |
| Where you stopped on one issue | `add_comment` on that issue |
| How the session ended | `status`, before you stop |

Do not write markdown into the repo unless the user explicitly asks for a
repo file. `README.md` and agent instruction files (`CLAUDE.md`,
`AGENTS.md`) are the exception: they are part of the repo and stay there.

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

### Before you stop

The table above says where each kind of thing goes. The failure is not knowing
that — it is reaching the end of a session with the reasoning still only in the
conversation. So the last thing you do, before the status doc and before you
answer, is one explicit pass over the session:

> What did this session produce that the next one would otherwise have to
> rediscover?

Then route each item through the table above. It is one sweep, not a memory
dump, and the routing is the whole point: a choice written as a memory loses
its alternatives, a fact written into `status` is overwritten by the next save,
and work written as a comment is tracked by nothing.

Four rules for the sweep:

- **Search before writing.** If the brain already holds it, do not add a second
  copy — update the doc, or `add_decision(supersedes=…)` if the new item
  replaces an old one. A duplicate is worse than nothing: two records disagree
  and the reader cannot tell which is current.
- **The bar is a different session, a month from now, on another machine:**
  would it act differently knowing this? If not, do not store it. Restating
  what the code already shows costs the next session reading time and buys it
  nothing.
- **Never secrets, credentials, tokens or machine-local paths** — the rule from
  above, restated here because this is the moment it is most at risk: the useful
  fact and the unstoreable one often arrive in the same sentence.
- **A typical session yields 0–3 items, and zero is a real answer.** Ten
  memories out of one session means the bar slipped, not that the session was
  rich.

Do this even when nothing is being committed and no issue was closed — a
session that only worked something out is exactly the one whose output lives
nowhere else.

The sweep **is** the ritual. There is no separate "close the session" call:
the record of what happened is the decisions, issues, comments, memories and
status doc it produced, and the status doc is what the next session reads
first. Make sure it says how this one ended.

### Docs

Canonical docs are `status`, `architecture`, `data_model`, `product` and
`preferences` — one of each per project. The first four are expected of every
project and reported missing until they exist; `preferences` is canonical but
optional, so a project without one is not incomplete. You are not limited to
these: `save_doc` with any kebab-case name creates a custom doc, and that is
the right move for a topic that does not fit one of them.

- Read before you write, always. `save_doc` replaces the whole body, it does
  not merge.
- **Edit with `patch_doc`, not `save_doc`.** `patch_doc(project, doc,
  old_string, new_string)` swaps one exact string and leaves everything else
  alone, so changing a line costs the line rather than the document — and
  nothing you did not mention can go missing, which is the failure a body
  retyped from memory produces silently. `old_string` has to match exactly
  once: copy it out of `get_doc`, whitespace included, and widen it until it is
  unique. Reach for `save_doc` when the doc does not exist yet, or when the
  rewrite genuinely replaces the whole body — the status doc every session.
- **Rename or move with `update_doc`.** `update_doc(project, doc, title?,
  folder?)` changes the title or the folder and never sees the body, so a
  move costs one field instead of the document. Only custom docs take a
  folder; `""` puts one back at the root.
- **One topic per doc, linked — never one doc that holds everything.** A
  doc is what one reader opens for one question, and `get_doc` costs the
  reader the whole body, so a doc that has grown a second subject is two
  docs. When a section becomes its own thing — a subsystem, a runbook, a
  design, the details behind a decision — give it its own kebab-case doc
  and leave a one-line pointer `[[that-doc]]` where the section was, in
  place of the text. The reader who needs it follows the link; the one who
  does not never paid for it. The canonical docs stay overviews: an
  `architecture` that names each subsystem and links `[[subsystem-x]]` for
  the depth beats one that inlines all of it.
- **Link docs to each other with wikilinks.** `[[architecture]]` names a
  doc in the same project, `[[zenve3d/architecture]]` one in another
  project, `[[alice:zenve3d/architecture]]` one shared with you (the same
  ref you address the project by), and `[[architecture|the design]]` sets
  the link text. The CLI's `llmbrain://zenve3d/architecture` locator works
  too, inside an ordinary `[text](…)` link. Every link is clickable in the
  dashboard, `get_doc` answers with `links` (each target, and whether it
  exists yet) and `backlinks` (every doc that names this one), so a
  reference can be followed without a search. A link to a doc nobody has
  written is fine — it reads as dangling until that doc is saved. Docs
  only: `[[#12]]` for issues does not exist yet.
- 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.
- Custom docs can carry a one-level `folder` — a dashboard grouping, not part
  of the address. Pass it only when the user asks for a doc in a folder
  (`""` moves one back to the root); leaving it out never touches the folder
  a doc already has.
- An image belongs in the brain, not on a third-party host and never as
  inline base64. `llmbrain upload <file> -p <ref>` stores it (≤ 2 MB) and
  prints the `![name](url)` line — paste that into the doc. The URL works
  anywhere the doc is read, including a shared link.
- The same command takes an **HTML page or a PDF** — a report, a chart, a
  rendered export. It comes back as a `[name](url)` link, and opening it
  shows the page. Those are the only files the brain stores: PNG, JPEG, GIF,
  WebP, HTML, PDF. Anything else is refused, and that is deliberate — a
  `.md`, a `.txt`, a `.csv`, anything a person reads as text, is a **doc**
  (`save_doc`), never a file.
- A page **you built** — an HTML report the user asked for, a chart, a
  rendered summary — goes straight in with `upload_html_artifact(project,
  name, html)`: no temp file, no shell. HTML only, and the server checks
  the body is a document; markdown handed to it is refused with `save_doc`
  named. Paste the returned `[name](url)` line into the doc that should
  link it. Over 256 KB, or for an image or PDF, write the file to disk and
  use `llmbrain upload`.
- Files go the other way too. When the user points at something in the
  project's Files — "implement design.html", "check the mock I uploaded" —
  `list_artifacts` finds it and `get_artifact` reads it: an HTML page comes
  back as text to work from directly, so implement from that and never ask
  for it to be pasted. An image or a file over the 256 KB text cap comes back
  as metadata and a URL (`truncated: true` for the second) — `curl -L <url>
  -o <name>` and read the local file.

#### `preferences` — facts about the user

When the user states a preference or corrects how you work — "don't commit
unless I ask", "use uv, never pip", "tables, not prose", "we deploy with
dokploy, don't suggest alternatives" — write it into `preferences` in the same
session. Then follow it in later sessions without being told again: that is
the entire reason it is stored.

- `preferences` is about the **user**: tools they like, how they want to be
  communicated with, what they do by hand.
- `conventions` is about the **project**: naming, layer rules, release
  ritual, anything a different person on the same codebase would also follow.
- Merging the two makes both unusable. When a line would read oddly as
  "the user prefers…", it is a convention.
- Short markdown bullets, one preference per line, with the why when there is
  one — `start_session` puts this in front of you before work starts, so
  compactness is the point.
- It is per project, like every other doc. A preference that holds everywhere
  gets repeated in the projects where it applies.

The `status` doc is a snapshot, not a changelog — rewrite it whole every
time, in three parts: what was done, current state, what's next. Progress
inside one issue goes in a comment on that issue, not here. "What was done"
keeps only the last few dated entries — three is plenty; delete the older
ones on each save instead of carrying them forward. Deleting is safe exactly
when the routing table above was followed: a choice is a decision, issue
detail is a comment on the issue, a lasting fact is a memory. If dropping an
entry would lose something, that something is filed in the wrong place —
file it, then delete. Status must never be the only copy of anything
durable — and it need not copy what the brain answers on demand either:
`start_session` already returns the open issues and roadmap, `list_decisions`
the choices, the issue thread its own history. A pointer ("detail on #26's
thread") beats a restatement every time.

### Issues and milestones

Issues are the unit of work; milestones group them into the roadmap.

- Set `status=in_progress` when you start and `status=done` when you finish.
  The brain derives the active issue and where work stopped from those
  timestamps, so a stale status makes it lie to the next session.
- Work you discover mid-session becomes an issue with a real body: context,
  approach, acceptance criteria. A bare title is not a spec.
- `priority` is `low` | `medium` | `high` | `critical`, and it is what orders
  every list issues are picked from — `list_issues` and `start_session` return
  highest first, most recently active within a priority. New issues are
  `medium`; set something else only when the work really is more or less
  urgent than the rest, because a field set on everything ranks nothing. Ask
  before raising one above `high` — `critical` is the user's call, not yours.
- Labels are created on first use — use them freely.

### Decisions

`add_decision(project, title, body_md)` records what was chosen, why, and the
alternatives considered. Sessions systematically under-use it, and the reason is
always the same: the choice felt like a passing remark at the time and went into
status-doc prose, where the next `save_doc` overwrote it.

Record a decision when any of these happens — no judgement call needed:

| In the session | What to write |
|---|---|
| "we chose X over Y" | the choice, why X won, what Y would have cost |
| "we won't do X because" | the rejection and the reason, so it is not re-proposed |
| "keep doing X this way" | the rule and what goes wrong when it is broken |

Do it **before the session ends**, in the same session the choice was made —
the reasoning is the part that evaporates, and the code only ever shows the
outcome. A decision is cheap: three sentences beats nothing.

Decisions are append-only — no update, no delete. Evolution is a *new*
decision pointing at the one it replaces:

- `add_decision(..., supersedes=<old decision id>)` retires the old one. The
  old decision stays readable and now reports what replaced it, which is how a
  reader tells "we changed our mind" from "we never thought about it".
- Supersede only the current head of a chain. Pointing at a decision that was
  already superseded is rejected, and the error names the head to use instead.
- `get_decision` returns both directions: `supersedes` (what this retired) and
  `superseded_by` (what retired this, null while it is current).
- `list_decisions` returns compact newest-first pointers with superseded ones
  flagged, and search still finds them — history is kept on purpose. Never
  quote a decision marked superseded as the current answer.

Docs and decisions are not alternatives. The doc holds the state that resulted
(`architecture` says how the system is built); the decision holds why it went
that way and what was rejected. Writing the reasoning into a doc loses it at
the next overwrite, so a decision never substitutes a doc update, and a doc
update never substitutes the decision.

### Memories — one named fact

`remember(project, name, description, body, labels?, source?)` stores a single
durable fact as a card. It is the cheapest thing in the brain and the one with the
lowest bar: if you learned something about a project that is true beyond this
conversation and too small to justify a doc, remember it.

- `name` — a kebab-case slug, the memory's address (`uv-add-needs-rebuild`).
  Remember on an existing name **replaces** that memory, card and body, so a
  fact that changed is refreshed in place, never duplicated beside itself.
- `description` — one line, 140 chars: the punchline. The rule, warning or
  fact itself, specific enough to act on straight from the index — "HEAD 404s
  on every /public/* route — probe with GET", never "a note about routing".
  `start_session` pushes it and search matches it at title weight, so the
  distinguishing terms belong in it.
- `body` — one level deeper, never a restatement of the description: the
  incident that taught the fact (date, commit, issue), **why** it is true,
  and **how to apply** it — the exact commands, the recovery steps, the
  exceptions — plus the names of related memories. Capped at 2000 characters.
  Labels are optional and share the project's issue labels.
- `source` — who vouched for it: `user` when the human said the thing in so
  many words, `agent` (the default) for anything you inferred, observed or
  were told by a tool. A `user` memory reads as an instruction to the next
  session and an `agent` one as a finding, so over-claiming `user` is worse
  than missing it. Re-remembering never downgrades: an `agent` write on a
  `user` fact replaces the wording and keeps `user`, and the response shows
  the stored source either way.

What it is for, concretely:

- `voyage-key-base-url` — "the Voyage key is a MongoDB Atlas model key, so it
  needs a custom base URL"
- `flaky-oauth-test` — "`test_oauth_refresh` is flaky — rerun before
  suspecting your change"
- `user-machines` — "the user's other machine is Windows; check both installers"

One well-shaped card in full — punchline on top, the layers underneath:

```
name:        flaky-oauth-test
description: test_oauth_refresh is flaky — rerun it before suspecting your change
body:
Fails about one run in ten on a token-expiry race; first seen in CI on
2026-03-14, unchanged since (#87 tracks the real fix).

**Why:** the test freezes the clock but not the refresh window, so a slow
runner crosses the expiry mid-assertion.

**How to apply:** rerun the single test before bisecting your change; twice
red in a row means it is really broken. Related: `ci-retry-policy`.
```

These are the facts that today either bloat the `status` doc — where the next
`save_doc` overwrites them — or evaporate with the session.

**Which record takes it.** The boundaries are not stylistic; putting a fact in
the wrong one loses it:

| What you have | Where it goes | Why not a memory |
|---|---|---|
| A choice and its reasoning | `add_decision` | a memory is a *fact*, not a choice, and carries no alternatives |
| A fact about the *user* | the `preferences` doc | memories are about the project and the world, not the person |
| Work still to be done | `create_issue` | a memory carries no action and nothing tracks it to done |
| Anything with structure or prose | `save_doc`, then `patch_doc` to change it | a fact that needs headings has outgrown the cap |
| Where you stopped on one issue | `add_comment` | issue-level progress belongs on the issue |

- Memories are **pushed and retrieved, not read in bulk**: `start_session`
  carries the most recently updated cards (name + description, plus
  `source: user` on the facts the human stated) and `search` covers the
  rest. When a card or a search hit is the one you need,
  `get_memory(project, name)` reads that body alone — the incident, the why
  and how to apply it. `list_memories` is for reviewing or pruning, not for
  reading them into context.
- **Editing is re-remembering.** Search first if unsure what name a fact lives
  under; then `remember` the same name with the corrected card and body.
- `forget(project, name)` deletes permanently, index entry and all. Use it the
  moment a memory turns out to be wrong with nothing true to replace it —
  unlike a superseded decision, there is no history worth keeping, and a wrong
  fact left in place keeps misleading every session that finds it.

#### Comments — where you stopped

`add_comment(project, number, body_md)` appends a note to one issue. Comments
are append-only and come back with `get_issue`, oldest-first, so the next
session reads the spec and the history together.

Leave one whenever you stop mid-issue: what you tried, what is blocked, which
file or test the next session should start at. That detail belongs on the
issue — `status` is the project-level snapshot, and growing it with the inner
life of one issue buries the parts every session needs. A finished issue takes
comments too: the commit it shipped in, or what turned out to be wrong, is
worth appending.

### Skills

The brain stores skills too — account-scoped, one skill usable across every
project. `list_skills` shows what you can reach; `get_skill` and `save_skill`
read and edit a skill *in the brain*.

Installing one onto this machine is the CLI's job, not yours:

```
llmbrain skills pull <name> --global   # for every project on this machine
llmbrain skills pull <name> --local    # for this project only
```

Never install by writing `get_skill`'s files to disk yourself. The CLI writes
the one cross-agent store (`.agents/skills`), links it where each agent looks,
and records a manifest entry so `pull` can update it and `doctor` can check
it. A hand copy serves only one agent, blocks a proper install later, and
silently drifts from the brain. The same rule in reverse: local edits go up
with `llmbrain skills push <name>`, not by retyping files into `save_skill`.

Some skills are public: `llmbrain skills browse` lists what anyone can pull,
and `llmbrain skills pull <handle>:<name>` installs one. A public skill is
read-only to everyone but its owner — to build on one, pull it and push your
own copy under a name of yours. Publishing needs approval, so a skill of the
user's goes to the gallery with `llmbrain skills publish <name>` (or the
dashboard) and waits for review; do not offer to publish anything unasked.

### Project refs

A bare slug addresses one of your own projects; `owner-handle:slug` one
shared with you. Slugs are unique per account, not globally, so an ambiguous
bare slug is rejected rather than guessed. `list_projects` gives the exact
ref and whether you can write to it.

### Read-only keys

If `save_doc` and `create_issue` are missing from your tool list, this 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 be read-only even with a write
key; `list_projects` gives the role for each.

## Links

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