memgineering 0.4.2 → 0.6.0

package/assets/memgineering-setup/SKILL.md

@@ -1,173 +1,252 @@
 ---
 name: memgineering-setup
-description: Use when installing or configuring memgineering — after `npm i -g memgineering`, when the user asks to set it up, connect their notes, install it into their agents, turn auto-update on or off, or when a memgineering command reports that no brain is linked. Triggers include "set up memgineering", "connect my notes", "메모리 설정해줘", "노트 연결", "memgineering setup", "no brain is linked".
+description: Use when installing or configuring memgineering, when moving a brain between a machine and an account, or whenever the user asks WHICH of their AI tools can see this memory. Triggers include "set up memgineering", "connect my notes", "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".
 type: skill
 allowed-tools: Bash(memgineering:*)
 ---
 
 # Setting memgineering up
 
-Two things have to happen, and they are separate on purpose:
+## Which tools this actually reaches, today
 
-1. **Register with the agents** — so this and every other AI tool on the
-   machine knows the brain exists. One command.
-2. **Connect a brain** — which folder holds the notes. This one is the user's
-   decision, and it involves showing them what gets stored.
+Answer this from here, not from a guess. The line is capability, not brand, so
+it does not move as products come and go:
 
-## 1. Register
+|                                           |                                                                                                               |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| **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. |
 
-```
-memgineering setup --agent
-```
+`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.
 
-`--agent` is the non-interactive path, meant for you: it detects the installed
-tools, injects the guidance block, installs these skills, and takes its
-remaining answers from flags rather than prompts.
+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.
+
+## 1. Register with the agents
 
 ```
 memgineering setup --agent \
   --tools claude,codex \        # default: everything detected
   --auto-update on \            # default: on, and recommended
-  --hook on                     # SessionStart resurface, Claude Code only
+  --hook on                     # session-start summary + rules before an edit
 ```
 
-Look at `memgineering setup --dry-run` first if you want to report what would
-change before changing it.
-
-**Ask the user before choosing for them** when a flag would set policy rather
-than mechanics: auto-update is the one that matters, since it means the tool
-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 in your terminal. Run it and let them drive; do not
-answer for them.
+`--dry-run` reports what would change without changing it.
+
+**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.
+
+**`--hook off` removes them**, it does not merely decline to add them, so it is
+the answer when someone already has the callbacks and has decided they do not
+want them. Only groups memgineering wrote are taken out; anything else in that
+settings file is left alone.
+
+**After setup the agent session has to restart** for the guidance to load. Say
+so, or they will wonder why nothing changed.
+
+### When it reports something it could not do
+
+The guide lives between `<!-- memgineering-start -->` and
+`<!-- memgineering-end -->`, and those markers are the only way it can be found
+again. Two outcomes are worth recognising:
+
+- **`N file(s) could not be written`** — a guide setup wrote is still in that
+  file with its markers gone, or a settings file is not valid JSON. Everything
+  else in that run WAS applied; the exit code is non-zero so the one skipped
+  file is not mistaken for a clean install. Put the markers back around the
+  block, or delete the block, then run setup again. Never append a second copy
+  by hand: two guides means both are in the user's context every session.
+- **`Appended below an unmarked guide`** — the same shape, on a file setup has
+  no record of writing, so it installed rather than refusing. Look at the file:
+  if an older unmarked copy is now sitting above the new block, delete that copy.
+  If those lines are the user's own writing, nothing is wrong.
+- **`Replaced N file(s) you had edited`** — the bytes on disk were not the ones
+  setup last wrote, so someone's own words were just overwritten. setup owns
+  those files and an upgrade has to replace them; what belongs to the user goes
+  OUTSIDE the markers, where nothing touches it. Ordinary upgrades do not print
+  this.
+
+The hooks go to Claude Code and Codex, and only there. Codex asks the user to
+review new hooks once at the start of the next session and runs neither until
+they answer.
+
+Grok is the case worth knowing, because the obvious guess is wrong: it has
+hooks, more events than either of those two, and `~/.grok/hooks/` needs no
+trust prompt — but a hook there cannot say anything to the model. Measured
+three ways on 1.0.3, each with a value the session could not have known:
+`PreToolUse` with `additionalContext`, `SessionStart` stdout, and
+`UserPromptSubmit` with `additionalContext`. All three hooks ran; none of the
+three arrived. Its own docs agree — `PreToolUse` reads `decision`/`deny`, and
+"every other event is passive". So Grok gets the guide and the skills, which do
+reach it, and nothing that would spawn a process to talk to nobody.
+
+On Grok and Antigravity, run `memgineering resurface` yourself when you start
+work in a folder, and `memgineering rules` before you change anything — that is
+the same job the hooks do elsewhere, done by hand.
 
 ### When a person needs a screen, not flags
 
 ```
