memgineering 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -11,6 +11,236 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+### Added
+
+- **Every command works on a hosted brain.** `revise`, `resurface`, `retire`,
+  `unretire`, `exclude` and `unexclude` used to refuse when this machine was
+  pointed at a hosted brain and tell you to add `--local`. They go to the server
+  now. Nothing memgineering offers says no because your brain is not on this
+  disk.
+
+- **The setup screen starts with where your memory goes.**
+  `memgineering setup --web` used to open a Google sign-in before it showed you
+  anything, so the first thing you saw was a consent page for a product that
+  had not told you what it was. It now opens on the choice — what memgineering is in one
+  sentence, then a plain comparison of keeping the memory on this machine
+  against keeping it in an account, and what each costs. One brain is free, and
+  stays free. The sign-in only starts once you have picked it, and the code to
+  approve is shown on the last screen. Draft terms and a privacy draft are
+  reachable from the same screen; they are marked as drafts because they have
+  not been through legal review.
+
+- **`memgineering pull [folder]`** — download your hosted brain back to this
+  machine, as the markdown it is. Until now notes went up and nothing came back,
+  so "your memory is yours" stopped being demonstrable the moment you used the
+  hosted side. It **never overwrites**: a file already at that path is left
+  exactly as it is and reported as skipped, which is what makes it safe to point
+  at the wrong folder and what makes an interrupted download finishable by
+  running the command again. Notes your rules exclude come down too — excluded
+  means "stop reading this", not "this is no longer yours" — and `.memgignore`
+  travels with them, so the folder does not silently un-exclude anything. The
+  result is plain markdown; `memgineering link <folder>` is what turns it into a
+  brain on this machine, and it is not done for you. `--dry-run` lists what would
+  be written without writing it.
+
+- **`memgineering push`** — upload the brain on this machine to your hosted one,
+  keeping every note at the path it already had. Nothing is deleted locally, a
+  note already up there is counted as already up there rather than as a failure
+  (so an interrupted upload is finished by running the command again), and any
+  note the server refuses is listed in the summary instead of quietly dropped
+  from the count. `--dry-run` lists what would go without sending anything.
+
+### Changed
+
+- **Setup no longer decides about accounts behind your back.** Run by an agent,
+  it skipped sign-in and said nothing — so you got a folder on one machine and
+  found out later that your memory does not follow you. It now says plainly that
+  no account was used and how to connect one, and the install tells your agent to
+  ask you first: memory on this machine, or synced across your devices and tools.
+
+- **After install, your agent finishes the job.** Installing used to print
+  `Next: memgineering setup` — which agents dutifully relayed to their user as a
+  command to type, in a product whose whole premise is that the agent does this
+  for you. The install now tells the agent to ask you one question — should it
+  set things up, or would you rather choose on a screen — and then run setup
+  itself. The message is also no longer suppressed when output is piped, which
+  is exactly the case where an agent is the one reading it.
+
+- **`--local` still does exactly what it did.** The product works with no
+  server: pass `--local` to any command and it reads and writes the folder on
+  this machine, whether or not you are signed in.
+
+- **A hosted `resurface` says what it ranked by.** It has three signals where a
+  local brain has four — it cannot know which folder you asked from, because the
+  server records what was recalled and never where you were standing. The output
+  names the signals it used rather than leaving you to notice that "recalled 14×
+  in this folder" stopped appearing.
+
+- **`revise --input` is refused against a hosted brain**, rather than partly
+  honoured. The JSON can name a different memory and set fields the flags do not
+  expose, so sending only the understood parts would report a success for a
+  change you did not ask for. Pass the change as flags, or use `--local`.
+
+- **What you exclude travels with your brain.** The rules live in a
+  `.memgignore` file inside the brain rather than in a setting beside it, so a
+  hosted brain pulled back down to a folder is still scoped the way you scoped
+  it. `undo` for an exclusion is `unexclude`, not `undo <op_id>`.
+
+- **`memgineering login`, `logout` and `whoami`** — sign in to a hosted brain.
+  Optional, and nothing that already worked needs it: a brain is still a folder
+  of markdown files on your machine, and every other command works on it with no
+  account and no network.
+
+  `login` pairs this machine with an account without a token ever appearing in a
+  browser. It prints a code, opens an approval page, and collects the token
+  itself once you approve — so the credential never lands on a screen, in a
+  scrollback, or in a chat window.
+
+  **Agents should use `login --emit-only`.** It starts the sign-in, opens the
+  browser and returns immediately rather than waiting for a human to click,
+  which no agent's command timeout survives. The next `memgineering` command
+  claims the token automatically. Show the printed code in your reply: the
+  approval page asks the user to check it against what they were shown, and on
+  surfaces where you are the only thing that saw it, they cannot.
+
+  `logout` revokes on the server before forgetting anything locally — a token
+  deleted only here still works for whoever has a copy. `--all` ends every
+  session on the account, `--local` forgets it here when the server is
+  unreachable and says plainly what that does not do.
+
+- **`setup` offers an account as its first step, and lets you walk past it.**
+  Skipping installs byte-for-byte the same files; there is a test that compares
+  the two trees. With no terminal it does nothing unless you pass `--login`, so
+  an agent running `setup --agent` never opens a browser you did not ask for.
+
+- **`MEMGINEERING_API_URL`** points the account commands at a different brain
+  server. The token is stored with the server that minted it and is never sent
+  anywhere else.
+
+- **The `--human` prompt no longer hangs where there is no terminal.** Asking for
+  `--human` says which mode you want; it does not conjure a screen to draw a
+  prompt on.
+
+- **The setup screen no longer promises a sync it does not perform.** Its first
+  screen ticks "the same memory on another machine" for keeping the memory in an
+  account — and choosing that only signed you in. No hosted brain was created and
+  no note was uploaded, so you would have found out on the second machine. The
+  last screen now says the notes are still only on this machine and what changes
+  that; the machine-readable half tells your agent the same thing, and to ask you
+  before sending anything to a server.
+
+- **Two screens no longer ask near-identical questions.** "기억을 어디에
+  둘까요?" (this machine or an account) was followed two screens later by "기억을
+  어디에 담을까요?" (which folder to read). The second is now "어느 폴더를
+  쓸까요?".
+
+- **The screen separates what is kept here from what an upload sends.** It said
+  only a note's title and first paragraph get stored — true of the index on this
+  machine, and read as the whole of what reaches the server by anyone who had
+  just chosen an account. Uploading sends the entire file, and the screen now
+  says so where the claim is made.
+
+- **The privacy draft says notes are stored in plain text.** No end-to-end
+  encryption; whoever runs the server can technically read them, and not doing so
+  is a promise rather than an impossibility. It was the one fact a person
+  weighing whether to put a diary in an account most needs, and the easiest to
+  leave out.
+
+- **The setup screen stopped handing out commands.** It answered three of a
+  non-developer's questions with one — how to stop a note being surfaced, how to
+  update, how to connect a folder — and each answer was a command to type, on the
+  one screen built for somebody who has never opened a terminal. Each is now
+  phrased as something to ask their agent for. A test fails if any
+  `memgineering <verb>` reappears on that page.
+
+- **Folder suggestions say how many notes each one holds.** The list offered
+  every folder containing at least one markdown file, so a photo archive with a
+  stray README sat beside somebody's actual notes with nothing to tell them
+  apart. The count is the reason each row is there, so it is now on the row.
+  Filtering harder was the wrong fix: a folder with one note is still notes.
+
+- **The terms draft lists what it has not decided.** Legal entity and
+  jurisdiction, where the servers are, how long a deletion takes to reach
+  backups, how a breach would be announced, and where to delete an account —
+  absent from the draft, and now absent in writing rather than by omission.
+
+- **`recall` stopped telling Korean users their own Korean notes were
+  unreachable.** When a query found nothing, the footer could claim "this
+  brain's notes are mostly written in English … no rewording in another
+  language will reach them" — in a brain holding Korean notes. Two scaffolding
+  files were voting: `01_BASE/` was already excluded, `00_HUB/` was not, and on
+  a small brain one English note `init` wrote decides the count. A note like
+  `글꼴은 Pretendard 하나로` then votes English on the strength of the product
+  name, and the majority flips. The hub no longer votes, and the warning is
+  suppressed outright when any note somebody wrote is in the asker's script —
+  the claim is about reachability, and one such note makes it false.
+
+  Caught by a fresh-context agent, which read the footer, believed it, and told
+  its user that Korean titles are not searchable. A hint that is wrong does not
+  merely mislead — it stops the tool being used.
+
+- **`resurface` shows what a brain holds before anything has been recalled from
+  it.** It ranked purely on evidence of use — recalled here, recalled anywhere,
+  read lately — and dropped everything that scored zero. A note that had only
+  ever been written scored zero, so a brain nobody had searched yet returned its
+  five untouched `01_BASE/` templates and none of its actual notes, even at
+  `--limit 8`. That is a loop with no way in: a note is not surfaced until it has
+  been recalled, and surfacing is how you find out it exists.
+
+  It runs at session start, so that was an agent's entire first impression of the
+  brain. Measured: one saw five "not filled in yet" placeholders, concluded there
+  was nothing there, and did not call memgineering again for the rest of the
+  session.
+
+  Never-reached notes now rank, below anything with evidence behind them, and
+  untouched templates take at most two of the slots instead of all five. When
+  nothing has been recalled yet the page says so in a line — the order means
+  "what this holds", not "what matters here". Refusing to guess was right;
+  refusing to speak was not.
+
+- **Checking whether you are signed in no longer opens a Google consent page.**
+  The `not_signed_in` hint read "YOU run `memgineering login --emit-only`" with
+  no precondition attached, and agents follow instructions — so an agent that
+  ran `whoami` to orient itself started a sign-in. Measured during testing:
+  three consent windows appeared in a user's browser in a session where nobody
+  had mentioned accounts. `setup` already refused to do this on the grounds that
+  nobody should be sent to a consent screen they did not ask for; the tool held
+  both positions and this one ran more often. The hint now leads with the fact
+  that an account is optional and `--local` is right there, and gates the
+  sign-in on the user having asked for one.
+
+- **`resurface` says what to do with what it just showed.** It printed five
+  cards and stopped, at session start, to a reader that is always an agent. One
+  was handed a note saying this site does not use blue, with the hex codes in
+  the summary, and shipped a page with a blue accent: the memory reached its
+  context and never reached its output. It now closes with three lines — these
+  are the user's own decisions, follow them unasked, recall before answering
+  something already settled, remember what this session decides. Untouched
+  templates also stop explaining themselves at length when real notes share the
+  page; six lines about unfilled files were burying the two that mattered.
+
+- **A hosted brain answers the same way as a local one when nothing has been
+  recalled from it yet** — the notes, plus a line saying the order is what the
+  brain holds rather than what matters here. It used to return an empty list,
+  which reads as an empty brain.
+
+### Agent guidance
+
+- **The hub now says which tools this actually reaches.** A fresh-context test
+  asked an agent to make ChatGPT, Claude and Codex share one memory; it set up
+  the two it could and then had to read the product's source code to find out
+  whether ChatGPT was possible at all. On a machine without that source it
+  would have had to guess. The guidance now states plainly that `setup` covers
+  Claude Code, Codex and Gemini CLI, that anything with a shell works, and that
+  web and phone surfaces have no connector yet — including the specific wrong
+  answer to avoid ("you are signed in, so it works everywhere").
+
+- The bundled guidance changed: the hub now tells your agent to fetch your
+  notes back with `pull` whenever you ask for them, and the setup skill says
+  the account question on the first screen is yours to answer rather than
+  something it should decide or pre-empt. **Restart your agent session after
+  upgrading** — the guidance is read once, when the session starts.
+
 ## [0.4.2] — 2026-08-10
 
 ### Fixed

