memgineering 0.4.2 → 0.6.0

package/assets/memgineering-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-memory
-description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, says something worth keeping, or wants their memory set up so it knows who they are. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "is this still true", "which one do I go with", "set up my memory", "fill in my profile", "teach it about me", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "내 정보 채워줘", "나에 대해 알려줘", "what do you know about my setup". Covers recall, open, evidence, remember, revise, undo, resurface, and filling in the `01_BASE/` files by asking.
+description: Use when the user refers to something they told you before, asks what was decided, tells you something worth keeping, settles something that should hold next time, or wants their memory set up so it knows who they are. Triggers include "what did I decide about X", "check my notes", "how do we do this again", "remember this", "is this still true", "from now on", "never do X again", "set up my memory", "fill in my profile", "what do you know about my setup". This is the map — it says which verb answers which question and points at the skill that covers it.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -12,326 +12,67 @@ database: they wrote those files, they can open them in any editor, and
 memgineering reads them and keeps a derived index outside the folder. Deleting
 that index costs a rebuild and nothing else.
 
-Everything below assumes the brain is already linked. If a command answers
-`no brain is linked yet`, see "Getting connected" at the bottom.
+This page is the map. Each verb below has one or two lines here and its detail
+in one of four skills; open the one you need rather than all of them.
 
-## Answering from what they already know
+## Which verb answers which question
 
-Recall first whenever the question sounds settled — a past decision, their
-setup, their preferences, why something is the way it is.
+| the question in front of you                                   | verb                               | detail                 |
+| -------------------------------------------------------------- | ---------------------------------- | ---------------------- |
+| "what did we decide about…", anything that sounds settled      | `recall "<their words>"`           | `memgineering-recall`  |
+| you have a card and need what is behind it                     | `open <handle>`                    | `memgineering-recall`  |
+| two memories disagree, or one looks old                        | `evidence <handle>`                | `memgineering-recall`  |
+| new folder, or "where were we" — nothing to search for yet     | `resurface`                        | `memgineering-recall`  |
+| you learned something durable                                  | `remember "<it>" --reason "<why>"` | `memgineering-writing` |
+| a conclusion you recorded has changed                          | `revise <ref> --claim …`           | `memgineering-writing` |
+| that write was wrong                                           | `undo --reason "<why>"`            | `memgineering-writing` |
+| no longer current / stop reading this file                     | `retire` · `exclude`               | `memgineering-writing` |
+| their `01_BASE/` files are still templates                     | `onboard`, then ask                | `memgineering-writing` |
+| the user settled something that should hold next time          | `remember "<it>" --rule`           | `memgineering-rules`   |
+| what already binds me here?                                    | `rules`                            | `memgineering-rules`   |
+| nothing is connected yet, or it needs to reach another machine | `link` · `init` · `push` · `pull`  | `memgineering-setup`   |
 
-```
-memgineering recall "how do we deploy"
-```
+Everything below is what holds no matter which of those you are doing.
 
-```
-## recall: how do we deploy  (2 cards)
+## Recall before you answer, write when you learn
 
-### 1. Deploy is manual
-stated
+Two habits, and they are the whole product:
 
-> launchctl kickstart on the Mac Studio, no CD pipeline
+- **Before answering anything that sounds already settled**, recall. Their
+  project, their setup, their preferences, their past reasoning — and before
+  repeating advice you have no evidence they wanted.
+- **When this session decides something durable**, write it. No approval step
+  by design: it is recorded and reversible, so a wrong entry costs one `undo`,
+  not a permanent mistake. Do not ask permission for ordinary observations.
 
-`open: deploy-manual`
-```
+**Pass `--reason` on every write.** It goes in the ledger and it is the only
+part of the record that still means anything to whoever reads it six months
+from now. It is refused if it looks like it carries a credential.
 
-The output is already shaped for your context — headings, a quoted summary,
-and a handle. Paste it in as-is rather than reformatting it into prose.
+If the user settled something rather than told you something — "from now on",
+"never", "we always do it this way" — that takes `--rule`. See `memgineering-rules`.
 
-**But read it before you use it.** These are candidates ranked by relevance,
-not a list of answers: anything matching a word from the query is returned, so
-the tail of a long result can be only loosely related. That is deliberate —
-for a memory system, failing to return a note someone knows is there is worse
-than returning one they can ignore. Use the top matches that actually answer
-the question and leave the rest; quoting all of them back as if each were
-relevant is how a useful recall turns into noise.
+## What to raise rather than just doing
 