-memgineering setup --web
-memgineering setup --web --print-url     # no browser here — hand over the link
+memgineering setup --human       # checkbox screen in your terminal
+memgineering setup --web         # a page in their own browser
+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.
+Reach for `--web` when the user is not reading your terminal at all. Its first
+screen is the account question, and it is theirs: the page explains what
+memgineering is, compares this machine against an account, and starts a sign-in
+only after they pick. **Do not pre-empt it by running `login` first.** If they
+already told you which way, pass `--login` / `--no-login` and the screen opens
+with that selected.
 
-**After setup, the agent session has to restart** for the guidance to load.
-Say so — the user will otherwise wonder why nothing changed.
+It covers step 2 as well, with the same disclosure `link --dry-run` prints. The
+page serves on `127.0.0.1` with a one-time key and **the command does not return
+until it is answered or ten idle minutes pass** — a screen nobody answered has
+set nothing up, so wait for it rather than reporting done.
 
 ## 2. Connect a brain
 
-Two cases, and picking the wrong one is disruptive.
-
-**They already keep notes somewhere** — Obsidian, a folder of markdown,
-anything:
+**They already keep notes somewhere:**
 
 ```
-memgineering link ~/Documents/Notes
+memgineering link ~/notes
 ```
 
-This prints exactly what would be indexed and what would be refused, including
-a sample of the real lines that would be stored, then asks. **Run it and stop.**
-Let them read it and answer. Do not pass `--yes` for them: the screen is the
-one moment they decide what this tool may read, and answering on their behalf
-takes that away.
-
-If your shell has no terminal attached, `link` will say so rather than
-pretending the answer was no. When that happens, show them the decision
-instead of making it:
+Prints exactly what would be indexed and what would be refused — with samples of
+the real lines that would be stored — then asks. **Run it and stop.** Do not
+pass `--yes` for them: that screen is the one moment they decide what this tool
+may read.
 
-```
-memgineering link ~/Documents/Notes --dry-run
-```
+With no terminal attached it says so rather than assuming no. Then show them
+`memgineering link <path> --dry-run` — same disclosure, writes nothing — wait
+for a real yes, and only then run with `--yes`.
 
-That prints the same disclosure and writes nothing: every note that would be
-indexed with the exact line that would be stored, plus any file the credential
-scanner is holding back. Put it in front of them, wait for a real yes, and
-only then run with `--yes` — which records the decision they actually made.
-
-If they cannot see your terminal at all, hand them the command rather than
-answering for them.
-
-**What to tell them, in one line before they answer:** the title and first
-paragraph of every note listed gets stored outside the folder, and if the
-session-start hook is on, a few of those summaries appear in every new session
-without anyone asking. Anything they would not want in either place goes in a
-`.memgdeny` file at the top of the folder — one path per line, no wildcards:
+**Tell them one thing before they answer:** the title and first paragraph of
+every listed note gets stored outside the folder, and with the session-start
+hook on, a few of those summaries reach every new session unasked. Anything they
+would not want in either place goes in `.memgdeny` at the top of the folder, one
+path per line, no wildcards:
 
 ```
 30_personal/medical.md
 journal/                 (a trailing slash covers a whole folder)
 ```
 
