BrainLLM

Give Claude a memory that survives the session.

A persistent, graph-structured second brain for Claude and any MCP client — built on TriliumNext Notes, served over the Model Context Protocol.

brainllm site · How it works · Use cases · Docs

What is BrainLLM?

LLMs forget. Every session starts from zero: who you are, what you're working on, what was decided yesterday, what went wrong last week. BrainLLM fixes that.

BrainLLM is an MCP server that gives an LLM a real, persistent memory — stored in TriliumNext Notes, a mature open-source knowledge base you self-host and own. The model opens each session by loading who you are and what's live, writes durable facts the moment they surface, wires knowledge together as a typed graph, and closes each session with a log, a diary entry, and a database backup. The next session picks up exactly where the last one ended.

It's a single Bun/TypeScript service with two dependencies (the MCP SDK and Zod), speaking to Trilium exclusively through its public ETAPI. Your memory lives in your Trilium instance — inspectable, editable, and portable, never locked inside a vendor's black box.

Who it's for

Anyone running an LLM as a long-running collaborator, not a one-shot Q&A tool — across coding, research, personal knowledge management, or day-to-day operational tracking — who wants that collaborator to actually remember: who you are, what's in flight, what was decided, without you re-explaining it every session. If you're comfortable self-hosting one small service and a Trilium instance, BrainLLM turns "the model forgot everything again" into a solved problem. It works with any MCP-capable client (Claude Desktop, Claude Code, or anything else speaking MCP), not just one product.

From experiment to open source

BrainLLM began in February 2026 as a personal experiment: could an LLM operate a real, self-hosted second brain reliably enough to be trusted as its own memory — orienting, writing, connecting, and closing sessions without a human doing the filing? Through sustained daily, production use the answer held. The design has settled, the failure modes have been found and fixed, and the project has graduated from experiment to something efficient and stable enough to share — so it's now open source. It still runs the author's own sessions every day; what you're reading is the same code, not a demo. It also still carries the shape of one person's daily use — see Adapting to your environment for exactly what that means and what to change.

The core principle

The model supplies content. The server owns form.

Placement, naming, labels, deduplication, relation bookkeeping, lifecycle aging, archival, date stamping, HTML sanitization, backups — and structure itself — are all deterministic server policy, never delegated to the LLM. The model never chooses a parent note, never sets a label, never checks for duplicates, never stamps a date. That division is what makes the memory reliable: every guarantee is enforced at the tool layer, not requested via prompt.

Design highlights

• Structure is enforced, not requested — every content kind has a canonical structure, served by template() and held on write: a new thread requires its goal, thread/diary/session entries open with an identification line (which LLM, which environment, which session type), threads carry exactly one Resolution (owned by resolve()), duplicate section headings are detected, and Last updated stamps are server-maintained.
• Domains born complete — creating a knowledge domain creates its book and its canonical Sources note (marker legend, stamp, grouped source list, revision table), so every claim has a sourcing home from the first write.
• A visible graph — graph() renders the whole relation graph (or any note's neighborhood) as a Mermaid flowchart, maintained as a native Trilium note.
• One-call day orientation — day() serves the previous session, its change log, everything touched since, and the month's deliverables in a single call.
• Resilient plumbing — every backend call is timeout-bounded with retry on idempotent reads; all writes are idempotent or duplicate-guarded, so crashes and retries never double-write; content surgery survives the editor's own HTML rewriting; renaming a domain cascades to everything inside it; the maintenance sweep heals drift it finds.

How it works

At bootstrap, BrainLLM builds a five-area tree in Trilium. Every note the tools create is typed, labeled, dated, and placed by server policy:

BrainLLM  (#brainLlmRoot)
├── 👤 Master       Biography · Goals · Preferences               (the user — maintained singletons)
├── 🤖 LLM          Responsibilities · Protocols · Self-correction · Diary/  (the assistant's self-model + daily diary)
├── 🗂️ Memory       Sessions/ · Threads/                          (daily session logs + multi-session work)
├── 📚 Knowledge    Master/ · Domains/<domain>/{ Sources, info }  (learned facts beyond/contra training)
└── 💡 Insights     Logs/ · Graph                                 (the brain's record of itself)

A session follows an enforced protocol: start() orients (who you are, live threads, what changed since last time) → the model works, writing durable facts as they surface → session() → addendum() → maintain() → remarks() → diary() → close() commits the log, regenerates the daily change log, and triggers a DB backup. The pre-close gate is enforced in code: close() refuses until every step actually ran, in order — narrating "I did the steps" doesn't count, only tool calls do. The gate is durable, written to the session note rather than held in memory, so it survives a restart mid-session and behaves the same on stdio and HTTP.

Orientation is deliberately cheap. start() returns your singletons as section headings — enough for the model to know what the brain holds — and it pulls the one section that matters. Serving the entire self-model on every session meant a one-line question cost the same as a day's work; start(depth="full") is still there for the sessions that genuinely need it.

Knowledge is a typed graph: a closed vocabulary of 16 relations (extends, contradicts, supports, partOf, supersedes, corrects, …), wired by connect() or at creation, traversed by explore() (links / backlinks / neighborhood / shortest path), rendered by graph(), and audited by maintain(deep), which heals duplicate edges and flags what a note application would never think to look for: orphaned notes, stale content, duplicate titles, structural drift inside a note, bodies past the read ceiling, stubs that were labelled and never written, titles carrying a date (which defeats dedup-by-title), threads heavy enough to want consolidating, Sources notes whose verification table was never filled in, and bodies carrying doubly-escaped markup. Most of it is computed from note properties server-side rather than by reading bodies, so the report is complete rather than truncated. Findings can be acknowledged (maintain(ack=[…])) so a flag you have judged correct goes quiet until that note's content actually changes — a warning that reappears every run and is correctly ignored every run trains you to skim the list.

Quick start

Prerequisites

• Bun v1.0+
• A running TriliumNext instance (desktop app or server)

1. Install and build

git clone https://github.com/miisodev/BrainLLM
cd BrainLLM
bun install
bun run build

2. Get an ETAPI token

Or skip this step. Set TRILIUM_PASSWORD instead of TRILIUM_ETAPI_TOKEN and BrainLLM mints a token itself on first start, caching it beside brainllm.json so restarts reuse it rather than creating a new one each time. This is the easiest path for a container deploy, where there's no terminal to run a setup command in.

To do it explicitly instead, either let init mint one:

TRILIUM_BASE_URL=http://localhost:8080 TRILIUM_PASSWORD=your-trilium-password bun run init