memgineering 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -11,6 +11,144 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.27.0] — 2026-10-18
+
+### Added
+
+- **`recall --json` says why nothing the user wrote came back.** An answer
+  with no card the user wrote — no cards at all, or only cards still exactly
+  what `init` wrote (`scaffolding: true`) — had no `hint`: most of the advice
+  the terminal footer gives was left out, and so was a hosted brain's own
+  `hint`. It now carries `hint`, the single most specific next step, and an
+  answer of template cards only keeps its cards; `hint` is absent whenever a
+  card the user wrote came back. First, a brain with nothing to search. One
+  with no notes yet (for a hosted brain, as its account listing reports) gets
+  the `remember` command that writes the first one there — or, after `--brain`
+  named a brain this machine does not point at, the `memgineering use --brain`
+  that makes it the target, since `remember` has no `--brain`. A folder brain
+  that left out everything it had gets "Nothing in this brain could be
+  searched: …", described below. After that: notes in a script the question is
+  not in, other brains that were not read (a `--brain` or `--vault` command for
+  each), meaning that was not searched (with the server's reason), the hosted
+  server's own advice, and last, what was searched in this brain and what to
+  try there — fewer or broader words, `--depth standard` after
+  `--depth exact`, or dropping `--scope`.
+- **`reindex` and `push` name the symlinks they did not follow.** The walk
+  never follows a symlink, so notes in a folder behind one were counted
+  nowhere and named by nothing. `reindex`, and a `push` that has notes to
+  send, now list every symlink that is not itself a note — under `--json` as
+  the new `skipped_other_symlinks`, beside `excluded_folders` — and a left-out
+  count beside a non-empty one of either is a floor, not the whole answer. A
+  `push` with nothing to send still calls such a folder empty and names no
+  link.
+
+### Changed
+
+- **`recall` says when a brain in a folder left notes out of the search, in
+  the terminal as well as in `--json`.** The notes it counts were excluded by
+  the user's rules, listed in `.memgdeny`, held back because the name looks
+  private, refused because the content looks like a credential, or sit behind
+  a symlink. Notes inside a folder the rules exclude are not among them: the
+  walk never looks inside such a folder, so they are neither searched nor
+  counted. Whenever no card the user wrote came back — no cards at all, or
+  only cards still exactly what `init` wrote — and one of those notes was left
+  out, the answer says how many and why, lists beside them any excluded
+  folders and other symlinks nobody looked inside, and says that
+  `memgineering reindex` names each one: in the terminal under
+  `_Nothing matched._`, or under the "Nothing you have written matched this."
+  header above template cards, and under `--json` at the start of `hint`.
+  Excluded folders and other symlinks on their own, beside notes that were
+  searched, change nothing. When every note was left out — nothing indexed,
+  and the walk left out notes, or only folders and links it never looked
+  inside, which are not evidence of a note — the answer says "Nothing in this
+  brain could be searched: …" and nothing more about the brain: that sentence
+  and the `reindex` command are the whole `hint`, and the terminal no longer
+  adds "try fewer or broader words". When other notes were searched and one of
+  the counted notes was left out, `hint` starts with "Not every note in this
+  brain was searched: …" and goes on with the step it would otherwise give,
+  whose last-resort sentence then reads "Within the rest of this brain, …".
+  Recall never names a held-back note or shows its content. In the terminal, a
+  folder with no notes and nothing left out, answers with at least one card
+  the user wrote, and empty answers where notes were searched and none of the
+  counted kinds was left out all look as they did.
+- **An answer of template cards only now names the brains the recall did not
+  read.** In the terminal it lists them under its header, with the command
+  that reads each, as an empty answer always has — except when the notes being
+  in another script is the reason: then, as for an empty answer, the script
+  notice prints instead of that block, and `hint` carries the script sentence
+  rather than the other-brains step, after the left-out count when a note was
+  also left out.
+
+### Fixed
+
+- **Two memgineering commands refreshing the registry sign-in at once no
+  longer cost one of them its link.** On a machine signed in to the registry,
+  a `memgineering registry` command refreshes that sign-in as it starts, and
+  the registry rotates the token on every refresh, so of two commands that
+  refresh together it refuses the second. That one used to report the link as
+  gone (`not_linked`, with "`memgineering login` re-links both"), or, for the
+  verbs that can read without an account — `registry search`, `read`, `pull`
+  and the like — carry on anonymously. It now waits up to about two seconds
+  for the token the winning command saved and retries once with it, never
+  with its own spent token. If the retry loses too — with three or more
+  commands started together, say — or no newer token turns up within those
+  two seconds, a command that needs the sign-in reports `not_authenticated`
+  with a hint to run it again, and one that can read without it reads
+  anonymously, as before. Running it again does not always work: when the
+  command that won was a `logout`, or its save never landed, the next run
+  finds no newer sign-in and reports `not_linked`.
+- **A busy or unreachable registry no longer reads as an expired link.** A
+  command that needs the registry sign-in, such as `registry publish`, turned
+  every failed refresh into `not_linked` and pointed at `memgineering login`,
+  which fixes neither. A refresh that meets a rate limit, a server error or no
+  network now reports that: `rate_limited`, the registry's own code, or
+  `server_unreachable`.
+- **The sign-in file is no longer briefly missing while it is written.**
+  `credentials.json` used to be deleted and then written again, so a command
+  that read it in between took this machine for signed out. Saving it now
+  writes a new file and renames it into place (still mode 600), and a stale
+  temp file left by a crash is swept by a later save; a sign-out still deletes
+  the file. Changes also take a lock, and a rotated registry token is saved
+  only while the file still holds the token its refresh spent, so a sign-in or
+  sign-out that lands while another command's refresh is out is kept rather
+  than overwritten. A change that cannot take the lock within two seconds goes
+  ahead without it, and a lock held for more than 30 seconds is taken over as
+  dead; in either case the two can still cross.
+- **`logout` revokes the registry session even when a command beside it has
+  just refreshed it.** It reads the sign-in file again right before revoking,
+  and its refresh retries a lost race the same way, where it used to give up
+  and leave the session to expire on its own
+  (`"registry": "revoke-failed-expires-on-its-own"` under `--json`).
+
+### Agent guidance
+
+- `memgineering-recall`: with `--json`, an answer with nothing the user wrote
+  in it — no cards, or only template cards (`scaffolding: true`), which are
+  what `init` wrote and not the user's notes — carries `hint`, the one next
+  step; read it before concluding anything from `cards: []` or from template
+  cards. A `memgineering use --brain` in a hint moves this machine's pointer
+  for every later command, so offer it to the user and run it only on their
+  yes. Held-back notes are counted in both modes. For a counted note, tell the
+  user that such a note exists and why — never that the brain is empty or that
+  they never wrote it down — and, to say where, run the printed `reindex` and
+  give them the path; do not open, print or read a held-back note unless they
+  ask what it says. An excluded folder or another symlink is a place nobody
+  looked inside, not evidence of a note: say that recall could not look inside
+  it and that `reindex` names it, and do not say a note was held back. An empty
+  answer is not proof that the user never wrote something: recall never looks
+  inside a folder their own rules exclude, so say what was searched and that
+  such folders were not, and do not open one yourself. An answer of template
+  cards only also names the brains it did not read; run that command before
+  saying the fact was never written down.
+- `memgineering-setup`: `reindex` and `push` list `skipped_other_symlinks`;
+  read their left-out count together with it and `excluded_folders`, because
+  beside a non-empty one the count is a floor. A `recall` that brings back
+  nothing the user wrote counts the same set by reason — beside notes it did
+  search, only when a note is among them — and prints the `reindex` command,
+  never a path.
+
+Restart your agent session after upgrading so it reads the new guidance.
+
 ## [0.26.0] — 2026-10-10
 
 ### Changed

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.26.0
+version: 0.27.0
 ---
 
 # memgineering

package/assets/memgineering-recall/SKILL.md

@@ -191,18 +191,72 @@ 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
-compensate. At the default depth this has already searched every note body of
-**the brain it searched**, so "nothing" is real information about that brain
-rather than a hint to search harder — read `semantic` first, per above. Broader
-words are still worth one retry; `--depth exact` is not — it looks at strictly
-less.
+compensate. At the default depth this has already searched the body of every
+note recall could read in **the brain it searched**, so "nothing" is real
+information about those notes rather than a hint to search harder — read
+`semantic` first, per above. Broader words are still worth one retry;
+`--depth exact` is not — it looks at strictly less.
+
+In a brain in a folder, that is not a promise about every file. Notes it left
+out are counted below, but recall never looks inside a folder the user's own
+rules exclude (`.gitignore`, `.memgignore`, the rules file): notes in one are
+neither searched nor counted, and an answer where other notes were searched does
+not mention them. So an empty answer is not proof that the user never wrote
+something down. Say what was searched, and that folders their rules exclude
+were not, rather than telling them they never wrote it. Do not open such a
+folder yourself.
 
 One brain is not the account. On a hosted account with more than one brain, an
-empty answer now names the brains that were NOT read and prints a runnable
-`--brain` command for each. Run it before you tell them the fact was never
-written down — four testers reached that conclusion about a note sitting in the
-next brain, and three of them said it out loud. Reading another brain does not
-move the machine's pointer.
+empty answer — or one of template cards only — names the brains that were NOT
+read and prints a runnable `--brain` command for each. Run it before you tell
+them the fact was never written down — four testers reached that conclusion
+about a note sitting in the next brain, and three of them said it out loud.
+Reading another brain does not move the machine's pointer.
+
+With `--json`, an answer with nothing the user wrote in it carries `hint`: no
+cards, or only template cards (`scaffolding: true`, below) — those are what
+`init` wrote, not the user's notes. `hint` is the one next step, the most
+specific that applies. First, the brain had nothing to search: it has no notes
+yet (the `remember` command that writes the first one into that brain — or,
+after `--brain` named a brain this machine does not point at, the
+`memgineering use --brain "<name>"` that makes it the target, since `remember`
+has no `--brain`), or it is a folder whose every note was left out (how many,
+why, and the `memgineering reindex` command that names each one). Then: its
+notes are in a script the question is not (ask again in that language), another
+brain was not read (the `--brain` or `--vault` command that reads it), meaning
+was not searched (and the server's reason), the hosted server's own advice, or
+fewer and broader words. Read it before you conclude anything from
+`cards: []` or from template cards. A `memgineering use --brain` in a hint
+moves this machine's pointer for every later command, not just the next one:
+offer it to the user and run it only on their yes. `hint` is absent whenever a
+card they wrote came back.
+
+**Held-back notes are counted in both modes.** When an answer has nothing the
+user wrote in it, recall counts what a brain in a folder left out, says why,
+and prints the `memgineering reindex` command that names each one: in the
+terminal right under `_Nothing matched._` or under the template cards' header,
+and at the front of `hint`. It opens with "Nothing in this brain could be
+searched: …" when no note could be searched at all, and with "Not every note in
+this brain was searched: …" when other notes were searched and at least one
+note of the first kind below was left out. Recall itself never names or shows a
+left-out note. The counts come in two kinds, and they mean different things:
+
+- **Notes**: excluded by the user's rules (`.gitignore`, `.memgignore`, the
+  rules file), listed in `.memgdeny`, held back because the name looks private,
+  refused because the content looks like a credential, or behind a symlink. A
+  note the user wrote exists and was left out on purpose. Do NOT tell them the
+  brain is empty or that they never wrote it down: tell them such a note exists,
+  and why; to say where it is, run that `reindex` — it lists each path and
+  changes no note — and give them the path. Do not open, print or read a
+  held-back note into the conversation unless they ask what it says: it was
+  held back because it may be private.
+- **Places nobody looked inside**: an excluded folder ("not looked inside"), or
+  another symlink, which is never followed. These are not evidence of a note —
+  an ignored `images/` or `.venv/` holds none. Say that recall could not look
+  inside them and that `reindex` names them; do not say a note was held back.
+  When "Nothing in this brain could be searched" lists only these, the brain may
+  hold no notes at all. Beside notes that were searched they are not counted at
+  all — see **Nothing matched** above.
 
 **Cards that are not answers.** A card marked `not filled in yet` is one of the
 five `01_BASE/` files, still exactly what `init` wrote (line endings aside). Nobody has answered

package/assets/memgineering-setup/SKILL.md

@@ -506,17 +506,23 @@ by hand in the ordinary case — writes keep the index in step on their own.
 what is missing and clears stored rows for notes the brain has since been told
 not to read, reporting both; `--local` forces the folder brain. On a brain in a
 FOLDER it also names what it left out — notes a deny name, a `.memgignore` rule
-or a symlink kept from the index, and any folder a rule excluded whole — so "3
-notes rebuilt" is never the whole answer when a fourth was dropped. A hosted
-reindex cannot say that: the rules are applied on the machine that pushed, so
-the server only ever saw what arrived.
+or a symlink kept from the index, any folder a rule excluded whole, and any other
+symlink, which is never followed — so "3 notes rebuilt" is never the whole
+answer when a fourth was dropped. A hosted reindex cannot say that: the rules are
+applied on the machine that pushed, so the server only ever saw what arrived.
 
 Under `--json` that is `not_indexed` with `denied_by_name`, `denied_explicitly`,
-`excluded_by_rule`, `skipped_symlinks` and `excluded_folders`. **Read the count
-together with `excluded_folders`**: a rule that names a folder stops the walk at
-the folder, so nothing inside it is ever counted — `not_indexed: 0` beside a
-non-empty `excluded_folders` means the count is a floor, not the answer. `push`
-reports the same set with its total under `not_sent`. `--rebuild`
+`excluded_by_rule`, `skipped_symlinks`, `excluded_folders` and
+`skipped_other_symlinks`. **Read the count together with the last two**: a rule
+that names a folder stops the walk at the folder, and a symlink is never
+followed, so the notes in such a folder are never counted — `not_indexed: 0`
+beside a non-empty `excluded_folders` or `skipped_other_symlinks` means the count
+is a floor, not the answer. `push` reports the same set with its total under
+`not_sent`. A `recall` that brings back nothing the user wrote — no cards, or
+only templates — counts the same set by reason in both modes (beside notes it
+did search, only when a note is among them) and prints this command, never a
+path; what to tell the user then is in `memgineering-recall`.
+`--rebuild`
 exists for one situation only, where an embedding model changed the shape of its
 answers without changing its name and the index has to be laid down again.