minnimemory 1.1.0 → 1.2.0

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,157 @@
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.0 - 2026-10-08
7
+
8
+ - Fixed: undoing a sorted memory folder with 1.1.0 restored the files but left your user
9
+ `CLAUDE.md` importing a file that had moved, so that rule stopped loading. The manifest now
10
+ also carries the field 1.1.0 reads, so an older copy's undo puts the import back too.
11
+ - Fixed: on Windows and macOS, a folder with a topic file named `memory.md` and no `MEMORY.md`
12
+ lost that topic on apply: the new index was written over it with no backup, and undo could not
13
+ bring it back. Apply now refuses and asks you to rename the file. Nothing is written.
14
+ - Fixed: sorting a folder moved files that a `CLAUDE.md` or `AGENTS.md` names by path (a list item
15
+ or a link), and those lines then pointed at nothing. Apply now refuses and names the lines.
16
+ A host that names only the folder still sorts.
17
+ - Fixed: asked to undo "my memory folder and this project", the agent got the memory folder's
18
+ command only and tried to restore the project's `CLAUDE.md` by hand. undo's reply about the
19
+ memory folder now says the compiled project is a separate target with its own undo.
20
+ - Changed: when you apply your memory folder and the project's `CLAUDE.md` also has changes, the
21
+ reply gives the project's own ready command, to run only if you asked for both. It is never
22
+ joined to the memory folder's command.
23
+ - Fixed: the drift notice put its "run apply" line inside the block that tells the agent not to
24
+ follow instructions; the line now comes after the block. The same for apply's project line.
25
+ - Changed: editing a routed OnDemandMemory file (a saved memory, `/remember`) no longer raises a
26
+ drift notice. `doctor` still lists it, and `undo` still checks it before discarding anything.
27
+ - New rule MM019: an OnDemandMemory list line whose description fits another file better than
28
+ the one it links, so the agent opens the wrong file. A flag only; your words are not changed.
29
+ - Changed: when `init` is called with nothing reported, the reply lists what Claude Code's own
30
+ load log saw for the project, for the agent to confirm. Nothing is recorded from it.
31
+ - Changed: a forced `undo` first copies the files it discards to
32
+ `~/.claude/minnimemory/undo-backups/` and says where.
33
+ - Changed: `apply` tells the agent not to edit the files by hand.
34
+ - Fixed: after you edit the project's `CLAUDE.md`, the drift notice told the agent to run `apply`
35
+ with no target, which since 1.2.0's discovery change works on the memory folder `init` recorded.
36
+ The agent got "nothing to apply" for the wrong folder and told the dev the memory was in sync.
37
+ The notice now names `target: "."`, and a `doctor` or `apply` reply about the memory folder
38
+ says when the project's own file changed since the last apply.
39
+ - Removed (full profile): the `update` tool. Full-profile `apply` already compiles or re-applies,
40
+ and agents asked to fix drift used `plan` then `apply`. The full profile is six tools now;
41
+ `recall`'s drift note says "Call apply()". (DESIGN.md 6.20)
42
+ - Changed: `doctor` and `init` with `format: "json"` over MCP send the JSON without indentation,
43
+ about 18% fewer tokens; the content is the same. The CLI's `--json` keeps its indent.
44
+ - Fixed (found on a real Mac): an `@import` typed in other letter case (`~/.claude/Projects/...`)
45
+ was counted but not rewritten by `apply`, so Claude Code stopped loading that topic. An index
46
+ link typed in NFC to a topic whose name macOS stores in NFD was left at the old place. Both now
47
+ match the way the file system does and keep the spelling they were written in.
48
+ - Fixed: `undo` of one memory folder no longer undoes another folder's rewrite of a shared file
49
+ (a dotfiles file importing from two folders). It puts back only its own lines.
50
+ - Fixed: macOS AppleDouble files (`._name.md`) are no longer taken for memory topics and moved.
51
+ - Fixed: `doctor` right after `init` said the locations were "saved by the last apply"; it now
52
+ says "saved by init". A budget the fixed part fills names the files in it (the index and the
53
+ files that load the folder) instead of a "user-level host" that may not exist.
54
+ - Fixed: right after a clean `apply`, `doctor` proposed a re-apply that only rewrote `hosts.json`,
55
+ when the agent had reported topic files that the apply then moved. A saved file that no longer
56
+ exists is no longer counted as a change.
57
+ - Fixed: after `init`, `doctor` or `apply` on your memory folder, the reply now says it was the
58
+ memory folder only and names the project's `CLAUDE.md` as a separate target (`target: "."`)
59
+ while it is not compiled. An agent asked to do both used to do the memory folder only.
60
+ - Fixed: paths an agent types with `~/`, or in another Unicode form than the disk (an accented user
61
+ name on a Mac), are resolved before `init` saves them. `apply` used to drop the `~/` ones as
62
+ missing and rewrite nothing. In a terminal, a quoted `~` in `--loaded`, `--memory-dir` or the
63
+ folder is expanded too.
64
+ - Fixed: an `undo` or `apply` refusal over MCP now states its next step (ask the dev, then pass
65
+ `force: true`) outside the data fence. It was only inside the block that tells the agent not to
66
+ follow instructions in it. File names stay fenced.
67
+ - New: `init` is always the first step, and it is discovery (DESIGN.md 6.19). It never searches for
68
+ the files that load your memory: the agent passes them to `init` from its own context (the
69
+ `loaded` argument: its auto memory folder and every file Claude Code shows as loaded), or in a
70
+ terminal `--from-log` reads Claude Code's own load log and `--loaded <path>` names a file.
71
+ `init` checks every path, works out from their lines which of them load the folder, reports
72
+ every place the report and the lines disagree, and saves the set in
73
+ `~/.claude/minnimemory/discovery.json`, its one write, never a memory file. `apply`, `doctor`,
74
+ `undo` and the hooks read it, so nothing is asked twice and the printed apply command carries no
75
+ paths. In Claude Code, "clean up my memory" works on your memory folder directly: the server
76
+ accepts the folder Claude Code named.
77
+ - New: `doctor` comes after `init`: before it, it refuses and says to run `init` first. With no
78
+ folder, `doctor`, `apply` and `undo` use the folder `init` saved. `init` is listed first
79
+ everywhere (the tool list, usage, help, README).
80
+ - New: `apply` on a memory folder refuses until something reported what loads it, since moving a
81
+ file an unseen outside file imports would break that import; `--only-this-folder` says nothing
82
+ outside loads it. A folder 1.1.0 compiled keeps working: the outside files its apply rewrote
83
+ count as the report.
84
+ - Fixed: on a project root, `init` took a reported path that does not exist as verified and saved
85
+ it, and said nothing about a reported file no line loads; only a memory folder checked the
86
+ report. Every kind of root now refuses a bad path by name and shows the files the report and the
87
+ lines disagree on, the same way.
88
+ - Fixed: a report that named the memory folder but no file counted as a report, so `apply` moved
89
+ the folder's files and an import of them from the user `CLAUDE.md` broke (seen with a weak
90
+ agent that passed an empty list). An empty list is no report now: `init` says what to pass,
91
+ `apply` refuses; `--only-this-folder`, or the set an earlier apply saved, still says nothing
92
+ outside loads it.
93
+ - Fixed: an agent that reported only files inside the memory folder left the user `CLAUDE.md` out,
94
+ and `apply` moved the topics it imports. The user `CLAUDE.md` is now the one file checked
95
+ without a report: when a line in it loads the folder it is counted, named as not reported, and
96
+ its import rewritten with the rest.
97
+ - Fixed: `apply` with no `--budget` on a compiled workspace planned at the default budget and wrote
98
+ it into the manifest, so a re-apply after a hand edit changed a 2,300 budget to 2,000 and MM001
99
+ appeared. It now keeps the budget the workspace was applied with, like the preview does.
100
+ - Fixed: a project under the home folder counted `~/.claude/CLAUDE.md` as one of its own
101
+ parent-folder files, so `doctor .` reported the dev's personal memory as the project's. Every
102
+ command now reads only the folder it is given and the folders below it (DESIGN.md 6.17).
103
+ - Fixed: a file named directly (`doctor CLAUDE.md`) dropped its own `@imports` from the total.
104
+ - Fixed: a folder named `memory` anywhere under `~/.claude/projects/` was taken for a Claude Code
105
+ memory folder; only `projects/<slug>/memory`, or the `autoMemoryDirectory` folder, is one.
106
+ - New: the always-loaded total of a memory folder counts the reported files that load it, through
107
+ a chain such as `CLAUDE.md` -> `@AGENTS.md`, and says what the total covers.
108
+ - A host links a folder by path only where Claude Code would act on it: a list item or a link
109
+ target. A path in a passing sentence or a code example does not link.
110
+ - New: `apply` saves the reported set beside the folder's backups, in the gitignored
111
+ `.minnimemory/hosts.json`, so a re-apply reads it from anywhere.
112
+ - Fixed: a plain memory folder that a host names by path is read on demand, not counted as
113
+ always-loaded.
114
+ - Fixed: `apply` rewrote any `@` line whose file name matched a moved file; it now rewrites only
115
+ lines that resolve into the folder, in every linked host, each with its own backup for `undo`.
116
+ - Fixed: on Windows and macOS, a path spelled with different letter case (or, on macOS, a
117
+ different Unicode form) than the file on disk was treated as outside its folder.
118
+ - Fixed: an `@import` path with accented letters (`@C:/Users/José/...`) was cut off at the accent.
119
+ - Fixed: a folder opened through a link missed an import that names its real path.
120
+ - Fixed: a Claude Code memory folder's `MEMORY.md` was counted in full, but Claude Code loads
121
+ only its first 200 lines / 25 KB. The total now counts that part, the new rule MM017 (high)
122
+ names the lines past it, and `apply` refuses a list that would land past it and says how many
123
+ lines to cut (issue #360).
124
+ - Fixed: over MCP, naming a folder outside the project that nobody reported got a bare refusal;
125
+ the answer now gives the terminal command for that folder. A `~/` target means the home folder
126
+ (issues #365, #369).
127
+ - Fixed: MM004 counts a `[[name]]` link, the form Claude Code's memory uses; files reached that
128
+ way were reported unreachable (issue #367).
129
+ - New: MM018 (med) reports an OnDemandMemory list line that links a file that does not exist, and
130
+ names the likely renamed file when one sits beside it (issue #368).
131
+ - Fixed: `init` on a memory folder opened with a map saying "every session: 0 tokens"; the map
132
+ now lists what loads with the folder and its total is the audit's (issue #366).
133
+ - Fixed: a "leave this as it is" verdict no longer lists file writes, "-0.0%" and "Run apply()"; it
134
+ says there is nothing to apply and names the forced write once (issue #370).
135
+ - Fixed: over MCP, "which folder?" now names the server root's path and says a memory folder is
136
+ outside it, and "nothing to undo" names the folder it checked; an agent undid the project
137
+ instead of the memory folder and reported it done (issue #371).
138
+ - New: `init` and `doctor` take `--diff summary` (no file diffs), and the terminal command the
139
+ MCP tools give for a memory folder uses it; the full diff printed 32 KB on a 67-file memory
140
+ (issue #372).
141
+ - Fixed: `install`'s last line names the same copy it registered, not `npx` (issue #373).
142
+ - Fixed: an `@import` chain through a file of any name (`~/.claude/CLAUDE.md` ->
143
+ `@~/dotfiles/claude/global.md` -> a memory topic) was missed, so the topic counted as on demand
144
+ and `apply` moved it out from under the import, and Claude Code stopped loading it. Chains are
145
+ followed through any markdown file, as Claude Code does, and apply rewrites and undo restores
146
+ the import in that file (issue #374).
147
+ - Fixed: a file that links a memory folder only by loading the next file (a CLAUDE.md that is
148
+ `@AGENTS.md`) now says so, `loads AGENTS.md, which names this folder` (issue #376).
149
+ - Removed: `--include-auto-memory`, `--follow-external-imports` and `install --auto-memory` (still
150
+ accepted, with a one-line notice). The MCP tools ask for a target instead of assuming the root.
151
+
6
152
  ## 1.1.0 - 2026-10-06
7
153
 
154
+ - Known issue, found after publish: the discovery bugs fixed under Unreleased above. A project
155
+ under the home folder over-counts its always-loaded total by the user-level `CLAUDE.md`.
156
+
8
157
  - Kept: the memory-folder list header still says "Read one file, not its siblings." Dropping it
9
158
  made the agent search the routed file instead of opening it, and a measured working session
10
159
  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,20 +31,8 @@ $ 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
34
  always-loaded, files this plan rewrites: 897 -> 363 tokens (-59.5%)
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
36
  verdict: compile. Every turn with no routed file open saves 534 tokens; a turn with every
50
37
  routed file open (615 tokens) costs 81 more than today. It pays unless routed text is open
51
38
  on nearly every turn.
@@ -55,34 +42,44 @@ $ npx -y minnimemory doctor
55
42
  copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md)
56
43
  write .claude/OnDemandMemory/CLAUDE__history.md +53 -0
57
44
  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...
45
+ ...
63
46
 
64
- plan: ebda8c39f4ab505d
47
+ plan: e36132de24a037c0
65
48
  dry run, nothing written. To write these files, run:
66
- npx -y minnimemory apply --plan ebda8c39f4ab505d
49
+ npx -y minnimemory apply --plan e36132de24a037c0 --budget 2000 .
67
50
 
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
51
+ $ npx -y minnimemory apply --plan e36132de24a037c0 --budget 2000 .
52
+ 5 file(s) written; originals are under .minnimemory/. Undo any time: npx -y minnimemory undo .
71
53
 
72
54
  $ 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.
55
+ nothing to apply: no drift since the last apply
75
56
 
76
57
  $ npx -y minnimemory undo
77
58
  restored 1 file(s) in /path/to/your/repo
78
59
  deleted: 4 path(s), .minnimemory/ included
79
60
  ```
80
61
 
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.
62
+ `doctor` is for later, after `init`: it refuses until `init` has run here ("run init first").
63
+ With no folder, `doctor`, `apply` and `undo` use the folder `init` saved. Its exit code (`0`
64
+ clean, `1` findings at or above `--fail-on`, `2` an error) is what a CI step keys on.
65
+
66
+ **Your Claude Code memory folder** (`~/.claude/projects/<project>/memory`) is loaded with files
67
+ outside it: your `~/.claude/CLAUDE.md` and anything it imports. minnimemory never searches for
68
+ those; it reads only what it is told Claude Code loads, so it cannot guess wrong. In Claude Code
69
+ the agent tells it (below). In a terminal, give it Claude Code's own load log, or the files by
70
+ hand:
71
+
72
+ ```
73
+ $ npx -y minnimemory init ~/.claude/projects/<project>/memory --from-log
74
+ $ npx -y minnimemory init ~/.claude/projects/<project>/memory --loaded ~/.claude/CLAUDE.md
75
+ ```
76
+
77
+ `init` checks each path and saves the set for `apply`, `doctor` and `undo`. `apply` on a memory
78
+ folder refuses until something was reported, because moving a file that an unseen outside file
79
+ imports would break that import; `--only-this-folder` says nothing outside loads it.
83
80
 
84
81
  `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
82
+ matches the hash `init`/`doctor` showed you, so what you saw is exactly what gets written. Plain
86
83
  `apply` (no `--plan`) works too and skips that check. Every command the tool prints is the one to
87
84
  paste, with the target path when it is not the current directory. Run from an installed copy
88
85
  (the npx cache, a global install, a checkout) the command calls that same copy directly, `node
@@ -135,35 +132,39 @@ Four verbs, the same four whether your agent calls them or you type them:
135
132
 
136
133
  | verb | what it does | writes anything? |
137
134
  |---|---|---|
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 |
135
+ | `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 |
136
+ | `doctor` | after `init`, never first: the audit, drift since the last apply, the re-apply diff | no |
137
+ | `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
138
  | `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
139
 
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.
140
+ The order is always the same: `init`, then `apply`. A week later, after you have edited a memory
141
+ file by hand, `doctor`, then `apply` again. `undo` at any time. `doctor` before `init` refuses and
142
+ says to run `init` first.
146
143
 
147
144
  It works on two shapes, through one engine. A **host file** (`CLAUDE.md`, `AGENTS.md`,
148
145
  `GEMINI.md`, `.cursorrules`) is trimmed in place: the file itself becomes the AlwaysOnMemory
149
146
  body plus a fenced OnDemandMemory list, and routed pieces land beside it in
150
147
  `.claude/OnDemandMemory/`. A **memory folder** (an index such as Claude Code's `MEMORY.md` plus
151
148
  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
149
+ topic file a linked host imports moves into `AlwaysOnMemory/`, trimmed the same way; every
153
150
  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.
151
+ always-loaded set of a memory folder also counts the files outside it that load it, because
152
+ Claude Code loads them on every turn too: your `~/.claude/CLAUDE.md` when it imports from the
153
+ folder, directly or through a chain (`CLAUDE.md` -> `@AGENTS.md`, or a stub that imports a
154
+ dotfiles file which imports from the folder), and a `CLAUDE.md` or `AGENTS.md` that names the
155
+ folder in a list item or a link. minnimemory never searches for those files: it reads only the
156
+ files it is told Claude Code loads (the agent passes them to `init` from its own context; in a
157
+ terminal `--from-log` reads Claude Code's own load log, or `--loaded <path>` names each one), and
158
+ works out from their lines which of them load the folder. The report lists each linked file and
159
+ how, the reported files that load nothing in the folder, and any place the report and the lines
160
+ disagree. An `@import` line that changes is shown as its own block in the diff. A project root
161
+ reads only itself: no parent `CLAUDE.md`, no user files. With no folder named and nothing
162
+ recorded, the terminal asks and an MCP tool asks the agent to ask you.
163
+
164
+ Claude Code names its memory folder itself (`~/.claude/projects/<project>/memory` by default, or
165
+ the folder an `autoMemoryDirectory` setting points at), and the agent passes that path to `init`
166
+ as it sees it, so the folder is never worked out from a slug. The MCP server accepts that one
167
+ folder outside the project it runs in, because Claude Code named it.
167
168
 
168
169
  **A file with `__` in its name is the tool's** (`<parent>__history.md`, `<parent>__detail.md`
169
170
  for a project root; the same names for a sorted folder's sources): a merge of every dated,
@@ -204,16 +205,16 @@ server tells the agent the loop on connect, so these four requests are all it ta
204
205
 
205
206
  | you say | the agent calls | what you see |
206
207
  |---|---|---|
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 |
208
+ | "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
209
  | "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" |
210
+ | "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
211
  | "undo the memory compile" | `undo` | the command that restores the originals and removes `.minnimemory/`, and the operations it performs |
211
212
 
212
213
  Every write goes through your own tool's approval prompt. The MCP server itself only reads, and
213
214
  it never sends your files' content through the model: `apply`/`undo` return the command and the
214
215
  operation list (about 240 tokens on the fixture above, about 300 on an 85-file memory folder);
215
216
  `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
217
+ `init`/`doctor` return a summary diff over MCP by default (the plan table plus one line per
217
218
  file); pass `diff: "full"` for the complete unified diff the terminal always shows.
218
219
 
219
220
  ## What gets generated
@@ -256,39 +257,16 @@ The CLI and the MCP basic profile share the same four lifecycle verbs; the only
256
257
  who writes: the CLI writes to disk itself, the MCP tools return the one command to run and the
257
258
  operations it performs (file content only on request, `content: true`).
258
259
 
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
260
  ### `minnimemory init [path]`
284
261
 
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
262
+ `init` is always the first step. It takes where Claude Code loads from (the agent passes it
263
+ over MCP; in a terminal `--from-log`, `--loaded` or `--memory-dir`), checks every path, and saves
264
+ it in your Claude config folder for `apply`, `doctor`, `undo` and the hooks: the one thing `init`
265
+ writes, never a memory file. Then the map of every file Claude Code loads here: for a project, its
266
+ own `CLAUDE.md` / `AGENTS.md`, `CLAUDE.local.md`, `.claude/rules/` (a rule with `paths:`
267
+ frontmatter loads only when a matching file is read), subfolder files Claude reads when it works
268
+ there and every `@` import inside it; for a memory folder, its index, the files it loads and the
269
+ 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
270
  `map`, beside `doctor` and `plan`.
293
271
 
294
272
  The map starts with a `setup` block, so you know how the project is set up before anything is
@@ -302,13 +280,12 @@ undone exactly as a `CLAUDE.md` host is.
302
280
 
303
281
  `install` also adds an `InstructionsLoaded` hook, which records what Claude Code actually loads
304
282
  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.
283
+ repo). `init --from-log` reads it as the report of what loads your memory folder.
307
284
 
308
285
  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.
286
+ overwrite and the full content of every file it would create, then the command to run. It never
287
+ writes a memory file: passing `--write` or `--update` prints one line ("init never writes; use
288
+ apply") and exits.
312
289
 
313
290
  On a memory folder the plan sorts every always-loaded topic file into `AlwaysOnMemory/`, trimmed
314
291
  in place, and every other topic file into `OnDemandMemory/`, untouched; routed pieces join
@@ -333,6 +310,10 @@ kept out to fit, so change `--budget` with the numbers in front of you.
333
310
  | flag | effect |
334
311
  |---|---|
335
312
  | `--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 |
313
+ | `--loaded <path>` | a file Claude Code loads this session; repeatable; the only way a file outside the folder is read (`--host-file` still works) |
314
+ | `--memory-dir <path>` | the auto memory folder Claude Code names; also the folder to use |
315
+ | `--from-log` | take the loaded files from Claude Code's own load log for this folder |
316
+ | `--diff summary` | the plan and the operation list without the file diffs |
336
317
  | `--budget <n>` | always-loaded token budget AlwaysOnMemory must fit (default: see above) |
337
318
  | `--profile <name>` | how much guidance to embed: `auto`, `none`, `routing`, `full` (default `auto`) |
338
319
  | `--allow-secrets` | preview as if a credential-shaped source were allowed through |
@@ -344,16 +325,41 @@ depends on, about 210 tokens; `full` is the complete discipline set, about 710 t
344
325
  refuses (with `--force` to override) a compile that would not shrink the always-loaded prefix,
345
326
  naming the before/after tokens and the break-even point.
346
327
 
328
+ ### `minnimemory doctor [path]`
329
+
330
+ After `init`, never first: it refuses until `init` has run for this project, and with no path
331
+ it uses the folder `init` saved. The audit, drift since the last apply (MM010), then the re-apply
332
+ plan and "run apply", or "nothing to apply". Never modifies anything. Works on a repo, a memory folder, or a
333
+ single file. Names a workspace compiled by an older layout (manifest v4/v5) as such, with "run
334
+ undo, then apply" as the fix.
335
+
336
+ | flag | effect |
337
+ |---|---|
338
+ | `--json` | machine-readable output: the audit under `doctor`, the plan under `plan` |
339
+ | `--force` | on a compiled workspace with no drift, show the re-apply plan anyway |
340
+ | `--ci` | terse output, no colour |
341
+ | `--fail-on <sev>` | exit 1 at this severity or above: `low`, `med`, `high` (default `high`) |
342
+ | `--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) |
343
+ | `--only <ids>` | run only these rules, comma separated |
344
+ | `--ignore <ids>` | skip these rules, comma separated |
345
+ | `--rules` | list the rule set and exit |
346
+
347
+ Exit codes: `0` clean, `1` findings at or above `--fail-on`, `2` execution error, so a CI step
348
+ (`npx -y minnimemory doctor --ci --fail-on med`) can fail the build on memory bloat the same way
349
+ a lint error would.
350
+
347
351
  ### `minnimemory apply [path]`
348
352
 
349
- Writes what `doctor` or `init` showed. Looks at the workspace and does the right thing: an
353
+ Writes what `init` or `doctor` showed. On a memory folder it refuses until `init` was told what
354
+ loads it (moving a file an unseen outside file imports would break that import);
355
+ `--only-this-folder` says nothing outside loads it. Looks at the workspace and does the right thing: an
350
356
  uncompiled host file or memory folder gets a fresh compile; a compiled workspace with drift gets
351
357
  re-applied, keeping every hand edit and every routed file; a compiled workspace with no drift
352
358
  prints "nothing to apply" and changes nothing. Same flags, backups (`.minnimemory/original/`,
353
- `.minnimemory/previous/`) and refusals as `doctor`/`init`.
359
+ `.minnimemory/previous/`) and refusals as `init`/`doctor`.
354
360
 
355
361
  `--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
362
+ matches" when the hash differs from the one `init`/`doctor` printed, so what you approved is
357
363
  what gets written; plain `apply` skips that check and always writes the current plan.
358
364
 
359
365
  `apply` follows a pointer: if `CLAUDE.md` is only `@AGENTS.md` or "See `AGENTS.md`", it compiles
@@ -391,12 +397,10 @@ Starts an MCP server, `--profile basic` (the same four verbs, always registered)
391
397
 
392
398
  | flag | effect |
393
399
  |---|---|
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 |
400
+ | `--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`) |
401
+ | `--allow-write` | adds the full profile's write tool. No effect on basic, which is read-only by construction |
398
402
 
399
- `doctor`/`init` take `diff: "summary"` (default) or `"full"`; `apply`/`undo` take `content: true`
403
+ `init`/`doctor` take `diff: "summary"` (default) or `"full"`; `apply`/`undo` take `content: true`
400
404
  to include file content for a host without a shell. With `format: "json"`, `init` returns three
401
405
  keys, `map` (each load group, and each file's path, tokens and owner), `doctor` and `plan`;
402
406
  `doctor` returns the last two. Every reply's data block carries a code drawn for that reply in
@@ -414,7 +418,6 @@ add` line above, turns on the drift notice hook, and prints the next step.
414
418
  |---|---|
415
419
  | `--scope <name>` | `user`, `project`, or `local`, same meaning as `claude mcp add -s` (default `user`) |
416
420
  | `--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
421
  | `--dry-run` | print the command without running it, exit 0 |
419
422
  | `--force` | remove an existing registration first, then re-add |
420
423
  | `--no-hook` | skip the drift notice hook (on by default) |
@@ -478,9 +481,9 @@ The MCP server's own always-loaded cost, measured (not assumed), approx-v2 token
478
481
 
479
482
  | | tokens |
480
483
  |---|---|
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 |
484
+ | basic profile tool schemas (`init`, `doctor`, `apply`, `undo`), read-only | 1,173 |
485
+ | basic profile tool schemas, `--allow-write` (no effect on basic) | 1,173 |
486
+ | server instructions text | 50 |
484
487
 
485
488
  Measured against a real registered server over an in-memory MCP transport, not assumed. Claude
486
489
  Code defers a tool's full schema until it decides
@@ -490,7 +493,7 @@ kept under about 60 tokens for that reason.
490
493
 
491
494
  ## Security
492
495
 
493
- - `doctor`, `init`, `apply`, `undo`, and `mcp` make no network calls and never run a subprocess.
496
+ - `init`, `doctor`, `apply`, `undo`, and `mcp` make no network calls and never run a subprocess.
494
497
  - `apply`/`undo` refuse a symlinked source and refuse to write or delete through a symlink, so a
495
498
  cloned repo cannot point a memory file, or a routed piece, at a file outside the workspace.
496
499
  - `apply` refuses to write when the source holds a credential-shaped string, unless you pass
@@ -525,7 +528,7 @@ kept under about 60 tokens for that reason.
525
528
  No. Every command makes no network calls at all. There is no telemetry and no API key.
526
529
 
527
530
  **Will it destroy my `CLAUDE.md`?**
528
- No. `doctor`/`init` are dry run by default. `apply` copies your original verbatim to
531
+ No. `init`/`doctor` are dry run by default. `apply` copies your original verbatim to
529
532
  `.minnimemory/original/` before anything is modified, never writes over that backup, and `undo`
530
533
  restores it byte-identical on the machine that ran `apply`.
531
534
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "minnimemory",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "MinniMemoryMCP: an MCP server that gives an AI coding agent curated memory. Tools audit the agent's memory file, compile it into a small AlwaysOnMemory body plus OnDemandMemory files, serve it back on demand and keep it maintained. Deterministic, lossless, offline. Built by MinniAI.",
5
5
  "type": "module",
6
6
  "mcpName": "io.github.MinniAI-com/minnimemory",