memgineering 0.23.1 → 0.25.0

package/CHANGELOG.md

@@ -11,6 +11,144 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.25.0] — 2026-10-04
+
+### Added
+
+- **Hosted recall says which search found each card.** Every card carries
+  `matched` (`words`, `meaning` or `both`), and a card found by meaning alone is
+  marked "matched by meaning only — none of the question's words are in this
+  note", in the terminal and in `brain_recall` alike.
+- **Hosted brains label untouched starter templates too.** `recall` and `open`
+  say "not filled in yet" for a `01_BASE/` file that is still exactly the
+  template, as folder brains always did (`scaffolding` in `--json`).
+- **`recall` says when one project filled the whole answer** — "All 8 cards are
+  from `owner/beta`. Also in this brain: `owner/alpha` — add `--scope <name>`"
+  (`scope_spread` in `--json`). Declared scopes only; folder names are not
+  projects.
+- **`setup --help` says how a chat app reaches your brain** — ChatGPT, Claude.ai,
+  Claude Desktop and Cowork connect to a hosted brain at
+  `https://mcp.memgineering.com/mcp`, with no install on this machine.
+- **`remember` shows the scope it stamped and where it came from** — the git
+  remote, the folder's name, `--scope`, or a name set with `memgineering
+  project` (`scope_via` in `--json`).
+
+### Changed
+
+- **Common English words no longer count as a match.** `i`, `is`, `what`,
+  `about`, `do` and the like used to match first-person starter notes whatever
+  the question was about. Recall now matches on the words that carry the
+  question; Korean queries are unchanged, and a question made only of such
+  words ("who am I") still works.
+- **At most two untouched starter templates per recall.** The rest are counted
+  and named as left out (`templates_withheld`); nothing you wrote is ever held
+  back. A mixed answer now says how many of its cards are still templates.
+- **`resurface` ranks by what you opened and what answered, not by what was
+  merely listed.** A card that trailed at the bottom of many recalls no longer
+  climbs the page; the reason line reads "opened 2× · surfaced 10× in this
+  project" or "…, never opened".
+- **`auto-update: on` now installs.** Once a day, when a newer version exists,
+  a global install updates itself in the background — never from a session hook,
+  never under CI, and never a project-local or npx copy (a project under a broad
+  npm prefix such as `prefix=$HOME` counts as project-local). One install runs
+  at a time: `memgineering update` typed while a background install runs says
+  so (`update_in_progress` in `--json`) instead of starting a second. A failed
+  attempt is reported on the next run with how to turn it off.
+- **The setup reminder informs instead of ordering, and is shorter after the
+  first time.** It says what `setup --web` does — opens a setup screen in the
+  user's browser and returns at once — and asks the agent to check with the user
+  first unless they asked for setup. The old wording told the agent to run setup
+  without waiting, which fresh agent sessions reasonably read as a prompt
+  injection. The full text appears once per machine; every later command, and
+  `--version` / `--help` in a pipe, get two lines. The notice after an upgrade
+  ("the guidance in your agent tools is older") and the one asking for a brain
+  follow suit. The upgrade notice now says what a refresh overwrites and which
+  earlier choices a flag-less run would reset — auto-update, hooks, the tool list,
+  and a sign-in on a machine that is not signed in — names the flag that keeps
+  each, and no longer tells the agent to keep the refresh from you.
+
+### Fixed
+
+- **A note whose path is `constructor`, `toString` or `__proto__` no longer
+  breaks `recall` and `open`.** On a hosted brain, every recall that returned
+  such a note failed.
+- **`setup` reports what happened, not what was asked for**: "Registered with"
+  lists only tools whose guide was written, each hook is reported on the tools
+  that received it (Grok's end-of-turn hook is no longer described as a
+  session-start one), and a project-local copy is told its hooks and guide need
+  a global install to reach it.
+- **`setup`'s refusals say how to get unstuck**: an unknown tool name and a
+  known tool that has not been opened yet get different answers, and the
+  supported tools are listed with their `--tools` names.
+
+### Agent guidance
+
+- The setup skill now says a chat app with no shell can reach your hosted brain
+  through the connector at `https://mcp.memgineering.com/mcp` (ChatGPT and
+  Claude.ai steps included) — it used to say there was no connector — and that a
+  brain kept only as a folder needs both steps: move it up, then add the
+  connector. The hub itself now says ChatGPT and Claude.ai reach a hosted brain
+  through that connector.
+- The recall skill covers the template cap, `matched`, `scope_spread`, and the
+  new resurface wording; the writing skill names the folder-name scope fallback;
+  the setup skill explains what auto-update does and to pass `--hook` when
+  turning it off.
+- Restart your agent session after upgrading so it reads the new guidance.
+
+## [0.24.0] — 2026-09-12
+
+### Added
+
+- **`memgineering rescope <ref>` changes which project a memory binds in.**
+  `scope` decides which of the two rule budgets a decision is drawn from — it
+  is the field that answers "does this bind me here" — and nothing could write
+  it. Moving one meant `supersede`, which retires the loser, so folding a
+  project-scoped rule into an unscoped one would have made the rule vanish
+  everywhere except the project it was scoped to.
+  Two flags, deliberately: `--scope <project>` narrows or moves,`--global`
+  widens. A rule that stops naming a project starts binding in every project,
+  and that is the change hardest to notice afterwards, so it is spelled rather
+  than being what happens when the scope is left off.
+- **`memgineering expire <ref> --until <date>` gives a memory an end date, and
+  does not retire it.** Until that date it is current; after it, recall still
+  returns it — one step below what is current, and labelled. Recall has always
+  understood this; only the writer was missing. Reach for it when a memory was
+  always going to run out, rather than when a decision has been overtaken.
+- **A hosted brain's rule list says how fresh each rule is** (`freshness` on
+  `POST /rules`), so an agent handed a rule whose end date has passed is told
+  so rather than reading it as current.
+
+### Fixed
+
+- **Retiring a rule now stops it being pushed to agents on a hosted brain.**
+  The rule list filtered "is it marked as a rule" and nothing else, while the
+  local one has always dropped retired rules — putting a decision somebody
+  retired in front of an agent as binding is the tool arguing with them.
+  `retire` writes the status and leaves the marking alone, so nothing else
+  caught it: on a hosted brain, which is what a signed-in machine reads,
+  retiring a rule did not stop the before-edit hook showing it.
+- **A date written into a note that states no claim is no longer ignored.**
+  Freshness read `valid_until` only off a stated claim, and most notes state
+  none — so an end date in such a note was read by nothing at all.
+- **An upgrade now tells your agent that its guidance went stale.** The only
+  thing that ever said so was a `postinstall` script, and npm 12 blocks install
+  scripts by default — measured on 12.0.2, all it prints is `1 package had
+  install scripts blocked`, which does not say what the blocked script would
+  have said. So on that npm an upgrade left a new binary beside the hub and
+  skills an older release wrote, in `~/.claude`, `~/.codex` and `~/.gemini`,
+  and both halves reported success. The CLI now says it itself, before any
+  command, on a channel npm cannot block: run `memgineering setup` once and it
+  goes quiet. It stays out of `guard`, which runs on every file edit.
+
+### Agent guidance
+
+`memgineering-rules` and `memgineering-writing` both changed: there are now
+three ways a rule stops applying rather than two (`--no-rule`, `retire`,
+`expire`), and `rescope` is how a rule moves between projects. **Restart your
+agent session after upgrading** so the new guidance is loaded — or run
+`memgineering setup`, which the CLI will now ask for by itself when the
+installed guidance is older than the binary.
+
 ## [0.23.1] — 2026-09-11
 
 ### Fixed

