Memory & Learning

brAIn keeps one small, human-readable document about your home at /config/.brain/memory/memory.md — preferences, entity nicknames, household patterns, device quirks. It’s what turns “turn on the beacon” into the office lamp, and every surface in the add-on reads and writes it: the terminal, voice, insight runs, study sessions.

The whole design answers one question: what, exactly, has it learned? If you can’t point at a line and say “it knows that”, it isn’t memory.

What ends up in it

Real lines from a real document — the kind of thing that changes an answer rather than padding a profile:

• “The office” means the upstairs back bedroom, not the study downstairs.
• Sarah is a light sleeper. Nothing in the hallway should go above 15% brightness between 23:00 and 06:00.
• Heating is an 8 kW air-source heat pump on weather compensation. It is not a boiler, so “boost the heating” means raising the flow temperature.
• The garage fridge is meant to run 24/7. Its draw looking abnormal at 3 am is the defrost cycle, not a fault.
• Never rename an entity_id without asking — several are referenced in a Node-RED flow I cannot see.

That last kind matters more than it looks: memory is where you put the rules you’d otherwise have to repeat in every request.

One document, one writer

What	Where	Is it memory?
memory.md	/config/.brain/memory/	Yes. The canonical document — plain markdown, user-editable, capped at memory_max_kb (default 8 KB).
voice.md	/config/.brain/memory/	Derived. A ≤2 KB distillate spliced into voice prompts. Don’t edit it; it’s regenerated.
inbox/	/config/.brain/memory/	No — a queue. Candidate facts waiting to be folded in.
Hypotheses	/config/.brain/memory/	No — a queue. Open guesses awaiting a yes/no.
Change log	/config/.brain/memory/	No — an audit trail, so you can see what changed and undo it.

Only the queues are ever written to directly. Nothing writes memory.md except the consolidator, which folds the inbox in once a day (or early when 20+ facts are pending), deduping, resolving contradictions newest-wins, and enforcing the size cap. One writer means no races, and it means the document stays a document rather than an append-only log.

⇪ File into memory now on the Memory tab runs that same pass immediately — same script, same safety checks. It empties Waiting to be filed, and what was in it is now in the document, which is the one place it’s read and edited from. If the pass keeps the facts instead — it does that rather than write a document it isn’t happy with — it says so, and the queue stays where it was.

The inbox, the hypothesis queue, and the change log are never injected into prompts. They’re plumbing, not knowledge.

A consolidation can’t quietly erase what it knows

A pass that would drop more than 60% of the document’s content lines is refused outright, and any failure leaves memory untouched with the inbox still pending. Nothing is ever half-written: both memory.md and voice.md are replaced atomically or not at all.

How it learns

• You tell it — say “remember that…” to a voice assistant, run brain memory add "…" in the terminal, or call brain.add_memory from an automation.
• It notices — when a voice conversation ends, a bounded reflection pass (cheap model, no tools) extracts up to 3 durable facts: preferences, corrections, nicknames. Transient states, one-off commands, and secrets are excluded.
• It studies — brain learn <topic> (or the brain.study service, or /learn in the terminal) runs a deep session on one subject and files what it finds. Without a topic it picks whatever has gone stalest.
• It analyses — insight runs file their durable findings the same way, through the same inbox.

Guesses, not questions

Earlier versions asked open-ended questions, which piled up unanswered and left you reading raw Q&A transcripts. brAIn instead states what it believes, phrased for a yes/no:

“The garage fridge is meant to run 24/7 — right?”

Two taps in the Memory tab settle it:

• ✓ files it as a plain memory line. It’s now a fact like any other; the guess is gone.
• ✗ records a dead end that is never revisited, in any wording.

The rules are enforced in code, not merely requested in a prompt — a model that ignores the budget still can’t grow the queue:

• 3 open at a time, maximum.
• 14-day expiry — an unanswered guess retires itself.
• Never re-proposed, confirmed or rejected, however it’s reworded.

binary_sensor.brain_waiting_on_you turns on when a guess needs an answer, with the text in its pending attribute. That exists to be automated: a guess sitting in a panel nobody has open expires unanswered, but pushed to a phone it costs one tap.

Learning you can see from outside the panel

• brain_learned fires as a logbook event for every new fact, so “brAIn learned: the hallway sensor drops offline around 2am” appears in your home’s timeline next to lights and doors.
• sensor.brain_facts_learned — how many things it knows.
• sensor.brain_last_learned — the most recent one, with the text as an attribute.

Viewing, editing, undoing

The Memory tab shows the document formatted, with ✎ Edit markdown for the raw file and a Teach it something box that merges a new fact straight in. Everything there is also on the command line:

brain memory list                        # what it knows
brain memory add "Guests use the loft"   # queue a fact yourself
brain memory inbox                       # facts awaiting consolidation
brain memory hypotheses                  # pending guesses
brain memory consolidate                 # run a consolidation pass now
brain memory log                         # what changed recently, and why
brain memory undo 2                      # revert memory change #2 from that log
brain memory forget "the loft is warm"   # queue a line for removal
brain memory edit                        # open memory.md in $EDITOR
brain memory clear --confirm             # reset (old file kept as memory.md.bak)

brain learn energy                       # study a topic now
brain learn                              # study whatever is stalest

memory.md is yours. Edit it freely — your edits are the source of truth, and the consolidator merges around them rather than over them. brain memory log shows every change the consolidator made, in plain English, and brain memory undo <n> reverts one.

Two different undos

brain memory undo reverts a change to what brAIn knows. Plain brain undo reverts a change Claude made to a file in your /config. They’re separate journals, and neither can touch the other’s.

Services

# Queue a fact from an automation
action: brain.add_memory
data:
  fact: "The dog gets fed at 7 and 17 — kitchen lights on then means feeding time"
  confidence: high     # high | medium | low (default medium)

# Study a topic in the background; results arrive in memory, not in a response
action: brain.study
data:
  topic: "energy"      # omit to study whatever has gone stalest

Kill switches

• learning: false — the master switch. Stops the reflection pass, the consolidator, and study sessions. Existing memory is left untouched and still used.
• memory_injection: false — keep learning, stop splicing memory into voice prompts.
• brain memory clear --confirm — forget everything learned so far.