how it works

A brain with rules, not a pile of embeddings

Every guarantee BrainLLM makes is enforced at the tool layer rather than requested in a prompt. Here is what that actually looks like.

The tree

Five areas, built on first run

Created by bootstrap() against a fresh Trilium instance. The root carries a discovery marker, and every structural note is engraved with its purpose at creation.

BrainLLM
โ”œโ”€โ”€ ๐Ÿ‘ค Master      the user โ€” durable identity
โ”‚   โ””โ”€โ”€ Biography ยท Goals ยท Preferences        3 singletons
โ”œโ”€โ”€ ๐Ÿค– LLM         the assistant's self-model
โ”‚   โ”œโ”€โ”€ Responsibilities ยท Protocols           2 singletons
โ”‚   โ””โ”€โ”€ Diary/          one [yyyy-mm-dd] note per day
โ”œโ”€โ”€ ๐Ÿ—‚๏ธ Memory      the operational record
โ”‚   โ”œโ”€โ”€ Sessions/       one [yyyy-mm-dd] note per day
โ”‚   โ””โ”€โ”€ Threads/        titled multi-session work
โ”‚       โ””โ”€โ”€ <Thread>/   Context + Resolution only,
โ”‚                       day-to-day lives in dated children
โ”œโ”€โ”€ ๐Ÿ“š Knowledge   learned info beyond training
โ”‚   โ”œโ”€โ”€ Master/         user facts beyond bio/goals/prefs
โ”‚   โ””โ”€โ”€ Domains/        one Sources note + N information notes
โ””โ”€โ”€ ๐Ÿ’ก Insights    the brain's record of itself
    โ”œโ”€โ”€ Logs/           auto-generated daily change log
    โ””โ”€โ”€ Graph           live Mermaid render of the relation graph
Note classes

Three behaviours, fourteen kinds

What a note is determines how writes to it behave. This is the distinction that keeps a knowledge base from decaying into a changelog.

Singletons

Exactly one maintained note; writes upsert into it. They hold current-state truth, edited in place โ€” biography, goals, preferences, responsibilities, protocols, and each domain's Sources note.

Dated records

One per calendar day, titled by date. Diary and session writes append a timestamped block, because chronology is the point. The daily log is regenerated in place โ€” one clean snapshot, never stacked.

Collections

Titled notes, deduplicated by normalised title within their scope. A thread is itself a book: its body holds only Context and Resolution, and each active day gets its own child.

Lifecycle

Threads age. Nothing is deleted.

Degradation demotes rather than removes, so an archived note keeps its content and stays retrievable. Any touch reactivates it.

active  โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ  resolved | superseded   terminal, archived in place
  โ”‚ untouched 21 days
  โ–ผ
dormant โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ  archived in place       #archived + #closed
  โ”‚ untouched 45 days more
  โ–ผ

Singletons never age

They are maintained, not recorded. Sessions, diary entries and logs never age either โ€” they are records by nature.

Eternal is exempt

A thread marked eternal is skipped by the sweep entirely, for work the user wants kept permanently active.

Aging keys off a label

Not modification date โ€” a thread's own body rarely changes once written, so date-based aging would retire a thread being worked on daily.

The graph

Sixteen verbs, closed vocabulary

Connections are typed and rejected if they aren't on the list, because an untyped "related to" edge carries no information a reader can act on.

Pick the most specific verb that's true

extends ยท contradicts ยท supports ยท causes ยท references ยท partOf ยท worksWith ยท mentors ยท instanceOf ยท supersedes ยท implements ยท inspiredBy ยท sourceOf ยท derivedFrom ยท corrects โ€” and relatesTo as the last resort.

Why corrects exists

Revising a note in place leaves no trace its previous claim was ever believed โ€” so nothing tells a later reader to be suspicious of sibling notes written in the same pass, by the same reasoning, on the same day. In a memory whose value is being trustworthy about the past, silent overwriting is the operation to trust least.

The gate

Ordered, durable, and checked by tool call

A session can't commit until every step has run โ€” and in the right order, because the diary is the closing record and should be written with the reflection cues in hand.

session()  โ†’  addendum()  โ†’  maintain()  โ†’  remarks()  โ†’  diary()  โ†’  close()

Gate state lives on today's session note as a label, not in process
memory โ€” so it survives a restart and behaves identically whether the
server is running over stdio or behind a load balancer.

See it running.

Five minutes to a working brain, if you already have Trilium up.

Quick start โ†’ See use cases