memgineering 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -11,6 +11,98 @@ language the reader wants. The bilingual rule the monorepo applies to
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-08-29
+
+### Added
+
+- **A hosted brain's base files can finally be written.** `memgineering
+  base-write 01_BASE/USER.md --input <file|-|text>` fills or replaces the
+  body of a `01_BASE/` file on a hosted brain — the files `onboard` points
+  at, which until now could only be filled on a folder and left a hosted
+  brain reading as a blank form forever. The `memgineering:` block above
+  the body survives byte-for-byte, a body that would itself parse as
+  frontmatter is refused rather than stored as a note that invents its own
+  id, and replacing requires the revision a prior read handed you. On a
+  folder brain the verb refuses and names the file to open instead: there,
+  bodies belong to your own file tools, and that has not changed.
+- **The write is in the ledger, and `undo` takes it back.** A base write
+  records the same row every other change does; `undo` restores the
+  replaced body, or deletes the file when the write is the one that
+  created it. The replaced prose waits OUTSIDE the ledger, for 90 days —
+  the ledger records hashes and a reverse patch, never a note's text, and
+  an append-only copy of deleted prose would be one nothing screens. After
+  90 days the sweep takes it and that particular write can no longer be
+  reversed; the refusal says so plainly rather than calling it "expired".
+  The privacy page names this store and its window.
+- **Boundaries screen base writes too**, with one exemption: a note that
+  declares `never_store` words may say its own words in its own body —
+  which is what a BOUNDARIES.md is for — and that write carries the
+  `declared` mark in the ledger, so a crossing the record cannot name is
+  not possible. Other notes' declared words still refuse there.
+- **A draft leaves a ledger row the moment it exists.** `propose` (and the
+  hosted equivalent) now records that a draft was made, so a proposal that
+  expired unseen is visible in `log` instead of having never existed. The
+  row carries no patch and no hashes, because nothing changed: undoing it
+  is refused with the way out named — decide it, approve or reject. A bare
+  `undo` steps over a waiting draft rather than refusing because one is
+  pending, and `evidence` counts drafts on their own line instead of
+  inflating what changed.
+
+### Changed
+
+- **`revise` against a hosted brain now answers with the boundary words the
+  note actually holds**, parsed from the bytes that landed rather than the
+  ones that were sent. `--never-store-add` uses that answer instead of
+  reading the note back, so widening a boundary costs one round trip fewer
+  while the check that catches a server storing something other than what
+  it accepted stays exactly as strong. A server too old to answer that way
+  is detected by the absence and read back as before.
+- `revise --json` against such a server therefore carries a `never_store`
+  field.
+
+### Fixed
+
+- **The `undo` line printed after a `--local` write now says `--local`.**
+  It printed `--vault` or nothing, so on a machine signed in to a hosted
+  brain the suggested undo acted on the cloud brain — a suggestion that
+  failed when followed, on the exact machine `--local` exists for. Both
+  flags print when both were passed.
+- The refusal a folder brain gives `base-write` names the file to edit in
+  full; an earlier form truncated long paths, cutting off the one thing
+  the message exists to say.
+
+### Agent guidance
+
+- The `memgineering-writing` skill changed: onboarding branches on where
+  the brain lives (file tools on a folder, `base-write` on a hosted
+  brain), the line claiming no route can edit a base file's body is gone,
+  and the `propose` section says a draft leaves a ledger row and is closed
+  by deciding. **Restart your agent session after upgrading** so the new
+  guidance is what gets injected.
+
+### Note for older clients
+
+Two ledger verbs are new (`write`, `propose`). A CLI older than this
+release skips a line it does not recognise in a folder brain's ledger, and
+its bare `undo` then refuses outright rather than reversing the wrong
+thing — it stops instead of guessing. Upgrading both ends removes the gap.
+
+## [0.13.1] — 2026-08-28
+
+### Changed
+
+- **The README matches the CLI it ships with.** It had drifted in the ways
+  that mislead: "Nothing is uploaded" predated hosted brains (now: nothing is
+  uploaded until you `push` or connect one); the brain-resolution order
+  omitted the signed-in machine pointer, which outranks every folder rule;
+  the command table was missing thirteen verbs, including the entire account
+  group; and storage boundaries — the control "Your notes stay yours" is
+  about — were absent entirely. Also fixed: the environment table now lists
+  `MEMGINEERING_API_URL` and `MEMGINEERING_AGENT_HOME`, the tool list names
+  what `setup` actually installs into (Claude Code, Codex, Grok, Gemini CLI),
+  and `resurface`'s folder-local ranking signal is described as existing only
+  for a brain on this machine. No behaviour changed.
+
 ## [0.13.0] — 2026-08-28
 
 ### Added

package/README.md

@@ -3,9 +3,9 @@
 One memory for the AI you connect.
 
 Your notes stay in a folder you own. Every agent you use — Claude Code, Codex,
-Antigravity — reads and writes the same brain through one CLI, so what you told one
-of them is there for the next one, tomorrow, and in whatever tool you move to
-after that.
+Grok, Gemini CLI, anything that can run a command — reads and writes the same
+brain through one CLI, so what you told one of them is there for the next one,
+tomorrow, and in whatever tool you move to after that.
 
 **You do not have to run any of this yourself.** Ask whichever agent you are
 already talking to — "install memgineering and set it up" — and it does the
@@ -75,14 +75,23 @@ away.
 
 ## Your notes stay yours
 
-- **Nothing is uploaded.** The index is derived and lives outside your notes
-  folder; deleting it costs a rebuild and nothing else.
+- **Nothing is uploaded until you say so.** A brain is a folder on this disk;
+  only `push`, or connecting a hosted brain, carries notes to your account. The
+  index is derived and lives outside your notes folder; deleting it costs a
+  rebuild and nothing else.
 - **Prose is never rewritten.** `revise` only touches the memory block in a
   note's frontmatter. Your paragraphs are yours.
 - **You decide what is read.** `link` shows the actual lines that would be
   stored — not a description of them — before anything is indexed. Notes whose
   content looks like a credential are refused automatically; anything else you
   want left alone goes in `.memgdeny`.
+- **You decide what is never written.** Say "nothing about my health goes in
+  here" and the declaration is enforced, not advised:
+  `remember "…" --never-store "health, hospital"` records the boundary in your
+  own words, and any later write carrying one of them is refused with the word
+  and your declaration quoted back — whether or not the agent read anything
+  first. Widen it one word at a time with `revise --never-store-add`; retire
+  the declaration to lift it.
 - **`memgineering unlink --purge`** removes every trace this tool kept locally.
 
 ## Progressive reading
@@ -102,19 +111,23 @@ and read it" in a single call.
 
 ## Several brains
 
-A personal one, a team folder that syncs, one per repository. Which one answers
-is decided by where you are:
+A personal one, a team folder that syncs, one per repository, one in your
+account. Which one answers is decided in this order:
 
-1. `--vault <path>`
-2. a `.memgineering` pointer, found by walking up from the current directory
-3. the brain the current directory is inside
-4. the only one linked
+1. an explicit flag — `--vault <path>`, `--brain <name>` (a hosted brain, without
+   moving the machine's pointer), or `--local`
+2. the hosted brain this machine is pointed at, when you are signed in
+3. a `.memgineering` pointer, found by walking up from the current directory
+4. the brain the current directory is inside
+5. the only one linked
 
 If nothing settles it, memgineering refuses and lists the candidates rather
-than guessing. To bind a directory once — a repository root, say:
+than guessing. To bind a directory once — a repository root, say — or to point
+the whole machine at a hosted brain:
 
 ```bash
 memgineering use ~/brains/work    # writes a relative path when it can, so it commits