package/assets/MEMGINEERING.md

@@ -2,7 +2,7 @@
 name: memgineering
 description: Use whenever the user refers to something they told you before, asks what was decided, tells you something worth keeping, or settles something that should hold next time. The memory lives in their own folder and outlives this session; check it before answering from guesswork, and write to it when you learn something durable.
 type: skill
-version: 0.23.1
+version: 0.25.0
 ---
 
 # memgineering
@@ -83,6 +83,8 @@ at six skills, each of which loads on its own when its topic comes up:
 - `memgineering-registry` — the public layer
 - `memgineering-installing` — putting a package in their project, and updating it
 
+Not shell-only: ChatGPT and Claude.ai reach a hosted brain via connector `https://mcp.memgineering.com/mcp`.
+
 A host short on room lists a skill by NAME ONLY, no description — measured on
 Claude Code. When you cannot see what it covers, READ
 `<tool-home>/skills/memgineering-<name>/SKILL.md` before deciding it is empty.

package/assets/memgineering-recall/SKILL.md

@@ -153,6 +153,11 @@ What you must not do is report what came back as everything the brain holds,
 which is exactly what a short answer looks like to anyone who does not read the
 line under it.
 
+When every card with a project came from ONE project and the brain holds
+others, recall says so (`scope_spread`: the project, and up to five others). If
+the user meant one of those, ask again with `--scope <that project>` — the note
+they want may be ranked just below a page full of the one the question named.
+
 ## Whether meaning was searched
 
 A hosted brain can match on meaning as well as words — the same idea in other
