memgineering 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -11,6 +11,181 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [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
+
+- **The language warning no longer fires on a query that worked.** On a brain
+  holding notes in more than one language, `recall "배포"` returned the Korean
+  note it was looking for and was told, above the result, that the query could
+  not reach the brain. A query that reached a note you wrote reached the brain,
+  whatever script it was in. It now stays quiet in that case, and still speaks
+  when everything that came back was `01_BASE/` scaffolding — which `init`
+  writes in English for everybody, so matching it is not evidence the query
+  landed. Found by using 0.2.0 against a real brain; a single-language fixture
+  could not produce it.
+
 ## [0.2.0] — 2026-08-09
 
 The record can say why, and you can see what a memory is actually worth.
@@ -46,9 +221,8 @@ The record can say why, and you can see what a memory is actually worth.
   however it is worded — and the old zero-result footer suggested broader
   wording, the one remedy that cannot work. Four testers hit this and came
   within one command of telling their user the brain held nothing on a subject
-  it had notes about. The warning also appears above results, because the
-  failure is rarely a clean zero: a couple of English scaffolding notes match
-  and look like an answer.
+  it had notes about. It appears above results too, since the failure is rarely
+  a clean zero: a couple of scaffolding notes match and look like an answer.
 - **`use` with no argument now says which brain you are on**, and how it
   resolved — by pointer, by containment, or by being the only one linked. Its
   own help had always promised this; it reported only whether a pointer file

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,67 @@ 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.
 
+## 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.** These files' bodies are prose, and `revise` only touches
+frontmatter — so write the body with your normal file tools, then set the
+summary so recall shows the real thing rather than the prompt:
+
+```
+memgineering revise 01_BASE/USER.md \
+  --action reinforce \
+  --claim "<one line: who they are>" \
+  --summary "<the line recall should show>"
+```
+
+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

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.