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 or become a YouTube member - 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. It is written for you.
Prefer watching? The video above walks through what THOR is and why it exists.
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.
Related MCP server: memini
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.
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 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.
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.
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.
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 it will not be waved off with a promise to do it later.
It costs almost nothing to carry. A note is capped at 300 characters and a block at four notes and 1200 characters, so what lands in the conversation is a few hundred tokens, not a whole rules file re-read on every turn. A memory of ten thousand notes costs the same per turn as one of fifty. Nothing calls out to a model to decide what to send - it is a local program reading a local file, so there is no network round trip in front of your keystroke. The one exception is the handful you deliberately pin: those are read out in full at the start of a conversation, so pin sparingly and the cap does the rest. Measured on the author's own machine and memory: about 110 ms per call and around 1500 characters delivered when something applies, against roughly 660 ms for version 1. One machine, one memory - treat it as an order of magnitude, not a specification.
Stale notes are hunted, not left to rot. A note whose proof comes out false is reported instead of quietly going on being wrong. A note that keeps firing without anyone ever saying whether it belonged gets asked about, and two verdicts of "this did not belong" retire it from every channel while leaving it findable. In version 1 a note that went wrong simply stayed.
Crowding is visible and refused. Only a few notes fit in a block, so notes compete. Version 2 counts that competition, tells you when you have just stored something onto a spot too crowded to ever show it, names what is holding the place, and refuses the write outright when every spot the note could take is already full of heavier ones. A note tied to one file, folder or command is refused the moment that single place already holds as many as it can ever show - lighter rivals count too, so a heavier note can no longer bump a lighter one out of sight unnoticed. Version 1 accepted it and said nothing, which is how a memory fills up with advice nobody will ever see.
The memory above is built for work. It has a gate, notes that interrupt you, and a hard cap on how much ever reaches the conversation - all of which is exactly wrong for a recipe.
So 2.1 adds a library, and it is a genuinely separate thing: its own file, its own two commands, and no way to reach the first memory at all. Nothing you put in it can ever interrupt you, compete with a note, or take up room in a block. You only ever see it because you asked.
It works the way a shelf works.
Everything lives on a shelf, and shelves do not nest. Books, recipes, a training log, what you spent. Filing something without naming a shelf is refused, and the refusal lists the shelves you have, so your assistant picks from real ones instead of inventing a name.
Only you create a shelf. If nothing fits, your assistant has to ask you what the new one should be called. This is the rule that stops a tidy list of eight from becoming a sprawl of sixty.
A shelf that grows gets labels, never a split. Two hundred recipes on one shelf, filtered by "bbq" or "dessert", stays one shelf. That is what keeps the list of shelves short enough to hold in your head.
You get an index, not a wall of text. Open a shelf and you see one line per entry. Ask for one by number to read it whole.
The same thing twice is refused, pointing at the entry you already have.
Nothing is ever deleted. Retiring an entry takes it out of the listing and leaves it readable.
A search never answers "nothing". If your words miss - and they will, since the words you ask with are rarely the words you wrote - it hands you the shelf to read instead. Asking for "ribbetjes" when you wrote "ribben" finds it.
The short way - one command. It downloads the latest release, checks the download against the checksum published next to it, unpacks it into your home folder, and runs the whole setup.
Windows, in PowerShell:
irm https://raw.githubusercontent.com/nworks3d/THOR-memory-bible-for-AI/main/install.ps1 | iexLinux:
curl -fsSL https://raw.githubusercontent.com/nworks3d/THOR-memory-bible-for-AI/main/install.sh | shNo administrator rights, and nothing is installed outside your own user folder. The automated setup targets Claude Code today. It touches two of its files - Claude Code's own settings and the list of tools it may use - and backs up both before it does. Rather read the script before you run it? Open that same link in a browser first. There is no macOS build yet, so on a Mac take the route below. Using a different assistant? See Using it from another assistant below.
Or build it yourself. You need a Rust toolchain. Nothing else: no key to get, no model to download first, no account.
cd thor2 && cargo build --release --features semantic
--features semanticis not optional, and leaving it off fails silently. Without it everything still builds, still runs, and still answers every word-for-word search correctly. What stops working is searching by meaning: it returns nothing at all, with no error anywhere. The reliable way to tell the two apart is size. Look atthor2/target/release/serve.exe- over 20 MB is the right build, a few MB is the wrong one. Build it again with the flag.
Then run the setup yourself. That is the same step the one-command install ends with, and in the normal case you type no paths at all:
thor2/target/release/install.exeIt finds your assistant's own two configuration files by itself, creates your memory if you do not have one yet, wires THOR into your assistant, and registers the part your assistant writes through. It backs up both files before it touches them, it never removes anything it did not put there, and running it twice changes nothing the second time.
A brand new memory does not arrive empty. It gets a handful of short notes on how to write a note that comes back to you later, and your assistant is handed them at the start of every conversation from then on. That matters more than it sounds: an assistant with nothing in front of it writes notes in a shape that never fires again, and neither of you would notice for weeks. They are ordinary notes - unpin one, rewrite it in your own words, or throw it out. An existing memory is never seeded, so upgrading never pushes anything into your own notes.
You only reach for a flag if your setup is unusual: --settings and --mcp-json
send it at other files, --db and --serve-exe override where it looks, and
--no-mcp sets up a memory your assistant can read but not write, on purpose.
If a program it needs is missing, it stops and says so rather than installing
something that would sit silent.
Then restart your assistant. The part it writes through only comes alive after a restart. Until then, it can already read the memory but not add to it.
Step 3 - check it.
thor2/target/release/doctor.exe --db "C:\Users\you\AppData\Local\thor2\thor.db"Fourteen plain-language lines, one per part: whether your memory is healthy, whether searching by meaning is switched on, how many of your notes can prove themselves, how many point at files that are no longer there, and how many are bound to something that can never happen. It changes nothing.
One of those lines only speaks up when it has something to report: if it ever says your memory's own log file has outgrown the memory itself, something is stopping a save from ever finishing - close any other program that might have that same memory open, and run the check again. Newer builds also cap how big that log file is allowed to grow, so this should be rare.
Step 4 - give each project its own memory. From that project's folder:
thor2/target/release/install.exe --project "my-project"This matters more than it sounds. Skip it and THOR gets worse the more you use
it, because every search starts competing with projects you were not asking
about. All it does is write a small file called .thor-project holding that
name, so you can also just create that file yourself. It refuses to change a
name that is already there, because renaming a project's scope would strand
every note already filed under the old one.
If you are the assistant doing the setup, AGENTS.md is the walkthrough for the steps above.
The automated setup above is for Claude Code specifically. Any other assistant that can be pointed at an external tool server can still use THOR, through the container published alongside every release instead of a local build.
A generic client config, the shape most tool-calling assistants expect:
{
"mcpServers": {
"thor": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-v", "thor-data:/data",
"ghcr.io/nworks3d/thor-mcp:2.3.1",
"mcp", "--db", "/data/thor.db"
]
}
}
}docker run -i --rm -v thor-data:/data ghcr.io/nworks3d/thor-mcp:2.3.1 mcp --db /data/thor.dbThe container does not build a fresh memory by itself - point -v at a folder
or named volume that already holds a thor.db (a copy of the one your own
build created, say). -i keeps input open, which is what talking to it over
stdio needs; drop --rm if you would rather keep the stopped container around
than have it clean up after itself.
The old advice was to start a fresh chat often, because long ones got worse and you lost everything anyway. With THOR that advice is out of date. One long conversation is now the better habit.
When a conversation gets long, the assistant's tools squeeze out the older parts to make room. THOR covers that moment: your standing rules come straight back, and it nudges your assistant to write down anything important that was never saved. Starting a fresh chat is covered too - your rules and your project's background are loaded in from the start.
So stay in one conversation while you are on one piece of work. Start a fresh one on purpose - because you have moved on to something else, or because this one has talked itself into a corner - not because it is getting long.
Worth knowing before you start, because the beginning is the least impressive part and it is easy to conclude too early that nothing is happening.
Day one, it stops nothing. A fresh memory holds a handful of starting notes: how to write one that comes back, plus the honesty and agent-spawning habits that hold on any project. The part of THOR that can refuse a wrong change only works on notes that carry a proof, and you have not written any yet. So on the first day you get those notes at the start of a conversation and a nudge at the end, and no refusals at all. That is not a fault; there is simply nothing yet to refuse with.
Your first note will probably be turned down. It asks for two things most people leave out: when the note should come back to you, and what would show it had gone wrong. If the note is about something expensive, or names a command or a filename, it asks a third: is there a text whose presence means the mistake is happening? Answering "no, there is nothing to catch here" is enough, and often it is the truthful answer. The refusal names everything that is missing at once and says what to write instead, so the second attempt usually lands. It is strict on purpose - a note nobody can ever prove wrong is a note that quietly stops being true.
The value arrives once you have notes about real places. A note tied to a file, a folder or a command comes back exactly when you touch that thing. A handful of those is worth more than fifty general ones, and after a week or two of writing them down as you go, your assistant stops asking you the same questions.
Then check what you have built with doctor. It tells you plainly how much of
your memory can actually stop a wrong change, how often it has, and which parts
nothing ever re-reads.
Everything above describes a memory that starts empty. If you are coming from version 1, or from any pile of notes written before proofs existed, the shape is different and worth saying plainly, because the obvious plan does not work.
THOR asks you about one old note per session. That is a brake, not a broom. It keeps the pile from growing while you work, and it was never meant to clear one: at one a day, a backlog of thousands outlives you.
The broom is the health check, pointed at the folder your projects actually live in:
doctor --db <your thor.db> --checkouts <the folder holding your projects> --fullThat names every note whose anchor points at nothing, every proof that now comes out false, and every note stored somewhere too crowded to ever be shown. Set aside an afternoon rather than a coffee, and go through it in one sitting. The list is long because the memory is old, not because anything is broken.
Two things make that afternoon safe to be decisive in. Correcting a note keeps the old version, so nothing you wrote is lost and you can always read back what it used to say. And removing one does not delete it either: it stops being handed to anyone, stays findable, and the reason you gave stays attached to it.
Use it for a week and see whether your assistant stops asking you the same things. That is the only test that answers the question you actually have.
THOR was measured head to head against another memory tool for months, and those numbers are not here any more. Not because they were bad - they were good - but because a score measured on someone else's notes tells you about them, not about you. The tool is here. The verdict is yours.
What your assistant actually calls, grouped the same way the memory itself is split in two.
Code lane - projects, rules, how to work:
remember - store a new rule, note, report or lookup entry
revise - correct one that already exists, instead of a near-duplicate
retract - remove one that turned out wrong (a reason is required; nothing
is deleted)
resolve - settle two versions of the same fact that diverged apart
pin - make an existing note a standing rule, served at every session start
unpin - stop it being one
get - show one item whole, by id
lookup - search everything - every project, by scope, by key, or by free
text
history - walk one item's whole past, oldest first
mark - judge whether something you were served actually helped
status - how much of the memory can actually stop a mistake, and how much
has gone stale
search_code - search the project's own indexed source code
where_used - find every place one function, struct or variable is defined
and used
outline - see everything one file declares, in line order
Library lane - recipes, books, training, expenses, kept apart from the code lane:
library - read a shelf's index, one entry, or search across shelves
shelve - file a new entry, or correct one that already exists
page | what it answers |
for your AI assistant: how to set THOR up | |
the version 2 program: how it is built and what each part does | |
the standard version 2 is judged against, and the test enforcing each rule | |
how a note proves itself, in detail | |
changing THOR: the bar for a pull request |
MakerViking - for the inspiration and the great fight. This project would not exist without the spark, and it would not be half as good without someone worth pushing against. Skål!
mimir (MakerViking/mimir) - the reason THOR exists at all. In the old Norse stories, Mimir guards the well of knowledge; here it set the bar THOR had to clear, and for a long stretch it cleared plenty of its own. Every early comparison in this project was against mimir, wins and losses both published on purpose, because a rival that good deserves honest numbers.
Ideas borrowed, both ways. Two things THOR does came from mimir's own work and were rebuilt here in THOR's own way, and mimir in turn credits THOR for reading code into memory and for checking memory on every message - exactly the kind of exchange open source is for. Thanks, MakerViking.
THOR is built by N-Works 3D. If it has earned its keep - saved you an explanation, caught a mistake before it cost you, or just meant you did not have to start from scratch - there are two easy ways to help keep it going:
Buy me a Ko-fi - a one-off, whenever you feel like it.
Become a YouTube member - monthly, if you want to keep it going.
No pressure and no paywall - it all stays open either way. Skål, and thanks for reading this far.
Bug reports and pull requests welcome. THOR is a memory your assistant is supposed to trust, so the bar is being right rather than having more features. The checklist is in CONTRIBUTING.md.
GPLv3.
Code lane: shows one item whole, by id. Use lookup instead when the id is not already known. Read-only. Reports a plain, honest error - never a blank reply that could look like success - when the id is unknown, when the item is DIVERGED (more than one current head; read history, then use resolve), or when its stored body will not parse. Replies with the item as formatted JSON, or the error text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id to show. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it fully delivers: it declares the tool read-only, promises a plain honest error rather than a blank success-like reply, enumerates the exact error conditions, and describes the two possible outputs. This is exemplary transparency for a simple read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet dense: purpose, sibling guidance, read-only guarantee, error behavior, and return format are all covered in about five sentences. It is front-loaded with the most important information and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read-only tool with no output schema and no annotations, this description is fully complete. It tells the agent what the tool does, when to use it (and when not to), what errors look like, and what the response will be. Nothing needed for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers 'id' at 100%, but the description adds meaningful semantics: the id must already be known, an unknown id produces an honest error instead of a blank result, and the reply is the whole item. This goes beyond the schema's 'The id to show' by clarifying the contract and failure behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource ('shows one item whole, by id') and immediately distinguishes itself from the sibling 'lookup', which is for when the id is not known. This gives an agent a crisp mental model of the tool without needing to inspect the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use 'lookup' when the id is not already known, and for DIVERGED items it tells the agent to read history and then use 'resolve'. These are concrete routing instructions that select this tool versus the relevant alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: walks one item's whole life by id, oldest first - every declare, revise and retraction, each with its sequence number, revision hash and author. Use get instead for only the current version. Read-only; nothing is ever deleted from the log, so this still answers for a retracted item - read it before you revise or retract again. Replies with one line per revision, or the plain 'no history for id X' for an unknown id (not an error).
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id whose whole life to walk. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly: 'Read-only; nothing is ever deleted from the log' explains durability and safety. It also discloses the unknown-id response ('no history for id X' is 'not an error') and the one-line-per-revision reply format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: primary action, sibling alternative, behavioral guarantees, and output format. It is front-loaded with the core verb and resource, then strategically narrows scope and edge cases without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description's explicit mention of reply format ('one line per revision') and unknown-id handling fills the gap. It also covers retraction semantics and a pre-revision/retraction use case, making it complete for an agent to invoke safely and correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema's description of id ('The id whose whole life to walk') already conveys meaning. The tool description reinforces the id's role but adds no new syntactic or format detail beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states a specific verb and resource: 'walks one item's whole life by id, oldest first' and lists what is included (declare, revise, retraction with sequence number, revision hash, author). It also distinguishes from sibling get: 'Use get instead for only the current version.'
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit alternative guidance: 'Use get instead for only the current version.' Also gives a concrete precondition: 'read it before you revise or retract again.' This clearly tells the agent when to choose history over get and when the history is still meaningful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Library lane: reads the owner's everyday knowledge - recipes, books, a training log, expenses - kept apart from the code lane; nothing here is ever injected, ranked against a rule, or counted toward any cap. Use shelve to write instead. No arguments lists the shelves and how much each holds; shelf lists that shelf's entries (label narrows it); id returns one entry whole; query searches, optionally within shelf. Read-only. A search never answers 'nothing' - it hands back the shelf, or the shelf list, to read instead, since the words asked with are rarely the words written. Replies with the requested listing or entry, or that fallback.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | One entry's number, as the listings show it. Returns it whole. | |
| label | No | Narrow one shelf to the entries carrying this label. Labels are how a big shelf stays usable - there are never sub-shelves. | |
| query | No | Free text. Searched over titles, bodies and labels, in four steps that end in a list to read rather than in an empty answer. | |
| shelf | No | One shelf, by name. On its own it lists that shelf, one line per entry. With `query` it searches inside that shelf only. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it does so thoroughly. It explicitly states 'Read-only', that nothing here is 'ever injected, ranked against a rule, or counted toward any cap', and discloses the search fallback behavior: a search never answers 'nothing' but returns the shelf or shelf list instead. It also states what replies generally look like ('the requested listing or entry, or that fallback').
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately concise and front-loaded with the primary purpose, then moves through invocation modes and behavioral caveats. Every sentence contributes useful information, though phrases like 'since the words asked with are rarely the words written' are explanatory but could be trimmed. Overall it is efficient for a tool with four optional parameters and no annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description does a good job covering all call modes, the read-only safety profile, the fallback search behavior, and the write alternative. It does not specify exact response JSON structure or error/edge-case handling, but the four invocation modes and their replies are described well enough for an agent to select and call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, and the schema already documents each parameter individually. The description adds value beyond the schema by explaining the no-arguments mode, how label narrows a shelf, how query can be scoped 'within shelf', and how parameters combine to produce different listings. This lifts it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'reads the owner's everyday knowledge' in the 'Library lane', and enumerates concrete examples like recipes, books, and expenses. It explicitly distinguishes itself from the code lane and from the sibling shelve tool ('Use shelve to write instead'). The multiple invocation modes (no args, shelf, id, query) are all tied to a clear read-only purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit routing: use shelve for writes, and use this tool for reading everyday knowledge kept apart from the code lane. It also explains which call shape to use for which result ('No arguments lists the shelves...', 'shelf lists that shelf's entries', 'id returns one entry whole', 'query searches'). It does not exhaustively distinguish from other read siblings like lookup or get, but the lane separation and mode-by-mode guidance are strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: searches THOR's memory - every project, archive kinds (Report, Chunk) included - never scoped to only the current project. Call this before remember, so an existing near-duplicate becomes a revise instead. No arguments returns the catalogue of scopes; scope alone lists everything filed there; scope with query narrows a search to it; query alone searches everywhere; key answers only a Lookup item's own exact key (query and scope are then ignored). Read-only, and never an injection surface - nothing here reaches you unprompted. Replies with up to 25 matching lines (id, kind, text) and how many more exist, the catalogue, or a plain 'no matches'.
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | An exact Lookup key. When given, this is the ONLY parameter used - `query` and `scope` are ignored - and only a real Lookup item can ever answer it. | |
| query | No | Free-text search over every live item's text and tags, any project, archive kinds (Report/Chunk) included - never a Lookup item (those answer only to their own `key`, see below). | |
| scope | No | One scope, by name, as the catalogue lists it. On its own it opens that scope: every item filed under it, one line each, complete. Together with `query` it narrows that search to this scope alone. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses read-only behavior ('Read-only'), non-interactivity ('nothing here reaches you unprompted'), matching limits ('up to 25 matching lines'), and the shape of replies ('id, kind, text' plus counts). It doesn't explicitly discuss rate limits or failure modes, but the behavioral surface is unusually well disclosed for a search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but purposeful; nearly every clause earns its place and the critical scoping constraint and call-before-remember advice are front-loaded. It is a long paragraph, but the complexity of five invocation modes justifies the length. It could be slightly tightened, but there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description covers what an agent needs: return shapes (catalogue, matches with id/kind/text, 'no matches'), limits, scope semantics, and exclusions (Lookup items are not queryable by free-text). The sibling context and missing output schema are fully compensated by the description's detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 100%, but the description adds semantic interactions beyond the schema: 'key answers only a Lookup item's own exact key (query and scope are then ignored)' clarifies precedence, and the mode-by-mode breakdown (no args, scope alone, scope+query, query alone) explains what combination produces what result. This is meaningful added value over the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a strong verb-resource pair ('searches THOR's memory') and immediately distinguishes itself from a current-project-scoped search. It names the sibling 'search_code' implicitly by contrast ('never scoped to only the current project') and covers all invocation modes, so an agent knows exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says 'Call this before remember, so an existing near-duplicate becomes a revise instead,' which gives a concrete when-to-use instruction and a direct alternative ('remember', 'revise'). It also enumerates the parameter-mode conditions (no arguments, scope alone, scope+query, query alone, key alone), leaving no ambiguity about which input combination to choose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: judges an item you were served or looked up. Default records that it HELPED, which clears noise recorded before it (a later noise mark still counts - the newest verdict wins). Pass noise:true for the opposite; two noise marks since the last useful one retire the item from the injection surfaces, though it stays fully findable via lookup. On a replica this queues instead of writing ('queued for the main machine' is not an error). Refused when the item is not live (retracted or archived) - there is nothing to judge. Replies with the verdict recorded, or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the item being judged. | |
| noise | No | Set true to record the OPPOSITE: this item did not belong where it fired. Two noise judgements, with no mark of usefulness, retire it from the injection surfaces; it stays fully findable via lookup. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden, and it is thorough: it explains default behavior, verdict precedence, noise semantics, retirement from injection surfaces, replica queueing, refusal conditions, and the response contents.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence contributes necessary behavioral information. It is front-loaded with the core purpose and proceeds logically through default behavior, alternative behavior, replica handling, refusals, and reply format.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema and no annotations, the description is remarkably complete. It covers expected inputs, edge cases, failure modes, asynchronous behavior, and the response the agent will receive, leaving no material ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds value beyond the schema by explaining the default verdict, the meaning of noise:true, and the real-world consequences of repeated noise marks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: judging an item by recording a verdict (helped or noise). It distinguishes itself from mere lookup or history tools, though it does not explicitly compare itself to any sibling tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates when to use the tool: for items you were served or looked up. It also explains when the tool is refused (for non-live items). It does not explicitly discuss alternatives among sibling tools, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: lists what one file declares, in line order - its shape without reading the whole thing. Use where_used instead to find every caller of one symbol. Takes a repository-relative path. Read-only. States plainly when the index has never seen that path, which differs from 'this file defines nothing' - a file added since the last index build falls in the first case. Replies with one line per definition (name and line number), or the plain 'not indexed' or 'defines nothing' text.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Repository-relative path, exactly as the index stores it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral disclosure burden. It does this well by stating read-only status, explaining the important distinction between 'not indexed' and 'defines nothing,' and specifying the exact response format: one line per definition with name and line number.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place: purpose, alternative tool, parameter requirement, read-only flag, edge-case behavior, and output format. The purpose is front-loaded, and the length is justified because there are no annotations to offload behavioral information to.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only tool with no output schema, this description is complete. It covers how to invoke the tool, what it returns, how to interpret the two plain-text outcomes, and which sibling to use for a different need. No critical operational detail is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents the single path parameter as 'Repository-relative path, exactly as the index stores it.' The description only repeats the repository-relative aspect without adding new syntax, validation, or format details, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: it lists what one file declares in line order, giving the file's shape without reading the whole file. It also explicitly distinguishes itself from the where_used sibling, so an agent can tell them apart immediately.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing guidance: 'Use where_used instead to find every caller of one symbol.' This tells the agent when not to use outline and which sibling to choose instead. The intended use case—inspecting a file's declared shape—is clear from the first sentence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: adds the Always binding to an existing item, so it is served in full at every session start; every other binding and field stays untouched. Use revise instead when anything besides the binding needs to change. Idempotent - pinning an already-pinned item changes nothing and is not an error. On a replica this queues instead of writing ('queued for the main machine' is not an error). Refused, loudly, when the item's kind may carry no binding at all (a Report or Chunk). Replies 'pinned' with the event sequence, 'already pinned', or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id to pin (add the Always binding to it). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral burden. It discloses idempotency, replica queueing behavior, refusal conditions for items that cannot carry a binding, and the possible reply strings. This is unusually complete for a tool description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence in the description carries a distinct, useful behavioral fact. It is dense but not bloated, and the most important purpose is front-loaded before edge cases and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a tool with no output schema and no annotations. It covers the normal success outcome, the no-op case, replica behavior, refusal cases, and the alternative tool, leaving little for an agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the only parameter id with 100% coverage and a clear description. The tool description reinforces that the item is existing, but does not need to add more because the schema handles parameter semantics fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action: adds the Always binding to an existing item, and clarifies the effect ('served in full at every session start'). It also distinguishes the tool from revise by name, so an agent can tell what pin does without inferring from the name alone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to use revise instead when anything besides the binding needs to change, which gives clear routing between sibling tools. It also covers the already-pinned case, replica behavior, and refusal cases, so an agent knows when the operation will not behave as a normal write.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: declares a NEW item (Rule, Orientation, Report, Lookup or Chunk) through the write gate. Call lookup first so this corrects an existing item instead of storing a near-duplicate; for anything about the owner's own life use shelve, never this. On a replica this queues instead of writing ('queued for the main machine' is not an error). Refuses, with the exact reason and the fix, when a Rule/Orientation has no binding, no falsifier, or exceeds 300 characters, or when a Report/Chunk names no project scope; nothing is written on a refusal. check_kind/check_path/check_literal(s) optionally attach a machine-runnable proof alongside the falsifier - see server instructions for the six check kinds. Replies with the stored id, kind and event sequence, or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Caller-chosen id, kept forever. Pick something short, stable and grep-able (e.g. "no-force-push-main"), not a sentence. | |
| key | No | Required for a Lookup: the exact key a future `lookup` call names to get this item back. Meaningless for the other four kinds. | |
| kind | Yes | One of: rule, orientation, report, lookup, chunk. | |
| tags | No | ||
| text | Yes | The fact itself. A Rule/Orientation is refused past 300 characters - move reasoning into a Report instead of lengthening this. | |
| always | No | Bind this item to the pinned Always layer (served in full at every session start). Only a Rule/Orientation may set this. | |
| expires | No | ISO-8601 date. Only a Report may carry this - a Rule, Orientation, Lookup or Chunk with an expiry is refused (they last until revised). | |
| moments | No | Action names this item fires on (repeatable), e.g. ["push"]. Only a Rule/Orientation may bind to a moment. The ones that actually fire are derived from a real command or file path (publish, commit, push, deploy and the rest - see intent::from_command/from_path), plus remember itself. answer and claim_done are refused on a NEW binding: nothing produces either yet, so a rule bound only to one would store cleanly and never fire. | |
| project | No | Project this item belongs to. Omit for a global, cross-project item. | |
| targets | No | Exact targets this item fires on (repeatable). Only a Rule/Orientation may bind to a target; the value must be the real path/command/etc, never a glob and never a bare role name. | |
| severity | No | One of: irreversible, costly, house_style. Meaningless (and refused as a binding target would be) on a Report/Lookup/Chunk. | |
| falsifier | No | What observation would prove this fact wrong, one sentence. Required for a Rule or Orientation - they never expire, so this is the only thing that ever names when one has gone stale. | |
| check_kind | No | One of: path_exists, contains, absent, absent_all, forbidden, requires. An optional machine-runnable check, alongside (never instead of) falsifier - only a Rule/Orientation may carry one, and only while it currently HOLDS can it block a write. Every kind except forbidden needs check_path; path_exists refuses check_literal/check_literals; contains/absent/requires need one of them; absent_all/forbidden need check_literals. requires catches something FORGOTTEN rather than written - see server instructions. Omit all four check_* fields for no check at all. | |
| check_path | No | The exact file this check inspects, relative to the checker's root - or, for contains/absent/absent_all only, a DIRECTORY: every regular file directly inside it, never one in a subdirectory. Use the directory form when one fact spans more than one file there (e.g. a setting duplicated across two config files). Required with every check_kind except forbidden, which carries no path at all and is refused if one is given. | |
| check_literal | No | The exact literal a "contains" or "absent" check_kind looks for. Refused together with "path_exists", or together with check_literals; required with "contains"/"absent". | |
| check_literals | No | A SET of literals to forbid together, for check_kind absent_all (in one file) or forbidden (everywhere, no file). One rule forbidding several things at once (e.g. every banned punctuation character) is ONE item with a set here, never several near-identical items each forbidding one literal. Each literal is its own array entry, never joined into one delimited string. Refused together with check_literal, refused empty, and refused with any other check_kind. | |
| new_collection_named_by_owner | No | THE OWNER JUST NAMED A NEW COLLECTION - repeat that name here exactly as he gave it, and it will be opened. The only way an unopened collection can be written to: nothing existing fit, you showed him the refusal (it lists both lanes), you asked, and he answered with a name. Never fill this in on your own judgement or to get past a refusal. Must match the project (or key) on this same call, or the write is refused anyway. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full transparency burden. It does well: refusal conditions are spelled out, 'nothing is written on a refusal' is stated, replica queuing is disclosed, and the reply shape is described. It could go further on permissions or side effects, but the core behavior is unusually well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One dense paragraph, but each sentence earns its place: purpose, pre-call lookup, life-item exclusion, replica behavior, refusal guarantees, check semantics, and response shape. The core purpose is front-loaded, and there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given a complex 17-parameter tool with no output schema, the description supplies the missing operational context: when to call it, when not to, what happens on a replica, refusal behavior, and what the reply will contain. It deliberately delegates itemized check-kind details to server instructions, which is reasonable alongside a heavily documented schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 94%, so the schema already documents the parameters thoroughly. The description adds only a high-level note about check_kind/check_path/check_literal(s) being an optional machine-runnable proof and points to server instructions, which is helpful but not essential beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: 'declares a NEW item (Rule, Orientation, Report, Lookup or Chunk) through the write gate.' It immediately distinguishes itself from siblings by saying lookup is for correcting existing items and shelve is for the owner's life, so an agent can tell what this tool is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing guidance is given: 'Call lookup first' to avoid near-duplicates, and 'for anything about the owner's own life use shelve, never this.' It also tells the agent what to expect on a replica ('queued for the main machine' is not an error), which is a useful when-to-use signal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: settles an item with more than one current head - what get reports as DIVERGED, from two machines revising the same fact apart. Read history first; never guess which head is real. Name the surviving revision hash in keep and every other current head in discard - leaving one out fails rather than silently discarding it. On a replica this queues instead of writing ('queued for the main machine' is not an error). The head set is rechecked under the write lock, so a head that appears mid-decision fails the call loudly instead of being dropped. Replies 'resolved onto ', or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The diverged id. | |
| keep | Yes | The revision hash that survives. | |
| discard | Yes | Every other current head, in full. Leaving one out fails rather than silently discarding it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses replica queuing ('queued for the main machine' is not an error), rechecking under the write lock causing loud failure, and the exact success/refusal reply text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence carries operational information: purpose, preconditions, replica behavior, concurrency, and response format. It is front-loaded with the core purpose and then covers failure modes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutable, concurrency-sensitive tool with no output schema and no annotations, the description covers prerequisites, failure semantics, replica behavior, and return text. An agent has enough to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents id, keep, and discard. The description operationalizes keep as 'surviving revision hash' and discard as 'every other current head', but this mostly restates the schema, with no additional parameter format or value constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'settles an item with more than one current head' and ties it to the exact state 'what get reports as DIVERGED'. This clearly distinguishes it from sibling tools like get, which reports divergence, and revise, which creates divergent versions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger condition ('what get reports as DIVERGED') and instructs the agent to 'Read history first; never guess which head is real'. It does not explicitly enumerate alternatives or when-not-to-use conditions, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: removes an item that is simply WRONG or no longer applies - it stops being live everywhere (session start, the moment of action, lookup), but nothing is deleted, and history still walks it. Use revise instead when the item merely changed. A reason is required; a blank one is refused. On a replica this queues instead of writing ('queued for the main machine' is not an error). Bringing the fact back later is a fresh remember, never a revise of the tombstone. Replies 'retracted ()', or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id to retract. | |
| reason | Yes | Why it is wrong or no longer applies. Required, and a blank one is refused: without it nobody can later tell a decision from an accident. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries full weight and does so thoroughly. It discloses the non-destructive nature ('nothing is deleted, and history still walks it'), replica queueing behavior, the required non-blank reason, the exact reply format, and the tombstone rule. Nothing about the operation's side effects is hidden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence carries distinct information: purpose, scope, alternative, constraint, replica behavior, future recovery, and reply format. Despite density, it is well-organized and front-loaded with the core semantics before the edge cases. There is no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has subtle semantics (tombstone, live-everywhere removal, replica queueing), and the description addresses all of them. It also covers the required reason, refusal behavior, response format, and post-retraction workflow. With no output schema, this level of detail is sufficient for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the description does not add meaning beyond the schema for parameters. It reinforces the reason requirement and the refusal of blank reasons, but those are already stated in the schema's property description. Baseline 3 is appropriate since the schema already documents both parameters fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'removes an item that is simply WRONG or no longer applies', and immediately distinguishes it from the sibling 'revise'. It also clarifies the nuanced effect (stops being live everywhere, but nothing is deleted), so an agent can tell exactly what retract does versus other mutations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative: 'Use revise instead when the item merely changed', giving a clear decision rule. It also explains what to do after retraction ('Bringing the fact back later is a fresh remember, never a revise of the tombstone'), and covers replica behavior without treating it as an error. This is complete routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: corrects an EXISTING item by id, through the same write gate as remember, plus one more rule: a field left unmentioned keeps its current value, and none may silently vanish - clear one on purpose with an empty string (severity, project, expires, key, falsifier) or check_kind "" (clears the check). On a replica this queues instead of writing ('queued for the main machine' is not an error). Prefer this over remember for anything that already exists and merely changed. Refuses, with the exact reason, on the same grounds as remember, plus a field dropped without being named. Replies with the revised id and event sequence, or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id of the existing item to correct. | |
| key | No | Omit to keep the current key; pass "" to clear it. | |
| tags | No | Replaces the whole tag list. Omit to keep the current tags; pass an empty list to clear them on purpose - the same omit-keeps/empty-clears convention as severity/project/expires/key/falsifier, spelled with a list: omitted means unmentioned, an empty array means deliberately cleared, a real list replaces the whole set. | |
| text | No | New text, replacing the whole body. Omit to keep the current text unchanged. For a SMALL correction to a long item, prefer `append` or `replace_from`/`replace_to` below - retyping a 290-character rule to fix one word is friction on exactly the maintenance this memory needs most, and it is the reason corrections get skipped. | |
| always | No | Replaces whether this item is bound Always - see `moments`' own note. | |
| append | No | Add this to the END of the current text, with one space between. Refused together with `text` (say what the body is, or say what to add to it, never both). The result still goes through the whole gate, so a 300-character limit is enforced on what comes out, not on what you typed. | |
| expires | No | Omit to keep the current expiry; pass "" to clear it. | |
| moments | No | Replaces the moment bindings. Give this, `targets`, and/or `always` TOGETHER to replace the WHOLE binding list in one call - when none of the three are given, the existing bindings are kept untouched. See RememberArgs' own note on which moments actually fire - a NEW answer/ claim_done binding is refused here too, though one the item already carried stays correctable. | |
| project | No | Omit to keep the current project; pass "" to make it global. | |
| targets | No | Replaces the target bindings - see `moments`' own note on how the three binding fields combine. | |
| severity | No | One of: irreversible, costly, house_style. Omit to keep the current value; pass "" to clear it. | |
| falsifier | No | Omit to keep the current falsifier; pass "" to clear it (a Rule or Orientation left with none is refused, same as at creation). | |
| check_kind | No | One of: path_exists, contains, absent, absent_all, forbidden, requires. Omit all four check_* fields to keep the current check untouched; pass check_kind as "" to clear it (refused if check_path/check_literal/check_literals is also given). Give check_kind plus whichever of check_path/check_literal/check_literals the kind takes, together, to replace the check wholesale - see RememberArgs' own check_kind note for what each kind needs and which to prefer. | |
| check_path | No | See check_kind's own note on the omit/clear/replace convention, and RememberArgs' own note on check_path for the directory shape contains/absent/absent_all also accept (every regular file DIRECTLY inside it, never a subdirectory). Refused outright if check_kind is "forbidden" - that kind carries no path at all. | |
| replace_to | No | What `replace_from` becomes. Pass an empty string to delete the substring. | |
| replace_from | No | Replace the FIRST occurrence of this substring in the current text with `replace_to`. Refused unless `replace_to` is given too, refused together with `text`, and refused when the substring is not actually in the current text - a silent no-op would report success while changing nothing. | |
| check_literal | No | See check_kind's own note on the omit/clear/replace convention. | |
| check_literals | No | The set form of check_literal, for check_kind absent_all or forbidden - see RememberArgs' own note on why this is a repeatable field rather than a delimited string. Same omit/clear/replace convention as check_kind: an empty list here reads the same as omitting it, since a list has no separate way to say 'given, but deliberately empty'. | |
| new_collection_named_by_owner | No | THE OWNER JUST NAMED A NEW COLLECTION - repeat that name here, exactly as he gave it. Same field, same rule and same one flow as on remember: only after nothing fitted, you showed him the refusal and he answered with a name. It must match the project (or key) this call files the item under. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it delivers: it discloses the write-gate mutation path, the omit-keeps/empty-clears merge semantics, the replica queueing behavior, the refusal grounds (including the unnamed-field-drop rule), and the reply format (revised id and event sequence, or refusal text). This is exceptional disclosure for an unannotated write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but tightly structured: purpose first, then the core merge rule, then the replica caveat, then usage preference, then refusals and reply. Roughly 120 words cover a 19-parameter tool's essential contract with zero filler; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite high complexity (19 params) and no annotations or output schema, the description covers the full operational contract: what it does, the merge/clear model, replica behavior, refusal conditions, and the response shape. The schema covers all parameter details at 100%, so nothing an agent needs to invoke it correctly is left unaddressed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description earns one extra point by synthesizing the cross-cutting convention — 'a field left unmentioned keeps its current value, and none may silently vanish' — which unifies the per-parameter omit/clear semantics that the schema spells out individually. It adds a conceptual frame the schema alone does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening states a specific verb and resource: 'corrects an EXISTING item by id,' which immediately distinguishes revise from create-oriented siblings like remember. It also explicitly contrasts itself ('Prefer this over remember for anything that already exists and merely changed'), so an agent can select it without inspecting the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing advice: 'Prefer this over remember for anything that already exists and merely changed.' It also tells the agent when behavior differs ('On a replica this queues instead of writing') and how to interpret the non-error response. This is clear when-to-use guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: searches the indexed SOURCE CODE of the current project, not the memory - a case-insensitive substring search. Use lookup instead for facts stored in memory, or where_used for one symbol's callers. Read-only. Every answer names the commit the text was read at and whether the working copy has since moved on - open the real file before trusting a line number. States plainly when no code index is configured, rather than returning an empty result. Replies with up to 10 matching snippets as path:start-end plus text.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Most hits to return. Defaults to 10. | |
| query | Yes | Case-insensitive substring to find in the indexed source. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so well. It discloses read-only behavior, that results name the commit read, warns that the working copy may have moved on, advises opening the real file before trusting line numbers, and states the tool plainly reports when no code index is configured rather than returning empty results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence earns its place: purpose, sibling routing, safety, staleness warning, error behavior, and output format are all covered without repetition. It is front-loaded with the core purpose and uses sentence-level structure that is easy for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description correctly explains the return format: up to 10 snippets as path:start-end plus text, with commit context. It also covers the no-index case and the staleness caveat. For a two-parameter search tool, the description is complete enough for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents both parameters. The description adds little beyond what the schema says: it mentions case-insensitive substring matching and a 10-snippet output default, but these largely mirror the schema's own descriptions. Baseline 3 is appropriate since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: searches the indexed SOURCE CODE of the current project, not memory. It further clarifies the search is case-insensitive substring matching. It distinguishes itself from lookup and where_used, making sibling differentiation clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use lookup instead for facts stored in memory, and where_used instead for a symbol's callers. This gives direct routing guidance among siblings with no ambiguity about when this tool is the right choice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Library lane: files one new entry on an EXISTING shelf, or corrects one by id - never the code lane, and it cannot create a shelf. Use remember instead for facts about code or how to work, never for the owner's own life. On a replica this queues instead of writing ('queued for the main machine' is not an error). Refused, naming the shelves that do exist, when none fits (ask the owner what a new one should be called); refused on a near-duplicate of an entry already on that shelf, pointing at it; refused past roughly 600 characters unless one_thing_because names the single thing the entry is. Replies 'filed ' or 'revised ', or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | CORRECT AN ENTRY THAT ALREADY EXISTS instead of filing a new one: its number, as the shelf listing shows it. The fields given replace what is there; the number stays, and the version replaced stays readable. Use this whenever a filed entry turns out wrong, badly worded or missing a label - a second entry saying the same thing better makes a shelf unreadable. Omit it to file something new. | |
| body | No | The rest, at any length. Optional. | |
| shelf | Yes | An EXISTING shelf. If none fits, ask the owner - you may not create one. | |
| title | No | One line that stands on its own. This is the index. When correcting an entry (see `id`), leave it empty to keep the title it has. | |
| labels | No | Optional labels for filtering inside a shelf. | |
| one_thing_because | No | WHY THIS LONG BODY IS STILL ONE THING - required past the length where an entry is usually several things glued together, ignored below it. Name the single thing it is (e.g. "one pizza dough recipe") in a real sentence. Cannot name it in one? Then it is more than one thing - file separate entries on the same shelf with labels instead. Filler here does not get a pile past the question. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses replica queueing behavior, exact success replies ('filed <id>' / 'revised <id>'), refusal categories (no fitting shelf, near-duplicate, over-length body), and the one_thing_because requirement. This is far beyond the minimum for a write operation and gives the agent accurate expectations for side effects and errors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single dense paragraph, but every sentence carries useful information and the main operation is front-loaded. Some semicolon-heavy refusal clauses could be more readable, but there is no filler or redundant restating of the schema. It earns its length through behavioral and routing detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter write tool with no output schema and no annotations, the description is remarkably complete. It explains input requirements, output strings, refusal behavior, queue behavior, and the alternative tool. The rich schema fills in the remaining parameter-level details, so an agent has everything needed to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has 100% description coverage, so the baseline is 3. The description adds important semantic constraints beyond the schema, such as the ~600-character threshold for one_thing_because and the fact that id means correction rather than new filing. It does not restate every parameter, but the schema handles those details; the description enhances the most decision-critical semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: it "files one new entry on an EXISTING shelf, or corrects one by id." It also actively distinguishes itself from the code lane and from the remember sibling, so an agent can tell which lane this belongs to. The core operation is unambiguous and not a tautology of the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit routing guidance: "Use remember instead for facts about code or how to work, never for the owner's own life." It also states what shelve cannot do (create a shelf) and instructs the agent to ask the owner when no existing shelf fits. This is clear when-and-when-not guidance with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: reports what the memory holds right now - live item counts per kind, how many Rule/Orientation items exist, how many were declared but have never once fired, how many were served repeatedly without ever being marked useful, and how many carry no falsifier. Use get or history instead for one specific item. Read-only, takes no arguments. Replies with one count per line.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It discloses that the tool is read-only, takes no arguments, returns one count per line, and lists the exact count categories. This gives the agent an accurate behavioral model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then enumerates the specific counts. It is slightly dense with enumerated categories, but every clause adds useful behavioral or selection information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only status tool with no output schema, the description fully covers what the tool does, what it returns, and how it differs from nearby siblings. No critical gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, which is the baseline-4 case. The description reinforces this by saying 'takes no arguments,' so there is no ambiguity left.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb and resource: 'reports what the memory holds right now' via live counts across specified categories. It clearly differentiates itself from get/history by noting those are for one specific item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use this tool versus alternatives: 'Use get or history instead for one specific item.' This gives an agent a clear routing decision without needing to open sibling schemas.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: removes the Always binding from an existing item; every other binding and field stays untouched. Use revise instead when anything besides the binding needs to change. Idempotent - unpinning an item with no Always binding changes nothing and is not an error. On a replica this queues instead of writing ('queued for the main machine' is not an error). Refused, loudly, when removing Always would leave the item with no binding left to ever fire on - give it a Moment or Target binding first, or leave it pinned. Replies 'unpinned' with the event sequence, 'already unpinned', or the refusal text.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The id to unpin (remove the Always binding from it). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses idempotency, replica queueing behavior, the refusal condition, and the possible reply strings. This is exceptional behavioral transparency for a mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but every sentence conveys necessary information: purpose, alternative, edge cases, and response semantics. Slightly long and the 'Code lane:' opener is opaque, but otherwise well-structured and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with no output schema and meaningful edge cases, the description covers operation semantics, alternatives, idempotency, replica behavior, refusal conditions, and expected replies. Nothing essential to invoking it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already documents the sole 'id' parameter as 'The id to unpin (remove the Always binding from it)'. The description adds context like 'existing item' and idempotency, but does not substantially enhance the parameter's meaning beyond the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('removes') and resource ('the Always binding from an existing item'), and explicitly distinguishes itself from revise. This gives an agent a clear, differentiated understanding of the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use revise when anything besides the binding needs to change, and explains when unpin is refused. This provides concrete selection criteria and a conditional path for using it correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Code lane: answers who defines and who uses one symbol name - the question to ask before changing a function, struct or variable, since the reference list IS the blast radius. Use outline instead to see everything one file declares. Read-only. Resolution is by bare name only, so two unrelated things sharing a name come back together - open the files rather than treating the list as a conclusion. Replies with every definition and use site as file:line, the indexed commit, and whether the checkout has since moved on.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The bare symbol name: a function, class, struct or variable. | |
| limit | No | Most sites to return per side. Defaults to 30. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that resolution is by bare name only, that unrelated same-name symbols are grouped together, and that results include the indexed commit and whether checkout has moved on. It lacks explicit statements about permissions or rate limits, but given this is a read-only query tool, the behavioral disclosure is strong.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact but information-dense. Every sentence earns its place: purpose, usage timing, alternative, read-only nature, important caveat, and expected reply format. It is front-loaded with the primary question and blast-radius framing, making it easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description tells the agent what it will get (every definition and use site as file:line, indexed commit, checkout state) and what caveats apply. It doesn't explicitly document the 'limit' parameter's effect on output, but the schema already describes that. Without an output schema, mentioning the reply shape is valuable. Minor gap: no statement about performance or large result handling beyond the limit default.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds useful semantic context about 'bare symbol name' and matching behavior, but does not add much beyond the schema's parameter descriptions. It clarifies the meaning of 'name' well enough, so a 3 is fair.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific operation (finding definitions and uses of a symbol name) and clearly distinguishes this from the sibling 'outline', which is about file-level declarations. The verb 'answers who defines and who uses' and the explicit 'code lane' qualifier make the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to use this tool: 'the question to ask before changing a function, struct or variable'. It also names the alternative, 'Use outline instead to see everything one file declares', and warns about the blast radius interpretation. It even advises opening files rather than treating the result list as a conclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0gethistorylibrarylookupmarkoutlinepinrememberresolveretractrevisesearch_codeshelvestatusunpinwhere_usedEach tool targets a distinct read/write/action niche: get current by id, history log, lookup search, remember/revise/retract lifecycle, resolve divergence, pin/unpin bindings, mark feedback, library/shelve for the separate lane, and three distinct code inspection tools. Descriptions explicitly cross-reference confusable alternatives, so an agent should not misselect.
Names are consistently lowercase and readable, but the set is not a uniform verb_noun pattern: most are single verbs, while library, history, and status are nouns, and search_code/where_used use underscore phrases. This is a minor style deviation rather than a chaotic mix.
At 16 tools, the server sits just above the typical well-scoped 3-15 range. Each tool covers a meaningful part of the memory lifecycle, so it is not bloated, but the count is slightly heavy for the stated scope.
The code lane is well covered: create, read, update, retract, history, search, conflict resolution, bindings, feedback, and status. However, the library lane has no way to create a shelf and no deletion mechanism, which is a notable gap since shelve explicitly refuses when no existing shelf fits.
Agent memory that refuses to guess: evidence-gated recall, exact-source reads, verifiable deletion.
Memory for coding agents: the decisions, the dead ends, and where the last session stopped.
The system of record for AI agent authority: playbooks, routed policy questions, reusable rules.
Persistent cross-session memory shared by Codex, Claude Code, ChatGPT, and other AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/nworks3d/THOR-memory-bible-for-AI'
If you have feedback or need assistance with the MCP directory API, please join our Discord server