+memgineering use --brain "work"   # this machine now reads that hosted brain
 ```
 
 ## Starting a session
@@ -123,40 +136,74 @@ memgineering use ~/brains/work    # writes a relative path when it can, so it co
 memgineering resurface
 ```
 
-No query. It ranks by what has been recalled in this folder before, how
-recently, and which of your base notes have gone unread. `memgineering setup`
-can register it to run automatically when a Claude Code session starts.
+No query. It ranks by what has been recalled before, how recently, and which of
+your base notes have gone unread — a folder-local signal joins in when the
+brain lives on this machine. `memgineering setup` can register it to run
+automatically when a Claude Code session starts.
 
 ## Commands
 
-|                                     |                                                       |
-| ----------------------------------- | ----------------------------------------------------- |
-| `recall <query>`                    | recall memory cards for a question                    |
-| `open <ref>`                        | open one memory — by handle, id, path, or exact title |
-| `remember <text>`                   | write something down now                              |
-| `revise <ref>`                      | change a memory's conclusion                          |
-| `undo [op]`                         | take back the last change, or a named one             |
-| `resurface`                         | what is worth having in view, unasked                 |
-| `init <path>`                       | create a brain, laid out and ready                    |
-| `link <path>`                       | read notes you already keep                           |
-| `use [brain]`                       | bind this folder to one brain                         |
-| `push` · `pull`                     | carry a brain to your account, and back down again    |
-| `unlink` · `reindex` · `sync-rules` | brain housekeeping                                    |
-| `log`                               | what changed, and what can still be undone            |
-| `retire` · `unretire`               | mark a memory no longer current, or current again     |
-| `exclude` · `unexclude`             | stop reading a note entirely, or resume               |
-| `setup`                             | install into your agents                              |
-| `update`                            | update memgineering itself                            |
+**Memory — day to day**
+
+|                   |                                                       |
+| ----------------- | ----------------------------------------------------- |
+| `recall <query>`  | recall memory cards for a question                    |
+| `open <ref>`      | open one memory — by handle, id, path, or exact title |
+| `evidence <ref>`  | how much a memory has been used, and why it changed   |
+| `remember <text>` | write something down now                              |
+| `revise <ref>`    | change a memory's conclusion                          |
+| `undo [op]`       | take back the last change, or a named one             |
+| `resurface`       | what is worth having in view, unasked                 |
+| `rules`           | the standing decisions that bind here                 |
+
+**Brain — set up and point**
+
+|                                     |                                                                          |
+| ----------------------------------- | ------------------------------------------------------------------------ |
+| `init <path>`                       | create a brain, laid out and ready                                       |
+| `onboard`                           | what to ask so it knows who it belongs to                                |
+| `link <path>`                       | read notes you already keep                                              |
+| `use [brain]`                       | bind this folder — or, with `--brain`, point the machine at a hosted one |
+| `unlink` · `reindex` · `sync-rules` | brain housekeeping                                                       |
+| `log`                               | what changed, and what can still be undone                               |
+
+**Curation — occasional**
+
+|                         |                                                     |
+| ----------------------- | --------------------------------------------------- |
+| `retire` · `unretire`   | mark a memory no longer current, or current again   |
+| `exclude` · `unexclude` | stop reading a note entirely, or resume             |
+| `consolidate`           | find memories worth merging — reads, writes nothing |
+| `propose <action>`      | draft a change for approval — writes no note        |
+| `proposals`             | review what is waiting — approve, reject, rebase    |
+
+**Account — optional; everything above works without it**
+
+|                                      |                                                     |
+| ------------------------------------ | --------------------------------------------------- |
+| `login` · `logout` · `whoami`        | the account session on this machine                 |
+| `brains`                             | list your hosted brains, and which one answers here |
+| `create` · `rename` · `delete-brain` | make, rename, or delete a hosted brain              |
+| `push` · `pull`                      | carry a brain to your account, and back down again  |
+
+**System**
+
+|          |                            |
+| -------- | -------------------------- |
+| `setup`  | install into your agents   |
+| `update` | update memgineering itself |
 
 Every command takes `--json`.
 
 ## Environment
 