package/README.md

@@ -7,12 +7,21 @@ Gemini — reads and writes the same brain through one CLI, so what you told one
 of them is there for the next one, tomorrow, and in whatever tool you move to
 after that.
 
+**You do not have to run any of this yourself.** Ask whichever agent you are
+already talking to — "install memgineering and set it up" — and it does the
+whole thing, asking you only what it genuinely cannot decide.
+
+<details>
+<summary>The commands, for the agent (or for you, if you prefer a terminal)</summary>
+
 ```bash
 npm i -g memgineering
-memgineering setup
+memgineering setup --agent              # or --web to choose the settings on a screen
 memgineering link ~/Documents/Notes     # or: memgineering init ~/brain
 ```
 
+</details>
+
 ## What it does
 
 ```bash
@@ -131,6 +140,7 @@ can register it to run automatically when a Claude Code session starts.
 | `init <path>`                       | create a brain, laid out and ready                    |
 | `link <path>`                       | read notes you already keep                           |
 | `use [brain]`                       | bind this folder to one brain                         |
+| `push` · `pull`                     | carry a brain to your account, and back down again    |
 | `unlink` · `reindex` · `sync-rules` | brain housekeeping                                    |
 | `log`                               | what changed, and what can still be undone            |
 | `retire` · `unretire`               | mark a memory no longer current, or current again     |
@@ -148,13 +158,27 @@ Every command takes `--json`.
 | `MEMGINEERING_JSON=1`      | force JSON output without the flag                  |
 | `MEMGINEERING_NO_UPDATE=1` | skip the version check for one run                  |
 
-## What is coming
+## A brain that is not on this machine
+
+A brain can also live in a memgineering account, so the same memory reaches
+every tool and device you sign in from. Nothing about the local path went away —
+`--local` reads the folder on this disk whether or not you are signed in.
+
+```bash
+memgineering push                 # carry this folder up, note by note
+memgineering pull ~/my-brain      # bring it back down, as markdown
+```
+
+The pair is deliberately asymmetric in the same direction: **`push` never
+deletes anything here, and `pull` never overwrites anything here.** A file
+already at that path is left alone and reported, so an interrupted transfer is
+finished by running the command again and a mistyped folder costs you nothing.
 
-**0.2.0 — cloud brains.** Today a brain is a folder on this machine. Next it
-can also live in a memgineering account, so the same memory reaches ChatGPT,
-Claude on the web, and anywhere a browser goes. The local path is not going
-away: what syncs is your originals, your ledger and your rules — never a
-vendor's copy of your notes.
+What `pull` writes is your notes, at the paths they had, including the ones your
+rules exclude — excluded means "stop reading this", not "this is no longer
+yours" — with `.memgignore` alongside them so the scoping survives the trip.
+It is a folder of markdown, not yet a brain: `memgineering link` is what makes
+it one, and it shows you what it would read first.
 
 ## Licence
 

package/assets/MEMGINEERING.md

@@ -12,6 +12,22 @@ use can read and write through the `memgineering` CLI. It outlives this
 session and this tool. Treat it as the place where what they know actually
 lives, and this conversation as temporary.
 
+## Which tools this actually reaches, today
+
+Answer this from here, not from a guess. "Every AI tool" above means every tool
+that can run this CLI — and that is a shorter list than people assume.
+
+|                                              |                                                                                                                       |
+| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| **Claude Code · Codex · Gemini CLI**         | `memgineering setup` installs into these. They read and write the same brain.                                         |
+| **Anything else with a shell**               | Works — the CLI is the whole interface. Nothing has to be built for a new tool.                                       |
+| **ChatGPT · Claude on the web · phone apps** | **Not yet.** There is no connector. A hosted brain is reachable by them in principle and is not wired up in practice. |
+
+So when someone asks _"will my ChatGPT remember this too?"_, the answer is **not
+yet, and here is what does** — not a hedge, and not a promise. Saying "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.
+
 ## When to reach for it
 
 **Start a session by asking what you are missing.** Before working in an
@@ -95,6 +111,23 @@ six months from now, and it is refused if it looks like it carries a credential.
 memgineering revise <handle> --claim "Deploying is manual now." --summary "manual only"
 ```
 