@@ -177,6 +182,12 @@ anything about what the user knows.
 If coverage says notes are missing entries, meaning was searched over part of
 the brain. Do not report that as a complete search.
 
+When meaning was used, each card also says what reached it — `matched`:
+`"words"`, `"meaning"`, or `"both"`. A `"meaning"` card (printed as _matched by
+meaning only_) shares no word with the question. That is right for a note in
+another language and wrong for one the model merely found nearby, so read its
+summary before you answer from it — never quote it back on the label alone.
+
 ## Two answers that are answers
 
 **Nothing matched.** Say so, and do not go read their folder yourself to
@@ -198,7 +209,9 @@ five `01_BASE/` files, still byte-for-byte what `init` wrote. Nobody has answere
 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`.
+than answer from them — see `memgineering-writing`. At most two such cards come
+back per answer; the rest are counted (`templates_withheld`), never silently
+dropped, and nothing anyone wrote is ever held back.
 
 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_,
@@ -219,8 +232,11 @@ On a hosted brain the folder counts too, as a name rather than a path: the CLI
 sends the folder's project — `owner/repo` from the git remote, or whatever
 `memgineering project` shows — and the server ranks what was asked about in
 that project first. The response says so itself: `ranked_by` gains `asked about
-in this project`, a card's reason reads `recalled 2× in this project`, and the
-footer names which project those words mean. Trust the footer over your
+in this project`, a card's reason reads `opened 1× · surfaced 2× in this project`
+(or `surfaced 2× …, never opened`), and the footer names which project those
+words mean. Only an open, or being the FIRST card of a recall, counts toward
+the order; a card merely listed further down is counted in words but earns
+nothing. Trust the footer over your
 assumption in the other cases as well — it says when this folder names no
 project (nothing was sent), and when the server does not rank by project yet
 (it was sent and ignored). A path never leaves the machine either way.

package/assets/memgineering-rules/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+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" — and, for moving one, "that should apply everywhere", "not just this project", "all my projects", "only in this repo from now on". Covers remember --rule, rules, rescope, and what the before-edit hook shows.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -150,12 +150,23 @@ Two consequences worth knowing before you mark things:
   are why they no longer can: a rule scoped to the project has its own room and
   cannot lose every slot to whatever the user has been reaching for lately. It
   still pays to keep the standing set small — ten is what a session reads.
-- **Two ways out, and they are not the same.** `memgineering revise <ref>
+- **Three ways out, and they are not the same.** `memgineering revise <ref>
 --no-rule --reason "…"` says it was never a rule: it stops being shown before
   an edit, and stays a perfectly ordinary current memory that recall returns.
   `memgineering retire <ref>` says it no longer holds: it stops binding AND
-  drops to the bottom of recall, labelled. Reach for the first when the marking
-  was the mistake and the second when the decision has been overtaken.
+  drops to the bottom of recall, labelled. `memgineering expire <ref> --until
+<date>` says it held until then: it KEEPS binding and recall keeps returning
+  it, ranked below what is current and labelled from that date. Reach for the
+  first when the marking was the mistake, the second when the decision has been
+  overtaken, and the third when it was always going to run out.
+- **`memgineering rescope <ref>` changes WHERE a rule binds, not whether it
+  does.** `--scope <project>` binds it in that project alone — agents working
+  anywhere else stop being shown it. `--global` binds it everywhere, which is
+  the change hardest to notice afterwards, so it has a flag of its own rather
+  than being what happens when you leave the scope off. Nothing the note says
+  changes either way, and `memgineering undo` reverses it.
+  Ask before widening: a rule the user wrote about one repository, made global,
+  arrives in every session they open.
 - **`--no-rule` on its own asks for nothing else.** No claim, no summary — the
   conclusion, the summary and the title come back byte for byte, which is the
   whole reason it exists. It used to go through `revise`, which requires a

package/assets/memgineering-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-setup
-description: Use when installing or configuring memgineering, when moving a brain between a machine and an account, when renaming or deleting a hosted brain, or whenever the user asks WHICH of their AI tools can see this memory. Triggers include "set up memgineering", "connect my notes", "rename my brain", "delete that brain", "does my other AI see this too", "which of my tools can read this", "will it work in the app on my phone", "no brain is linked".
+description: Use when installing or configuring memgineering, when moving a brain between a machine and an account, when renaming or deleting a hosted brain, or whenever the user asks WHICH of their AI tools can see this memory. Triggers include "set up memgineering", "connect my notes", "rename my brain", "delete that brain", "does my other AI see this too", "which of my tools can read this", "will it work in the app on my phone", "can I use this in ChatGPT", "does it work in Claude.ai", "no brain is linked".
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -12,20 +12,37 @@ allowed-tools: Bash(memgineering:*)
 Answer this from here, not from a guess. The line is capability, not brand, so
 it does not move as products come and go:
 
-|                                           |                                                                                                               |
-| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
-| **Any tool that can run a shell command** | Reads and writes the same brain. Nothing has to be built for a tool that does not exist yet.                  |
-| **Any tool that cannot**                  | **Not yet.** There is no connector. A hosted brain is reachable in principle and is not wired up in practice. |
+|                                                              |                                                                                                                                                                                  |
+| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Any tool that can run a shell command**                    | Reads and writes the same brain. Nothing has to be built for a tool that does not exist yet.                                                                                     |
+| **A chat app that takes a custom MCP connector, no shell**   | Reads and writes the **hosted** brain on their account through `https://mcp.memgineering.com/mcp`, once they add that connector in the app and sign in with Google. Not a folder brain. |
+| **Neither**                                                  | **Not yet.**                                                                                                                                                                     |
 
 `memgineering setup` writes its guidance into the agent tools it finds on the
 machine, and `setup --dry-run` names the ones it actually found rather than
 guessing from a list.
 
 So when someone names a tool and asks whether it remembers too, work it out from
