minnimemory 1.0.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/README.md CHANGED
@@ -5,84 +5,81 @@ 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
+ memory map for /path/to/your/repo: every file Claude Code loads, by its own rules
26
+ every session: 897 tokens
25
27
 
26
- ```
27
- $ npx -y minnimemory doctor
28
-
29
- MM003 "Current status" (lines 6-11) holds a status heading and high
30
- dated entries and status language in the always-loaded
31
- prefix
28
+ MM003 "Current status" (lines 28-33) holds a status heading and high
29
+ status language in the always-loaded prefix
32
30
  -> move it to an OnDemandMemory file; editing it here invalidates
33
31
  the prompt cache every time
34
32
  ...2 more findings...
35
33
 
36
- 3 findings (2 high, 1 med)
37
- always-loaded prefix: 689 tokens across 1 file (budget 2,000, within)
38
- tokenizer: approx-v2, an offline estimate
39
-
40
- project root: /path/to/your/repo
41
- index: CLAUDE.md
42
-
43
- CLAUDE.md 689 -> 184 tokens (share 1,896)
44
- .claude/OnDemandMemory/CLAUDE__history.md 503 volatile test, src, error, deploys
45
-
46
- always-loaded prefix: 689 -> 267 tokens (-61.2%)
47
- break-even: 422 tokens of OnDemandMemory open all session
48
- budget: 2,000 (default; pass --budget to change it)
49
- verdict: compile. Every turn with no routed file open saves 422 tokens; a turn with every
50
- routed file open (503 tokens) costs 81 more than today. It pays unless routed text is open
34
+ always-loaded, files this plan rewrites: 897 -> 363 tokens (-59.5%)
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).
36
+ verdict: compile. Every turn with no routed file open saves 534 tokens; a turn with every
37
+ routed file open (615 tokens) costs 81 more than today. It pays unless routed text is open
51
38
  on nearly every turn.
52
39
 
53
40
  operations:
54
41
  write .minnimemory/.gitignore +4 -0
55
42
  copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md)
56
- write .claude/OnDemandMemory/CLAUDE__history.md +61 -0
57
- write CLAUDE.md +7 -56
58
- write .minnimemory/graph.json +252 -0
59
- write .minnimemory/manifest.json +45 -0
60
-
61
- diff:
62
- ...the full unified diff of every file above...
43
+ write .claude/OnDemandMemory/CLAUDE__history.md +53 -0
44
+ write CLAUDE.md +6 -47
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,49 +257,35 @@ 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 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).
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
270
+ `map`, beside `doctor` and `plan`.
271
+
272
+ The map starts with a `setup` block, so you know how the project is set up before anything is
273
+ proposed: the host file Claude Code starts from, the file it points at when it is only a pointer
274
+ (`CLAUDE.md` holding `@AGENTS.md`), the one file `apply` will rewrite, and whether that file is
275
+ already compiled. When the project holds an `AGENTS.md` that Claude Code does not load, the map
276
+ ends with a `not loaded by Claude Code` group that names each one and why: a `CLAUDE.md` in the
277
+ same folder takes its place, or a `CLAUDE.md` higher up switches `AGENTS.md` off and no pointer
278
+ sits beside it. Those files count toward no total. An `AGENTS.md` host is compiled, audited and
279
+ undone exactly as a `CLAUDE.md` host is.
292
280
 
293
281
  `install` also adds an `InstructionsLoaded` hook, which records what Claude Code actually loads
294
282
  for each project in a small file under your Claude config folder (machine-local, never in a
295
- repo). `init` marks each file Claude Code was seen loading and lists anything it loaded that the
296
- rules missed; `doctor` reports the same as MM016.
283
+ repo). `init --from-log` reads it as the report of what loads your memory folder.
297
284
 
298
285
  Then the first-time preview: the audit, then the plan with a unified diff of every file `apply` would
299
- overwrite and the full content of every file it would create, then the command to run. Never
300
- writes: passing `--write` or `--update` prints one line ("init never writes; use apply") and
301
- 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.
302
289
 
303
290
  On a memory folder the plan sorts every always-loaded topic file into `AlwaysOnMemory/`, trimmed
304
291
  in place, and every other topic file into `OnDemandMemory/`, untouched; routed pieces join
@@ -311,38 +298,77 @@ nothing is volatile the plan says so, tells you what a lower budget would save (
311
298
  second plan), and leaves the choice to you. A lower `--budget` is shared fairly: a file that fits
312
299
  an equal share stays whole, the largest files split the rest, and a heading-less file over its
313
300
  share keeps its leading paragraphs and routes the rest as `<name>__detail.md`. A single host
314
- file keeps the flat 2,000 default. The plan prints the budget it used and names every section
301
+ file's default budget is 60% of the file, never under 2,000. On a file over about 3,300 tokens,
302
+ where 60% is above that floor, the saving lands at 40% or more with the rules still in the file;
303
+ a smaller file saves less, since the floor lets it keep more: its rule sections and what every task needs (commands, build,
304
+ test, architecture) stay, by content rather than by heading alone, and its records, references
305
+ and one-task runbooks move; a section over the room keeps its head and routes the rest as one
306
+ "(continued)" piece. The plan prints the budget it used and names every section
315
307
  kept out to fit, so change `--budget` with the numbers in front of you.
316
308
  `.minnimemory/` (backups, manifest) is bookkeeping only, never something Claude Code auto-loads.
317
309
 
318
310
  | flag | effect |
319
311
  |---|---|
320
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 |
321
317
  | `--budget <n>` | always-loaded token budget AlwaysOnMemory must fit (default: see above) |
322
318
  | `--profile <name>` | how much guidance to embed: `auto`, `none`, `routing`, `full` (default `auto`) |
323
319
  | `--allow-secrets` | preview as if a credential-shaped source were allowed through |
324
320
  | `--episodic-json` | plan episodic OnDemandMemory files (changelogs, logs) as JSON, not Markdown |
325
321
 
326
- **Profiles:** `auto` picks `none` when the source is under the token budget and `routing` at or
327
- over it. `none` embeds nothing but the one-line routing note; `routing` is the rules routing
328
- depends on, about 200 tokens; `full` is the complete discipline set, about 690 tokens. `apply`
322
+ **Profiles:** `auto` is the same as `none` today, for every source: the list header already
323
+ tells the agent how to route. `none` embeds no rules block; `routing` is the rules routing
324
+ depends on, about 210 tokens; `full` is the complete discipline set, about 710 tokens. `apply`
329
325
  refuses (with `--force` to override) a compile that would not shrink the always-loaded prefix,
330
326
  naming the before/after tokens and the break-even point.
331
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
+
332
351
  ### `minnimemory apply [path]`
333
352
 
334
- 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
335
356
  uncompiled host file or memory folder gets a fresh compile; a compiled workspace with drift gets
336
357
  re-applied, keeping every hand edit and every routed file; a compiled workspace with no drift
337
358
  prints "nothing to apply" and changes nothing. Same flags, backups (`.minnimemory/original/`,
338
- `.minnimemory/previous/`) and refusals as `doctor`/`init`.
359
+ `.minnimemory/previous/`) and refusals as `init`/`doctor`.
339
360
 
340
361
  `--plan <hash>` recomputes the plan from disk and refuses with "the plan on disk no longer
341
- 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
342
363
  what gets written; plain `apply` skips that check and always writes the current plan.
343
364
 
344
365
  `apply` follows a pointer: if `CLAUDE.md` is only `@AGENTS.md` or "See `AGENTS.md`", it compiles
345
- `AGENTS.md` and leaves the pointer untouched. Neither follows a symlink, in either direction. A
366
+ `AGENTS.md` and leaves the pointer untouched. A compiled host file renamed afterwards (for
367
+ example `CLAUDE.md` to `AGENTS.md`, with or without a pointer left behind) is the same host:
368
+ `doctor` reports the rename, and one `apply` carries the manifest and the backups over, so `undo`
369
+ still restores your original into the file that holds your memory now. A pointer rewritten by
370
+ hand so that it no longer reaches the compiled file is reported as drift; `apply` then writes
371
+ nothing and tells you the two ways out. Neither follows a symlink, in either direction. A
346
372
  workspace compiled by an older layout (manifest v4/v5) refuses with "run undo, then apply".
347
373
 
348
374
  ### `minnimemory undo [path]`
@@ -357,19 +383,29 @@ reports that as a finding before it matters). Works the same, byte for byte, on
357
383
  compiled by an older layout (manifest v4 or v5) - "run undo, then apply" always has an undo to
358
384
  run.
359
385
 
386
+ **`undo` works only on the machine that ran `apply`.** The backups in `.minnimemory/original/`
387
+ are gitignored, so they never reach your repo: a teammate's clone has the compiled files and
388
+ the manifest, but nothing to restore from. There, the way back is git history (the commit
389
+ before the compile). If `.minnimemory/manifest.json` is lost or unreadable (a git merge
390
+ conflict is enough), `apply` refuses and changes nothing; `undo --force` still restores every
391
+ backup in `original/` and leaves `.claude/OnDemandMemory/` for you to delete, since nothing then
392
+ records which files there it wrote.
393
+
360
394
  ### `minnimemory mcp [path]`
361
395
 
362
396
  Starts an MCP server, `--profile basic` (the same four verbs, always registered) by default.
363
397
 
364
398
  | flag | effect |
365
399
  |---|---|
366
- | `--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`) |
367
- | `--allow-write` | adds the full profile's write tools. No effect on basic, which is read-only by construction |
368
- | `--follow-external-imports` | let the tools follow `@path` imports outside the server root |
369
- | `--include-auto-memory` | let the tools see the operator's OS-level Claude Code auto-memory folder, and resolve `"auto-memory"` as a target |
370
-
371
- `doctor`/`init` take `diff: "summary"` (default) or `"full"`; `apply`/`undo` take `content: true`
372
- to include file content for a host without a shell. Register it with your agent rather than
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 |
402
+
403
+ `init`/`doctor` take `diff: "summary"` (default) or `"full"`; `apply`/`undo` take `content: true`
404
+ to include file content for a host without a shell. With `format: "json"`, `init` returns three
405
+ keys, `map` (each load group, and each file's path, tokens and owner), `doctor` and `plan`;
406
+ `doctor` returns the last two. Every reply's data block carries a code drawn for that reply in
407
+ its open and close lines, so no line of memory text can end it; a memory line that looks like
408
+ the marker is also shown with "(quoted)" in the text form, and the JSON form keeps it exact. Register it with your agent rather than
373
409
  running it by hand: `npx -y minnimemory install` above (a direct `node "<path>/cli.js" mcp`
374
410
  registration), or by hand with `claude mcp add minnimemory -- npx -y minnimemory mcp`.
375
411
 
@@ -381,12 +417,12 @@ add` line above, turns on the drift notice hook, and prints the next step.
381
417
  | flag | effect |