+**Get their notes out whenever they ask** — a backup, a new machine, "where is
+my memory actually kept", or plain curiosity about what is stored:
+
+```
+memgineering pull ~/my-brain
+```
+
+It downloads their hosted brain as markdown and **never overwrites** a file
+already there, so it is safe to run twice and safe to point at the wrong
+folder. `push` is the other direction and never deletes anything locally.
+
+Say what arrives: notes the brain excludes from recall come down too, with
+`.memgignore` beside them. Excluded means "stop reading this", not "this is no
+longer theirs" — but readable files in a folder is not something to let them
+discover later. What lands is markdown, not yet a brain here; offer
+`memgineering link <folder>` rather than running it.
+
 ## What to raise with the user rather than just doing
 
 The tool does not gate writes; your judgement does. Tell them — plainly, once

package/assets/memgineering-memory/SKILL.md

@@ -335,3 +335,29 @@ 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.
+
+## Moving a brain between this machine and their account
+
+```
+memgineering push                    # this folder → their account
+memgineering pull ~/my-brain         # their account → a folder here
+```
+
+Both are safe to run twice, and each is careful in the opposite direction:
+**`push` never deletes anything locally, `pull` never overwrites anything
+locally.** Whatever was already there is left alone and counted in the summary,
+so an interrupted transfer finishes by running the same command again.
+
+Reach for `pull` when the user asks to get their notes out, wants a backup,
+is moving machines, or asks where their memory actually lives. **Say what it
+brings**: notes the brain excludes from recall come down too — excluded means
+"stop reading this", not "this is no longer yours" — along with `.memgignore`,
+so nothing is silently un-excluded on the way. If any of those arrive, tell
+them; readable files in a folder is not something to discover later.
+
+What lands is markdown and nothing more. It is not a brain on this machine
+until `memgineering link <folder>` — offer that as a next step rather than
+doing it, since it is a second decision they did not ask for.
+
+`--dry-run` on either verb lists what would move and moves nothing. Use it when
+the user is unsure which folder they mean.

package/assets/memgineering-setup/SKILL.md

@@ -55,6 +55,20 @@ one at a time, in plain language. Reach for it when the user is not reading
 your terminal at all — they have never opened one, or they are the one who has
 to decide and a checkbox screen you are driving is not where they can.
 
+**Its first screen is the account question, and it is theirs.** The page
+explains what memgineering is, compares keeping the memory on this machine
+against keeping it in an account — what works without one (everything), what
+only works with one (the same memory on another machine, and on a machine they
+no longer have), what it costs (one brain, free) — and only starts a sign-in
+after they pick. Do not answer it for them and do not pre-empt it by running
+`login` first.
+
+If they already told you which way they want it, pass `--login` or
+`--no-login`: the screen opens with that answer selected rather than asking
+again, and they can still change it. If they chose an account, the page shows
+a short code at the end — read it out to them; approving it in the browser is
+the last thing they do.
+
 It covers step 2 as well: the page offers the notes folders it finds on the
 machine, and shows the same disclosure `link --dry-run` prints — how many notes
 would be indexed, which ones are refused and why, with samples of the lines