memgineering 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -11,6 +11,235 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-08-10
+
+A template is not an answer, a revision that revises nothing is not written,
+and linking a second brain no longer breaks the first one everywhere.
+
+### Added
+
+- **`recall` tells a template apart from an answer.** A card that is one of the
+  five `01_BASE/` files and is still byte-for-byte what `init` wrote is marked
+  `not filled in yet`; when every card in a result carries that mark, one line
+  above them says nothing you have written matched, and points at `onboard`.
+  `--json` carries it as `scaffolding`. Nothing is removed from the result —
+  the label is a fact about the file, so an unfilled base note padding out a
+  weak answer is visible as padding instead of reading like a conclusion. The
+  mark disappears the moment the file is edited, which is also the moment a base
+  note starts being the best answer in the brain.
+
+- **`revise` refuses a revision that revises nothing.** When the claim, summary
+  and title all match what the note already holds, nothing is written and the
+  reason is given — a user repeating an answer they had already given used to
+  become ledger entries recording no change. Saying `--reason` makes it a real
+  record again, which is what `reinforce` is for.
+- **`revise` says when a conclusion landed above `init`'s instructions.** These
+  files take two steps — write the body, then record the claim — and doing only
+  the second leaves a note whose frontmatter concludes something while the prose
+  under it is still the form telling you what to write.
+
+### Changed
+
+- **`revise --help` says which `--action` to pick and what it costs to pick
+  wrong.** Only `supersede` moves `valid_from`, so using it on a fact that was
+  true all along dates it from today. Filling in a blank `01_BASE/` file for the
+  first time is `reinforce`.
+
+### Fixed
+
+- **Linking a second brain no longer breaks the first one everywhere.** With
+  more than one brain linked and no pointer in the current folder, every command
+  refused as ambiguous — so a scratch brain linked for an afternoon stopped
+  `recall` and `remember` working in every other directory, for every tool
+  sharing the config. The first brain linked is now the default and is used when
+  nothing more specific applies; `memgineering use --default <path>` changes it,
+  and `--vault`, a `.memgineering` pointer, and standing inside a brain all
+  still win. The ambiguity refusal remains for the case it was written for —
+  several brains and nothing ever said which — and now names the one-time fix.
+  Upgrading picks the brain you already had, not the next one you happen to
+  link.
+- **The cross-language warning no longer fires over a base file the user wrote.**
+  It decided "did this query reach anything the person wrote" from the path — a
+  match under `01_BASE/` did not count — so somebody who had answered those five
+  questions could ask about their own preferences, get their own note, and be
+  told the query could not reach their brain. It now asks whether the file has
+  been touched, which is what it meant all along.
+
+### Agent guidance
+
+- `memgineering-memory` covers the `not filled in yet` mark and the header above
+  a result made only of templates: what they mean, and that a card carrying one
+  is not evidence of anything.
+- `memgineering-memory` spells out that filling in a base file is two steps —
+  write the body, then record the claim — why it is `--action reinforce` rather
+  than the default, and that re-recording something unchanged is refused.
+- `memgineering-setup` covers the default brain, and says not to abandon a write
+  because the brain was ambiguous: a refused `remember` means the thing the user
+  asked you to keep was not kept.
+
+**Restart your agent session after upgrading** so the updated skills load.
+
+## [0.3.0] — 2026-08-10
+
+Recall says how old a memory is and why two of them disagree; a screen for
+people who did not come here for flags; and seven places the tool was doing
+something other than what it said.
+
+### Added
+
+- **Cards carry an age.** `recall` prints `stated · 3 days ago`, and `--json`
+  carries `age_days`. Deciding whether to revise a memory or write a new one is
+  a recency judgement, and the card was missing the field that decides it.
+- **Contradictions you can act on.** When two memories disagree, the block now
+  gives each side's date and quotes the reason recorded for its last change,
+  and names `retire` as the way to settle it. Previously it said only that they
+  disagreed, which left the reader to go and find out why.
+- **`revise --title`.** `recall` renders the title as a card's heading, so a
+  superseded conclusion used to go on asserting itself in every heading while
+  the summary underneath said otherwise.
+- **A warning when the prose stops agreeing with the conclusion.** After a
+  supersede, if the note's body still states the claim that was just replaced,
+  `revise` says so. It does not touch the body — that is yours — but an
+  invisible contradiction inside one note is worse than a visible one.
+- **`setup --web` — setting it up on a screen, for someone who has never opened
+  a terminal.** The browser is asked one question at a time: which agents share
+  the memory, whether the tool keeps itself updated, whether note summaries are
+  handed to every new session, and which folder holds the notes. The folder step
+  shows what `link` shows — how many notes would be indexed, which files are
+  refused and why, with samples of the exact lines that would be stored — before
+  anything is read. Applying calls the same installer the flags do, so both doors
+  leave the same files behind. The page is self-contained and served on
+  `127.0.0.1` with a one-time key in its URL; it opens the browser itself
+  (`--print-url` where there is none) and closes when the setup is applied or
+  after ten idle minutes.
+
+### Fixed
+
+- **One note could stop the tool for minutes.** The credential scanner's
+  short-secret pattern backtracked cubically on text that matched a label and
+  then failed at the digits: 200 spaces cost 12ms, 800 cost 279ms, 1,600 cost
+  2.2 seconds — against a 20,000-character field. Bounded now, and flat: the
+  same input takes 0.01ms at 20,000 characters, with every short-secret shape
+  still detected and no new false positives.
+- **`undo` could delete a note you did not name.** It resolved an operation id
+  by unchecked prefix and took the oldest match, so `undo 6` removed the oldest
+  note whose id began with a six and reported success. It now requires the same
+  five-character minimum `open` does and names the candidates when a prefix is
+  ambiguous.
+- **`undo` on a damaged ledger reversed the wrong operation.** A line lost to an
+  interrupted write is normally the newest one, so "the last change" stops being
+  answerable — and a bare `undo` was then taking the change before it. It
+  refuses now and points at `log`; `undo <op_id>` still works, because that
+  record parsed and you said which one you meant.
+- **`revise --action conflict` said "Revised" and wrote nothing.** Recording a
+  disagreement deliberately does not overwrite either conclusion, but reporting
+  a revision while discarding the claim you passed is the tool telling you
+  something untrue about your own brain. It now says what it did, says the claim
+  was not written, and names `--action supersede` for the other case.
+- **Every read re-checked the same directories, once per note.** Resolving a
+  path refuses symlinks by walking it component by component, and in a brain
+  whose notes sit under `20_TIMELINE/observations/2026-08/` three of every four
+  checks were re-asking about the same three directories: 659ms per command at
+  twelve thousand notes, against 220ms for the identical guarantee. Directories
+  cleared during one command are not re-checked during that command; the memo
+  dies with the command, and the final component — the one the answer is about —
+  is always checked.
+- **`resurface` presented `init`'s own boilerplate as something you had
+  written.** A base file nobody has filled in still carries the summary `init`
+  gave it — so a fresh brain answered "what should you already know here" with
+  "Tooling · recalled 14× in this folder · The tools, machines and commands I
+  actually use", for a file whose body is one empty bullet. It still surfaces,
+  because an unfilled base file is the most worth raising, but it is labelled
+  `not filled in yet` and says the line is a prompt. Judged by comparing the
+  file byte-for-byte against what `init` wrote: an exact match cannot be a false
+  positive, and the moment somebody touches the file it goes back to being their
+  note.
+- **`revise` moved a memory's start date every time it ran.** `valid_from` is
+  when the fact became true, and it was being written as an edit timestamp — so
+  `reinforce`, whose whole job is "same conclusion, better support", walked the
+  date forward on every use. A tester added a reason to a memory and watched its
+  start date land a day after the thing it describes. `supersede` still stamps
+  now, because a replaced conclusion does start now; `reinforce` and `conflict`
+  leave it alone, and the new `--valid-from` sets it when the caller knows the
+  real date.
+- **The contradiction footer told you to retire a side you had already
+  retired.** Two testers hit it independently: retire, run recall, and be
+  advised to retire. The disagreement is still shown — both notes are still in
+  the brain — but when every side is settled the footer says so.
+- **The rules file written into your notes folder was in Korean.** Every other
+  string this tool emits is English on the theory that an agent re-renders for
+  its reader — but this one is a document left on disk among somebody's own
+  notes, with no agent standing between it and whoever opens it. It also still
+  called the tool Kordis.
+- **`stated` was glossed as something it does not mean.** It reports that a
+  card's fields came from the note rather than from inference, which is why a
+  note carrying a `memgineering:` block but no claim is `stated` — and `open`
+  then printed `stated` in its header and "nothing here states a conclusion"
+  two lines below. Both sentences were right; the gloss was describing the
+  wrong thing, and now says "these fields came from the note".
+- **`log` blamed an external edit it could not have known about.** Divergence
+  has more than one cause — an editor, or a write whose ledger entry never
+  landed — and the message asserted the first as fact.
+- **A brain whose folder was deleted made every command ambiguous, forever.**
+  The linked list is written by `link` and was never re-checked, so one gone
+  path — a scratch folder, a moved vault — meant every verb refused until
+  somebody found and unlinked it. Missing folders no longer count toward
+  ambiguity, are listed as `(missing)` when it still is ambiguous, and are not
+  removed from the config: a folder that is absent today may be an unmounted
+  disk tomorrow.
+- **`use` with no argument threw instead of answering.** It is the command you
+  run to find out why the others are refusing, and it was refusing the same
+  way. It now describes the situation, including when nothing resolves.
+- **The `undo` line printed after a write can be pasted and run.** It carries
+  `--vault` when the command was given one — a tester copied it verbatim and
+  got "2 brains are linked, so this is ambiguous", from a process that knew
+  which brain it had just written to one line earlier.
+- **`log` read the whole brain to print twenty lines.** Checking whether notes
+  still match the ledger was run over the entire history rather than the rows
+  being shown: 161ms at a hundred operations, 5.7 seconds at twenty thousand,
+  and worse with every use. Scoped to what is displayed, and the footer now says
+  "N of these 20" rather than a brain-wide count it did not pay for.
+- **A reason attached to an undone operation was still being quoted.** `recall`
+  and `evidence` would explain a change the note no longer contains.
+- **The `stated` gloss appeared under cards that did not say `stated`.**
+  Defining a word the card does not carry teaches the reader something false
+  about what they are looking at.
+
+### Changed
+
+- `remember`'s two ids are labelled — `note:` and `undo:` — because a tester
+  tried the note id with `undo`.
+- A bare `undo` now reports what it reversed and when, and cautions when that
+  operation is more than ten minutes old. With another agent or a session hook
+  writing to the same brain, "the last change" is not necessarily yours.
+
+- **`memgineering onboard`** — what to ask so the brain knows who it belongs to.
+  It does not run the conversation, and that is the design: a CLI cannot ask
+  "what should I never do without asking you first" and understand the answer,
+  but the agent reading this output can. So it returns the work — which of the
+  five base files are still exactly what `init` wrote, what each is for, and
+  where to start asking — and reports that there is nothing to do once they are
+  written.
+- **`init` now hands the base files to the agent instead of the user.** It used
+  to close with "Start by filling in 01_BASE/USER.md", which is homework nobody
+  does — and what goes in those files (who they are, how they want answers,
+  what to ask before doing) cannot be typed into a form. It comes out of a
+  conversation, so `init` asks the agent to have one, and the skill carries the
+  questions.
+
+### Agent guidance
+
+- `memgineering-memory` covers reading a card's age and the contradiction block,
+  and asks for `--reason` on every write.
+- `memgineering-memory` also covers filling in `01_BASE/` — the questions, how
+  to ask them, and the one narrow case where writing a brain file directly is
+  the right move.
+- `memgineering-setup` covers `--web`: when to put a screen in front of a person
+  rather than answer setup's flags for them, and that the command does not
+  return until they have finished with it.
+
+**Restart your agent session after upgrading** so the updated skills load.
+
 ## [0.2.1] — 2026-08-09
 
 ### Fixed