-Then open only what matters:
-
-```
-memgineering open deploy-manual                      # the claims behind the card
-memgineering open deploy-manual --detail summary     # + its headings
-memgineering open deploy-manual --detail chunks      # + every section
-memgineering open deploy-manual --section preflight  # one section
-memgineering open deploy-manual --detail full        # the whole note
-```
-
-`open` takes a handle, a full id, a path inside the brain, or a note's exact
-title — so when you already know what you want, skip the recall.
-
-### When one round trip is enough
-
-```
-memgineering recall "deploy" --limit 1 --detail full
-```
-
-Best match, read whole, one call. Use this when the user's question clearly
-points at one note.
-
-### Nothing matched
-
-Say so. Only titles, aliases and summaries are searched, so suggest broader
-words — but do not go read their folder yourself to compensate. A brain that
-answers "nothing" is giving you real information.
-
-### Cards that are not answers
-
-A card marked `not filled in yet` is one of the five `01_BASE/` files, still
-byte-for-byte what `init` wrote. Nobody has answered it, so it is evidence of
-nothing — do not quote it back as if it were what they think.
-
-When every card carries that mark, recall says so above them:
-
-```
-⚠ Nothing you have written matched this.
-  Every card below is still the template `init` wrote
-```
-
-That is the moment to offer to fill them in rather than to answer from them —
-`memgineering onboard` prints the questions. The cards are still listed, because
-the label is a claim about the file, not a decision about what you may see;
-`--json` carries the same fact as `scaffolding: true`.
-
-The mark disappears the moment the user writes in the file. A base note they
-have filled in is an ordinary note of theirs and often the best answer in the
-brain — `who am I`, `what am I not allowed to do`, `where does everything live`
-are all answered from `01_BASE/`.
-
-## Filling in the base files, which only you can do
-
-`init` creates five files in `01_BASE/` and leaves them empty, because what
-goes in them cannot be typed into a form. Who the user is, how they want
-answers, what you must ask before doing, what would be expensive to get wrong,
-what they actually run — those come out of a conversation.
-
-They matter more than any single memory: `resurface` puts these at the top of a
-new session, and an empty one teaches the next agent nothing. A brain whose
-base is untouched is a brain that starts every session from zero.
-
-**Offer once, at the natural moment** — right after `init`, or the first time
-`resurface` marks one `not filled in yet`.
-
-```
-memgineering onboard
-```
-
-Says which of the five are still untouched and what to ask for each. Run it
-first rather than working from the list below; it knows what has already been
-done, and asking somebody a question they have answered is its own kind of
-forgetting. Then follow their answers rather than the script.
-
-They may also ask for it outright — "set up my memory", "fill in my profile",
-"내 정보 채워줘". Same job, and it is the only entry point that works when you
-did not offer.
-
-```
-01_BASE/USER.md            who they are, what they work on, what they are trying to do
-01_BASE/PREFERENCES.md     how they like answers, code, decisions — length, tone, how much checking in
-01_BASE/BOUNDARIES.md      what you must ask before doing. The one they will regret not saying
-01_BASE/CRITICAL_FACTS.md  what is expensive to get wrong — deploy, money, data, people
-01_BASE/TOOLING.md         editors, languages, machines, the commands they actually run
-```
-
-**How to ask.** One question at a time, in their words, and stop when the
-answers thin out — three good lines beat a filled-in template. Take what they
-say in passing during ordinary work too; most of `TOOLING.md` gets written by
-noticing, not by asking.
-
-**How to write it — both halves.** `revise` only touches frontmatter, so it
-takes two steps, and skipping the first is the common failure: write the body
-with your normal file tools FIRST, replacing `init`'s instructions with what
-they actually said, then record the conclusion.
-
-```
-# 1. replace the body — their words, not the template's prompt
-# 2. then:
-memgineering revise 01_BASE/USER.md \
-  --action reinforce \
-  --claim "<one line: who they are>" \
-  --summary "<the line recall should show>"
-```
-
-A claim written above the untouched template leaves the file reading as a form
-somebody half-filled — the conclusion in the frontmatter, the instructions for
-writing one still underneath. `revise` warns when you do this; the warning means
-go back and write the body.
-
-`--action reinforce`, not the default, and the reason is the date. `supersede`
-stamps `valid_from` with now because a replaced conclusion starts now — but
-these facts were always true and you have only just been told them. Dating them
-today is wrong in the one field a memory store exists to get right.
-
-This is the ONE place you edit a brain file directly, and the boundary is
-narrow: `01_BASE/` only, and only while the file is still the template `init`
-wrote. Nothing is lost — there is no history to break and nothing to undo — and
-after that first pass these files are theirs like any other note, changed
-through `revise` and never behind their back.
-
-**What not to do.** Do not invent an answer to move on, and do not fill a file
-because it is empty. `BOUNDARIES.md` guessed at is worse than blank: the next
-agent will read it as something the user said.
-
-## Deciding which one to trust
-
-When two memories disagree, or one looks old enough to doubt, do not settle it
-by date.
-
-```
-memgineering evidence deploy-manual
-```
-
-```
-  surfaced       34×  (12× in this folder, 22× elsewhere)
-  opened         12×  (35% of the recalls that surfaced it)
-  last used      3 days ago
-  in the ledger  since 2026-05-02  ·  changed 2×
-
-**well-used** — it has been reached for and read. The record backs it.
-
-why it last changed:
-> CD was removed from the repo
-```
-
-**Newer does not win.** A rule that has stood for eleven months has eleven
-months of nobody contradicting it behind it; a note written last week has a
-week. What separates them is whether either was ever actually used, and what
-the last person to change their mind said. Both are in the output above.
-
-Three standings, and each is a fact rather than a grade:
-
-- **well-used** — recall returned it and somebody read it
-- **surfaced, never opened** — it keeps coming back and nobody reads it. Either
-  it does not answer those questions, or its summary does not say what it knows
-- **never recalled** — nothing has ever surfaced it. It may be perfectly true
-  and simply never needed, but nothing supports it either
-
-If it says this machine has no recall history, the numbers mean nothing yet —
-that log is local, so a brain synced to a new laptop starts empty. Say that
-rather than reporting the memory as unused.
-
-## Writing things down
-
-```
-memgineering remember "deploys are manual — launchctl by hand, no CD" \
-  --reason "watched the deploy happen by hand twice"
-```
-
-Lands immediately as its own note and is recallable at once. There is no
-approval queue: the design trades permission-before for correction-after, and
-every write records how to reverse it.
-
-**Pass `--reason` on every write.** It goes in the ledger, and it is the only
-part of the record that survives being read six months later by somebody — the
-user, or you in a new session — who no longer remembers the conversation. Every
-write verb takes it: `remember`, `revise`, `retire`, `exclude`, `undo`. The one
-on `undo` is usually the most valuable of all, because it is the moment an
-earlier conclusion turned out to be wrong.
-
-It is refused if it looks like it contains a credential. The ledger travels
-with the brain, so that would be a permanent synced copy — say what changed
-without the value, or drop the flag; the write itself is unaffected.
-
-```
-memgineering undo --reason "that belonged to the other project"   # the last change
-memgineering undo <op_id>      # a specific one
-memgineering log               # what changed, why, and what can still be undone
-```
-
-Write down: decisions and their reasons, constraints, corrections the user
-made to you, how something actually works once you found out. Skip: things
-true only inside this conversation, and anything they said they did not want
-kept.
-
-**Recall first, then decide which verb.** If what you just learned answers a
-note that is already there — the vague one, the one that says "nobody wrote
-this down" — `revise` it instead. `remember` would leave two current notes on
-the same subject and the next recall would return both, which is the
-re-discovery problem the user was trying to end. New subject → `remember`.
-Existing subject, now settled → `revise`.
-
-### Changing a conclusion
-
-```
-memgineering revise deploy-manual \
-  --claim "Deploying is manual — pushing to main does nothing." \
-  --summary "manual only, no CD"
-```
-
-- `--action supersede` (default) — the conclusion CHANGED. Stamps `valid_from`
-  with now, because a replaced conclusion starts now.
-- `--action reinforce` — the SAME conclusion, new support. Leaves `valid_from`
-  alone. Use it when nothing about the fact changed, only your evidence.
-- `--action conflict` — two notes DISAGREE. Records the edge, leaves both
-  standing, and deliberately does not write the claim you passed.
-- `--dry-run` shows the diff and writes nothing
-
-Pick by what changed, not by habit: `supersede` on a fact that was true all
-along dates it from today, and the date is the field this is all for.
-
-**Re-recording something unchanged is refused.** If the claim, summary and title
-all match what the note already holds, `revise` writes nothing and says so —
-otherwise a user repeating themselves turns into ledger entries that record no
-change. When you do mean "this still holds", say what confirms it:
-`--action reinforce --reason "<what confirms it>"`. Check with `open <ref>`
-before rewriting something you may already have.
-
-This only ever rewrites the memory block in a note's frontmatter. The prose is
-the user's; neither this command nor you should rewrite it uninvited.
-
-### Retiring versus excluding
-
-```
-memgineering retire <ref> --reason "the date moved"   # no longer current, still visible
-memgineering exclude path/to/note.md --reason "names an internal host"   # stop reading it
-```
-
-Retiring keeps the note in recall, ranked last and labelled. Excluding takes it
-out of the index and never touches the file. If the user says "delete", ask
-which they mean — they are different, and guessing picks one.
-
-## Starting a session
-
-```
-memgineering resurface
-```
-
-No query. It ranks by what has been recalled in this folder before, how
-recently, and which of the user's base notes have gone unread — the things you
-should already know here before they have to tell you again.
-
-## What to raise with the user
-
-The tool does not ask; you decide. Say something, once and plainly, when:
-
-- the output marks the target `⚠ critical target` — that is `01_BASE/`, the
-  files defining who they are and what you may do
-- you are about to record something said in passing that may be sensitive
-- what you learned contradicts a memory currently marked current
-
-Everything else: do it, and mention it in a sentence.
+The tool does not gate writes; your judgement does. Tell them, plainly and
+once, when the change touches `01_BASE/` (the output marks these
+`⚠ critical target`), when you are recording something said in passing they may
+not want kept, or when what you learned contradicts a memory marked current.
+Everything else: write it and mention it in a sentence.
 
 ## Rules
 
 - **Never edit brain files with Read/Write/Edit.** Only the CLI records the