-|                            |                                                     |
-| -------------------------- | --------------------------------------------------- |
-| `MEMGINEERING_HOME`        | state and derived index (default `~/.memgineering`) |
-| `MEMGINEERING_JSON=1`      | force JSON output without the flag                  |
-| `MEMGINEERING_NO_UPDATE=1` | skip the version check for one run                  |
+|                            |                                                              |
+| -------------------------- | ------------------------------------------------------------ |
+| `MEMGINEERING_HOME`        | state and derived index (default `~/.memgineering`)          |
+| `MEMGINEERING_JSON=1`      | force JSON output without the flag                           |
+| `MEMGINEERING_NO_UPDATE=1` | skip the version check for one run                           |
+| `MEMGINEERING_API_URL`     | hosted brain server (default `https://api.memgineering.com`) |
+| `MEMGINEERING_AGENT_HOME`  | where `setup` installs agent files (default: your home)      |
 
 ## A brain that is not on this machine
 

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.13.0
+version: 0.14.0
 ---
 
 # memgineering

package/assets/memgineering-writing/SKILL.md

@@ -205,7 +205,10 @@ memgineering propose supersede --memory <id> --claim "…" --reason "…" --exce
 memgineering propose reclassify --memory <id> --kind decision --reason "…" --excerpt "…"
 ```
 
-`propose` is where the judgement goes in, and it still writes no note. The
+`propose` is where the judgement goes in, and it still writes no note — but it
+does leave a ledger row the moment the draft exists, so `log` shows a draft
+that later expired unseen instead of pretending it never was. Undoing that row
+is refused on purpose: a draft is closed by deciding it, approve or reject. The
 actions are `supersede`, `reinforce`, `conflict`, `retire`, `unretire` and
 `reclassify` — the same vocabulary `revise` uses, plus the one that only changes
 what sort of memory it is. **`--excerpt` is required for every one of them**,
@@ -290,9 +293,20 @@ its own kind of forgetting. They may also ask outright ("set up my memory", "fil
 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:
+**How to write it — both halves.** `revise` only touches frontmatter, so the
+body comes first, and how you write it depends on where the brain lives. On a
+folder: your normal file tools, replacing the template's prompt with what they
+actually said. On a hosted brain there are no files — the body goes through the
+verb built for exactly this:
+
+```
+memgineering base-write 01_BASE/USER.md --input -
+```
+
+(`--input` takes a file, `-` for stdin, or the text inline. Only `01_BASE/`
+files — an ordinary note's body is never written this way. The write lands in
+the ledger and `undo` can take it back, though not forever: the replaced body
+is kept 90 days.) Then record the conclusion either way:
 
 ```
 memgineering revise 01_BASE/USER.md \
@@ -384,9 +398,12 @@ which you meant.
 To lift a boundary entirely: `memgineering retire <the declaration>`. That is
 the un-declare path, and it is the user's decision, never yours.
 
-On a hosted brain the declaration NOTE is the record — there is no route that
-edits a base file's body, so mirroring the sentence into `BOUNDARIES.md` is a
-folder-brain and onboarding-time thing.
+On a hosted brain the declaration NOTE is the record, and since 0.14.0 the
+sentence can ALSO live in `BOUNDARIES.md` itself: `base-write` fills a base
+file's body where there are no files to edit. A boundary note may say its own
+declared words in its own body — that write carries the `declared` mark in the
+ledger — but OTHER notes' declared words still refuse there like everywhere
+else.
 
 ### When a write is refused