package/NOTICE

@@ -1,7 +1,7 @@
 memgineering
-Copyright 2026 memgineering
+Copyright 2026 Chang Do Geon ("Rayul", 장도건)
 
-This product includes software developed by memgineering
+This product includes software developed for memgineering
 (https://memgineering.com).
 
 Licensed under the Apache License, Version 2.0. See LICENSE for the full

package/assets/MEMGINEERING.md

@@ -26,6 +26,21 @@ No query — it ranks by what has been recalled here before, how recently, and
 which of their core notes have gone unread. It is the answer to a vague
 question that recall cannot serve, because there is nothing to search for yet.
 
+**Fill in their base files when they are still empty.** `init` leaves five
+files in `01_BASE/` as templates, and `resurface` marks an untouched one
+`not filled in yet`. What goes in them — who they are, how they want answers,
+what to ask before doing — only comes out of a conversation, and every session
+starts from zero until it exists. Offer once, ask one question at a time; the
+`memgineering-memory` skill has the questions and how to write the answers.
+They can also ask for it directly — "set up my memory", "내 정보 채워줘" — and
+that is the same job.
+
+```
+memgineering onboard
+```
+
+Says which are still untouched and what to ask for each.
+
 **Recall before answering** anything that sounds like it was settled before:
 
 - "what did we decide about…", "how do I deploy this again", "왜 이렇게 했더라"

package/assets/memgineering-memory/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memgineering-memory
-description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, or says something worth keeping. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "is this still true", "which one do I go with", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "what do you know about my setup". Covers recall, open, evidence, remember, revise, undo, and resurface against the user's own brain folder.
+description: Use when the user asks about something they told you before, refers to a past decision, wants their own notes searched, says something worth keeping, or wants their memory set up so it knows who they are. Triggers include "what did I decide about X", "check my notes", "how do we deploy again", "remember this", "is this still true", "which one do I go with", "set up my memory", "fill in my profile", "teach it about me", "예전에 뭐라고 정했더라", "내 노트에서 찾아줘", "이거 기억해둬", "내 정보 채워줘", "나에 대해 알려줘", "what do you know about my setup". Covers recall, open, evidence, remember, revise, undo, resurface, and filling in the `01_BASE/` files by asking.
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
@@ -74,6 +74,103 @@ Say so. Only titles, aliases and summaries are searched, so suggest broader
 words — but do not go read their folder yourself to compensate. A brain that
 answers "nothing" is giving you real information.
 
+### Cards that are not answers
+
+A card marked `not filled in yet` is one of the five `01_BASE/` files, still
+byte-for-byte what `init` wrote. Nobody has answered it, so it is evidence of
+nothing — do not quote it back as if it were what they think.
+
+When every card carries that mark, recall says so above them:
+
+```
+⚠ Nothing you have written matched this.
+  Every card below is still the template `init` wrote
+```
+
+That is the moment to offer to fill them in rather than to answer from them —
+`memgineering onboard` prints the questions. The cards are still listed, because
+the label is a claim about the file, not a decision about what you may see;
+`--json` carries the same fact as `scaffolding: true`.
+
+The mark disappears the moment the user writes in the file. A base note they
+have filled in is an ordinary note of theirs and often the best answer in the
+brain — `who am I`, `what am I not allowed to do`, `where does everything live`
+are all answered from `01_BASE/`.
+
+## Filling in the base files, which only you can do
+
+`init` creates five files in `01_BASE/` and leaves them empty, because what
+goes in them cannot be typed into a form. Who the user is, how they want
+answers, what you must ask before doing, what would be expensive to get wrong,
+what they actually run — those come out of a conversation.
+
+They matter more than any single memory: `resurface` puts these at the top of a
+new session, and an empty one teaches the next agent nothing. A brain whose
+base is untouched is a brain that starts every session from zero.
+
+**Offer once, at the natural moment** — right after `init`, or the first time
+`resurface` marks one `not filled in yet`.
+
+```
+memgineering onboard
+```
+
+Says which of the five are still untouched and what to ask for each. Run it
+first rather than working from the list below; it knows what has already been
+done, and asking somebody a question they have answered is its own kind of
+forgetting. Then follow their answers rather than the script.
+
+They may also ask for it outright — "set up my memory", "fill in my profile",
+"내 정보 채워줘". Same job, and it is the only entry point that works when you
+did not offer.
+
+```
+01_BASE/USER.md            who they are, what they work on, what they are trying to do
+01_BASE/PREFERENCES.md     how they like answers, code, decisions — length, tone, how much checking in
+01_BASE/BOUNDARIES.md      what you must ask before doing. The one they will regret not saying
+01_BASE/CRITICAL_FACTS.md  what is expensive to get wrong — deploy, money, data, people
+01_BASE/TOOLING.md         editors, languages, machines, the commands they actually run
+```
+
+**How to ask.** One question at a time, in their words, and stop when the
+answers thin out — three good lines beat a filled-in template. Take what they
+say in passing during ordinary work too; most of `TOOLING.md` gets written by
+noticing, not by asking.
+
+**How to write it — both halves.** `revise` only touches frontmatter, so it
+takes two steps, and skipping the first is the common failure: write the body
+with your normal file tools FIRST, replacing `init`'s instructions with what
+they actually said, then record the conclusion.
+
+```
+# 1. replace the body — their words, not the template's prompt
+# 2. then:
+memgineering revise 01_BASE/USER.md \
+  --action reinforce \
+  --claim "<one line: who they are>" \
+  --summary "<the line recall should show>"
+```
+
+A claim written above the untouched template leaves the file reading as a form
+somebody half-filled — the conclusion in the frontmatter, the instructions for
+writing one still underneath. `revise` warns when you do this; the warning means
+go back and write the body.
+
+`--action reinforce`, not the default, and the reason is the date. `supersede`
+stamps `valid_from` with now because a replaced conclusion starts now — but
+these facts were always true and you have only just been told them. Dating them
+today is wrong in the one field a memory store exists to get right.
+
+This is the ONE place you edit a brain file directly, and the boundary is
+narrow: `01_BASE/` only, and only while the file is still the template `init`
+wrote. Nothing is lost — there is no history to break and nothing to undo — and
+after that first pass these files are theirs like any other note, changed
+through `revise` and never behind their back.
+
+**What not to do.** Do not invent an answer to move on, and do not fill a file
+because it is empty. `BOUNDARIES.md` guessed at is worse than blank: the next
+agent will read it as something the user said.
+
 ## Deciding which one to trust
 
 When two memories disagree, or one looks old enough to doubt, do not settle it
@@ -160,11 +257,24 @@ memgineering revise deploy-manual \
   --summary "manual only, no CD"
 ```
 
-- `--action supersede` (default) replaces the conclusion
-- `--action reinforce` keeps it and adds support
-- `--action conflict` records that two notes disagree without picking a winner
+- `--action supersede` (default) — the conclusion CHANGED. Stamps `valid_from`
+  with now, because a replaced conclusion starts now.
+- `--action reinforce` — the SAME conclusion, new support. Leaves `valid_from`
+  alone. Use it when nothing about the fact changed, only your evidence.
+- `--action conflict` — two notes DISAGREE. Records the edge, leaves both
+  standing, and deliberately does not write the claim you passed.
 - `--dry-run` shows the diff and writes nothing
 
+Pick by what changed, not by habit: `supersede` on a fact that was true all
+along dates it from today, and the date is the field this is all for.
+
+**Re-recording something unchanged is refused.** If the claim, summary and title
+all match what the note already holds, `revise` writes nothing and says so —
+otherwise a user repeating themselves turns into ledger entries that record no
+change. When you do mean "this still holds", say what confirms it:
+`--action reinforce --reason "<what confirms it>"`. Check with `open <ref>`
+before rewriting something you may already have.
+
 This only ever rewrites the memory block in a note's frontmatter. The prose is
 the user's; neither this command nor you should rewrite it uninvited.
 

package/assets/memgineering-setup/SKILL.md

@@ -40,7 +40,32 @@ updates itself. Recommend `on` — old versions can lose access to hosted
 features later — but it is theirs to decide.
 
 If the user would rather click than type, `memgineering setup --human` gives
-them a checkbox screen. Run it and let them drive; do not answer for them.
+them a checkbox screen in your terminal. Run it and let them drive; do not
+answer for them.
+
+### When a person needs a screen, not flags
+
+```
+memgineering setup --web
+memgineering setup --web --print-url     # no browser here — hand over the link
+```
+
+`--web` opens a page in their own browser and asks the same questions there,
+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.
+
+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
+that would be stored — before anything is read. When they finish, both steps
+are done and there is nothing left for you to run.
+
+The page is served on `127.0.0.1` with a one-time key in the URL, and closes
+itself when the setup is applied or after ten idle minutes. **The command does
+not return until then.** Run it, tell the user to look at their browser, and
+wait for it — a setup screen nobody answered has not set anything up, so do not
+report it as done until the command comes back.
 
 **After setup, the agent session has to restart** for the guidance to load.
 Say so — the user will otherwise wonder why nothing changed.
@@ -112,8 +137,9 @@ one answers is decided by where you are, in this order:
 2. a `.memgineering` pointer file, found by walking up from the cwd
 3. the brain the current directory is inside
 4. the only one linked
+5. their default brain — the first one they linked, unless they changed it
 
-If it says the choice is ambiguous, bind the directory once:
+Bind a directory to one brain when that directory belongs to it:
 
 ```
 memgineering use ~/brains/work
@@ -122,6 +148,19 @@ memgineering use ~/brains/work
 Inside a repository this writes a relative path, so it can be committed and
 will resolve for a teammate who links the same brain.
 
+If it still says the choice is ambiguous — several brains, and nothing has ever
+said which is theirs — that is a question for them, not a guess for you. Show
+the list it printed and offer the one-time fix:
+
+```
+memgineering use --default ~/brains/work
+```
+
+**Do not give up on a write because of this.** A refused `remember` means the
+thing they asked you to keep was not kept, and "I could not tell which brain"
+is a solvable problem — ask which one, or use `--vault` for the write and raise
+the default with them afterwards.
+
 ## Checking it worked
 
 ```