--- name: portable-memory description: A durable, plain-text memory for an AI assistant that any business can run — a folder of notes, one always-loaded index, and a size guard that refuses to fail silently. Use when setting up memory for a new person or business, when the index needs checking or consolidating, or when asking whether the memory system is healthy. Works with any assistant that can read files and run a command; nothing here is specific to one vendor. --- # portable-memory A memory an assistant actually keeps: **a folder of plain-text notes, one small index that is loaded into every conversation, and a guard that stops the index silently losing content.** Nothing here needs a server, a database, or an account. It is files and two small scripts. ## Why this exists, stated honestly The index file is loaded into every conversation, and past a limit the end is not loaded. Claude Code's documentation, for one, says it loads the first 200 lines or 25 KB of its memory index, whichever comes first. The assistant then does not know the last things it was told, and unless someone checks, nobody notices. Every other design choice here follows from that one fact. Other assistants have other limits, so the guard takes `--cliff` and `--max-lines`. **A human remembering to check is not a solution.** It failed for us four times, and each time the reaction was to write down a threshold, which then went stale as the file grew. **The number must be re-derived every run, by a program, or it will be wrong exactly when it matters.** ## The three parts | part | what it is | why | |---|---|---| | `notes/` | one plain `.md` file per thing worth remembering | text survives every tool change; git gives you history for free | | `MEMORY.md` | the small always-loaded index | the assistant cannot read 3 000 notes every turn; it reads this and follows links | | `memory-size-check.mjs` | the guard | the index has a silent failure mode and must police itself | `MEMORY.md` has two halves, and the split is the whole trick: - **the protected part** — the rules that must always be in context. **Never cut this to save space.** - **the cuttable part** — one line per topic, each pointing at a note. **This is the only part that may be trimmed**, and trimming means *moving a line's detail into its own note*, never rewording it to save bytes. ## Checking it — run this, do not eyeball it ```bash node memory-size-check.mjs --dir ``` Exit codes are the contract, so a script can rely on them: ``` 0 ok within the derived budget 1 over the index is too big or has too many lines — move a line's detail out into its own note 2 cannot-check it could not look. THIS IS NOT A PASS. The size is UNKNOWN. ``` Add `--json` for machine-readable output. `--hooks-heading ""` if your index uses different wording for the split. `--limit` sets the cuttable allowance, `--cliff` sets the size at which your assistant truncates (the default 24576 bytes is one host's limit, so check yours), and `--help` lists everything. **The guard refuses what it does not understand.** An unknown option (`--limt`), a bad number (`--limit banana`), an option with no value, a heading it cannot find, a heading that appears twice, and an index with no rules and no notes (headings, quoted instructions and comments do not count) are all `cannot-check`, exit 2. A typo in a flag must never produce a confident pass, and an earlier version of this tool did exactly that. Headings inside code blocks and comments are ignored, so an example in your own notes cannot become the split point. `node test.mjs` runs the 59 cases that pin this down, for both scripts. **Exit 2 is the one people get wrong.** "Could not check" is not "fine". If the file is missing, empty, or the heading has been renamed, the guard says so and exits non-zero **rather than reporting healthy** — because a check that cannot see is exactly how a silent failure hides. ## How to use it day to day - **Before changing something you have touched before, read its note first.** The system is only worth what gets written into it. - **Write the note when you learn the thing**, not later. An unwritten finding is one somebody rediscovers from scratch. - **One line in the index per note**, pointing at it. When the index gets full, move a line's detail into the note it points at — the index is a signpost, not a store. - **Run the check at the start of a session.** If it says `over`, fix it then. Not later. ## Finding a note ```bash node memory-search.mjs "" --dir ``` ``` 0 found matches, best first, with WHY each one matched 1 no-match the search ran and found nothing. That is an answer. 2 could-not-look the folder was missing, a number was not a number, or an option was unknown. NOT the same as "nothing found". ``` Options: `--dir`, `--k`, `--json`. **An unknown option is refused, not ignored** — an ignored flag means the caller thought they asked for something they did not get. Unreadable notes are **counted and reported**, never silently skipped: "searched 200" and "searched 200, could not open 3" are different claims. **This is plain word search, not AI search, and that is a deliberate choice.** Heavier systems exist — an embedding model, a vector index, native modules that can fail to build on an ordinary laptop. They pay off for corpora of thousands of notes grown over years. **A business starting today has tens of notes.** Plain search finds the same answers at that size, has nothing to install, and cannot silently go stale — an index you forget to rebuild answers confidently from old data, which is worse than no index. ### Where it works and where it does not — measured, not claimed Run against a real corpus of a few thousand notes: | question | top score vs next | result | |---|---|---| | "invoice quote symmetry" | 51 vs 29 | correct note first | | "banking details on quotes" | 50 vs 20 | correct note first | | a rule about how to sign off a message | 80 vs 80 | both hits correct (a real tie) | | "the assistant stopped answering" | 23 vs 21 | **wrong** — a *Home Assistant* note, matched on the word "assistant" | **It fails on paraphrase, and it fails confidently.** The last row is the whole limitation: ask using words the note does not contain and you get something plausible and wrong. **So the tool shows its working.** Every result prints *why* it matched, and a near-tie prints **LOW CONFIDENCE** with both scores. The wrong answer above is a near-tie; the right ones are not. **The fix for a search that can be wrong is not to hide how it decided — it is to put the evidence next to the answer so a reader can see a weak match is weak.** **The practical consequence for whoever uses this: PUT THE WORDS PEOPLE WILL SEARCH FOR INTO THE NOTE'S FILE NAME.** A name match outscores everything else, and it is the one signal a human controls directly. `quoting.md` is worse than `how-we-price-and-quote-jobs.md`. ## What this is NOT - **Not a vector database or a knowledge graph.** For one business's own notes, a disciplined folder plus read-first beats a graph, and it can be read by a human when the AI is wrong. - **Not tied to one assistant.** The check is a plain script with no dependencies and JSON output, so any tool that can run a command can use it. - **Not a substitute for the habit.** The system does not enforce reading before acting. It makes the habit cheap and it refuses to hide when the index is full — that is all. ## Setting it up for someone 1. Copy `memory-size-check.mjs`, `memory-search.mjs` and `template/MEMORY.md`. **Copy no notes** — the notes are somebody else's data, and they are the one thing that must never travel. 2. Put the template `MEMORY.md` in the new folder and make an empty `notes/` beside it. 3. Run the check. It should say **ok** with a large headroom. Then empty `MEMORY.md` completely and run it again: it must say **cannot-check, exit 2** — *not* "ok, small file". **See that once before you rely on it**, so you know the guard reports blindness rather than health. 4. Replace the commented examples in the template with the rules that must always apply. Add nothing else to that section. **Step 3 is the only step that proves anything.** The rest is copying files. A guard nobody has watched fail is a guard nobody knows works — the whole point of this package is a check that refuses to say "fine" when it cannot see, and you should make it do that once, deliberately.