-that line and answer **not yet, and here is what does** — not a hedge, not a
-promise. "You are signed in, so it works everywhere" is the specific wrong
-answer: the account syncs the brain between machines, it does not add a surface
-that can read it.
+those rows and answer plainly — not a hedge, not a promise:
+
+- **ChatGPT** — Settings → **Developer mode** → add an MCP server with
+  `https://mcp.memgineering.com/mcp`, then sign in with Google when it asks.
+- **Claude.ai, Claude Desktop, Cowork** — **Customize** → **Connectors** →
+  **Add custom connector** → the same URL. One connector covers all three, and
+  custom connectors are on every plan, the free one included.
+- It reaches the brain **on their account**. A brain that lives only as a folder
+  on this machine is out of its reach until it is moved up (see "Moving a brain
+  between this machine and their account").
+- Moving it up does NOT make it appear in the chat app by itself. When their
+  brain is still a folder, the answer is both steps, in order: move it up, then
+  add the connector above in their app. An answer that stops at the first step
+  leaves them with an account brain and no way in.
+- `npx memgineering-mcp` — the local, stdio server — is **registry-only**. It has
+  no memory tools; for memory from a chat app, the URL above is the way.
+
+"You are signed in here, so it works everywhere" is still the wrong answer: the
+account syncs the brain between machines, and each chat app needs the connector
+added in that app, once.
 
 ## 1. Register with the agents
 
@@ -93,8 +110,15 @@ restart. (Measured: a fresh agent relayed "restart required" as fact, the user
 checked, and it was not one.)
 
 **Ask before setting policy for them.** Auto-update means the tool updates
-itself; `--hook on` means note summaries and their standing rules reach an agent
-unasked. Recommend both, but they are theirs to decide.
+itself: once a day, when a newer version exists, a global install starts
+`memgineering update` in the background and the next run uses it (a project-local
+or npx copy is never touched — it only gets the notice; nor is anything installed
+from a session hook or under CI). One install runs at a time: `memgineering
+update` run while a background install is going answers `update_in_progress`
+and installs nothing — wait a few minutes and run it again; it reports whether
+that install worked. `--hook on` means note
+summaries and their standing rules reach an agent unasked. Recommend both, but
+they are theirs to decide.
 
 **Error telemetry is theirs to decide too, and defaults to off.** With
 `--error-telemetry on`, the CLI sends an anonymous report when it ITSELF
@@ -441,9 +465,12 @@ as a next step rather than running it.
 
 ### What a hosted brain does that a folder does not
 
-Every verb works on either kind now, consolidation included. Two things are
+Every verb works on either kind now, consolidation included. Three things are
 only true of a hosted brain.
 
+**A chat app with no shell can reach it** — through the connector at the top of
+this file. A folder brain is reached only by tools that can run `memgineering`.
+
 **Meaning is searched, if a model is configured for it.** That is what lets an
 English question reach a Korean note. It needs `BRAIN_EMBEDDING_URL` and
 `BRAIN_EMBEDDING_MODEL` set on the server; with neither, the brain searches text
@@ -475,7 +502,7 @@ answers without changing its name and the index has to be laid down again.
 ## Turning things off
 
 ```
-memgineering setup --agent --auto-update off
+memgineering setup --agent --auto-update off --hook <on|off>   # --agent sets both; keep the hook as it was
 memgineering unlink            # stop reading a brain; notes untouched
 memgineering unlink --purge    # also delete the local index and undo snapshots
 ```

package/assets/memgineering-writing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-writing
-description: Use when you learn something durable and should record it, when a conclusion you already recorded turns out to have changed, when something needs undoing or retiring, when the brain has filled up with near-duplicates that want tidying, or when the user's `01_BASE/` files are still empty and only a conversation can fill them. Triggers include "remember this", "that didn't work", "this worked instead", "that's not right anymore", "undo that", "looks good", "set up my memory", "fill in my profile", "stop reading that note", "clean up my notes", "these two say the same thing", "is this a duplicate", "move my memories over", "bring my notes from the other tool", "don't save that", "never store that". Covers remember, revise, undo, log, retire, exclude, onboard, the consolidate/propose/approve flow, carrying facts in from another store, storage boundaries, and what to say before writing.
+description: Use when you learn something durable and should record it, when a conclusion you already recorded turns out to have changed, when something needs undoing or retiring, when the brain has filled up with near-duplicates that want tidying, or when the user's `01_BASE/` files are still empty and only a conversation can fill them. Triggers include "remember this", "that didn't work", "this worked instead", "that's not right anymore", "undo that", "looks good", "set up my memory", "fill in my profile", "stop reading that note", "clean up my notes", "these two say the same thing", "is this a duplicate", "move my memories over", "bring my notes from the other tool", "don't save that", "never store that", "that's only true until <date>", "it stops being true after", "don't tell me that forever". Covers remember, revise, undo, log, retire, expire, exclude, onboard, the consolidate/propose/approve flow, carrying facts in from another store, storage boundaries, and what to say before writing.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -23,10 +23,13 @@ reverse it. Do not ask permission for ordinary observations — write them, and
 mention it in a sentence.
 
 **A note born in a project folder carries that project as its `scope`** — the
-name comes from the git remote (`owner/repo`), or from the folder's binding
-(`memgineering project` shows it). The stamp is automatic; an explicit
-`--scope` beats it; a folder that names no project writes exactly what it
-always wrote. Two flags are worth reaching for on purpose:
+name comes from the folder's binding (`memgineering project` shows it), else the
+git remote (`owner/repo`), else — in a repository with no remote — the checkout
+folder's name. `remember` prints the scope and which of those it came from
+(`scope_via` in `--json`); when it is the folder name, say so, because that is
+the one nobody predicts. The stamp is automatic; an explicit `--scope` beats it;
+a folder that names no project writes exactly what it always wrote. Two flags
+are worth reaching for on purpose:
 
 ```
 memgineering remember "we always squash before merging" --rule --no-scope \
@@ -203,17 +206,26 @@ it>"`.
 This rewrites only the memory block in frontmatter. The prose is the user's;
 neither the command nor you should rewrite it uninvited.
 
-## Retiring versus excluding
+## Retiring versus expiring versus excluding
 
 ```
 memgineering retire <ref> --reason "the date moved"   # no longer current, still visible
+memgineering expire <ref> --until 2026-10-31 --reason "the phase ends then"  # NOT retired
 memgineering exclude path/to/note.md --reason "it has someone's phone number in it"   # stop reading it
 memgineering retract --actor "mcp:ChatGPT" --since 2026-09-01        # SHOWS what one writer / window wrote
 memgineering retract --actor "mcp:ChatGPT" --since 2026-09-01 --yes  # retires all of it, one ledger row each
 ```
 
 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
+out of the index and never touches the file.
+
+**`expire` is not a retirement, and the difference only shows up later.** It
+gives a memory an end date: until then it is current, and after it recall still
+returns it — one step below what is current, labelled with the date. Reach for
+it when the memory was always going to run out ("Phase 1 lands by the end of
+October", a key that rotates, a plan with a deadline in it) rather than when a
+decision has been overtaken. Retiring such a note says something untrue about
+it; leaving it says something untrue too. If the user says "delete", ask
 which they mean.
 
 ## Tidying up a brain: detect, draft, approve