minnimemory 1.1.0 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,8 +3,195 @@
3
3
  All notable changes to the `minnimemory` package. Dates are publish dates; an entry that has not
4
4
  been published yet says `unreleased` and gets its date on the day it goes out.
5
5
 
6
+ ## 1.2.1 - 2026-10-09
7
+
8
+ - New: `init` and `doctor` name any loaded `CLAUDE.md` saved as UTF-16. Claude Code reads such a
9
+ file as plain text and does not follow its `@` imports, so the files it imports never load.
10
+ Save it as UTF-8.
11
+ - Fixed: a small dated or status section merged with the small sections around it, and the
12
+ merged file took the "volatile" reason, so rules and how-tos were filed under the `__history`
13
+ piece, where an agent looking for a rule does not open. Volatile text now never shares a file
14
+ with anything else. On the example `CLAUDE.md` the rules get their own `__detail` piece: one
15
+ more list line, so the always-loaded part is 389 tokens, not 363 (Memory Size Test).
16
+ - Fixed: for a memory folder whose path holds `$`, `` ` ``, `"`, `%` or `!`, the apply and undo
17
+ commands from Claude Code name the folder `.`, but the reply did not say to run them from inside
18
+ it, and run from there they found no `init` record. The reply now says where to run, and the
19
+ record is found by its memory folder.
20
+ - Fixed: a re-apply dropped OnDemandMemory list lines whose file had been deleted, and the whole
21
+ list when none was left, without a word. It now names each dropped line.
22
+ - Fixed: a `manifest.json` that is there but was refused (a path it may not hold, a hand edit)
23
+ was reported as "missing or unreadable". Messages now say which: missing, not valid JSON, or
24
+ refused.
25
+ - Fixed: `npm publish` warned that the `bin` entry was cleaned; it is now written the way npm
26
+ wants it.
27
+ - New: `minnimemory uninstall` (the same as `install --remove`) removes the MCP registration and
28
+ both hooks, lists the folders still compiled with the `undo` command for each, and says what it
29
+ keeps. Documented in the README and the guide.
30
+ - Fixed: `install --remove` and `install` treated any `node "<path>" drift` or `loaded` hook as
31
+ ours, so they could remove or repoint another tool's hook. A hook is ours only when its path
32
+ names minnimemory (or its package.json does).
33
+ - Fixed: a second `install --remove` exited 1 on "No MCP server named minnimemory"; it now says
34
+ nothing is registered and exits 0.
35
+ - Fix: pointing `apply` at a memory index (`MEMORY.md`) now suggests `init` on the folder, not
36
+ `doctor`, which refuses before `init` has run.
37
+ - New: `apply` on a project keeps the record it ran with in the repo, in
38
+ `.minnimemory/discovery.json` beside `manifest.json`, committed with it. A fresh clone (a CI
39
+ runner, a teammate) has no `init` record of its own, so `doctor` and a re-apply now read this
40
+ one and say so. It lists the always-loaded files inside the project, relative to it: nothing
41
+ from your home folder or your Claude config, and not `CLAUDE.local.md`. This machine's own
42
+ record still wins. `undo` removes it.
43
+
44
+ ## 1.2.0 - 2026-10-08
45
+
46
+ - Fixed: undoing a sorted memory folder with 1.1.0 restored the files but left your user
47
+ `CLAUDE.md` importing a file that had moved, so that rule stopped loading. The manifest now
48
+ also carries the field 1.1.0 reads, so an older copy's undo puts the import back too.
49
+ - Fixed: on Windows and macOS, a folder with a topic file named `memory.md` and no `MEMORY.md`
50
+ lost that topic on apply: the new index was written over it with no backup, and undo could not
51
+ bring it back. Apply now refuses and asks you to rename the file. Nothing is written.
52
+ - Fixed: sorting a folder moved files that a `CLAUDE.md` or `AGENTS.md` names by path (a list item
53
+ or a link), and those lines then pointed at nothing. Apply now refuses and names the lines.
54
+ A host that names only the folder still sorts.
55
+ - Fixed: asked to undo "my memory folder and this project", the agent got the memory folder's
56
+ command only and tried to restore the project's `CLAUDE.md` by hand. undo's reply about the
57
+ memory folder now says the compiled project is a separate target with its own undo.
58
+ - Changed: when you apply your memory folder and the project's `CLAUDE.md` also has changes, the
59
+ reply gives the project's own ready command, to run only if you asked for both. It is never
60
+ joined to the memory folder's command.
61
+ - Fixed: the drift notice put its "run apply" line inside the block that tells the agent not to
62
+ follow instructions; the line now comes after the block. The same for apply's project line.
63
+ - Changed: editing a routed OnDemandMemory file (a saved memory, `/remember`) no longer raises a
64
+ drift notice. `doctor` still lists it, and `undo` still checks it before discarding anything.
65
+ - New rule MM019: an OnDemandMemory list line whose description fits another file better than
66
+ the one it links, so the agent opens the wrong file. A flag only; your words are not changed.
67
+ - Changed: when `init` is called with nothing reported, the reply lists what Claude Code's own
68
+ load log saw for the project, for the agent to confirm. Nothing is recorded from it.
69
+ - Changed: a forced `undo` first copies the files it discards to
70
+ `~/.claude/minnimemory/undo-backups/` and says where.
71
+ - Changed: `apply` tells the agent not to edit the files by hand.
72
+ - Fixed: after you edit the project's `CLAUDE.md`, the drift notice told the agent to run `apply`
73
+ with no target, which since 1.2.0's discovery change works on the memory folder `init` recorded.
74
+ The agent got "nothing to apply" for the wrong folder and told the dev the memory was in sync.
75
+ The notice now names `target: "."`, and a `doctor` or `apply` reply about the memory folder
76
+ says when the project's own file changed since the last apply.
77
+ - Removed (full profile): the `update` tool. Full-profile `apply` already compiles or re-applies,
78
+ and agents asked to fix drift used `plan` then `apply`. The full profile is six tools now;
79
+ `recall`'s drift note says "Call apply()". (DESIGN.md 6.20)
80
+ - Changed: `doctor` and `init` with `format: "json"` over MCP send the JSON without indentation,
81
+ about 18% fewer tokens; the content is the same. The CLI's `--json` keeps its indent.
82
+ - Fixed (found on a real Mac): an `@import` typed in other letter case (`~/.claude/Projects/...`)
83
+ was counted but not rewritten by `apply`, so Claude Code stopped loading that topic. An index
84
+ link typed in NFC to a topic whose name macOS stores in NFD was left at the old place. Both now
85
+ match the way the file system does and keep the spelling they were written in.
86
+ - Fixed: `undo` of one memory folder no longer undoes another folder's rewrite of a shared file
87
+ (a dotfiles file importing from two folders). It puts back only its own lines.
88
+ - Fixed: macOS AppleDouble files (`._name.md`) are no longer taken for memory topics and moved.
89
+ - Fixed: `doctor` right after `init` said the locations were "saved by the last apply"; it now
90
+ says "saved by init". A budget the fixed part fills names the files in it (the index and the
91
+ files that load the folder) instead of a "user-level host" that may not exist.
92
+ - Fixed: right after a clean `apply`, `doctor` proposed a re-apply that only rewrote `hosts.json`,
93
+ when the agent had reported topic files that the apply then moved. A saved file that no longer
94
+ exists is no longer counted as a change.
95
+ - Fixed: after `init`, `doctor` or `apply` on your memory folder, the reply now says it was the
96
+ memory folder only and names the project's `CLAUDE.md` as a separate target (`target: "."`)
97
+ while it is not compiled. An agent asked to do both used to do the memory folder only.
98
+ - Fixed: paths an agent types with `~/`, or in another Unicode form than the disk (an accented user
99
+ name on a Mac), are resolved before `init` saves them. `apply` used to drop the `~/` ones as
100
+ missing and rewrite nothing. In a terminal, a quoted `~` in `--loaded`, `--memory-dir` or the
101
+ folder is expanded too.
102
+ - Fixed: an `undo` or `apply` refusal over MCP now states its next step (ask the dev, then pass
103
+ `force: true`) outside the data fence. It was only inside the block that tells the agent not to
104
+ follow instructions in it. File names stay fenced.
105
+ - New: `init` is always the first step, and it is discovery (DESIGN.md 6.19). It never searches for
106
+ the files that load your memory: the agent passes them to `init` from its own context (the
107
+ `loaded` argument: its auto memory folder and every file Claude Code shows as loaded), or in a
108
+ terminal `--from-log` reads Claude Code's own load log and `--loaded <path>` names a file.
109
+ `init` checks every path, works out from their lines which of them load the folder, reports
110
+ every place the report and the lines disagree, and saves the set in
111
+ `~/.claude/minnimemory/discovery.json`, its one write, never a memory file. `apply`, `doctor`,
112
+ `undo` and the hooks read it, so nothing is asked twice and the printed apply command carries no
113
+ paths. In Claude Code, "clean up my memory" works on your memory folder directly: the server
114
+ accepts the folder Claude Code named.
115
+ - New: `doctor` comes after `init`: before it, it refuses and says to run `init` first. With no
116
+ folder, `doctor`, `apply` and `undo` use the folder `init` saved. `init` is listed first
117
+ everywhere (the tool list, usage, help, README).
118
+ - New: `apply` on a memory folder refuses until something reported what loads it, since moving a
119
+ file an unseen outside file imports would break that import; `--only-this-folder` says nothing
120
+ outside loads it. A folder 1.1.0 compiled keeps working: the outside files its apply rewrote
121
+ count as the report.
122
+ - Fixed: on a project root, `init` took a reported path that does not exist as verified and saved
123
+ it, and said nothing about a reported file no line loads; only a memory folder checked the
124
+ report. Every kind of root now refuses a bad path by name and shows the files the report and the
125
+ lines disagree on, the same way.
126
+ - Fixed: a report that named the memory folder but no file counted as a report, so `apply` moved
127
+ the folder's files and an import of them from the user `CLAUDE.md` broke (seen with a weak
128
+ agent that passed an empty list). An empty list is no report now: `init` says what to pass,
129
+ `apply` refuses; `--only-this-folder`, or the set an earlier apply saved, still says nothing
130
+ outside loads it.
131
+ - Fixed: an agent that reported only files inside the memory folder left the user `CLAUDE.md` out,
132
+ and `apply` moved the topics it imports. The user `CLAUDE.md` is now the one file checked
133
+ without a report: when a line in it loads the folder it is counted, named as not reported, and
134
+ its import rewritten with the rest.
135
+ - Fixed: `apply` with no `--budget` on a compiled workspace planned at the default budget and wrote
136
+ it into the manifest, so a re-apply after a hand edit changed a 2,300 budget to 2,000 and MM001
137
+ appeared. It now keeps the budget the workspace was applied with, like the preview does.
138
+ - Fixed: a project under the home folder counted `~/.claude/CLAUDE.md` as one of its own
139
+ parent-folder files, so `doctor .` reported the dev's personal memory as the project's. Every
140
+ command now reads only the folder it is given and the folders below it (DESIGN.md 6.17).
141
+ - Fixed: a file named directly (`doctor CLAUDE.md`) dropped its own `@imports` from the total.
142
+ - Fixed: a folder named `memory` anywhere under `~/.claude/projects/` was taken for a Claude Code
143
+ memory folder; only `projects/<slug>/memory`, or the `autoMemoryDirectory` folder, is one.
144
+ - New: the always-loaded total of a memory folder counts the reported files that load it, through
145
+ a chain such as `CLAUDE.md` -> `@AGENTS.md`, and says what the total covers.
146
+ - A host links a folder by path only where Claude Code would act on it: a list item or a link
147
+ target. A path in a passing sentence or a code example does not link.
148
+ - New: `apply` saves the reported set beside the folder's backups, in the gitignored
149
+ `.minnimemory/hosts.json`, so a re-apply reads it from anywhere.
150
+ - Fixed: a plain memory folder that a host names by path is read on demand, not counted as
151
+ always-loaded.
152
+ - Fixed: `apply` rewrote any `@` line whose file name matched a moved file; it now rewrites only
153
+ lines that resolve into the folder, in every linked host, each with its own backup for `undo`.
154
+ - Fixed: on Windows and macOS, a path spelled with different letter case (or, on macOS, a
155
+ different Unicode form) than the file on disk was treated as outside its folder.
156
+ - Fixed: an `@import` path with accented letters (`@C:/Users/José/...`) was cut off at the accent.
157
+ - Fixed: a folder opened through a link missed an import that names its real path.
158
+ - Fixed: a Claude Code memory folder's `MEMORY.md` was counted in full, but Claude Code loads
159
+ only its first 200 lines / 25 KB. The total now counts that part, the new rule MM017 (high)
160
+ names the lines past it, and `apply` refuses a list that would land past it and says how many
161
+ lines to cut (issue #360).
162
+ - Fixed: over MCP, naming a folder outside the project that nobody reported got a bare refusal;
163
+ the answer now gives the terminal command for that folder. A `~/` target means the home folder
164
+ (issues #365, #369).
165
+ - Fixed: MM004 counts a `[[name]]` link, the form Claude Code's memory uses; files reached that
166
+ way were reported unreachable (issue #367).
167
+ - New: MM018 (med) reports an OnDemandMemory list line that links a file that does not exist, and
168
+ names the likely renamed file when one sits beside it (issue #368).
169
+ - Fixed: `init` on a memory folder opened with a map saying "every session: 0 tokens"; the map
170
+ now lists what loads with the folder and its total is the audit's (issue #366).
171
+ - Fixed: a "leave this as it is" verdict no longer lists file writes, "-0.0%" and "Run apply()"; it
172
+ says there is nothing to apply and names the forced write once (issue #370).
173
+ - Fixed: over MCP, "which folder?" now names the server root's path and says a memory folder is
174
+ outside it, and "nothing to undo" names the folder it checked; an agent undid the project
175
+ instead of the memory folder and reported it done (issue #371).
176
+ - New: `init` and `doctor` take `--diff summary` (no file diffs), and the terminal command the
177
+ MCP tools give for a memory folder uses it; the full diff printed 32 KB on a 67-file memory
178
+ (issue #372).
179
+ - Fixed: `install`'s last line names the same copy it registered, not `npx` (issue #373).
180
+ - Fixed: an `@import` chain through a file of any name (`~/.claude/CLAUDE.md` ->
181
+ `@~/dotfiles/claude/global.md` -> a memory topic) was missed, so the topic counted as on demand
182
+ and `apply` moved it out from under the import, and Claude Code stopped loading it. Chains are
183
+ followed through any markdown file, as Claude Code does, and apply rewrites and undo restores
184
+ the import in that file (issue #374).
185
+ - Fixed: a file that links a memory folder only by loading the next file (a CLAUDE.md that is
186
+ `@AGENTS.md`) now says so, `loads AGENTS.md, which names this folder` (issue #376).
187
+ - Removed: `--include-auto-memory`, `--follow-external-imports` and `install --auto-memory` (still
188
+ accepted, with a one-line notice). The MCP tools ask for a target instead of assuming the root.
189
+
6
190
  ## 1.1.0 - 2026-10-06
7
191
 
192
+ - Known issue, found after publish: the discovery bugs fixed under Unreleased above. A project
193
+ under the home folder over-counts its always-loaded total by the user-level `CLAUDE.md`.
194
+
8
195
  - Kept: the memory-folder list header still says "Read one file, not its siblings." Dropping it
9
196
  made the agent search the routed file instead of opening it, and a measured working session
10
197
  saved 15% instead of 27%.
package/README.md CHANGED
@@ -5,26 +5,25 @@ project memory file on every turn, most of it irrelevant to the task in front of
5
5
  edited character near the top of that file busts prompt caching for everything after it.
6
6
  MinniMemoryMCP audits the file, compiles it into a small AlwaysOnMemory body plus OnDemandMemory
7
7
  files loaded only when relevant, and can undo the whole thing in one step. Four verbs, the same
8
- in Claude Code and in the terminal: `doctor`, `init`, `apply`, `undo`. Deterministic, lossless,
9
- offline: no model, no key, no network, and the MCP server never writes your disk.
8
+ in Claude Code and in the terminal: `init`, `doctor`, `apply`, `undo`. Deterministic, lossless,
9
+ offline: no model, no key, no network, and the MCP server never writes your memory files (its one
10
+ write is `init`'s record of where Claude Code loads from).
10
11
 
11
12
  Built by MinniAI.
12
13
 
13
14
  ## Try it in the terminal first
14
15
 
15
- Requires Node 18 or later. No install needed to try it once:
16
+ Requires Node 18 or later. No install needed to try it once. `init` is always the first step: it
17
+ finds what Claude Code loads, saves those locations, and previews the compile. Nothing is written
18
+ to your memory until you run `apply`. The full loop, against `examples/CLAUDE.md` (the fixture
19
+ shipped in this package), real output (approx-v2 tokenizer, an offline estimate; trimmed for
20
+ length):
16
21
 
17
22
  ```
18
- $ npx -y minnimemory doctor
19
- ```
23
+ $ npx -y minnimemory init .
20
24
 
21
- That is read-only: it audits whatever memory file or memory folder is in the current directory
22
- and, if it finds one, previews the compile. Nothing is written until you run `apply`. The full
23
- loop, against `examples/CLAUDE.md` (the fixture shipped in this package), real output
24
- (approx-v2 tokenizer, an offline estimate; line counts and hashes trimmed for length):
25
-
26
- ```
27
- $ npx -y minnimemory doctor
25
+ memory map for /path/to/your/repo: every file Claude Code loads, by its own rules
26
+ every session: 897 tokens
28
27
 
29
28
  MM003 "Current status" (lines 28-33) holds a status heading and high
30
29
  status language in the always-loaded prefix
@@ -32,57 +31,56 @@ $ npx -y minnimemory doctor
32
31
  the prompt cache every time
33
32
  ...2 more findings...
34
33
 
35
- 3 findings (3 high)
36
- all always-loaded files: 897 tokens across 1 file (budget 2,000, within)
37
- tokenizer: approx-v2, an offline estimate
38
-
39
- project root: /path/to/your/repo
40
- index: CLAUDE.md
41
-
42
- CLAUDE.md 897 -> 280 tokens (share 897)
43
- .claude/OnDemandMemory/CLAUDE__history.md 615 volatile error, posting, token, migration
44
-
45
- always-loaded, files this plan rewrites: 897 -> 363 tokens (-59.5%)
34
+ always-loaded, files this plan rewrites: 897 -> 389 tokens (-56.6%)
46
35
  best case: kept only on turns that open none of the moved files. Measured on another memory with an agent that can read and search, whole sessions cost 24.0% less and answers held (judge 76 of 81 vs 74 for the original; ledger 2026-10-06).
47
- break-even: 534 tokens of OnDemandMemory open all session
48
- budget: 2,000 (default: 60% of the file, at least 2,000; pass --budget to change it)
49
- verdict: compile. Every turn with no routed file open saves 534 tokens; a turn with every
50
- routed file open (615 tokens) costs 81 more than today. It pays unless routed text is open
36
+ verdict: compile. Every turn with no routed file open saves 508 tokens; a turn with every
37
+ routed file open (613 tokens) costs 105 more than today. It pays unless routed text is open
51
38
  on nearly every turn.
52
39
 
53
40
  operations:
54
- write .minnimemory/.gitignore +4 -0
55
- copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md)
56
- write .claude/OnDemandMemory/CLAUDE__history.md +53 -0
57
- write CLAUDE.md +6 -47
58
- write .minnimemory/graph.json +446 -0
59
- write .minnimemory/manifest.json +46 -0
60
-
61
- diff:
62
- ...the full unified diff of every file above...
63
-
64
- plan: ebda8c39f4ab505d
41
+ write .minnimemory/.gitignore +5 -0
42
+ copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md -> CLAUDE.md.bak)
43
+ write .claude/OnDemandMemory/CLAUDE__history.md +28 -0
44
+ write .claude/OnDemandMemory/CLAUDE__detail.md +28 -0
45
+ write CLAUDE.md +7 -47
46
+ ...
47
+
48
+ plan: 7eb0e22e815143d0
65
49
  dry run, nothing written. To write these files, run:
66
- npx -y minnimemory apply --plan ebda8c39f4ab505d
50
+ npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
67
51
 
68
- $ npx -y minnimemory apply --plan ebda8c39f4ab505d
69
- ...the same operations and diff, then:
70
- 5 file(s) written; originals are under .minnimemory/. Undo any time: npx -y minnimemory undo
52
+ $ npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
53
+ 5 file(s) written; originals are under .minnimemory/. Undo any time: npx -y minnimemory undo .
71
54
 
72
55
  $ npx -y minnimemory doctor
73
- ...the audit, then:
74
- no drift since the last apply: every compiled file matches the manifest. Nothing to re-apply.
56
+ nothing to apply: no drift since the last apply
75
57
 
76
58
  $ npx -y minnimemory undo
77
59
  restored 1 file(s) in /path/to/your/repo
78
60
  deleted: 4 path(s), .minnimemory/ included
79
61
  ```
80
62
 
81
- `doctor` exits 1 here, on purpose: the example carries two high findings, and the exit code
82
- (`0` clean, `1` findings at or above `--fail-on`, `2` an error) is what a CI step keys on.
63
+ `doctor` is for later, after `init`: it refuses until `init` has run here ("run init first").
64
+ With no folder, `doctor`, `apply` and `undo` use the folder `init` saved. Its exit code (`0`
65
+ clean, `1` findings at or above `--fail-on`, `2` an error) is what a CI step keys on.
66
+
67
+ **Your Claude Code memory folder** (`~/.claude/projects/<project>/memory`) is loaded with files
68
+ outside it: your `~/.claude/CLAUDE.md` and anything it imports. minnimemory never searches for
69
+ those; it reads only what it is told Claude Code loads, so it cannot guess wrong. In Claude Code
70
+ the agent tells it (below). In a terminal, give it Claude Code's own load log, or the files by
71
+ hand:
72
+
73
+ ```
74
+ $ npx -y minnimemory init ~/.claude/projects/<project>/memory --from-log
75
+ $ npx -y minnimemory init ~/.claude/projects/<project>/memory --loaded ~/.claude/CLAUDE.md
76
+ ```
77
+
78
+ `init` checks each path and saves the set for `apply`, `doctor` and `undo`. `apply` on a memory
79
+ folder refuses until something was reported, because moving a file that an unseen outside file
80
+ imports would break that import; `--only-this-folder` says nothing outside loads it.
83
81
 
84
82
  `apply --plan <hash>` recomputes the plan from what is on disk and refuses if it no longer
85
- matches the hash `doctor`/`init` showed you, so what you saw is exactly what gets written. Plain
83
+ matches the hash `init`/`doctor` showed you, so what you saw is exactly what gets written. Plain
86
84
  `apply` (no `--plan`) works too and skips that check. Every command the tool prints is the one to
87
85
  paste, with the target path when it is not the current directory. Run from an installed copy
88
86
  (the npx cache, a global install, a checkout) the command calls that same copy directly, `node
@@ -135,35 +133,39 @@ Four verbs, the same four whether your agent calls them or you type them:
135
133
 
136
134
  | verb | what it does | writes anything? |
137
135
  |---|---|---|
138
- | `doctor` | the audit, then the diff of every file `apply` would write (or drift since the last apply, on a workspace compiled before), then the command to run | no |
139
- | `init` | the map of every file Claude Code loads here (when, whose, tokens), then the same preview as `doctor`, for the first compile | no |
140
- | `apply` | writes what `doctor`/`init` showed, originals backed up first; `--plan <hash>` checks nothing moved since you looked | terminal: yes, to disk. MCP: no. It returns the command to run and the list of operations (paths and line counts, no content), and your agent runs the command through your approval |
136
+ | `init` | always first: takes where Claude Code loads from (your agent passes it; in a terminal `--from-log` or `--loaded`), checks and saves it, then the map of every file Claude Code loads (when, whose, tokens), the audit and the diff of every file `apply` would write, then the command to run | only its record of those locations, in your Claude config folder; never a memory file |
137
+ | `doctor` | after `init`, never first: the audit, drift since the last apply, the re-apply diff | no |
138
+ | `apply` | writes what `init`/`doctor` showed, originals backed up first; `--plan <hash>` checks nothing moved since you looked | terminal: yes, to disk. MCP: no. It returns the command to run and the list of operations (paths and line counts, no content), and your agent runs the command through your approval |
141
139
  | `undo` | puts your original memory files back and removes `.minnimemory/` | terminal: yes. MCP: no. It returns the command and the operations the same way |
142
140
 
143
- The order is always the same: `doctor` (or `init`, same thing on a fresh workspace), then
144
- `apply`. A week later, after you have edited a memory file by hand, `doctor` again, then `apply`
145
- again. `undo` at any time.
141
+ The order is always the same: `init`, then `apply`. A week later, after you have edited a memory
142
+ file by hand, `doctor`, then `apply` again. `undo` at any time. `doctor` before `init` refuses and
143
+ says to run `init` first.
146
144
 
147
145
  It works on two shapes, through one engine. A **host file** (`CLAUDE.md`, `AGENTS.md`,
148
146
  `GEMINI.md`, `.cursorrules`) is trimmed in place: the file itself becomes the AlwaysOnMemory
149
147
  body plus a fenced OnDemandMemory list, and routed pieces land beside it in
150
148
  `.claude/OnDemandMemory/`. A **memory folder** (an index such as Claude Code's `MEMORY.md` plus
151
149
  topic files, or the project's own Claude Code auto-memory folder) is sorted in place: every
152
- topic file the user-level host imports moves into `AlwaysOnMemory/`, trimmed the same way; every
150
+ topic file a linked host imports moves into `AlwaysOnMemory/`, trimmed the same way; every
153
151
  other topic file moves into `OnDemandMemory/`, untouched; routed pieces join it there. The
154
- always-loaded set of a folder counts the user-level `~/.claude/CLAUDE.md` and everything it
155
- imports, because Claude Code loads those on every turn too - the one `@import` line that changes
156
- is shown as its own block in the diff. The MCP server sees the auto-memory folder and the
157
- user-level file only when registered with `--include-auto-memory` (`npx -y minnimemory install
158
- --auto-memory`); the terminal commands always see them.
159
-
160
- By default the auto-memory folder is `<CLAUDE_CONFIG_DIR or ~/.claude>/projects/<slug>/memory`,
161
- where `<slug>` is derived from the project's path; an `autoMemoryDirectory` key in the USER-scope
162
- Claude Code `settings.json` (`<config dir>/settings.json` only, never a repo-local one) overrides
163
- the whole folder with the path it names, `~` included - a repo-local copy of the same key is
164
- ignored, and `doctor` says so, since a cloned repo must not be able to redirect this by shipping
165
- one. `CLAUDE_CODE_PROJECT_DIR_NAME`, when set, replaces the derived `<slug>` instead, so the
166
- project directory does not have to be reverse-engineered from the cwd.
152
+ always-loaded set of a memory folder also counts the files outside it that load it, because
153
+ Claude Code loads them on every turn too: your `~/.claude/CLAUDE.md` when it imports from the
154
+ folder, directly or through a chain (`CLAUDE.md` -> `@AGENTS.md`, or a stub that imports a
155
+ dotfiles file which imports from the folder), and a `CLAUDE.md` or `AGENTS.md` that names the
156
+ folder in a list item or a link. minnimemory never searches for those files: it reads only the
157
+ files it is told Claude Code loads (the agent passes them to `init` from its own context; in a
158
+ terminal `--from-log` reads Claude Code's own load log, or `--loaded <path>` names each one), and
159
+ works out from their lines which of them load the folder. The report lists each linked file and
160
+ how, the reported files that load nothing in the folder, and any place the report and the lines
161
+ disagree. An `@import` line that changes is shown as its own block in the diff. A project root
162
+ reads only itself: no parent `CLAUDE.md`, no user files. With no folder named and nothing
163
+ recorded, the terminal asks and an MCP tool asks the agent to ask you.
164
+
165
+ Claude Code names its memory folder itself (`~/.claude/projects/<project>/memory` by default, or
166
+ the folder an `autoMemoryDirectory` setting points at), and the agent passes that path to `init`
167
+ as it sees it, so the folder is never worked out from a slug. The MCP server accepts that one
168
+ folder outside the project it runs in, because Claude Code named it.
167
169
 
168
170
  **A file with `__` in its name is the tool's** (`<parent>__history.md`, `<parent>__detail.md`
169
171
  for a project root; the same names for a sorted folder's sources): a merge of every dated,
@@ -204,16 +206,16 @@ server tells the agent the loop on connect, so these four requests are all it ta
204
206
 
205
207
  | you say | the agent calls | what you see |
206
208
  |---|---|---|
207
- | "run doctor on my memory" | `doctor` | the findings, then a summary of the plan: one line per file (action, path, lines added/removed), the moves and the import rewrite in full |
209
+ | "clean up my memory" | `init`, with the auto memory folder and every file Claude Code shows as loaded in its context | the files that load your memory and how, then the findings and a summary of the plan: one line per file (action, path, lines added/removed), the moves and the import rewrite in full. Those locations are saved, so nothing is asked again |
208
210
  | "apply it" | `apply` | the command `npx -y minnimemory apply --plan <hash> [path]` to run and the operations it performs, one line each. Your originals are the first files written, to `.minnimemory/original/` |
209
- | "run doctor on my memory" (a week later) | `doctor` | the findings, what drifted since the last apply, and the re-apply plan, or "nothing to re-apply" |
211
+ | "check my memory" (a week later) | `doctor` | the findings, what drifted since the last apply, and the re-apply plan, or "nothing to re-apply" |
210
212
  | "undo the memory compile" | `undo` | the command that restores the originals and removes `.minnimemory/`, and the operations it performs |
211
213
 
212
214
  Every write goes through your own tool's approval prompt. The MCP server itself only reads, and
213
215
  it never sends your files' content through the model: `apply`/`undo` return the command and the
214
216
  operation list (about 240 tokens on the fixture above, about 300 on an 85-file memory folder);
215
217
  `content: true` adds the files themselves, for an agent that cannot run commands.
216
- `doctor`/`init` return a summary diff over MCP by default (the plan table plus one line per
218
+ `init`/`doctor` return a summary diff over MCP by default (the plan table plus one line per
217
219
  file); pass `diff: "full"` for the complete unified diff the terminal always shows.
218
220
 
219
221
  ## What gets generated
@@ -256,39 +258,16 @@ The CLI and the MCP basic profile share the same four lifecycle verbs; the only
256
258
  who writes: the CLI writes to disk itself, the MCP tools return the one command to run and the
257
259
  operations it performs (file content only on request, `content: true`).
258
260
 
259
- ### `minnimemory doctor [path]`
260
-
261
- The preview for a workspace compiled before: the audit, drift since the last apply (MM010), then
262
- the re-apply plan and "run apply", or "nothing to apply". On a workspace never compiled it is
263
- `init` under another name. Never modifies anything. Works on a repo, a memory folder, or a
264
- single file. Names a workspace compiled by an older layout (manifest v4/v5) as such, with "run
265
- undo, then apply" as the fix.
266
-
267
- | flag | effect |
268
- |---|---|
269
- | `--json` | machine-readable output: the audit under `doctor`, the plan under `plan` |
270
- | `--force` | on a compiled workspace with no drift, show the re-apply plan anyway |
271
- | `--ci` | terse output, no colour |
272
- | `--fail-on <sev>` | exit 1 at this severity or above: `low`, `med`, `high` (default `high`) |
273
- | `--budget <n>` | always-loaded token budget for MM001 (default: the budget the workspace was compiled at, else 60% of the host file, at least 2000) |
274
- | `--only <ids>` | run only these rules, comma separated |
275
- | `--ignore <ids>` | skip these rules, comma separated |
276
- | `--follow-external-imports` | follow `@path` imports that resolve outside the target directory |
277
- | `--rules` | list the rule set and exit |
278
-
279
- Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` execution error, so a CI step
280
- (`npx -y minnimemory doctor --ci --fail-on med`) can fail the build on memory bloat the same way
281
- a lint error would.
282
-
283
261
  ### `minnimemory init [path]`
284
262
 
285
- `init` opens with the map of every file Claude Code loads for this project, from Claude Code's
286
- own documented rules: the managed policy file, your user `CLAUDE.md` and `~/.claude/rules/`,
287
- `CLAUDE.md` / `.claude/CLAUDE.md` / `CLAUDE.local.md` in this folder and every folder above it,
288
- `AGENTS.md` when no `CLAUDE.md` exists, `.claude/rules/` (a rule with `paths:` frontmatter loads
289
- only when a matching file is read), subfolder files Claude reads when it works there, every `@`
290
- import, and the auto-memory folder. Each file is tagged with when it loads, whose it is, and its
291
- tokens. `--map` prints only the map (`--json` for the data); `init --json` puts the map under
263
+ `init` is always the first step. It takes where Claude Code loads from (the agent passes it
264
+ over MCP; in a terminal `--from-log`, `--loaded` or `--memory-dir`), checks every path, and saves
265
+ it in your Claude config folder for `apply`, `doctor`, `undo` and the hooks: the one thing `init`
266
+ writes, never a memory file. Then the map of every file Claude Code loads here: for a project, its
267
+ own `CLAUDE.md` / `AGENTS.md`, `CLAUDE.local.md`, `.claude/rules/` (a rule with `paths:`
268
+ frontmatter loads only when a matching file is read), subfolder files Claude reads when it works
269
+ there and every `@` import inside it; for a memory folder, its index, the files it loads and the
270
+ reported files that load it. Each file is tagged with when it loads, whose it is, and its tokens. `--map` prints only the map (`--json` for the data); `init --json` puts the map under
292
271
  `map`, beside `doctor` and `plan`.
293
272
 
294
273
  The map starts with a `setup` block, so you know how the project is set up before anything is
@@ -302,13 +281,12 @@ undone exactly as a `CLAUDE.md` host is.
302
281
 
303
282
  `install` also adds an `InstructionsLoaded` hook, which records what Claude Code actually loads
304
283
  for each project in a small file under your Claude config folder (machine-local, never in a
305
- repo). `init` marks each file Claude Code was seen loading and lists anything it loaded that the
306
- rules missed; `doctor` reports the same as MM016.
284
+ repo). `init --from-log` reads it as the report of what loads your memory folder.
307
285
 
308
286
  Then the first-time preview: the audit, then the plan with a unified diff of every file `apply` would
309
- overwrite and the full content of every file it would create, then the command to run. Never
310
- writes: passing `--write` or `--update` prints one line ("init never writes; use apply") and
311
- exits.
287
+ overwrite and the full content of every file it would create, then the command to run. It never
288
+ writes a memory file: passing `--write` or `--update` prints one line ("init never writes; use
289
+ apply") and exits.
312
290
 
313
291
  On a memory folder the plan sorts every always-loaded topic file into `AlwaysOnMemory/`, trimmed
314
292
  in place, and every other topic file into `OnDemandMemory/`, untouched; routed pieces join
@@ -333,6 +311,10 @@ kept out to fit, so change `--budget` with the numbers in front of you.
333
311
  | flag | effect |
334
312
  |---|---|
335
313
  | `--force` | on a compiled workspace with no drift, preview the re-apply plan anyway; also previews compiling a file the plan's verdict says to leave alone |
314
+ | `--loaded <path>` | a file Claude Code loads this session; repeatable; the only way a file outside the folder is read (`--host-file` still works) |
315
+ | `--memory-dir <path>` | the auto memory folder Claude Code names; also the folder to use |
316
+ | `--from-log` | take the loaded files from Claude Code's own load log for this folder |
317
+ | `--diff summary` | the plan and the operation list without the file diffs |
336
318
  | `--budget <n>` | always-loaded token budget AlwaysOnMemory must fit (default: see above) |
337
319
  | `--profile <name>` | how much guidance to embed: `auto`, `none`, `routing`, `full` (default `auto`) |
338
320
  | `--allow-secrets` | preview as if a credential-shaped source were allowed through |
@@ -344,16 +326,41 @@ depends on, about 210 tokens; `full` is the complete discipline set, about 710 t
344
326
  refuses (with `--force` to override) a compile that would not shrink the always-loaded prefix,
345
327
  naming the before/after tokens and the break-even point.
346
328
 
329
+ ### `minnimemory doctor [path]`
330
+
331
+ After `init`, never first: it refuses until `init` has run for this project, and with no path
332
+ it uses the folder `init` saved. The audit, drift since the last apply (MM010), then the re-apply
333
+ plan and "run apply", or "nothing to apply". Never modifies anything. Works on a repo, a memory folder, or a
334
+ single file. Names a workspace compiled by an older layout (manifest v4/v5) as such, with "run
335
+ undo, then apply" as the fix.
336
+
337
+ | flag | effect |
338
+ |---|---|
339
+ | `--json` | machine-readable output: the audit under `doctor`, the plan under `plan` |
340
+ | `--force` | on a compiled workspace with no drift, show the re-apply plan anyway |
341
+ | `--ci` | terse output, no colour |
342
+ | `--fail-on <sev>` | exit 1 at this severity or above: `low`, `med`, `high` (default `high`) |
343
+ | `--budget <n>` | always-loaded token budget for MM001 (default: the budget the workspace was compiled at, else 60% of the host file, at least 2000) |
344
+ | `--only <ids>` | run only these rules, comma separated |
345
+ | `--ignore <ids>` | skip these rules, comma separated |
346
+ | `--rules` | list the rule set and exit |
347
+
348
+ Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` execution error, so a CI step
349
+ (`npx -y minnimemory doctor --ci --fail-on med`) can fail the build on memory bloat the same way
350
+ a lint error would.
351
+
347
352
  ### `minnimemory apply [path]`
348
353
 
349
- Writes what `doctor` or `init` showed. Looks at the workspace and does the right thing: an
354
+ Writes what `init` or `doctor` showed. On a memory folder it refuses until `init` was told what
355
+ loads it (moving a file an unseen outside file imports would break that import);
356
+ `--only-this-folder` says nothing outside loads it. Looks at the workspace and does the right thing: an
350
357
  uncompiled host file or memory folder gets a fresh compile; a compiled workspace with drift gets
351
358
  re-applied, keeping every hand edit and every routed file; a compiled workspace with no drift
352
359
  prints "nothing to apply" and changes nothing. Same flags, backups (`.minnimemory/original/`,
353
- `.minnimemory/previous/`) and refusals as `doctor`/`init`.
360
+ `.minnimemory/previous/`) and refusals as `init`/`doctor`.
354
361
 
355
362
  `--plan <hash>` recomputes the plan from disk and refuses with "the plan on disk no longer
356
- matches" when the hash differs from the one `doctor`/`init` printed, so what you approved is
363
+ matches" when the hash differs from the one `init`/`doctor` printed, so what you approved is
357
364
  what gets written; plain `apply` skips that check and always writes the current plan.
358
365
 
359
366
  `apply` follows a pointer: if `CLAUDE.md` is only `@AGENTS.md` or "See `AGENTS.md`", it compiles
@@ -391,12 +398,10 @@ Starts an MCP server, `--profile basic` (the same four verbs, always registered)
391
398
 
392
399
  | flag | effect |
393
400
  |---|---|
394
- | `--profile <name>` | `basic` (default): `doctor`, `init`, `apply`, `undo`, read-only. `full`: the seven maintainer tools (`recall`, `modules`, `outline`, `doctor`, `plan`, always; `apply`, `update` with `--allow-write`) |
395
- | `--allow-write` | adds the full profile's write tools. No effect on basic, which is read-only by construction |
396
- | `--follow-external-imports` | let the tools follow `@path` imports outside the server root |
397
- | `--include-auto-memory` | let the tools see the operator's OS-level Claude Code auto-memory folder, and resolve `"auto-memory"` as a target |
401
+ | `--profile <name>` | `basic` (default): `init`, `doctor`, `apply`, `undo`, read-only. `full`: the six maintainer tools (`recall`, `modules`, `outline`, `doctor`, `plan`, always; `apply` with `--allow-write`) |
402
+ | `--allow-write` | adds the full profile's write tool. No effect on basic, which is read-only by construction |
398
403
 
399
- `doctor`/`init` take `diff: "summary"` (default) or `"full"`; `apply`/`undo` take `content: true`
404
+ `init`/`doctor` take `diff: "summary"` (default) or `"full"`; `apply`/`undo` take `content: true`
400
405
  to include file content for a host without a shell. With `format: "json"`, `init` returns three
401
406
  keys, `map` (each load group, and each file's path, tokens and owner), `doctor` and `plan`;
402
407
  `doctor` returns the last two. Every reply's data block carries a code drawn for that reply in
@@ -414,17 +419,33 @@ add` line above, turns on the drift notice hook, and prints the next step.
414
419
  |---|---|
415
420
  | `--scope <name>` | `user`, `project`, or `local`, same meaning as `claude mcp add -s` (default `user`) |
416
421
  | `--write` | serve the full profile with its write tools (`--profile full --allow-write`); the default basic profile never writes |
417
- | `--auto-memory` | append `--include-auto-memory` to the served command |
418
422
  | `--dry-run` | print the command without running it, exit 0 |
419
423
  | `--force` | remove an existing registration first, then re-add |
420
424
  | `--no-hook` | skip the drift notice hook (on by default) |
421
- | `--remove` | remove the MCP registration and the drift hook `install` added |
425
+ | `--remove` | remove the MCP registration and both hooks `install` added; the same as `minnimemory uninstall` |
422
426
  | `--host <name>` | `cursor`, `windsurf` or `json`: print the `mcpServers` snippet to paste (and the config file for Cursor and Windsurf) instead of registering with Claude Code; no hook |
423
427
 
424
428
  Idempotent: an existing registration is reported, with the command to change it, not duplicated.
425
429
  Without the `claude` CLI on `PATH` it prints the manual line and a JSON snippet instead, exit 2;
426
430
  if `claude` itself errors, its stderr is printed, exit 1.
427
431
 
432
+ ### `minnimemory uninstall`
433
+
434
+ Takes out what `install` added: the MCP registration (`claude mcp remove minnimemory`) and the two
435
+ hooks in your Claude `settings.json`. Every other hook and setting stays, including another tool's
436
+ hook that happens to look like ours. `--dry-run` shows the removals first; `--scope` matches the
437
+ one you installed with. Running it twice is harmless.
438
+
439
+ ```
440
+ npx -y minnimemory uninstall
441
+ ```
442
+
443
+ It does not undo your memory. A compiled folder keeps working as plain markdown without the tool,
444
+ and `uninstall` lists each one still compiled with its `undo` command, so run those first if you
445
+ want the originals back. It also leaves `~/.claude/minnimemory/` (the `init` records, the load log
446
+ and any undo backups); delete that yourself once you have checked `undo-backups/`. Restart Claude
447
+ Code afterwards.
448
+
428
449
  ### `minnimemory recall <path> <query...>`
429
450
 
430
451
  Ranks a compiled workspace's OnDemandMemory sections, or a manifest-less memory directory,
@@ -478,9 +499,9 @@ The MCP server's own always-loaded cost, measured (not assumed), approx-v2 token
478
499
 
479
500
  | | tokens |
480
501
  |---|---|
481
- | basic profile tool schemas (`doctor`, `init`, `apply`, `undo`), read-only | 1,102 |
482
- | basic profile tool schemas, `--allow-write` (no effect on basic) | 1,102 |
483
- | server instructions text | 49 |
502
+ | basic profile tool schemas (`init`, `doctor`, `apply`, `undo`), read-only | 1,173 |
503
+ | basic profile tool schemas, `--allow-write` (no effect on basic) | 1,173 |
504
+ | server instructions text | 50 |
484
505
 
485
506
  Measured against a real registered server over an in-memory MCP transport, not assumed. Claude
486
507
  Code defers a tool's full schema until it decides
@@ -490,7 +511,7 @@ kept under about 60 tokens for that reason.
490
511
 
491
512
  ## Security
492
513
 
493
- - `doctor`, `init`, `apply`, `undo`, and `mcp` make no network calls and never run a subprocess.
514
+ - `init`, `doctor`, `apply`, `undo`, and `mcp` make no network calls and never run a subprocess.
494
515
  - `apply`/`undo` refuse a symlinked source and refuse to write or delete through a symlink, so a
495
516
  cloned repo cannot point a memory file, or a routed piece, at a file outside the workspace.
496
517
  - `apply` refuses to write when the source holds a credential-shaped string, unless you pass
@@ -525,7 +546,7 @@ kept under about 60 tokens for that reason.
525
546
  No. Every command makes no network calls at all. There is no telemetry and no API key.
526
547
 
527
548
  **Will it destroy my `CLAUDE.md`?**
528
- No. `doctor`/`init` are dry run by default. `apply` copies your original verbatim to
549
+ No. `init`/`doctor` are dry run by default. `apply` copies your original verbatim to
529
550
  `.minnimemory/original/` before anything is modified, never writes over that backup, and `undo`
530
551
  restores it byte-identical on the machine that ran `apply`.
531
552