382
418
  |---|---|
383
419
  | `--scope <name>` | `user`, `project`, or `local`, same meaning as `claude mcp add -s` (default `user`) |
384
- | `--write` | append `--allow-write` to the served command |
385
- | `--auto-memory` | append `--include-auto-memory` to the served command |
420
+ | `--write` | serve the full profile with its write tools (`--profile full --allow-write`); the default basic profile never writes |
386
421
  | `--dry-run` | print the command without running it, exit 0 |
387
422
  | `--force` | remove an existing registration first, then re-add |
388
423
  | `--no-hook` | skip the drift notice hook (on by default) |
389
424
  | `--remove` | remove the MCP registration and the drift hook `install` added |
425
+ | `--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 |
390
426
 
391
427
  Idempotent: an existing registration is reported, with the command to change it, not duplicated.
392
428
  Without the `claude` CLI on `PATH` it prints the manual line and a JSON snippet instead, exit 2;
@@ -445,9 +481,9 @@ The MCP server's own always-loaded cost, measured (not assumed), approx-v2 token
445
481
 
446
482
  | | tokens |
447
483
  |---|---|
448
- | basic profile tool schemas (`doctor`, `init`, `apply`, `undo`), read-only | 1,072 |
449
- | basic profile tool schemas, `--allow-write` (no effect on basic) | 1,072 |
450
- | 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 |
451
487
 
452
488
  Measured against a real registered server over an in-memory MCP transport, not assumed. Claude
453
489
  Code defers a tool's full schema until it decides
@@ -457,7 +493,7 @@ kept under about 60 tokens for that reason.
457
493
 
458
494
  ## Security
459
495
 
460
- - `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.
461
497
  - `apply`/`undo` refuse a symlinked source and refuse to write or delete through a symlink, so a