-  change and keeps `undo` working; a hand edit is invisible to both.
+  change and keeps `undo` working; a hand edit is invisible to both. The one
+  narrow exception — first-pass `01_BASE/` bodies — is in `memgineering-writing`.
 - **Never invent a handle or id.** They come from `recall`, `resurface`, `open`.
+- **Nothing matched is a real answer.** Say the brain has nothing on it rather
+  than filling the gap with a guess.
 - **Store full ids, not short handles**, anywhere durable — your own memory, a
   document, a ticket. `open` prints the full `id:` for exactly this.
 - **`--json`** when you need to parse rather than read.
-- **Several brains** (personal, team, a repo's own) resolve by where you are.
+- **Several brains** (one of their own, a shared one, one per project) resolve by where you are.
   If a command says the choice is ambiguous, pass `--vault <path>` — or bind
   the directory once with `memgineering use <brain>`.
 
-## Getting connected
-
-```
-memgineering link ~/Documents/Notes      # notes they already keep
-memgineering init ~/brain                # nothing yet — creates the layout
-```
-
-`link` shows exactly what would be stored and asks first; run it in a terminal
-the user can see, and let them answer. Do not pass `--yes` on their behalf.
-
-With no terminal attached it says so instead of assuming the answer was no.
-Show them `memgineering link <path> --dry-run` — same disclosure, writes
-nothing — and run with `--yes` only once they have actually said yes.
+If a command answers `no brain is linked yet`, that is `memgineering-setup`.

package/assets/memgineering-recall/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: memgineering-recall
+description: Use when answering anything that sounds already settled — a past decision, the user's setup, their preferences, why something is the way it is — or when starting work in a folder and you need to know what you are missing. Also when two memories disagree and you have to decide which to trust. Triggers include "what did I decide about X", "how do we do this again", "check my notes", "is this still true", "which one do I go with", "where were we", "what should I know", "why did we do it this way", "how far did we get". Covers recall, open, evidence, resurface, and how much depth to ask for.
+type: skill
+allowed-tools: Bash(memgineering:*)
+---
+
+# Reading the user's brain
+
+Writing is `memgineering-writing`; decisions that bind you are
+`memgineering-rules`.
+
+## Recall, then open what matters
+
+```
+memgineering recall "what did we decide about the schedule"
+```
+
+```
+## recall: what did we decide about the schedule  (2 cards)
+
+### 1. Fridays are for review, not new work
+a standing decision · stated
+
+> nothing new goes out on a Friday — the day is for checking what already did
+
+`open: friday-review`
+```
+
+The output is already shaped for your context — paste it in rather than
+reformatting it into prose.
+
+**But read it before you use it.** These are candidates ranked by relevance, not
+a list of answers: anything matching a word from the query comes back, so the
+tail can be only loosely related. That is deliberate — failing to return a note
+someone knows is there is worse than returning one they can ignore. Use the top
+matches that actually answer the question; quoting all of them back as if each
+were relevant is how a useful recall turns into noise.
+
+**`a standing decision` is not decoration.** That card is a decision the user
+made, not an observation you are free to weigh against your own judgement — the
+same thing `memgineering rules` lists and the before-edit hook delivers. If what
+you are about to do goes against one, say so in a sentence rather than quietly
+doing either. In `--json` it is the `binding` field, present and `false` on an
+ordinary memory so you can tell "not a rule" from "this version does not say".
+See `memgineering-rules`.
+
+**A question asked as a sentence matches loosely.** Search is text over titles,
+aliases and summaries, so a whole-sentence query can come back matching one
+ordinary word in it, and every card will still read `stated` — that word is
+about who wrote the fields, never about whether the card answers you. Recall
+says so under the results when the query is a question or four words or more.
+Prefer fewer, more specific words.
+
+```
+memgineering open friday-review                    # the claims behind the card
+memgineering open friday-review --section why       # one section
+memgineering open friday-review --detail full       # the whole note
+```
+
+`open` takes a handle, a full id, a path inside the brain, or a note's exact
+title — so when you already know what you want, skip the recall.
+
+| depth              | what you get                                    |
+| ------------------ | ----------------------------------------------- |
+| `--detail card`    | title + summary (default)                       |
+| `--detail summary` | + the note's headings                           |
+| `--detail chunks`  | + every section, or one with `--section <name>` |
+| `--detail full`    | the whole note                                  |
+
+`memgineering recall "the schedule" --limit 1 --detail full` is "find the best match
+and read it" in one call.
+
+## Two answers that are answers
+
+**Nothing matched.** Say so. Only titles, aliases and summaries are searched, so
+suggest broader words — but do not go read their folder yourself to compensate.
+A brain that answers "nothing" is giving you real information.
+
+**Cards that are not answers.** A card marked `not filled in yet` is one of the
+five `01_BASE/` files, still byte-for-byte what `init` wrote. Nobody has answered
+it, so it is evidence of nothing — do not quote it back as what they think. When
+every card carries that mark, recall says so above them (`--json`:
+`scaffolding: true`), and that is the moment to offer to fill them in rather
+than answer from them — see `memgineering-writing`.
+
+The mark disappears once the user writes in the file. A filled-in base note is
+often the best answer in the brain: _who am I_, _what am I not allowed to do_,
+_where does everything live_ all live in `01_BASE/`.
+
+## Starting a session
+
+```
+memgineering resurface
+```
+
+No query. Ranks by what has been recalled in this folder before, how recently,
+and which base notes have gone unread — what you should already know here before
+they have to tell you again. It is the answer to a vague opening that recall
+cannot serve, because there is nothing to search for yet.
+
+## Deciding which one to trust
+
+```
+memgineering evidence friday-review
+```
+
+```
+  surfaced       34×  (12× in this folder, 22× elsewhere)
+  opened         12×  (35% of the recalls that surfaced it)
+  last used      3 days ago
+  in the ledger  since 2026-05-02  ·  changed 2×
+
+**well-used** — it has been reached for and read. The record backs it.
+why it last changed:
+> the team stopped working Fridays entirely
+```
+
+**Newer does not win.** A rule that has stood eleven months has eleven months of
+nobody contradicting it; a note written last week has a week. What separates
+them is whether either was ever actually used, and what the last person to change
+their mind said — both are in that output.
+
+Three standings, each a fact rather than a grade:
+
+- **well-used** — recall returned it and somebody read it
+- **surfaced, never opened** — it keeps coming back and nobody reads it. Either
+  it does not answer those questions, or its summary does not say what it knows
+- **never recalled** — nothing has surfaced it. It may be true and simply never
+  needed, but nothing supports it either
+
+If it says this machine has no recall history, the numbers mean nothing yet —
+that log is local, so a brain synced to a new laptop starts empty. Say that
+rather than reporting the memory as unused.
+
+## Rules
+
+- **Never invent a handle or id.** They come from `recall`, `resurface`, `open`.
+- **`--json`** when you need to parse rather than read.
+- **Several brains** resolve by where you are. If a command says the choice is
+  ambiguous, pass `--vault <path>` — or bind the directory with
+  `memgineering use <brain>`.

package/assets/memgineering-rules/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: memgineering-rules
+description: Use when the user settles something they expect to hold next time — a colour they will not use, a step never to skip, a way things get named here — or when you want to see what already binds you in this folder. A decision does not have to be announced as a rule to be one. Triggers include "from now on", "always", "never", "don't do that again", "let's go with X from here", "we always do it this way", "what rules do I have". Covers remember --rule, rules, and what the before-edit hook shows.
+type: skill
+allowed-tools: Bash(memgineering:*)
+---
+
+# Decisions that bind, not facts that inform
+
+Most of a brain answers a question. A few entries do not: they say what to do
+and what never to do, and they are only worth anything if they arrive before
+the thing they govern.
+
+## Why this exists
+
+Measured twice, on a real brain. A session was handed the user's recorded
+decision — stated plainly, with the specifics included — at session start, and
+produced work that contradicted it. Adding a stronger instruction to that
+session-start summary made the next run **worse**, not better.
+
+The wording was not the lever. The choice a rule governs is not made when a
+session starts; it is made when a file is written, several hundred turns of
+context later, by which point the opening summary is the oldest thing in the
+window.
+
+So a memory can now say that it **binds**, and those are put in front of
+whichever agent is working in that folder the first time it goes near a file
+that session — once, capped, silent for the rest.
+
+## Marking a decision
+
+```
+memgineering remember "no new work goes out on a Friday" --rule \
+  --reason "they have said it twice and it keeps getting missed"
+```
+
+`--rule` is what separates a decision from an observation. Everything else
+about the write is unchanged — same note, same ledger, same `undo`.
+
+**The user does not have to say the word "rule".** "from now on", "always",
+"never", "let's go with this", "we always do it this way" — that is a
+decision. Record it as one and say in a sentence that you did.
+
+**What is NOT a rule.** "The review usually takes an hour" is a fact, however true,
+and belongs in an ordinary `memgineering remember`. So does anything that only
+holds for the current task. Look at what widens or narrows the scope: "never",
+"always", "whenever" widen; "this time", "for now" narrow. If you are unsure,
+it is not a rule — an ordinary memory is still recallable, and a wrong rule
+spends a slot that something else needed.
+
+## Seeing what binds
+
+```
+memgineering rules
+```
+
+The standing decisions for this brain, strongest first, and nothing else. A
+zero-result answer says how to add one rather than printing nothing.
+
+A hosted brain answers this too, and `--rule` writes to one land marked. The
+marking lives in the note's own frontmatter either way, so a brain that was
+pushed from a folder keeps every rule it had.
+
+One difference is worth knowing rather than discovering. The before-edit hook
+reads a brain **on this machine**, so on a machine pointed at a hosted brain it
+shows the local folder's rules, not the hosted brain's — a network call on the
+path of every file write is not a trade this makes. `memgineering rules` shows
+whichever brain the machine is pointed at; add `--local` to see what the hook
+will actually deliver.
+
+## What the user's agent actually sees
+
+With the hooks installed (`memgineering setup` — Claude Code and Codex; see
+`memgineering-setup`), the first time a session touches a file in a folder with
+a brain, it receives the rules and one line of instruction:
+
+> Decisions this user has already made. They are theirs, not suggestions, and
+> they hold whether or not this task mentions them:
+> …
+> Follow them. If what you are about to do goes against one, say so in a
+> sentence instead of doing it quietly.
+
+**That last line is the job.** Following a rule silently is the easy half. When
+what the user just asked for goes against one of their own earlier decisions,
+say so in a sentence and let them choose — do not quietly obey either one.
+
+It never blocks an edit, never answers whether an edit is allowed, and never
+speaks twice in a session. Tools without hooks get nothing automatic here; on
+those, run `memgineering rules` yourself when you start work in a folder.
+
+## Eight, and why the number matters
+
+The list handed to an agent is **capped at eight**. This is a budget, not a
+technical limit: it arrives inside somebody's real task, and the failure this
+whole mechanism answers was an agent ignoring five cards at session start. A
+wall of thirty rules is the same failure with a bigger wall.
+
+So when a brain has more than eight, the output says how many were left out and
+points at `memgineering retire` rather than truncating in silence. The answer to
+a long list is fewer rules, not a longer one.
+
+Two consequences worth knowing before you mark things:
+
+- **Global habits crowd out project decisions.** A rule that has been recalled
+  in other folders outranks a project rule written yesterday that nobody has
+  reached for. If a user's own working preferences fill all eight slots, a new
+  a rule written for the folder they are in may never be shown. Keep the
+  standing set small.
+- **A retired rule stops being shown.** `memgineering retire <ref>` is the way
+  out when a decision no longer holds — it stays visible in recall, ranked last
+  and labelled, but it stops binding.