minnimemory 1.0.0-beta.1 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+All notable changes to the `minnimemory` package. Dates are publish dates; an entry that has not
+been published yet says `unreleased` and gets its date on the day it goes out.
+
+## 1.0.0 - 2026-09-27
+
+The first stable release. Prepared 2026-09-22, published 2026-09-27 as `latest`; `1.0.0-beta.2`
+(2026-09-18) stays on the `beta` tag.
+
+- Changed (2026-09-27): `init` opens with the map of every file Claude Code loads for the
+  project, from Claude Code's documented rules: managed policy, user `CLAUDE.md` and
+  `~/.claude/rules/`, `CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md` here and in every
+  folder above, `AGENTS.md` when no `CLAUDE.md` exists, recursive and `paths:`-scoped rules,
+  subfolder files, imports and auto memory, each with when it loads, whose it is and its tokens.
+  `--map` prints only the map.
+- Added: `install` registers an `InstructionsLoaded` hook (`minnimemory loaded`) that records what
+  Claude Code actually loads per project, machine-local; `init` checks its map against it and
+  `doctor` reports a file Claude loaded that the map missed (MM016). `install --remove` removes it.
+- Fixed: the always-loaded total now counts user rules, the managed policy file, parent folders'
+  CLAUDE files and nested rules, and no longer counts `paths:`-scoped rules; a host at
+  `.claude/CLAUDE.md` is found and compiled with its manifest at the project root.
+
+- Fixed (2026-09-27, macOS dev run): the auto-memory folder and the load log are found the way
+  Claude Code keys them. A project reached through a symlink (macOS `/tmp` and `/var` point into
+  `/private`, or a `~/dev` linked to another drive) is keyed by its real path, with the path as
+  typed as a fallback; a git worktree, and any folder inside it, shares the main checkout's
+  folder, as the Claude Code memory docs say. Before, both missed that memory. doctor's note on a
+  repo's own `autoMemoryDirectory` now says Claude Code does use it in a trusted folder and that
+  minnimemory still does not follow it (the 2026-09-26 security decision stands).
+- Fixed (2026-09-27, end-to-end dev run): an `@path` import line in a section apply routes out
+  now stays in the always-loaded file, under `## Imports`. Claude Code follows imports only from
+  files it loads at session start, so a routed import had silently stopped its file loading.
+
+- Fixed (2026-09-27, hands-on audit of the map): `AGENTS.md` is read when the only CLAUDE file
+  above is the user's own `~/.claude/CLAUDE.md` or an excluded one (the map was empty for an
+  AGENTS.md repo under the home folder). Printed commands use forward slashes, so Git Bash no
+  longer strips a Windows target path. The map says when its subfolder scan stopped at its cap;
+  `doctor` and the drift hook skip that scan, and MM016 builds the map only once a load log
+  exists (doctor on a 6,000-folder tree: 4.3 s to 0.2 s). `loaded` resolves a relative path
+  against the session's folder, and the map ignores logged files that no longer exist.
+
+- Fixed (2026-09-27, messy-developer live proof): a hand edit apply has nothing to route out of (a
+  sorted rule file, or `MEMORY.md` outside its list) is kept byte for byte and taken as the new
+  baseline, so the MM010 drift it raised clears; before, `apply` said "nothing to apply" and the
+  drift never cleared. The accepted file is backed up under `previous/`, so `undo` still names it.
+  `undo` with `force: true` over MCP returns a command that carries `--force`.
+- Fixed (2026-09-27, pre-publish audit): a project host file's budget is now that file's alone.
+  The user-level `~/.claude/CLAUDE.md`, its imports, the auto-memory index and `.claude/rules`
+  stay in MM001 (the audit line) but no longer enter the plan's before/after, share or manifest, so a machine with a
+  large user-level memory no longer compiles every project `CLAUDE.md` down to its title line,
+  and the MCP server's plan (made without the user-level host unless launched with
+  `--include-auto-memory`) hashes the same as the CLI's, so the printed `apply --plan` runs.
+- Fixed: `install` quotes the arguments it hands the shell on Windows, so a cli path with a
+  space (`C:\Users\First Last\...`) registers as one argument and the server starts.
+- Fixed: a source that is not valid UTF-8 is refused instead of rewritten (and backed up) with
+  replacement characters; a CRLF source is rewritten with CRLF.
+- Fixed: `undo` refuses without `--force` when a compiled file was edited since the last apply
+  or the workspace was re-applied since the first, naming what it would discard.
+- Fixed: MM008 also recognises `sk-proj-` OpenAI keys, AWS secret access keys and plain
+  `password:`/`api_key=` assignments that look like a real value.
+- Fixed: `.minnimemory/.gitignore` (replacing `original/.gitignore`) keeps `original/`,
+  `previous/` and the drift stamp out of git; a re-apply of an older workspace adds it.
+- Fixed: the memory-folder plan no longer says "nothing here is volatile" beside a routed
+  history piece, or offers a budget that saves a negative number; the CLI's dry-run line prints
+  the apply command on its own line; `install` warns when it registers a copy in the npx cache;
+  a `--budget -5` error says how to write it.
+
+- Changed (2026-09-27, workflow audit): over MCP, `apply` and `undo` return the command to run
+  (`npx -y minnimemory apply --plan <hash> [target]`, `npx -y minnimemory undo [target]`) and
+  the operation list with paths and line deltas, never file content, unless called with
+  `content: true` (for a host that cannot run commands). An `apply` on the example file went
+  from about 3,500 tokens to about 240; on an 85-file memory folder from about 13,400 to about
+  300 (moves are grouped by destination). The command names the target whenever it is not the server root (absolute for the
+  auto-memory folder) and always uses the `npx` form, so it runs as printed; the CLI's `init`
+  and `doctor` print the same real command (`init` used to print a literal `<hash>`).
+- New (2026-09-27): verdict `sort`. A memory-folder plan that recompiles no always-loaded file
+  and only moves loose topic files says so, with what the sort costs or saves per turn, instead
+  of "compile ... saves -173 tokens".
+- Changed (2026-09-27, MCP live proof): the operations block prints paths relative to the root
+  the header names, groups backups and moves per destination folder, and `doctor`/`init` over
+  MCP show four findings per rule (`format: "json"` keeps every one). On a real 78-file memory
+  folder a summary `doctor` went from about 11,000 tokens to about 3,500 and `apply` from about
+  3,300 to about 900. The CLI prints the same shorter block.
+- Fixed (2026-09-27, MCP live proof): `apply` is a fixed point. The command `apply` returns
+  (and the CLI's next-step line) carries the budget the plan was made with, `--force` on a leave
+  verdict and the CLI's own `--profile`/`--episodic-json`, so the hash is recomputed from the
+  same plan (a real agent got "the plan on disk no longer matches" for a plan made at `--budget
+  12000`). The plan's `after` now counts the user-level CLAUDE.md import lines growing by
+  `AlwaysOnMemory/`. The manifest records the budget it was applied with, and a re-apply with no
+  `--budget` or the same one leaves every undrifted compiled source alone instead of re-sharing
+  the pool over the trimmed sizes and trimming again; a different `--budget` recompiles.
+- Fixed (2026-09-27, MCP live proof): `install` writes the user-scope drift hook into the
+  Claude Code config dir's `settings.json` (`CLAUDE_CONFIG_DIR` when set), not always `~/.claude`;
+  under a relocated config dir it wrote the hook into the wrong file. The commands the tool
+  prints call the installed copy directly (`node "<path>/cli.js" apply ...`) when the CLI knows
+  where it runs from, so the plan hash is recomputed by the build that made it; `npx -y
+  minnimemory` is the fallback.
+- Fixed (2026-09-27, live proof): a memory saved into a topic file the sort only moved is no
+  longer reported as drift by `doctor` or the drift hook; MM010 checks the files the tool
+  rewrote and the routed pieces, as DESIGN.md 6.11 decision 3 always said. The sorted index's
+  header now names the folder its paths are relative to (in full for the machine-local Claude
+  Code memory folder), after the live proof's agent resolved `OnDemandMemory/pc_setup.md`
+  against the project directory first and wasted two reads.
+- Fixed (2026-09-27): the drift hook now also checks the project's Claude Code auto-memory
+  folder, whose `.minnimemory/` lives outside the project; it never fired there before. The
+  hook costs about 0.15 s per prompt (was 0.35 s): the CLI loads the MCP SDK only for the
+  `mcp` command.
+- Changed (2026-09-27): `install` registers the MCP server as a direct call to the installed
+  copy (`node "<path>/cli.js" mcp`), the same form as the drift hook, so Claude Code does not
+  re-resolve the package through `npx` on every launch; a registration that runs a different
+  command is repointed on the next `install` without `--force`. `npx -y minnimemory mcp` stays
+  the form for other hosts' JSON snippets and when `install` cannot tell where it runs from.
+- Fixed (2026-09-27): `apply` renders its report before writing, so every write shows its real
+  line delta (was `+0 -0`) and an empty `diff:` header no longer appears; it ends with what it
+  wrote and the undo command. `doctor`'s drift lines and the MCP error for an unflagged
+  `auto-memory` target name the exact command to run next.
+- First stable release. Same four verbs as the betas: `doctor`, `init`, `apply`, `undo`, in the
+  terminal and over MCP (`--profile basic`, the default); the seven-tool `--profile full` is unchanged.
+- New: `init` and `doctor` are one preview. Both print the audit, then a unified diff of every
+  file `apply` would write, then the next step ("run apply", or "nothing to apply"). `doctor`
+  keeps its CI exit code. `init` is the first-time name, `doctor` the returning one.
+- New: memory folders compile. `apply`/`undo` on an index plus topic files, or on a
+  project's Claude Code auto-memory folder, used to answer "nothing to compile"; now every
+  always-loaded topic file the index (or the user-level host) imports sorts into
+  `AlwaysOnMemory/`, trimmed in place; every other topic file sorts into `OnDemandMemory/`,
+  untouched; routed pieces join it there, one piece per parent per reason
+  (`<parent>__history.md`, `<parent>__detail.md`), not one per section. A project root goes
+  through the same engine: the host file is trimmed in place, routed pieces land in
+  `.claude/OnDemandMemory/`. `undo` puts every file back byte for byte, including a workspace
+  compiled by the pre-reorganization layout (manifest v4/v5), which `doctor` now names as such
+  and `apply`/`init` refuse ("run undo, then apply") rather than compile over it. DESIGN.md 6.10.
+- New: `apply` returns operations (copy, move, write, delete) instead of full file content for a
+  backup or a sorted move, and carries a `plan` hash plus the exact `npx -y minnimemory apply --plan
+  <hash> [target]` command; the CLI's `apply` gains `--plan <hash>` and refuses when the plan on disk no
+  longer matches. Drift (MM010) tracks only what the tool wrote: a file saved into
+  `AlwaysOnMemory/`/`OnDemandMemory/` by hand is not drift. DESIGN.md 6.11.
+- New: `doctor`/`init` take `diff: "summary"` (default over MCP) or `"full"`: the plan table plus
+  one line per file (action, path, lines added/removed), with the import rewrite and every move/
+  delete still shown in full. The CLI keeps the full diff by default. DESIGN.md 6.10.
+- New (revised 2026-09-27): on a memory folder the import is the placement decision. Every
+  stable section of an imported file is a candidate to stay, whatever its heading says;
+  "volatile" means a status heading, a changelog-shaped body or repeated status phrases, never
+  a date cited in a rule's rationale (`doctor`'s MM003 reads imported files the same way). With
+  no `--budget` every stable section stays and only volatile sections move; when nothing is
+  volatile the plan says so and names what a lower budget would save, from a real second plan.
+  A lower `--budget` is shared fairly (a file that fits an equal share stays whole, the largest
+  files split the rest) and a heading-less file over its share keeps its leading paragraphs and
+  routes the rest as `<name>__detail.md`. A single host file keeps the flat 2,000 default. The
+  first cut (a proportional share of half the sources, hint-matched headings, the lenient
+  volatility scorer) hollowed the maintainer's own rule files to frontmatter shells. DESIGN.md
+  6.10, decision 8.
+- New: the always-loaded count includes `.claude/rules/*.md` and `CLAUDE.local.md`, which Claude
+  Code also auto-loads beside the host file, alongside the user-level `~/.claude/CLAUDE.md` and
+  its imports (behind `--include-auto-memory` over MCP; always in the terminal).
+- Changed: when a project has no memory file but its auto-memory folder exists and was not
+  included, the error names the folder and the flag instead of listing places it did not look.
+- Changed: over MCP, `apply` and `undo` accept the `auto-memory` target behind
+  `--include-auto-memory`, like `doctor` and `init`; paths outside the server root come back
+  absolute, with the folder named.
+- Changed: `undo` gains `--force` (`force: true` over MCP) for a memory folder whose routed
+  files were edited since the last apply.
+- Changed (2026-09-27): `install` writes the drift hook as a direct call to the installed CLI (`node "<path>/cli.js" drift`) instead of `npx -y minnimemory drift`: about 0.3 s per prompt instead of 1.3 to 1.7 s. An existing npx entry is updated in place; re-run `install` after an upgrade. `init()`'s MCP description is one line (basic tools/list 986 -> 940 tokens). The plan's verdict line states the per-turn arithmetic: the saving on a turn with no routed file open and the extra cost on a turn with every routed file open.
+- Fixed (2026-09-27): `doctor`, `apply` and `undo` given the host file's path on a compiled workspace now read that workspace (they used to see a bare file, plan to strip its fenced list, and find nothing to undo). apply's write guard for a memory folder allows exactly the user-level host file outside the folder, not its whole directory. The MEMORY.md-as-host message points at `doctor`/`apply` on the folder. Dead write-protocol module and five unreachable exports removed. README, GUIDE and the site transcript regenerated from a real 1.0.0 run.
+- New: `minnimemory drift`, a Claude Code `UserPromptSubmit` hook that prints one short notice when
+  a memory file changed since the last `apply`, once per change, nothing when clean.
+  `minnimemory install` turns it on by default now; `--no-hook` opts out.
+- New: `minnimemory install --remove` removes the MCP registration and the drift hook `install`
+  added, leaving every other key and every other hook in Claude Code's settings untouched; every
+  successful `install` path prints the next step in one line.
+- New: the `apply` refusal on a source too small to benefit (verdict "leave"), in the CLI and
+  over MCP, shows the always-loaded token count before and after, and the break-even figure.
+- Removed: the compiler no longer adds section anchors to the OnDemandMemory list. They raised the
+  always-loaded prefix on every turn against a saving that was only ever projected, and no freshly
+  compiled workspace could produce one. Compiled output is otherwise unchanged. `doctor`'s MM014
+  stays, so a workspace compiled by an earlier version still gets told what its anchor lines cost.
+- The package ships as a minified bundle (`pkg/`) with one public declaration file. Behaviour is
+  unchanged.
+- The generated instruction block carries a one-line MinniAI copyright notice, and the LICENSE
+  gains a clause on the generated instructions. The LICENSE no longer calls itself a beta license.
+- Claude Code is the only supported host; the README no longer documents other hosts.
+- README rewritten terminal-first: install, first doctor, apply, undo, then use, commands,
+  security and license.
+
+## 1.0.0-beta.2 - 2026-09-18
+
+- `minnimemory install` registers the server with Claude Code in one command; running the bare
+  package with no TTY starts the server, so MCP hosts can launch it directly.
+- Shipped comments and strings scrubbed of internal paths; a leak check runs before every publish.
+
+## 1.0.0-beta.1 - 2026-09-17
+
+- First public release on npm.

