Quick start

BrainLLM needs a running TriliumNext instance and Bun 1.0 or later. It uses Bun's APIs directly and does not run on Node.

1. Run Trilium and create a token

Install TriliumNext on your computer or anywhere reachable over HTTP, then create a token under Options → ETAPI → Create token. Or skip the token and set TRILIUM_PASSWORD: BrainLLM creates one on first start and caches it.

2. Install

# from npm (needs bun on PATH)
npx -y brainllm

# or from source
git clone https://github.com/miisodev/BrainLLM
cd BrainLLM && bun install && bun run build

Client configuration

For Claude Desktop, Claude Code or any client that launches local servers:

{
  "mcpServers": {
    "BrainLLM": {
      "command": "npx",
      "args": ["-y", "brainllm"],
      "env": {
        "TRILIUM_BASE_URL": "http://localhost:8080",
        "TRILIUM_ETAPI_TOKEN": "your-token"
      }
    }
  }
}

For claude.ai, the Claude apps and Cowork, BrainLLM runs as a remote server instead: see Connect to Claude.

Bootstrap the brain

On a fresh Trilium, call bootstrap() once from your client, or run bun run init from a checkout. It builds the five-area tree, engraves each container's purpose and writes brainllm.json. It is safe to run at any time: it checks an existing root live and builds a new tree only on a confirmed miss.

Teach the model to operate it

The tools are terse single-word verbs; the working discipline lives in the bundled skill at skills/brainllm/. Copy it to ~/.claude/skills/brainllm for Claude Code and Cowork, or upload skills/brainllm.zip to claude.ai. Without it a model can call every tool correctly and still keep an untidy brain, because a correct call is not a correct practice.

Environment variables

Tool surface

45 tools by default: 35 verbs and 10 surface reads. BRAINLLM_MODE=full adds 33 raw Trilium tools, 78 in all. Every tool carries a human-readable title and is marked read-only, write or destructive, so clients can group their permission prompts; an unclassified tool is treated as a write, never a read.

Kinds and statuses

Sixteen kinds: biography, goals, preferences, responsibilities, protocols, selfcorrection, diary, session, thread, threadEntry, user, domain, information, sources, log and claim. Five statuses: active, dormant, resolved, superseded and eternal. Only threads age, and an eternal thread never does.

Session protocol

START   start()                    the first BrainLLM call of a session
        day()                      when start() reports a new day
DURING  remember · revise · recall · domain · connect · ...
END     session() → addendum() → maintain() → remarks() → diary() → close()

close() refuses until the closing steps have run, with session → remarks → diary in that order. diary() and close() take an identity line, "LLM · environment · agent/mode". The gate's state lives on the day's session note, so it survives a restart. session() lists the notes the session changed, so a figure corrected in one note can be checked everywhere it is recorded.

Editing large notes

• revise(noteId, section="Heading") replaces one section; mode="before", "after", "prepend" and "remove" act around it.
• revise(noteId, find="a few words", within="tr") replaces, inserts beside or removes the table row containing them. Inline formatting in the stored text doesn't stop a match.
• revise(domain="Name", find=, body=) previews a find and replace across a whole domain; add dryRun=false to write it.
• Reads take section=; records take block="14:05" or block="-1" for one addendum; read(ids=[...], text=true) returns readable text for orientation.
• diff(since="today") shows every change made today, with table edits reported cell by cell.

Transports

On a container host, mount a volume and set BRAINLLM_CONFIG to a file inside it, or discovery reruns on every cold start.

OAuth

claude.ai and the Claude apps connect with OAuth only; they have no field for a bearer token. BrainLLM is its own OAuth 2.1 authorization server, with PKCE, Client ID Metadata Documents and dynamic registration at /register. Set BRAINLLM_OWNER_PASSWORD to turn it on; unset, the OAuth surface does not exist. The consent screen names the requesting client and the address it returns to, and warns when that address is your own computer. Refresh tokens rotate on use and are stored only as hashes.

Health and backups

close() backs up into one of seven weekday slots. backup(name) keeps a named milestone, which stays on Trilium's volume until deleted there. health() reports Trilium's version, an estimate of the database's size, the heaviest notes and their revision counts, and the named backups taken through BrainLLM, and flags growth before the disk fills.

Troubleshooting

Still stuck? See Support.