462
498
  cloned repo cannot point a memory file, or a routed piece, at a file outside the workspace.
463
499
  - `apply` refuses to write when the source holds a credential-shaped string, unless you pass
@@ -492,8 +528,9 @@ kept under about 60 tokens for that reason.
492
528
  No. Every command makes no network calls at all. There is no telemetry and no API key.
493
529
 
494
530
  **Will it destroy my `CLAUDE.md`?**
495
- No. `doctor`/`init` are dry run by default. `apply` copies your original verbatim to
496
- `.minnimemory/original/` before anything is modified, and `undo` restores it byte-identical.
531
+ No. `init`/`doctor` are dry run by default. `apply` copies your original verbatim to
532
+ `.minnimemory/original/` before anything is modified, never writes over that backup, and `undo`
533
+ restores it byte-identical on the machine that ran `apply`.
497
534
 
498
535
  **Does this fight with prompt caching?**
499
536
  The opposite. Splitting volatile content out of the always-loaded prefix is precisely what keeps
@@ -1,75 +1,76 @@
1
- # Ledger API
2
-
3
- Ledger is a small double-entry bookkeeping service: a Fastify HTTP API over Postgres, with a
4
- nightly reconciliation worker. Single package, TypeScript throughout.
5
-
6
- ## Current status
7
-
8
- As of 2026-08-30 the billing rewrite is in progress and blocked on review of the new posting
9
- rules. The flaky reconciliation test is still skipped. Next steps: land the posting rules, then
10
- unskip the test, then cut 1.4.0.
11
-
12
- ## Conventions
13
-
14
- - All money is stored as integer cents. Never use floats for currency anywhere.
15
- - Every write goes through a repository function. Route handlers never touch the database.
16
- - Errors thrown across a service boundary are typed. No bare `throw new Error`.
17
- - Prefer small pull requests. One behaviour change per PR.
18
-
19
- ## Architecture
20
-
21
- Requests enter through `src/http/`, which validates and hands off to `src/services/`. Services
22
- compose repository calls from `src/repo/` inside a single transaction per request. The worker in
23
- `src/worker/` reuses the same services and runs on a cron schedule. There is no message queue.
24
-
25
- ## Layout
26
-
27
- ```
28
- src/
29
- ├── http/
30
- │ ├── routes/
31
- │ ├── schemas/
32
- │ └── errorMap.ts
33
- ├── services/
34
- ├── repo/
35
- ├── worker/
36
- └── errors.ts
37
- ```
38
-
39
- ## Authentication
40
-
41
- Bearer tokens are verified against the auth service on every request, cached for sixty seconds
42
- by token hash. Service-to-service calls use a signed header, not a bearer token. Never log a
43
- token, even truncated.
44
-
45
- ## Error handling
46
-
47
- Every service throws one of the typed errors in `src/errors.ts`. The HTTP layer maps them to
48
- status codes in exactly one place, `src/http/errorMap.ts`. Unknown errors become a 500 with a
49
- correlation id and are never surfaced to the client with their message.
50
-
51
- ## Testing
52
-
53
- Unit tests run with `npm test`. Integration tests need a database: `npm run db:up` then
54
- `npm run test:integration`. The reconciliation suite is slow and lives behind
55
- `npm run test:reconcile`. Always run the integration suite before opening a pull request that
56
- touches `src/repo/`.
57
-
58
- ## Deployment
59
-
60
- Pushing to main builds a container and deploys to staging automatically. Production is a
61
- manual promotion from the staging build. Migrations run before the new version starts; a
62
- migration that cannot roll back must be split into two deploys.
63
-
64
- ## Common tasks
65
-
66
- - Add an endpoint: schema in `src/http/schemas/`, handler in `src/http/routes/`, service call.
67
- - Add a migration: `npm run migrate:new <name>`, then edit the generated file.
68
- - Rotate the signing key: update the secret, deploy, then revoke the old key after one hour.
69
-
70
- ## Changelog
71
-
72
- - 2026-08-28 posting rules draft merged behind a flag
73
- - 2026-08-21 reconciliation worker moved to the shared services layer
74
- - 2026-08-14 typed errors introduced, error map centralised
75
- - 2026-08-07 v1.3.0 released
1
+ # Ledger API
2
+
3
+ Ledger is a small double-entry bookkeeping service: a Fastify HTTP API over Postgres, with a
4
+ nightly reconciliation worker. Single package, TypeScript throughout.
5
+
6
+ ## Conventions
7
+
8
+ - All money is stored as integer cents. Never use floats for currency anywhere.
9
+ - Every write goes through a repository function. Route handlers never touch the database.
10
+ - Errors thrown across a service boundary are typed. No bare `throw new Error`.
11
+ - Prefer small pull requests. One behaviour change per PR.
12
+ - Never log a token, even truncated.
13
+
14
+ ## Architecture
15
+
16
+ Requests enter through `src/http/`, which validates and hands off to `src/services/`. Services
17
+ compose repository calls from `src/repo/` inside a single transaction per request. The
18
+ reconciliation worker in `src/worker/` reuses the same services and runs on a cron schedule.
19
+ There is no message queue.
20
+
21
+ ## Commands
22
+
23
+ - `npm test` runs the unit tests. Integration tests need a database: `npm run db:up`, then
24
+ `npm run test:integration`. Run them before any pull request that touches `src/repo/`.
25
+ - `npm run test:reconcile` is the slow reconciliation suite.
26
+ - `npm run migrate:new <name>` adds a migration; edit the generated file.
27
+
28
+ ## Current status
29
+
30
+ As of 2026-08-30 the billing rewrite is in progress and blocked on review of the new posting
31
+ rules. The flaky reconciliation test is still skipped. Next steps: land the posting rules, then
32
+ unskip the test, then cut 1.4.0.
33
+
34
+ ## Authentication
35
+
36
+ Bearer tokens are verified against the auth service on every request, cached for sixty seconds
37
+ by token hash. Service-to-service calls use a signed header, not a bearer token. The cache is
38
+ keyed by token hash, so a revoked token can stay valid for up to a minute.
39
+
40
+ ## Error handling
41
+
42
+ Every service throws one of the typed errors in `src/errors.ts`. The HTTP layer maps them to
43
+ status codes in exactly one place, `src/http/errorMap.ts`. Unknown errors become a 500 with a
44
+ correlation id and are never surfaced to the client with their message.
45
+
46
+ ## Deployment
47
+
48
+ Pushing to main builds a container and deploys to staging automatically. Production is a
49
+ manual promotion from the staging build. Migrations run before the new version starts; a
50
+ migration that cannot roll back must be split into two deploys. Rollback is a promotion of the
51
+ previous staging build; the database is not rolled back, which is why migrations are additive.
52
+
53
+ ## Common tasks
54
+
55
+ - Add an endpoint: schema in `src/http/schemas/`, handler in `src/http/routes/`, service call.
56
+ - Rotate the signing key: update the secret, deploy, then revoke the old key after one hour.
57
+ - Replay a day of postings: `npm run replay -- --date YYYY-MM-DD`, on staging first.
58
+
59
+ ## Incident notes
60
+
61
+ - 2026-08-26 the reconciliation worker double-posted a batch after a retry; fixed by the
62
+ idempotency key on `postBatch`. Watch for `duplicate posting` in the worker log.
63
+ - 2026-08-12 staging ran out of connections under the load test; the pool went from 10 to 25.
64
+ - 2026-07-30 a migration locked `postings` for four minutes; migrations now run `CONCURRENTLY`.
65
+ - 2026-07-16 the auth cache served a revoked token for a minute; accepted, documented above.
66
+
67
+ ## Changelog
68
+
69
+ - 2026-08-28 posting rules draft merged behind a flag
70
+ - 2026-08-21 reconciliation worker moved to the shared services layer
71
+ - 2026-08-14 typed errors introduced, error map centralised
72
+ - 2026-08-07 v1.3.0 released
73
+ - 2026-07-24 signed service-to-service header replaced the shared secret
74
+ - 2026-07-10 v1.2.0 released, with the nightly reconciliation worker
75
+ - 2026-06-26 repository layer introduced; route handlers no longer touch the database
76
+ - 2026-06-12 v1.1.0 released