package/LICENSE

@@ -1,39 +1,45 @@
-MinniMemoryMCP License (Beta)
-
-Copyright (c) 2026 MinniAI. All rights reserved.
-
-1. Grant. MinniAI gives you a free, non-exclusive, non-transferable, revocable
-   license to install and run this software package (the "Software"),
-   unmodified, for your own use. Use inside your own company or for your own
-   commercial projects is allowed.
-
-2. Restrictions. You may not:
-   (a) copy, redistribute, sublicense, sell, rent or host the Software for
-       others;
-   (b) modify, translate or create derivative works of the Software;
-   (c) reverse engineer, decompile or disassemble the Software, except where
-       applicable law forbids this restriction;
-   (d) remove or alter any copyright or license notice in the Software.
-
-3. Your files. The files the Software reads or writes on your machine (memory
-   files such as CLAUDE.md, the .minnimemory folder, backups) are yours.
-   MinniAI claims no rights in them. The Software makes no network calls and
-   sends nothing off your machine.
-
-4. Beta software. This is a pre-release version. Features, output and
-   behaviour may change between versions without notice.
-
-5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
-   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-   Back up your files before using write features such as --allow-write.
-
-6. Limitation of liability. IN NO EVENT SHALL MINNIAI BE LIABLE FOR ANY
-   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
-   OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
-   THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.
-
-7. Termination. This license ends automatically if you break any of its
-   terms. When it ends, stop using the Software and delete your copies.
-
-8. Contact. https://minniai.com
+MinniMemoryMCP License
+
+Copyright (c) 2026 MinniAI. All rights reserved.
+
+1. Grant. MinniAI gives you a free, non-exclusive, non-transferable, revocable
+   license to install and run this software package (the "Software"),
+   unmodified, for your own use. Use inside your own company or for your own
+   commercial projects is allowed.
+
+2. Restrictions. You may not:
+   (a) copy, redistribute, sublicense, sell, rent or host the Software for
+       others;
+   (b) modify, translate or create derivative works of the Software;
+   (c) reverse engineer, decompile or disassemble the Software, except where
+       applicable law forbids this restriction;
+   (d) remove or alter any copyright or license notice in the Software.
+
+3. Your files. The files the Software reads or writes on your machine (memory
+   files such as CLAUDE.md, the .minnimemory folder, backups) are yours.
+   MinniAI claims no rights in them. The Software makes no network calls and
+   sends nothing off your machine.
+
+4. Generated instructions. The instruction text, rule text and structure
+   that the Software writes into your memory files (the "Generated
+   Instructions") are MinniAI's copyrighted work. You may keep and use them
+   in memory files on machines you control, for your own or your company's
+   AI agents. You may not extract, republish, redistribute or sell the
+   Generated Instructions, include them in another product or service, or
+   use them, in whole or in part, as training or evaluation data for a
+   machine learning model.
+
+5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+   Back up your files before using write features such as --allow-write.
+
+6. Limitation of liability. IN NO EVENT SHALL MINNIAI BE LIABLE FOR ANY
+   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
+   OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
+   THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.
+
+7. Termination. This license ends automatically if you break any of its
+   terms. When it ends, stop using the Software and delete your copies.
+
+8. Contact. https://minniai.com