minnimemory 1.2.0 → 1.3.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 +67 -0
- package/LICENSE +45 -45
- package/README.md +58 -23
- package/examples/CLAUDE.md +76 -76
- package/examples/README.md +11 -11
- package/package.json +59 -59
- package/pkg/chunks/chunk-5PBHKJLW.js +50 -0
- package/pkg/chunks/chunk-AXISH7T3.js +155 -0
- package/pkg/chunks/{mcpServer-UJE52S2W.js → mcpServer-V7GWYVQ6.js} +1 -1
- package/pkg/cli.js +123 -111
- package/pkg/index.d.ts +22 -22
- package/pkg/index.js +1 -1
- package/pkg/chunks/chunk-37XDFG6F.js +0 -50
- package/pkg/chunks/chunk-JPLA4NRD.js +0 -151
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,73 @@
|
|
|
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.3.0 - 2026-10-12
|
|
7
|
+
|
|
8
|
+
- New: on a memory folder, a topic file the index never linked now gets a generated list line
|
|
9
|
+
with trigger words, and `recall` and the prompt hook rank its sections too, so it stops being
|
|
10
|
+
a dead end the agent can only reach by searching (DESIGN.md 6.10, decision 22). A file whose
|
|
11
|
+
name marks it as a copy, an old version, a backup or scratch (`x (old).md`, `x.bak.md`,
|
|
12
|
+
`x_copy.md`, `x_v1.md`, `scratch.md`, `untitled.md`, `README.md`) is left off the list and
|
|
13
|
+
named in the plan. The prompt hook also prints only sections that share at least two distinct
|
|
14
|
+
words with the prompt, and at least half of its words; before, one incidental word was enough
|
|
15
|
+
to print a block on every such turn.
|
|
16
|
+
- Changed: the prompt hook (`minnimemory hook`) now places one section, the best, only when it
|
|
17
|
+
is under 400 tokens, only when the always-loaded text does not hold a better match for the
|
|
18
|
+
prompt, and only once per Claude Code session (it reads `session_id` and keeps a small record
|
|
19
|
+
under the OS temp dir). On a 27-task session it placed about 2.6k tokens instead of about
|
|
20
|
+
14.7k (DESIGN.md 6.10, decision 23). `recall()` gained `includeAlwaysOn` for the ranking; the
|
|
21
|
+
recall tool's own output is unchanged.
|
|
22
|
+
- New: `doctor --policy <file>` checks memory against a team's rule pack (`policy.json`). Two new
|
|
23
|
+
rules run only with it: MM020, a line the pack requires is missing from the always-loaded
|
|
24
|
+
memory (a copy only in an OnDemandMemory file does not count), and MM021, text the pack bans
|
|
25
|
+
is in a memory file, matched as plain text ignoring case and spacing. Each finding names the
|
|
26
|
+
pack entry (`ref` in `--json`) and never quotes the memory. The pack's `always_on_tokens` is
|
|
27
|
+
the MM001 budget when `--budget` is not given. Patterns are plain text only; a pack with
|
|
28
|
+
`regex` is refused and says to list each variant. Without `--policy`, `doctor` is unchanged,
|
|
29
|
+
and the MCP `doctor` tool does not take a pack.
|
|
30
|
+
- Support window: a workspace compiled by 1.0.0 is now three minor versions back, past the
|
|
31
|
+
window this release is tested against (6 months or 3 minors). One compiled by 1.2.1 is tested:
|
|
32
|
+
it reads with no high finding and every routed piece found. Re-apply an older workspace to
|
|
33
|
+
bring it inside the window.
|
|
34
|
+
|
|
35
|
+
## 1.2.1 - 2026-10-09
|
|
36
|
+
|
|
37
|
+
- New: `init` and `doctor` name any loaded `CLAUDE.md` saved as UTF-16. Claude Code reads such a
|
|
38
|
+
file as plain text and does not follow its `@` imports, so the files it imports never load.
|
|
39
|
+
Save it as UTF-8.
|
|
40
|
+
- Fixed: a small dated or status section merged with the small sections around it, and the
|
|
41
|
+
merged file took the "volatile" reason, so rules and how-tos were filed under the `__history`
|
|
42
|
+
piece, where an agent looking for a rule does not open. Volatile text now never shares a file
|
|
43
|
+
with anything else. On the example `CLAUDE.md` the rules get their own `__detail` piece: one
|
|
44
|
+
more list line, so the always-loaded part is 389 tokens, not 363 (Memory Size Test).
|
|
45
|
+
- Fixed: for a memory folder whose path holds `$`, `` ` ``, `"`, `%` or `!`, the apply and undo
|
|
46
|
+
commands from Claude Code name the folder `.`, but the reply did not say to run them from inside
|
|
47
|
+
it, and run from there they found no `init` record. The reply now says where to run, and the
|
|
48
|
+
record is found by its memory folder.
|
|
49
|
+
- Fixed: a re-apply dropped OnDemandMemory list lines whose file had been deleted, and the whole
|
|
50
|
+
list when none was left, without a word. It now names each dropped line.
|
|
51
|
+
- Fixed: a `manifest.json` that is there but was refused (a path it may not hold, a hand edit)
|
|
52
|
+
was reported as "missing or unreadable". Messages now say which: missing, not valid JSON, or
|
|
53
|
+
refused.
|
|
54
|
+
- Fixed: `npm publish` warned that the `bin` entry was cleaned; it is now written the way npm
|
|
55
|
+
wants it.
|
|
56
|
+
- New: `minnimemory uninstall` (the same as `install --remove`) removes the MCP registration and
|
|
57
|
+
both hooks, lists the folders still compiled with the `undo` command for each, and says what it
|
|
58
|
+
keeps. Documented in the README and the guide.
|
|
59
|
+
- Fixed: `install --remove` and `install` treated any `node "<path>" drift` or `loaded` hook as
|
|
60
|
+
ours, so they could remove or repoint another tool's hook. A hook is ours only when its path
|
|
61
|
+
names minnimemory (or its package.json does).
|
|
62
|
+
- Fixed: a second `install --remove` exited 1 on "No MCP server named minnimemory"; it now says
|
|
63
|
+
nothing is registered and exits 0.
|
|
64
|
+
- Fix: pointing `apply` at a memory index (`MEMORY.md`) now suggests `init` on the folder, not
|
|
65
|
+
`doctor`, which refuses before `init` has run.
|
|
66
|
+
- New: `apply` on a project keeps the record it ran with in the repo, in
|
|
67
|
+
`.minnimemory/discovery.json` beside `manifest.json`, committed with it. A fresh clone (a CI
|
|
68
|
+
runner, a teammate) has no `init` record of its own, so `doctor` and a re-apply now read this
|
|
69
|
+
one and say so. It lists the always-loaded files inside the project, relative to it: nothing
|
|
70
|
+
from your home folder or your Claude config, and not `CLAUDE.local.md`. This machine's own
|
|
71
|
+
record still wins. `undo` removes it.
|
|
72
|
+
|
|
6
73
|
## 1.2.0 - 2026-10-08
|
|
7
74
|
|
|
8
75
|
- Fixed: undoing a sorted memory folder with 1.1.0 restored the files but left your user
|
package/LICENSE
CHANGED
|
@@ -1,45 +1,45 @@
|
|
|
1
|
-
MinniMemoryMCP License
|
|
2
|
-
|
|
3
|
-
Copyright (c) 2026 MinniAI. All rights reserved.
|
|
4
|
-
|
|
5
|
-
1. Grant. MinniAI gives you a free, non-exclusive, non-transferable, revocable
|
|
6
|
-
license to install and run this software package (the "Software"),
|
|
7
|
-
unmodified, for your own use. Use inside your own company or for your own
|
|
8
|
-
commercial projects is allowed.
|
|
9
|
-
|
|
10
|
-
2. Restrictions. You may not:
|
|
11
|
-
(a) copy, redistribute, sublicense, sell, rent or host the Software for
|
|
12
|
-
others;
|
|
13
|
-
(b) modify, translate or create derivative works of the Software;
|
|
14
|
-
(c) reverse engineer, decompile or disassemble the Software, except where
|
|
15
|
-
applicable law forbids this restriction;
|
|
16
|
-
(d) remove or alter any copyright or license notice in the Software.
|
|
17
|
-
|
|
18
|
-
3. Your files. The files the Software reads or writes on your machine (memory
|
|
19
|
-
files such as CLAUDE.md, the .minnimemory folder, backups) are yours.
|
|
20
|
-
MinniAI claims no rights in them. The Software makes no network calls and
|
|
21
|
-
sends nothing off your machine.
|
|
22
|
-
|
|
23
|
-
4. Generated instructions. The instruction text, rule text and structure
|
|
24
|
-
that the Software writes into your memory files (the "Generated
|
|
25
|
-
Instructions") are MinniAI's copyrighted work. You may keep and use them
|
|
26
|
-
in memory files on machines you control, for your own or your company's
|
|
27
|
-
AI agents. You may not extract, republish, redistribute or sell the
|
|
28
|
-
Generated Instructions, include them in another product or service, or
|
|
29
|
-
use them, in whole or in part, as training or evaluation data for a
|
|
30
|
-
machine learning model.
|
|
31
|
-
|
|
32
|
-
5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
|
|
33
|
-
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
34
|
-
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
35
|
-
Back up your files before using write features such as --allow-write.
|
|
36
|
-
|
|
37
|
-
6. Limitation of liability. IN NO EVENT SHALL MINNIAI BE LIABLE FOR ANY
|
|
38
|
-
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
|
|
39
|
-
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
|
|
40
|
-
THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.
|
|
41
|
-
|
|
42
|
-
7. Termination. This license ends automatically if you break any of its
|
|
43
|
-
terms. When it ends, stop using the Software and delete your copies.
|
|
44
|
-
|
|
45
|
-
8. Contact. https://minniai.com
|
|
1
|
+
MinniMemoryMCP License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 MinniAI. All rights reserved.
|
|
4
|
+
|
|
5
|
+
1. Grant. MinniAI gives you a free, non-exclusive, non-transferable, revocable
|
|
6
|
+
license to install and run this software package (the "Software"),
|
|
7
|
+
unmodified, for your own use. Use inside your own company or for your own
|
|
8
|
+
commercial projects is allowed.
|
|
9
|
+
|
|
10
|
+
2. Restrictions. You may not:
|
|
11
|
+
(a) copy, redistribute, sublicense, sell, rent or host the Software for
|
|
12
|
+
others;
|
|
13
|
+
(b) modify, translate or create derivative works of the Software;
|
|
14
|
+
(c) reverse engineer, decompile or disassemble the Software, except where
|
|
15
|
+
applicable law forbids this restriction;
|
|
16
|
+
(d) remove or alter any copyright or license notice in the Software.
|
|
17
|
+
|
|
18
|
+
3. Your files. The files the Software reads or writes on your machine (memory
|
|
19
|
+
files such as CLAUDE.md, the .minnimemory folder, backups) are yours.
|
|
20
|
+
MinniAI claims no rights in them. The Software makes no network calls and
|
|
21
|
+
sends nothing off your machine.
|
|
22
|
+
|
|
23
|
+
4. Generated instructions. The instruction text, rule text and structure
|
|
24
|
+
that the Software writes into your memory files (the "Generated
|
|
25
|
+
Instructions") are MinniAI's copyrighted work. You may keep and use them
|
|
26
|
+
in memory files on machines you control, for your own or your company's
|
|
27
|
+
AI agents. You may not extract, republish, redistribute or sell the
|
|
28
|
+
Generated Instructions, include them in another product or service, or
|
|
29
|
+
use them, in whole or in part, as training or evaluation data for a
|
|
30
|
+
machine learning model.
|
|
31
|
+
|
|
32
|
+
5. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
|
|
33
|
+
KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
|
34
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
|
|
35
|
+
Back up your files before using write features such as --allow-write.
|
|
36
|
+
|
|
37
|
+
6. Limitation of liability. IN NO EVENT SHALL MINNIAI BE LIABLE FOR ANY
|
|
38
|
+
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
|
|
39
|
+
OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
|
|
40
|
+
THE USE OF OR OTHER DEALINGS IN THE SOFTWARE.
|
|
41
|
+
|
|
42
|
+
7. Termination. This license ends automatically if you break any of its
|
|
43
|
+
terms. When it ends, stop using the Software and delete your copies.
|
|
44
|
+
|
|
45
|
+
8. Contact. https://minniai.com
|
package/README.md
CHANGED
|
@@ -31,24 +31,25 @@ $ npx -y minnimemory init .
|
|
|
31
31
|
the prompt cache every time
|
|
32
32
|
...2 more findings...
|
|
33
33
|
|
|
34
|
-
always-loaded, files this plan rewrites: 897 ->
|
|
34
|
+
always-loaded, files this plan rewrites: 897 -> 389 tokens (-56.6%)
|
|
35
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
|
|
37
|
-
routed file open (
|
|
36
|
+
verdict: compile. Every turn with no routed file open saves 508 tokens; a turn with every
|
|
37
|
+
routed file open (613 tokens) costs 105 more than today. It pays unless routed text is open
|
|
38
38
|
on nearly every turn.
|
|
39
39
|
|
|
40
40
|
operations:
|
|
41
|
-
write .minnimemory/.gitignore +
|
|
42
|
-
copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md)
|
|
43
|
-
write .claude/OnDemandMemory/CLAUDE__history.md +
|
|
44
|
-
write
|
|
41
|
+
write .minnimemory/.gitignore +5 -0
|
|
42
|
+
copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md -> CLAUDE.md.bak)
|
|
43
|
+
write .claude/OnDemandMemory/CLAUDE__history.md +28 -0
|
|
44
|
+
write .claude/OnDemandMemory/CLAUDE__detail.md +28 -0
|
|
45
|
+
write CLAUDE.md +7 -47
|
|
45
46
|
...
|
|
46
47
|
|
|
47
|
-
plan:
|
|
48
|
+
plan: 7eb0e22e815143d0
|
|
48
49
|
dry run, nothing written. To write these files, run:
|
|
49
|
-
npx -y minnimemory apply --plan
|
|
50
|
+
npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
|
|
50
51
|
|
|
51
|
-
$ npx -y minnimemory apply --plan
|
|
52
|
+
$ npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
|
|
52
53
|
5 file(s) written; originals are under .minnimemory/. Undo any time: npx -y minnimemory undo .
|
|
53
54
|
|
|
54
55
|
$ npx -y minnimemory doctor
|
|
@@ -95,9 +96,10 @@ npx -y minnimemory install
|
|
|
95
96
|
One line. Registers the MCP server for every project on this machine (runs `claude mcp add
|
|
96
97
|
minnimemory -s user -- node "<path to minnimemory>/cli.js" mcp` and prints exactly that line: a
|
|
97
98
|
direct call to the installed copy, so Claude Code does not re-resolve the package through `npx`
|
|
98
|
-
on every launch), turns on
|
|
99
|
-
Restart Claude Code. Running it again is safe: it tells you
|
|
100
|
-
upgrading the package, run it again: it repoints
|
|
99
|
+
on every launch), turns on two prompt hooks by default (the memory hook and the drift notice,
|
|
100
|
+
see below), and prints the next step. Restart Claude Code. Running it again is safe: it tells you
|
|
101
|
+
it is already registered. After upgrading the package, run it again: it repoints the server and
|
|
102
|
+
the hooks at the new copy.
|
|
101
103
|
|
|
102
104
|
The registration points at the copy `install` ran from. Under `npx` that is the npx cache, which
|
|
103
105
|
`npm cache clean` or a newer version can remove, and `install` says so when it applies. For a
|
|
@@ -110,8 +112,15 @@ Useful variants:
|
|
|
110
112
|
| this repo only, not every project | `npx -y minnimemory install --scope project` |
|
|
111
113
|
| see the command without running it | `npx -y minnimemory install --dry-run` |
|
|
112
114
|
| re-register over an existing entry | `npx -y minnimemory install --force` |
|
|
113
|
-
| skip the
|
|
114
|
-
| remove the registration and the
|
|
115
|
+
| skip the hooks | `npx -y minnimemory install --no-hook` |
|
|
116
|
+
| remove the registration and the hooks it added | `npx -y minnimemory install --remove` |
|
|
117
|
+
|
|
118
|
+
The memory hook (`UserPromptSubmit`, `minnimemory hook`) runs before every prompt and places the
|
|
119
|
+
one short section of memory the prompt needs into the turn, only when the always-loaded memory
|
|
120
|
+
does not already hold a better match, once per session. The agent answers in one call instead of
|
|
121
|
+
opening or searching files. In a continuous 27-task session on our Control Case it cut the
|
|
122
|
+
session's cost by a third with answers graded as good (measured 2026-10-11; the number reaches
|
|
123
|
+
this README through the results ledger, like every figure here).
|
|
115
124
|
|
|
116
125
|
The drift notice hook (`UserPromptSubmit`) tells the agent when a memory file has changed since
|
|
117
126
|
the last `apply`, so you never have to remember to run `doctor` by hand. It checks the project
|
|
@@ -147,7 +156,10 @@ body plus a fenced OnDemandMemory list, and routed pieces land beside it in
|
|
|
147
156
|
`.claude/OnDemandMemory/`. A **memory folder** (an index such as Claude Code's `MEMORY.md` plus
|
|
148
157
|
topic files, or the project's own Claude Code auto-memory folder) is sorted in place: every
|
|
149
158
|
topic file a linked host imports moves into `AlwaysOnMemory/`, trimmed the same way; every
|
|
150
|
-
other topic file moves into `OnDemandMemory/`, untouched; routed pieces join it there.
|
|
159
|
+
other topic file moves into `OnDemandMemory/`, untouched; routed pieces join it there. A topic
|
|
160
|
+
file your index never linked gets a list line of its own, with trigger words, so it stops being
|
|
161
|
+
a dead end; a file whose name marks it as a copy (`x (old).md`, `x.bak.md`, `x_v1.md`) is left
|
|
162
|
+
off the list and named in the plan. The
|
|
151
163
|
always-loaded set of a memory folder also counts the files outside it that load it, because
|
|
152
164
|
Claude Code loads them on every turn too: your `~/.claude/CLAUDE.md` when it imports from the
|
|
153
165
|
folder, directly or through a chain (`CLAUDE.md` -> `@AGENTS.md`, or a stub that imports a
|
|
@@ -340,6 +352,7 @@ undo, then apply" as the fix.
|
|
|
340
352
|
| `--ci` | terse output, no colour |
|
|
341
353
|
| `--fail-on <sev>` | exit 1 at this severity or above: `low`, `med`, `high` (default `high`) |
|
|
342
354
|
| `--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) |
|
|
355
|
+
| `--policy <file>` | a team's rule pack (`policy.json`): MM020 reports a required line missing from the always-loaded memory, MM021 banned text in any memory file; its `always_on_tokens` is the MM001 budget when `--budget` is not given. Without it, neither rule runs |
|
|
343
356
|
| `--only <ids>` | run only these rules, comma separated |
|
|
344
357
|
| `--ignore <ids>` | skip these rules, comma separated |
|
|
345
358
|
| `--rules` | list the rule set and exit |
|
|
@@ -412,7 +425,7 @@ registration), or by hand with `claude mcp add minnimemory -- npx -y minnimemory
|
|
|
412
425
|
### `minnimemory install`
|
|
413
426
|
|
|
414
427
|
Registers minnimemory with the current host in one command instead of the manual `claude mcp
|
|
415
|
-
add` line above, turns on the drift notice hook, and prints the next step.
|
|
428
|
+
add` line above, turns on the memory hook and the drift notice hook, and prints the next step.
|
|
416
429
|
|
|
417
430
|
| flag | effect |
|
|
418
431
|
|---|---|
|
|
@@ -420,14 +433,31 @@ add` line above, turns on the drift notice hook, and prints the next step.
|
|
|
420
433
|
| `--write` | serve the full profile with its write tools (`--profile full --allow-write`); the default basic profile never writes |
|
|
421
434
|
| `--dry-run` | print the command without running it, exit 0 |
|
|
422
435
|
| `--force` | remove an existing registration first, then re-add |
|
|
423
|
-
| `--no-hook` | skip the drift notice
|
|
424
|
-
| `--remove` | remove the MCP registration and the
|
|
436
|
+
| `--no-hook` | skip the three hooks (memory, drift notice, load log; on by default) |
|
|
437
|
+
| `--remove` | remove the MCP registration and the hooks `install` added; the same as `minnimemory uninstall` |
|
|
425
438
|
| `--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 |
|
|
426
439
|
|
|
427
440
|
Idempotent: an existing registration is reported, with the command to change it, not duplicated.
|
|
428
441
|
Without the `claude` CLI on `PATH` it prints the manual line and a JSON snippet instead, exit 2;
|
|
429
442
|
if `claude` itself errors, its stderr is printed, exit 1.
|
|
430
443
|
|
|
444
|
+
### `minnimemory uninstall`
|
|
445
|
+
|
|
446
|
+
Takes out what `install` added: the MCP registration (`claude mcp remove minnimemory`) and the two
|
|
447
|
+
hooks in your Claude `settings.json`. Every other hook and setting stays, including another tool's
|
|
448
|
+
hook that happens to look like ours. `--dry-run` shows the removals first; `--scope` matches the
|
|
449
|
+
one you installed with. Running it twice is harmless.
|
|
450
|
+
|
|
451
|
+
```
|
|
452
|
+
npx -y minnimemory uninstall
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
It does not undo your memory. A compiled folder keeps working as plain markdown without the tool,
|
|
456
|
+
and `uninstall` lists each one still compiled with its `undo` command, so run those first if you
|
|
457
|
+
want the originals back. It also leaves `~/.claude/minnimemory/` (the `init` records, the load log
|
|
458
|
+
and any undo backups); delete that yourself once you have checked `undo-backups/`. Restart Claude
|
|
459
|
+
Code afterwards.
|
|
460
|
+
|
|
431
461
|
### `minnimemory recall <path> <query...>`
|
|
432
462
|
|
|
433
463
|
Ranks a compiled workspace's OnDemandMemory sections, or a manifest-less memory directory,
|
|
@@ -440,13 +470,18 @@ against a query. Changes nothing.
|
|
|
440
470
|
|
|
441
471
|
### `minnimemory hook`
|
|
442
472
|
|
|
443
|
-
A Claude Code `UserPromptSubmit` hook: reads the hook's JSON
|
|
444
|
-
|
|
445
|
-
|
|
473
|
+
A Claude Code `UserPromptSubmit` hook, registered by `install` by default: reads the hook's JSON
|
|
474
|
+
off stdin, ranks the prompt against the compiled memory, and prints one fenced memory section to
|
|
475
|
+
stdout, or nothing. It prints nothing when the always-loaded memory holds the best match, prints
|
|
476
|
+
only the single best section and only under 400 tokens, only when that section shares at least
|
|
477
|
+
two words with the prompt and at least half of them, and never the same section twice in one
|
|
478
|
+
session (it reads Claude Code's `session_id` and keeps a small record under the OS temp folder).
|
|
479
|
+
Measured live on 2026-10-11: a third lower session cost on a continuous 27-task session, answers
|
|
480
|
+
graded as good (Minni-AI run `2026-10-11-211152`).
|
|
446
481
|
|
|
447
482
|
| flag | effect |
|
|
448
483
|
|---|---|
|
|
449
|
-
| `--max-tokens <n>` | cap on
|
|
484
|
+
| `--max-tokens <n>` | cap on the ranked candidates (default 600); the placed section is capped at 400 regardless |
|
|
450
485
|
| `--headings` | print only heading-path lines, not the content |
|
|
451
486
|
| `--dir <path>` | an explicit memory directory, overriding the hook JSON's own cwd resolution |
|
|
452
487
|
|
package/examples/CLAUDE.md
CHANGED
|
@@ -1,76 +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
|
-
## 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
|
|
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
|
package/examples/README.md
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
|
-
# examples/
|
|
2
|
-
|
|
3
|
-
This folder holds fixtures shipped in the npm package. `CLAUDE.md` here is a fictional
|
|
4
|
-
project's memory file, used by the README walkthrough, the test suite, and the npm smoke test.
|
|
5
|
-
|
|
6
|
-
**Try this first:** copy `CLAUDE.md` into an empty directory and run
|
|
7
|
-
`npx -y minnimemory
|
|
8
|
-
file you cannot break, before you point the tool at your own memory.
|
|
9
|
-
|
|
10
|
-
It is not instructions for this repo. Do not edit it without updating the tests that assert
|
|
11
|
-
on it.
|
|
1
|
+
# examples/
|
|
2
|
+
|
|
3
|
+
This folder holds fixtures shipped in the npm package. `CLAUDE.md` here is a fictional
|
|
4
|
+
project's memory file, used by the README walkthrough, the test suite, and the npm smoke test.
|
|
5
|
+
|
|
6
|
+
**Try this first:** copy `CLAUDE.md` into an empty directory and run
|
|
7
|
+
`npx -y minnimemory init .` against it, then `apply`, then `undo`. That is the whole loop, on a
|
|
8
|
+
file you cannot break, before you point the tool at your own memory.
|
|
9
|
+
|
|
10
|
+
It is not instructions for this repo. Do not edit it without updating the tests that assert
|
|
11
|
+
on it.
|
package/package.json
CHANGED
|
@@ -1,59 +1,59 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "minnimemory",
|
|
3
|
-
"version": "1.
|
|
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
|
-
"type": "module",
|
|
6
|
-
"mcpName": "io.github.MinniAI-com/minnimemory",
|
|
7
|
-
"license": "SEE LICENSE IN LICENSE",
|
|
8
|
-
"author": "MinniAI",
|
|
9
|
-
"homepage": "https://minniai.com",
|
|
10
|
-
"publishConfig": {
|
|
11
|
-
"access": "public"
|
|
12
|
-
},
|
|
13
|
-
"engines": {
|
|
14
|
-
"node": ">=18.3"
|
|
15
|
-
},
|
|
16
|
-
"bin": {
|
|
17
|
-
"minnimemory": "
|
|
18
|
-
},
|
|
19
|
-
"main": "./pkg/index.js",
|
|
20
|
-
"types": "./pkg/index.d.ts",
|
|
21
|
-
"files": [
|
|
22
|
-
"pkg",
|
|
23
|
-
"examples",
|
|
24
|
-
"README.md",
|
|
25
|
-
"LICENSE",
|
|
26
|
-
"CHANGELOG.md"
|
|
27
|
-
],
|
|
28
|
-
"scripts": {
|
|
29
|
-
"build": "tsc -p tsconfig.json",
|
|
30
|
-
"bundle": "node scripts/bundle.mjs",
|
|
31
|
-
"prepublishOnly": "npm run typecheck && npm test && npm run build && npm run bundle && npm run leakcheck",
|
|
32
|
-
"leakcheck": "node scripts/leakcheck.mjs",
|
|
33
|
-
"graph-check": "node scripts/graph-check.mjs",
|
|
34
|
-
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
35
|
-
"pretest": "npm run build",
|
|
36
|
-
"test": "vitest run",
|
|
37
|
-
"test:watch": "vitest"
|
|
38
|
-
},
|
|
39
|
-
"keywords": [
|
|
40
|
-
"llm",
|
|
41
|
-
"agent",
|
|
42
|
-
"context",
|
|
43
|
-
"tokens",
|
|
44
|
-
"memory",
|
|
45
|
-
"claude",
|
|
46
|
-
"mcp",
|
|
47
|
-
"prompt-caching"
|
|
48
|
-
],
|
|
49
|
-
"devDependencies": {
|
|
50
|
-
"@types/node": "^22.10.2",
|
|
51
|
-
"esbuild": "^0.28.2",
|
|
52
|
-
"typescript": "^5.7.2",
|
|
53
|
-
"vitest": "^5.0.0"
|
|
54
|
-
},
|
|
55
|
-
"dependencies": {
|
|
56
|
-
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
57
|
-
"zod": "^3.25.0"
|
|
58
|
-
}
|
|
59
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "minnimemory",
|
|
3
|
+
"version": "1.3.0",
|
|
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
|
+
"type": "module",
|
|
6
|
+
"mcpName": "io.github.MinniAI-com/minnimemory",
|
|
7
|
+
"license": "SEE LICENSE IN LICENSE",
|
|
8
|
+
"author": "MinniAI",
|
|
9
|
+
"homepage": "https://minniai.com",
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"access": "public"
|
|
12
|
+
},
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=18.3"
|
|
15
|
+
},
|
|
16
|
+
"bin": {
|
|
17
|
+
"minnimemory": "pkg/cli.js"
|
|
18
|
+
},
|
|
19
|
+
"main": "./pkg/index.js",
|
|
20
|
+
"types": "./pkg/index.d.ts",
|
|
21
|
+
"files": [
|
|
22
|
+
"pkg",
|
|
23
|
+
"examples",
|
|
24
|
+
"README.md",
|
|
25
|
+
"LICENSE",
|
|
26
|
+
"CHANGELOG.md"
|
|
27
|
+
],
|
|
28
|
+
"scripts": {
|
|
29
|
+
"build": "tsc -p tsconfig.json",
|
|
30
|
+
"bundle": "node scripts/bundle.mjs",
|
|
31
|
+
"prepublishOnly": "npm run typecheck && npm test && npm run build && npm run bundle && npm run leakcheck",
|
|
32
|
+
"leakcheck": "node scripts/leakcheck.mjs",
|
|
33
|
+
"graph-check": "node scripts/graph-check.mjs",
|
|
34
|
+
"typecheck": "tsc -p tsconfig.json --noEmit",
|
|
35
|
+
"pretest": "npm run build",
|
|
36
|
+
"test": "vitest run",
|
|
37
|
+
"test:watch": "vitest"
|
|
38
|
+
},
|
|
39
|
+
"keywords": [
|
|
40
|
+
"llm",
|
|
41
|
+
"agent",
|
|
42
|
+
"context",
|
|
43
|
+
"tokens",
|
|
44
|
+
"memory",
|
|
45
|
+
"claude",
|
|
46
|
+
"mcp",
|
|
47
|
+
"prompt-caching"
|
|
48
|
+
],
|
|
49
|
+
"devDependencies": {
|
|
50
|
+
"@types/node": "^22.10.2",
|
|
51
|
+
"esbuild": "^0.28.2",
|
|
52
|
+
"typescript": "^5.7.2",
|
|
53
|
+
"vitest": "^5.0.0"
|
|
54
|
+
},
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
57
|
+
"zod": "^3.25.0"
|
|
58
|
+
}
|
|
59
|
+
}
|