memgineering 0.24.0 → 0.25.1

package/CHANGELOG.md

@@ -11,6 +11,139 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.25.1] — 2026-10-05
+
+A security release. Upgrade if you use `setup --web`, or a hosted brain with a
+chat-app connector.
+
+### Security
+
+- **`setup --web` no longer switches a machine to another account.** If the
+  setup screen is confirmed by a different account from the one this machine is
+  signed in to, nothing is written and the terminal says why. The setup screen
+  is only told "different account", never who is signed in here.
+- **Notes chosen for upload on the setup screen wait for a check on this
+  machine.** A setup left running in the background uploads nothing. The next
+  command names the folder, the account that would receive it, and the `push`
+  that sends it. That command is quoted, so neither a folder name nor a brain
+  name can run as shell code. A setup in the foreground asks first. A `push` of
+  that folder, or `logout`, clears the notice.
+- **The setup screen can link or upload only a folder this machine offered.**
+  It can create a new local brain only inside the home folder. A relative or
+  `~/` path is read against the home folder and created exactly where it was
+  checked, and symlinks are followed.
+- **`setup --web --json` prints `setup_url` only when no browser opened**, with
+  a hint to use `--print-url` if the browser never appeared. A machine signing
+  in for the first time is told once which account it was connected to.
+- **`login` tells the approval screen when and from what the sign-in came**
+  (`platform`, `client`). Its wording now says that screen asks the person to
+  type the code.
+- **Rules first written through a chat-app connector say so.** `memgineering
+  rules` and the before-edit hook print `(written by the ChatGPT connector)`
+  next to such a rule, and `--json` carries `written_by`. A rule asked for from
+  a chat app is now held as a note until the person promotes it at a terminal.
+  The hold is enforced by the server.
+
+### Fixed
+
+- `revise --rule` with the claim a note already holds makes it a rule. It used
+  to be refused as "already says this", and nothing bound.
+
+### Agent guidance
+
+- `memgineering-setup` explains what the setup link gives whoever holds it, and
+  what happens to an upload chosen on the screen.
+- `memgineering-rules` explains rules held from chat apps. Promoting one binds
+  the note's own text, so read it first with `memgineering open <id> --detail
+  full`; to word it differently, write a new rule with `remember --rule`. It
+  also explains the `written by` label.
+
+Restart the agent session after upgrading so it reads the new guidance.
+
+## [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

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.24.0
+version: 0.25.1
 ---
 
 # 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

@@ -69,6 +69,20 @@ 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.
 
+**A rule saved from a chat app waits for the user.** ChatGPT, Claude.ai and
+other connectors can write notes, but not rules: a rule asked for there is
+kept as an ordinary note, and binds only once the user promotes it at a
+terminal. Promoting binds the note's own text as the chat wrote it — `--claim`
+changes the summary, not the words that bind — so they read it first with
+`memgineering open <id> --detail full` (the card alone shows only the title and
+summary, which a chat app may have rewritten), then `memgineering revise <id> --rule --claim "<what
+the note says>"`. Worded differently, it is a new rule: `memgineering remember
+"<the rule>" --rule`. A connector also cannot change or unmark an existing rule. Once
+promoted, the rule says where its words came from — `(written by the ChatGPT
+connector)` beside it in `memgineering rules` and in the before-edit hook, and
+`written_by` in `--json`. Treat it as their rule; the label says which surface
+it was first said on.
+
 **A rule also wins a tie in `recall` now.** Where an ordinary memory and a
 standing decision matched a query equally well, the decision is ranked first —
 the asymmetry being that a missed fact costs the reader some context, while 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
 
@@ -49,6 +66,17 @@ Three things to do after running it:
    picks it up on its own when they do. There is nothing to poll and nothing
    to wait for.
 
+The link is the key to that screen, not the code: whoever holds the whole link
+can drive it. Give it only to them, never paste it anywhere else — with
+`--json`, `setup_url` is printed only when no browser opened.
+
+If they chose to upload existing notes on the screen, this machine does NOT
+upload them on its own: the next `memgineering` command shows which folder and
+which account would receive them, with the `push` that sends them. Check with
+them that the account is theirs before running it. And a machine already
+signed in to a different account is never switched by `setup --web` — the
+terminal says so; `logout` first if they really mean to switch.
+
 The screen asks everything `--agent` takes from flags — sign in, where the
 memory lives, which brain, which tools, auto-update, the session hook — with
 the recommended answer pre-selected. A person who is already signed in to
@@ -93,8 +121,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 +476,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 +513,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

@@ -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 \