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 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 -> 363 tokens (-59.5%)
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 534 tokens; a turn with every
37
- routed file open (615 tokens) costs 81 more than today. It pays unless routed text is open
36
+ verdict: compile. Every turn with no routed file open saves 508 tokens; a turn with every
37
+ routed file open (613 tokens) costs 105 more than today. It pays unless routed text is open
38
38
  on nearly every turn.
39
39
 
40
40
  operations:
41
- write .minnimemory/.gitignore +4 -0
42
- copy 1 file(s) -> .minnimemory/original/ (CLAUDE.md)
43
- write .claude/OnDemandMemory/CLAUDE__history.md +53 -0
44
- write CLAUDE.md +6 -47
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: e36132de24a037c0
48
+ plan: 7eb0e22e815143d0
48
49
  dry run, nothing written. To write these files, run:
49
- npx -y minnimemory apply --plan e36132de24a037c0 --budget 2000 .
50
+ npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
50
51
 
51
- $ npx -y minnimemory apply --plan e36132de24a037c0 --budget 2000 .
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 a drift notice hook by default (see below), and prints the next step.
99
- Restart Claude Code. Running it again is safe: it tells you it is already registered. After
100
- upgrading the package, run it again: it repoints both the server and the hook at the new copy.
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 drift notice hook | `npx -y minnimemory install --no-hook` |
114
- | remove the registration and the hook it added | `npx -y minnimemory install --remove` |
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. The
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 hook (on by default) |
424
- | `--remove` | remove the MCP registration and the drift hook `install` added |
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 off stdin, ranks the prompt against
444
- whatever memory is at hand, and prints a fenced memory block to stdout, or nothing on no hit.
445
- Experimental: measured offline only, not yet in a live session.
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 returned tokens (default 600) |
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
 
@@ -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
@@ -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 doctor` 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.
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.2.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
- }
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
+ }