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/CHANGELOG.md +384 -0
- package/README.md +166 -129
- package/examples/CLAUDE.md +76 -75
- package/package.json +3 -2
- package/pkg/chunks/chunk-37XDFG6F.js +50 -0
- package/pkg/chunks/chunk-JPLA4NRD.js +151 -0
- package/pkg/chunks/mcpServer-UJE52S2W.js +2 -0
- package/pkg/cli.js +203 -153
- package/pkg/index.d.ts +0 -5
- package/pkg/index.js +1 -1
- package/pkg/chunks/chunk-74LHXLLF.js +0 -34
- package/pkg/chunks/chunk-QDDKAHAE.js +0 -19
- package/pkg/chunks/chunk-QUL7N4BR.js +0 -120
- package/pkg/chunks/mcpServer-EWPP2F2F.js +0 -2
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: `
|
|
9
|
-
offline: no model, no key, no network, and the MCP server never writes your
|
|
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
|
|
19
|
-
```
|
|
23
|
+
$ npx -y minnimemory init .
|
|
20
24
|
|
|
21
|
-
|
|
22
|
-
|
|
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
|
-
|
|
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
|
-
|
|
37
|
-
|
|
38
|
-
|
|
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 +
|
|
57
|
-
write CLAUDE.md +
|
|
58
|
-
|
|
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:
|
|
47
|
+
plan: e36132de24a037c0
|
|
65
48
|
dry run, nothing written. To write these files, run:
|
|
66
|
-
npx -y minnimemory apply --plan
|
|
49
|
+
npx -y minnimemory apply --plan e36132de24a037c0 --budget 2000 .
|
|
67
50
|
|
|
68
|
-
$ npx -y minnimemory apply --plan
|
|
69
|
-
|
|
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
|
-
|
|
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`
|
|
82
|
-
|
|
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
|
|
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
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `apply` | writes what `doctor
|
|
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: `
|
|
144
|
-
|
|
145
|
-
|
|
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
|
|
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
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
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
|
-
| "
|
|
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
|
-
| "
|
|
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
|
|
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`
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
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`
|
|
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.
|
|
300
|
-
writes: passing `--write` or `--update` prints one line ("init never writes; use
|
|
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
|
|
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`
|
|
327
|
-
|
|
328
|
-
depends on, about
|
|
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 `
|
|
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
|
|
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
|
|
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.
|
|
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): `
|
|
367
|
-
| `--allow-write` | adds the full profile's write
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
`
|
|
372
|
-
|
|
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` |
|
|
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 (`
|
|
449
|
-
| basic profile tool schemas, `--allow-write` (no effect on basic) | 1,
|
|
450
|
-
| server instructions text |
|
|
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
|
-
- `
|
|
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
|
|
496
|
-
`.minnimemory/original/` before anything is modified, and `undo`
|
|
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
|
package/examples/CLAUDE.md
CHANGED
|
@@ -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
|
-
##
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
`
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
- 2026-08-
|
|
73
|
-
- 2026-
|
|
74
|
-
- 2026-
|
|
75
|
-
- 2026-
|
|
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
|