THOR-memory-bible-for-AI

![The AI Memory Bible](assets/banner.png)

# THOR - a memory for your AI coding assistant

**Your assistant forgets you the second you close the window. THOR does not.**

Tell it once:

- *never deploy on a Friday*
- *the invoice number goes in the payment reference, never in the description*
- *the dough is 65% water and rests overnight, not two hours*

Weeks later, in a conversation that has never heard of any of it, the right one
comes back on its own - while you are deploying, while you are invoicing, while
you are making dough. You did not search for it. You did not remind anyone.

It was built for code and it turned out not to care what the subject is. The
same memory holds your deploy rules, how your company does its billing, and what
you learned the last time you made pizza.

Runs on your own machine. No account, no key, nothing sent anywhere.

---

THOR is free and GPLv3. If it earns its keep, you can support the work:
**[buy me a Ko-fi](https://ko-fi.com/noizieworks)** or
**[become a YouTube member](https://www.youtube.com/channel/UCrEZc_oJR9mywNjqY115mRg/join)** -
no pressure, no paywall, everything stays open either way.

> **Are you an AI assistant, setting THOR up for the person you work with?** Go
> straight to **[AGENTS.md](AGENTS.md)**. It is written for you.

[![Watch: THOR explained on YouTube](https://img.youtube.com/vi/tCQOUdkhErQ/maxresdefault.jpg)](https://youtu.be/tCQOUdkhErQ)

*Prefer watching? The video above walks through what THOR is and why it exists.*

## What it does

**Remembers what you tell it.** A rule, a gotcha, a decision, the shape of the
project. Once, in your own words. It stays until you change it.

**Hands it back at the right moment.** Not a search box you have to remember.
The note arrives while you are touching the file or running the command it is
about, in a conversation that never heard it.

**Stops a wrong change, not just warns about it.** A note carrying something
checkable can refuse the write outright. Most notes only inform, and that is
deliberate: a rule that blocks honest work is the most expensive thing this
system can do.

**Keeps projects apart.** Every project has its own memory. One repo's rules
never leak into another.

**Says when it has rotted.** It counts its own dead ends: notes pointing at
files that moved, notes nothing ever reads, notes crowded out by louder ones.
Out loud, in plain language, so you can fix them.

**Stays on your machine.** No account, no key, no server. Nothing is sent
anywhere, ever.

## What that looks like in practice

Months ago you found out the hard way that this project is pinned to an older
Node, and anything newer breaks the build. You said so once, and moved on.

Today a fresh conversation opens `package.json` to add a dependency, sees an
engine range that looks out of date, and is one helpful edit away from bumping
it. Right then, before it types, your own sentence is in front of it.

That is the whole idea. Not a search box you remember to use. A memory that
shows up on time.

### "I already have a CLAUDE.md for that"

Most assistants read a rules file at startup - `CLAUDE.md`, `AGENTS.md`,
`.cursorrules`. It helps, and it runs out of road quickly.

Past a certain size it becomes a phone book, and nobody reads a phone book front
to back. Your assistant skims it, takes the gist and moves on. The rule was in
there. It got skipped. Nothing looks wrong afterwards, because the line is still
sitting in the file, so you go on believing you are covered.

Here is the part that is genuinely different. Picture a fresh agent, no history,
no idea what this project has already cost you, one keystroke away from the
exact write that broke production last spring. A rules file would have mentioned
it somewhere on page four. THOR stops the keystroke. The write does not happen -
and what stops it is the note *you* wrote, the day it broke.

That is the whole promise: not better advice, but a wrong change that does not
land.

Getting there is not free, and it is worth knowing before you start. A note only
earns that power if it is written to earn it: tied to a real file or command,
carrying something checkable that shows it still applies. THOR ships with a
handful of starting notes that teach exactly that, and refuses the ones that
cannot work. [AGENTS.md](AGENTS.md) spells out the rules of the game in full.

Three things make that work, and they all live in one file on your machine:

**1. Nothing is ever lost.** Every note is kept forever. Change your mind and
the old version stays too, so you can always look back at what you used to
think and when it changed. If two versions of a note ever conflict, THOR keeps
both and tells you, rather than quietly picking one and throwing the other away.
It is the same care you would give your source code, given to the things you
know.

**2. It arrives at the right moment.** THOR checks your memory on every message
you send. And the first time your assistant reaches for a file or runs a command
that one of your rules is about, that rule gets put in front of it right then.
Before the mistake, not after.

**3. Your assistant looks after it.** It is not a notebook you have to fill in
by hand. Your assistant can add notes, correct them, retire ones that stopped
being true, and flag which ones actually helped. A THOR that is used well is a
THOR your assistant is quietly tidying as you work.

It reads your code too. Point it at a project and it takes in the source and the
documentation, so "how does this bit work here" gets answered from your actual
project instead of a guess.

Everything stays on your machine. No cloud, no account, no subscription, and
nothing to sign up for. If some optional piece is missing, THOR quietly falls
back to a simpler way of working instead of breaking.

## A note that can actually stop you

Showing a warning at the right moment is worth a lot, and for a long time that
was all THOR could do. A note could speak. It could not refuse.

Version 2 lets a note carry a **proof of its own currency**: a small check THOR
can run right now to see whether the note is still true of your project. "This
file still contains that line." "That file is still there." "This character
never appears in anything we write."

That changes what a note is allowed to do:

- A note whose proof **runs and holds right now** may stop a wrong change
  outright.
- A note backed by words alone may warn, and only warn. It can inform your
  assistant; it can never forbid.
- If the proof **cannot run** - the file moved, the path is gone - nothing is
  blocked. It is reported as needing a look.

The reason for the split is uncomfortable and worth saying out loud. Notes rot.
You write one, the project moves on, and the note quietly becomes wrong. A tool
that let any old note block your work would spend most of its time blocking you
for reasons that stopped being true months ago. So THOR only hands that power to
notes that can prove, at that exact second, that they still describe your
project.

Which is why, as the top of this page already said, most of your notes will
never block anything. The health check prints how many can, and you should look
at it. On the author's own memory, when this was first measured, 2 notes out of
2999 could prove themselves; a day of deliberate work took that to 256. It moves
by hand, because deciding what proves a note is a judgement about that one note.

That the number is printed at all is the point: a safety net nothing is attached
to looks exactly like a safety net that works.

### THOR asks, so you do not have to remember to

Leaving that to whoever thinks of it means it never happens. So THOR asks, by
itself, in two places.

**When a note is written.** A note you call expensive, or one that spells out a
command, a flag or a filename, is not stored until one question is answered: is
there a text whose presence *means* the mistake is happening? If there is, the
note gets a proof built on exactly that text. If there is not - and often there
is not, because "check with me first" has nothing to catch - you say so and the
note goes in unchanged. Both are real answers. Only saying nothing is not.

**For the notes you already had.** Once per session, THOR picks one note that
names something concrete, has never been asked, and holds the turn until it is.
One at a time, forever, so a memory written before any of this existed still
gets worked through instead of being declared hopeless.

A caution worth stating plainly: THOR can prove that a note is *wired* so a
matching change would be stopped. It cannot know whether the text you typed is
the text the real command uses. A misspelled fragment is wired perfectly and
guards nothing. That is why the health check reports two different numbers - how
many notes could refuse something, and how many ever actually did. Trust the
second one.

## What changed in version 2

Version 1 remembered well and never argued. It would hand your assistant a note
at the right moment and hope. Version 2 is the same memory with a spine.

- **A note can refuse.** The headline, and the rest of this section is about it.
  Version 1 could only speak.
- **Bad notes no longer get in.** A note that cannot ever fire, has nothing that
  would prove it wrong, runs on for a page, or simply repeats one you already
  have: turned away at the door, with the reason and the fix. Version 1 stored
  whatever it was given, and you found out months later that half of it was
  unreachable.
- **It counts what it actually did.** How many notes can refuse something, how
  many ever have, how much of your memory nothing re-reads. Version 1 had no
  number for the one thing it was built to do, which is how a safety net stays
  broken for a year.
- **Maintenance is no longer optional.** At the end of a turn it asks for one
  thing: judge a note that keeps firing, fix one you just filed where it will
  never be seen, answer whether an expensive note can refuse anything. One at a
  time, and