-If it refuses because a `.memgdeny` line matches no file, that is working as
-intended — a rule with a wrong path protects nothing. Fix the paths it
-suggests, or remove the lines.
+A `.memgdeny` line matching no file is refused on purpose — a rule with a wrong
+path protects nothing.
 
-**They have no notes yet**:
+**They have no notes yet:**
 
 ```
 memgineering init ~/brain
 ```
 
-Creates the layout — eleven folders and five base files — and links it. Then
-tell them to fill in `01_BASE/USER.md` and leave the rest; the folders are
-there for when they are needed, not as homework.
+Creates the layout and links it. Tell them to fill in `01_BASE/USER.md` and
+leave the rest; the folders are there for when they are needed, not as homework.
 
 ### Several brains
 
-Normal: a personal one, a team folder that syncs, one per repository. Which
-one answers is decided by where you are, in this order:
+Normal — one of their own, a shared folder, one per project. Which one answers is
+decided in this order: `--vault <path>` → a `.memgineering` pointer found by
+walking up → the brain the cwd is inside → the only one linked → their default.
 
-1. `--vault <path>`
-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
+```
+memgineering use ~/brains/work          # bind this directory to one brain
+memgineering use --default ~/brains/work
+```
 
-Bind a directory to one brain when that directory belongs to it:
+Inside a repository `use` writes a relative path, so it can be committed and
+resolves for a teammate who links the same brain.
+
+**Do not give up on a write because the choice is ambiguous.** A refused
+`remember` means the thing they asked you to keep was not kept — ask which
+brain, or pass `--vault` for the write and settle the default afterwards.
+
+## Checking it worked
 
 ```
-memgineering use ~/brains/work
+memgineering recall "anything"     # should answer, even if with "nothing matched"
+memgineering log                   # what this brain has recorded
 ```
 
-Inside a repository this writes a relative path, so it can be committed and
-will resolve for a teammate who links the same brain.
+## Asking where things stand, without changing them
 
-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:
+There is no `status` verb. Three read-only questions cover it, and none of them
+writes anything:
 
 ```
-memgineering use --default ~/brains/work
+memgineering setup --agent --dry-run   # which tools are installed, what would change
+memgineering whoami                    # which account this machine is signed in as
+memgineering use                       # which brain answers recall and takes writes
 ```
 
-**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
+**`use` is the one to run before believing anything about where a note went.**
+Signed in and pointed at a hosted brain, it names that brain — where `recall`
+reads and every write lands — and then the folder on this disk, which `--local`
+reaches and which the before-edit hook reads.
+
+Pointed at one with no sign-in here (what `logout` leaves: token cleared,
+pointer kept), it names the **folder** first, because that is genuinely where
+the next write goes — nothing refuses, it falls through to the local brain.
+
+The third state is a sign-in left waiting by `login --emit-only`: it names the
+folder AND the waiting sign-in, because until somebody approves it the next
+command's claim is refused and the write lands in the folder — and once approved
+that same claim succeeds and everything goes to the hosted brain.
+
+In `--json`, read **`destination`**: `"hosted"`, `"local"`, or `"pending"`.
+`"pending"` is not a hedge — a sign-in waiting for approval lands writes in
+`brain` until somebody approves it and in the hosted brain after, and this
+command will not open a browser to find out which. Do not read
+`hosted.signed_in` for this: it is `false` for both the logged-out and the
+waiting state, and those go to different places. It reads state off the disk, so
+it answers with the server down and never finishes a sign-in just for being
+asked.
+
+`setup --agent --dry-run` is the one worth naming out loud, because the answer to
+"am I installed" lives behind a verb that otherwise installs. A tester who wanted
+the answer either avoided `setup` and had no answer, or ran it without
+`--dry-run`. It writes nothing at all — it reports.
+
+The hook itself is `memgineering guard`, deliberately absent from `--help`: it
+reads a PreToolUse payload on stdin and does nothing without one, so listing it
+would put "run this" in front of an agent for a command that cannot work when
+run. If a hook is misbehaving, that is the name to look for in the tool's hook
+config — not a command to invoke by hand.
+
+## Moving a brain between this machine and their account
 
 ```
-memgineering recall "anything"     # should answer, even if with "nothing matched"
-memgineering log                   # what this brain has recorded
+memgineering push                    # this folder → their account
+memgineering pull ~/my-brain         # their account → a folder here
 ```
 
