THOR

THOR - a memory for your AI coding assistant

Most memory tools can only remind your assistant. THOR can refuse.

Give it a note with a proof attached - a small check it can run right now, like "this file still contains that line." From then on the note stops being advice. THOR refuses the matching edit or command before it runs. Not a suggestion your assistant is free to skip. A hard stop.

That proof runs live, at the exact moment it matters, against your actual project. A note that has gone stale, that no longer describes what is really there, quietly stops counting as proof - so it can never block you by mistake.

Other local memories can refuse a write too. What is different is where the block comes from: a proof, checked live, never a rule taken on faith. And the whole loop that produces it, learning included, runs in one place: this machine.

Most notes only inform: pinned so they are handed over at the start of every session, or surfaced the first time your assistant reaches for the file or command they are about.

A note that keeps being served without ever being judged is asked about in one block, not one note at a time: the end-of-session review (/thor-eval), which THOR asks for about once a week per project. THOR does not stop an ordinary turn to ask whether one note helped or got in the way. The review only names a note your own session actually saw fire - never one that only ever showed up during other, unrelated work. Two "this did not belong" verdicts since the note was last rewritten stop a plain note from being served again, though it stays there if you go looking for it. A rewrite of the note's text, check or bindings starts that count again, and a note whose check can refuse is never hidden this way.

A health check names what has rotted, out loud: proofs that now come out false, notes pointing at nothing, notes too crowded to ever be shown.

Everything that is not code - a recipe, a book, a training log - lives in its own library, kept apart, so it never competes with a deploy rule for room.

Everything stays on your machine by default: no account, no key, no cloud - including what it learns about which of your notes are worth keeping. The only two things that can leave it are listed under "Stays on your machine" below.

Get started. Send this repository's link to your AI assistant (Claude Code) and say "install THOR". It does the whole setup itself; the only thing it asks of you is to close Claude Code and open it again, once. The full step-by-step is under Getting started further down. If you are the assistant, read AGENTS.md.

---

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.

*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. THOR never sends anything on its own. Exactly two things can leave your machine, and only because you say so: a bug report about THOR itself, sent to its GitHub page only after your explicit yes to the exact text shown (file paths, project and computer names, addresses, keys and passwords are removed first), and a backup of your memory to a place you name, if you choose one - a backup kept on this machine sends nothing. A short record of recent commands and replies, kept beside the memory so THOR can test its own rules, never leaves the machine and can be switched off (install --set-recording off).

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 set of starting notes that teach exactly that, and refuses the ones that cannot work. 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 by default. 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." Or, for catching something left out rather than something wrong: "every agent I spawn names which model to do the work with."

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.

That first kind of stop reaches further than an edit made through your assistant's own tools: deleting the protected file, emptying it out, or overwriting it from a command your assistant runs counts as the same wrong change, and is stopped the same way.

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 does it by itself, in two places.

When a note is written. You are not asked whether the note can be checked: THOR tries it. A rule that spells out a command, a flag or a filename is run through the same guard that watches your files and commands. If a check built on its own words really refuses the wrong change and lets ordinary changes through, the note is stored as a rule that can refuse. If no check holds, it is stored as a plain note: it still comes back at the right moment, it just cannot refuse anything. A note that is turned down says what to write instead.

For the notes you already had. THOR sorts the older notes itself at the start of each review (below). Only what needs your assistant's own judgement is handed over, in one block, 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.

The review is the broom: run /thor-eval at the end of a session. It walks through everything the memory has been served without a verdict, repairs what has quietly drifted out of date, and settles the debt in one pass instead of one note at a time. A session that never