minnimemory 1.2.1 → 1.3.1

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,66 @@
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.1 - 2026-10-12
7
+
8
+ - Fixed: on a memory folder with topic files the index never linked, `doctor` after `apply`
9
+ could keep saying "re-apply" with nothing changed, because choosing the generated list line's
10
+ trigger words again could move one word. A re-apply now keeps the words an earlier apply wrote
11
+ for that line, the way it already kept a routed piece's line. A folder sorted by 1.3.0 goes
12
+ clean on its next `doctor` with no further apply.
13
+ - Fix (#3): `undo` in a teammate's clone that had re-applied restored the compiled `CLAUDE.md`
14
+ and deleted the routed files it lists, with exit 0. A backup that already holds the
15
+ OnDemandMemory list is not an original, so undo now refuses and points at git history.
16
+ - Fix (#4): a new memory written into `OnDemandMemory/`, where the sorted index says new memory
17
+ files go, made every later `apply` refuse ("already exists at the destination"). It is now
18
+ adopted where it is, and a forced `undo` names it as kept with no index line.
19
+ - Fix (#5): `doctor` on a memory folder printed `apply .` as the re-apply command, which run from
20
+ the project re-applies the project. It now names the folder.
21
+ - Fix (#6): after applying and committing on a branch, `main` (whose checkout keeps only the
22
+ gitignored `original/`) counted as a lost manifest, and the forced undo it offered deleted the
23
+ branch's backups. It now reads as "not compiled on this checkout": `apply` says to undo on
24
+ that branch or merge it first, and `undo` keeps the backups.
25
+ - Fix (#7): after `init` on the memory folder, the reply's note about the project read as the
26
+ next step, and a Haiku session applied the project instead. The note now leads with the
27
+ folder's own step (`apply()` with no target), and `apply`/`undo` say an omitted target is the
28
+ recorded memory folder.
29
+ - Fix (#8): `init --only-this-folder` printed an apply command without the flag, which refused.
30
+ - Fix (#9): `init` on a memory folder with nothing reported no longer ends with an apply command
31
+ that would refuse; it says why and how to report.
32
+ - Fix (#10): the drift notice now fires in a session opened in a subfolder of a compiled project.
33
+ - Fix (#11): a deleted `.minnimemory/graph.json` is written again by the next `apply`.
34
+ - Fix (#12): after a memory-folder `init` or `apply`, the project hint shows only when the
35
+ project has something to apply. Undo's note for a deleted user `CLAUDE.md` now says so.
36
+
37
+ ## 1.3.0 - 2026-10-12
38
+
39
+ - New: on a memory folder, a topic file the index never linked now gets a generated list line
40
+ with trigger words, and `recall` and the prompt hook rank its sections too, so it stops being
41
+ a dead end the agent can only reach by searching (DESIGN.md 6.10, decision 22). A file whose
42
+ name marks it as a copy, an old version, a backup or scratch (`x (old).md`, `x.bak.md`,
43
+ `x_copy.md`, `x_v1.md`, `scratch.md`, `untitled.md`, `README.md`) is left off the list and
44
+ named in the plan. The prompt hook also prints only sections that share at least two distinct
45
+ words with the prompt, and at least half of its words; before, one incidental word was enough
46
+ to print a block on every such turn.
47
+ - Changed: the prompt hook (`minnimemory hook`) now places one section, the best, only when it
48
+ is under 400 tokens, only when the always-loaded text does not hold a better match for the
49
+ prompt, and only once per Claude Code session (it reads `session_id` and keeps a small record
50
+ under the OS temp dir). On a 27-task session it placed about 2.6k tokens instead of about
51
+ 14.7k (DESIGN.md 6.10, decision 23). `recall()` gained `includeAlwaysOn` for the ranking; the
52
+ recall tool's own output is unchanged.
53
+ - New: `doctor --policy <file>` checks memory against a team's rule pack (`policy.json`). Two new
54
+ rules run only with it: MM020, a line the pack requires is missing from the always-loaded
55
+ memory (a copy only in an OnDemandMemory file does not count), and MM021, text the pack bans
56
+ is in a memory file, matched as plain text ignoring case and spacing. Each finding names the
57
+ pack entry (`ref` in `--json`) and never quotes the memory. The pack's `always_on_tokens` is
58
+ the MM001 budget when `--budget` is not given. Patterns are plain text only; a pack with
59
+ `regex` is refused and says to list each variant. Without `--policy`, `doctor` is unchanged,
60
+ and the MCP `doctor` tool does not take a pack.
61
+ - Support window: a workspace compiled by 1.0.0 is now three minor versions back, past the
62
+ window this release is tested against (6 months or 3 minors). One compiled by 1.2.1 is tested:
63
+ it reads with no high finding and every routed piece found. Re-apply an older workspace to
64
+ bring it inside the window.
65
+
6
66
  ## 1.2.1 - 2026-10-09
7
67
 
8
68
  - New: `init` and `doctor` name any loaded `CLAUDE.md` saved as UTF-16. Claude Code reads such a
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
@@ -50,14 +50,14 @@ $ npx -y minnimemory init .
50
50
  npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
51
51
 
52
52
  $ npx -y minnimemory apply --plan 7eb0e22e815143d0 --budget 2000 .
53
- 5 file(s) written; originals are under .minnimemory/. Undo any time: npx -y minnimemory undo .
53
+ 7 file(s) written; originals are under .minnimemory/. Undo any time: npx -y minnimemory undo .
54
54
 
55
55
  $ npx -y minnimemory doctor
56
56
  nothing to apply: no drift since the last apply
57
57
 
58
58
  $ npx -y minnimemory undo
59
59
  restored 1 file(s) in /path/to/your/repo
60
- deleted: 4 path(s), .minnimemory/ included
60
+ deleted: 5 path(s), .minnimemory/ included
61
61
  ```
62
62
 
63
63
  `doctor` is for later, after `init`: it refuses until `init` has run here ("run init first").
@@ -96,9 +96,10 @@ npx -y minnimemory install
96
96
  One line. Registers the MCP server for every project on this machine (runs `claude mcp add
97
97
  minnimemory -s user -- node "<path to minnimemory>/cli.js" mcp` and prints exactly that line: a
98
98
  direct call to the installed copy, so Claude Code does not re-resolve the package through `npx`
99
- on every launch), turns on a drift notice hook by default (see below), and prints the next step.
100
- Restart Claude Code. Running it again is safe: it tells you it is already registered. After
101
- 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.
102
103
 
103
104
  The registration points at the copy `install` ran from. Under `npx` that is the npx cache, which
104
105
  `npm cache clean` or a newer version can remove, and `install` says so when it applies. For a
@@ -111,8 +112,15 @@ Useful variants:
111
112
  | this repo only, not every project | `npx -y minnimemory install --scope project` |
112
113
  | see the command without running it | `npx -y minnimemory install --dry-run` |
113
114
  | re-register over an existing entry | `npx -y minnimemory install --force` |
114
- | skip the drift notice hook | `npx -y minnimemory install --no-hook` |
115
- | 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).
116
124
 
117
125
  The drift notice hook (`UserPromptSubmit`) tells the agent when a memory file has changed since
118
126
  the last `apply`, so you never have to remember to run `doctor` by hand. It checks the project
@@ -148,7 +156,10 @@ body plus a fenced OnDemandMemory list, and routed pieces land beside it in
148
156
  `.claude/OnDemandMemory/`. A **memory folder** (an index such as Claude Code's `MEMORY.md` plus
149
157
  topic files, or the project's own Claude Code auto-memory folder) is sorted in place: every
150
158
  topic file a linked host imports moves into `AlwaysOnMemory/`, trimmed the same way; every
151
- 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
152
163
  always-loaded set of a memory folder also counts the files outside it that load it, because
153
164
  Claude Code loads them on every turn too: your `~/.claude/CLAUDE.md` when it imports from the
154
165
  folder, directly or through a chain (`CLAUDE.md` -> `@AGENTS.md`, or a stub that imports a
@@ -341,6 +352,7 @@ undo, then apply" as the fix.
341
352
  | `--ci` | terse output, no colour |
342
353
  | `--fail-on <sev>` | exit 1 at this severity or above: `low`, `med`, `high` (default `high`) |
343
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 |
344
356
  | `--only <ids>` | run only these rules, comma separated |
345
357
  | `--ignore <ids>` | skip these rules, comma separated |
346
358
  | `--rules` | list the rule set and exit |
@@ -413,7 +425,7 @@ registration), or by hand with `claude mcp add minnimemory -- npx -y minnimemory
413
425
  ### `minnimemory install`
414
426
 
415
427
  Registers minnimemory with the current host in one command instead of the manual `claude mcp
416
- 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.
417
429
 
418
430
  | flag | effect |
419
431
  |---|---|
@@ -421,8 +433,8 @@ add` line above, turns on the drift notice hook, and prints the next step.
421
433
  | `--write` | serve the full profile with its write tools (`--profile full --allow-write`); the default basic profile never writes |
422
434
  | `--dry-run` | print the command without running it, exit 0 |
423
435
  | `--force` | remove an existing registration first, then re-add |
424
- | `--no-hook` | skip the drift notice hook (on by default) |
425
- | `--remove` | remove the MCP registration and both hooks `install` added; the same as `minnimemory uninstall` |
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` |
426
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 |
427
439
 
428
440
  Idempotent: an existing registration is reported, with the command to change it, not duplicated.
@@ -458,13 +470,18 @@ against a query. Changes nothing.
458
470
 
459
471
  ### `minnimemory hook`
460
472
 
461
- A Claude Code `UserPromptSubmit` hook: reads the hook's JSON off stdin, ranks the prompt against
462
- whatever memory is at hand, and prints a fenced memory block to stdout, or nothing on no hit.
463
- 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`).
464
481
 
465
482
  | flag | effect |
466
483
  |---|---|
467
- | `--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 |
468
485
  | `--headings` | print only heading-path lines, not the content |
469
486
  | `--dir <path>` | an explicit memory directory, overriding the hook JSON's own cwd resolution |
470
487
 
@@ -499,8 +516,8 @@ The MCP server's own always-loaded cost, measured (not assumed), approx-v2 token
499
516
 
500
517
  | | tokens |
501
518
  |---|---|
502
- | basic profile tool schemas (`init`, `doctor`, `apply`, `undo`), read-only | 1,173 |
503
- | basic profile tool schemas, `--allow-write` (no effect on basic) | 1,173 |
519
+ | basic profile tool schemas (`init`, `doctor`, `apply`, `undo`), read-only | 1,183 |
520
+ | basic profile tool schemas, `--allow-write` (no effect on basic) | 1,183 |
504
521
  | server instructions text | 50 |
505
522
 
506
523
  Measured against a real registered server over an in-memory MCP transport, not assumed. Claude
@@ -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 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.
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,6 +1,6 @@
1
1
  {
2
2
  "name": "minnimemory",
3
- "version": "1.2.1",
3
+ "version": "1.3.1",
4
4
  "description": "MinniMemoryMCP: an MCP server that gives an AI coding agent curated memory. Tools audit the agent's memory file, compile it into a small AlwaysOnMemory body plus OnDemandMemory files, serve it back on demand and keep it maintained. Deterministic, lossless, offline. Built by MinniAI.",
5
5
  "type": "module",
6
6
  "mcpName": "io.github.MinniAI-com/minnimemory",