+Both are safe to run twice and careful in opposite directions: **`push` never
+deletes anything locally, `pull` never overwrites anything locally.** Whatever
+was already there is left alone and counted, so an interrupted transfer finishes
+by running the same command again. `--dry-run` on either lists what would move.
+
+Reach for `pull` when they want a backup, are moving machines, or ask 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`. Readable files in a folder is not
+something to let them discover later.
+
+**One `pull` is one brain, not one account.** If the output names other hosted
+brains (`other_brains` in `--json`), this folder is not their memory — it is part
+of it. Run `pull --brain <name> <folder>` for each before telling them anything
+is backed up. A partial backup nobody knows is partial is worse than one that
+failed.
+
+What lands is markdown, not yet a brain here. Offer `memgineering link <folder>`
+as a next step rather than running it.
+
 ## Turning things off
 
 ```

package/assets/memgineering-writing/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: memgineering-writing
+description: Use when you learn something durable and should record it, when a conclusion you already recorded turns out to have changed, when something needs undoing or retiring, or when the user's `01_BASE/` files are still empty and only a conversation can fill them. Triggers include "remember this", "that didn't work", "this worked instead", "that's not right anymore", "undo that", "looks good", "set up my memory", "fill in my profile", "stop reading that note". Covers remember, revise, undo, log, retire, exclude, onboard, and what to say before writing.
+type: skill
+allowed-tools: Bash(memgineering:*)
+---
+
+# Writing to the user's brain
+
+Reading is `memgineering-recall`; decisions that bind an agent are
+`memgineering-rules`.
+
+## Recording what you learned
+
+```
+memgineering remember "the deadline moved to the 30th" \
+  --reason "they said so on the call and the old date is still written down"
+```
+
+Lands immediately and is recallable at once. No approval queue by design: the
+trade is permission-before for correction-after, and every write records how to
+reverse it. Do not ask permission for ordinary observations — write them, and
+mention it in a sentence.
+
+**`--reason` on every write.** It goes in the ledger and is the only part of the
+record that still means anything six months later. Every write verb takes it:
+`remember`, `revise`, `retire`, `exclude`, `undo`. The one on `undo` matters
+most — it is the moment an earlier conclusion turned out to be wrong. It is
+refused if it looks like it carries a credential; say what changed without the
+value rather than dropping the flag.
+
+```
+memgineering undo --reason "that belonged to the other project"   # the last change
+memgineering undo <op_id>      # a specific one
+memgineering log               # what changed, why, what can still be undone
+```
+
+**`log` labels the id with the verb that takes it.** `undo: <id>` means `undo`
+will accept that one; `op: <id>` means it will not. `undo` is last-in-first-out
+per note — only the most recent operation on a note can be taken back, and the
+one underneath becomes available again the moment it is — so `op:` covers an
+operation a later one wrote over, one already undone, one that is itself an
+undo, a note edited outside the tool since, and a verb that brain cannot reverse
+(a hosted brain cannot reverse an `exclude`; neither reverses an `import`). The
+id is still shown either way so you can quote it, and `--json` carries
+`superseded` on both a hosted brain and one in a folder, so you do not have to
+read the label.
+
+**An operation id is not a memory handle**, though they look alike. `open` takes
+handles from `recall`; ids from `log` name changes. Handed one anyway, `open`
+says what it actually is and which note it touched, rather than "nothing here
+matches".
+
+**Write down:** something that turned out to work a particular way; a choice
+that got made, by them or by you; **an attempt that failed, and what finally
+worked instead**; a constraint; a decision they stated; work of yours they
+looked at and confirmed. The failed attempt is the one most often skipped and
+the one that saves the most — without it the next session walks the same dead
+end.
+**Skip:** anything true only inside this conversation, and anything they said
+they did not want kept.
+
+**If it is a decision rather than a fact** — something they settled and expect to
+hold next time — it takes `--rule`. See `memgineering-rules`.
+
+**Write what you checked, not what you worked out.** A decision is whatever the
+user says it is. A fact is not: anything a command or a file could confirm —
+an address, an identifier, a version, a path, a number — goes in verified, or
+not at all. If you derived it from a pattern rather than reading it, check it
+first, or write the part you know and leave the rest out. A guess in a note is
+indistinguishable from a fact the next time it is recalled, and it will be
+recalled long after anyone remembers it was a guess.
+
+**Recall first, then pick the verb.** If what you learned answers a note that
+already exists, `revise` it. `remember` would leave two current notes on one
+subject and the next recall returns both — the re-discovery problem the user was
+trying to end. New subject → `remember`. Existing subject, now settled →
+`revise`.
+
+## Changing a conclusion
+
+```
+memgineering revise friday-review \
+  --claim "Fridays are for review. Nothing new goes out that day." \
+  --summary "no new work on Fridays"
+```
+
+- `--action supersede` (default) — the conclusion CHANGED. Stamps `valid_from`
+  with now, because a replaced conclusion starts now.
+- `--action reinforce` — same conclusion, new support. Leaves `valid_from` alone.
+- `--action conflict` — two notes DISAGREE. Records the edge, leaves both
+  standing, 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 exists to get right.
+
+**Re-recording something unchanged is refused** — otherwise a user repeating
+themselves becomes ledger entries recording no change. When you do mean "this
+still holds", say what confirms it: `--action reinforce --reason "<what confirms
+it>"`.
+
+This rewrites only the memory block in frontmatter. The prose is the user's;
+neither the command nor you should rewrite it uninvited.
+
+## Retiring versus excluding
+
+```
+memgineering retire <ref> --reason "the date moved"   # no longer current, still visible
+memgineering exclude path/to/note.md --reason "it has someone's phone number in it"   # stop reading it
+```
+
+Retiring keeps the note in recall, ranked last and labelled. Excluding takes it
+out of the index and never touches the file. If the user says "delete", ask
+which they mean.
+
+## Filling in the base files, which only you can do
+
+`init` leaves five files in `01_BASE/` as templates, because what goes in them
+cannot be typed into a form. `resurface` puts them at the top of every session,
+so an empty one costs something every time.
+
+```
+memgineering onboard
+```
+
+Says which are still untouched and what to ask for each. Run it first rather
+than working from a script — asking somebody a question they already answered is
+its own kind of forgetting. They may also ask outright ("set up my memory", "fill in my profile"); same job.
+
+```
+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, 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 — money, data, other people
+01_BASE/TOOLING.md         the apps, machines and commands they actually use
+```
+
+**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.
+
+**How to write it — both halves.** `revise` only touches frontmatter, so write
+the body FIRST with your normal file tools, replacing the template's prompt with
+what they actually said, then record the conclusion:
+
+```
+memgineering revise 01_BASE/USER.md \
+  --action reinforce \
+  --claim "<one line: who they are>" \
+  --summary "<the line recall should show>"
+```
+
+A claim written above an untouched template leaves the file reading as a
+half-filled form; `revise` warns when you do this, and the warning means go back
+and write the body. `--action reinforce`, not the default: these facts were
+always true and you have only just been told them, so 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** — `01_BASE/` only, and
+only while it is still the template. After that first pass these are theirs like
+any other note.
+
+**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 reads it
+as something the user said.
+
+## What to raise with the user
+
+The tool does not ask; you decide. Say something, once and plainly, when the
+output marks the target `⚠ critical target` (that is `01_BASE/`), when you are
+recording something said in passing that may be sensitive, or when what you
+learned contradicts a memory currently marked current. Everything else: do it,
+and mention it in a sentence.
+
+## Rules
+
+- **Never edit brain files with Read/Write/Edit**, except the one case above.
+  Only the CLI records the change and keeps `undo` working.
+- **Their notes are theirs.** Prose is never rewritten by this tool, and should
+  not be rewritten by you without being asked.
+- **Store full ids, not short handles**, anywhere durable. `open` prints the
+  full `id:` for exactly this.