minnimemory 1.0.0-beta.1

package/dist/version.js

@@ -0,0 +1,7 @@
+/**
+ * The single source of the version string. Before this file, "0.1.0" was hand-typed in four
+ * places (cli.ts's own VERSION constant, and both McpServer constructors in mcpServer.ts), which
+ * is how they drift: a bump to one place with the others forgotten is silent, since nothing
+ * compares them.
+ */
+export const VERSION = "1.0.0-beta.1";

package/dist/writeProtocol.d.ts

@@ -0,0 +1,19 @@
+/**
+ * O9, the memory write protocol, as an OnDemandMemory file the compiler emits.
+ *
+ * The protocol is the instruction text an agent follows when it writes to memory. It is
+ * long (eleven items), so it never rides in the always-loaded prefix: rule 26 in the routing
+ * profile carries its one-sentence summary, and this OnDemandMemory file carries the whole
+ * text, routed to by the OnDemandMemory list like any other long-term file so the agent opens
+ * it when a task is about saving, remembering, or updating memory (P4).
+ *
+ * The wording is the interface spec's, verbatim (Research/FlagShipInterfaces/MinniMemoryInterfaceV1.0.md, O9);
+ * tests/interface-parity.test.ts fails on any drift. Edit the doc, then this file.
+ */
+export declare const WRITE_PROTOCOL_FILE_NAME = "memory_write_protocol";
+export declare const WRITE_PROTOCOL_HEADING = "Memory write protocol";
+/** Triggers the OnDemandMemory list carries for this file: the words a memory-writing task uses. */
+export declare const WRITE_PROTOCOL_TRIGGERS: string[];
+export declare const WRITE_PROTOCOL_LINES: readonly string[];
+/** The OnDemandMemory file's markdown: one heading, then the protocol text exactly as the doc states it. */
+export declare function renderWriteProtocolFile(): string;

package/dist/writeProtocol.js

@@ -0,0 +1,45 @@
+/**
+ * O9, the memory write protocol, as an OnDemandMemory file the compiler emits.
+ *
+ * The protocol is the instruction text an agent follows when it writes to memory. It is
+ * long (eleven items), so it never rides in the always-loaded prefix: rule 26 in the routing
+ * profile carries its one-sentence summary, and this OnDemandMemory file carries the whole
+ * text, routed to by the OnDemandMemory list like any other long-term file so the agent opens
+ * it when a task is about saving, remembering, or updating memory (P4).
+ *
+ * The wording is the interface spec's, verbatim (Research/FlagShipInterfaces/MinniMemoryInterfaceV1.0.md, O9);
+ * tests/interface-parity.test.ts fails on any drift. Edit the doc, then this file.
+ */
+export const WRITE_PROTOCOL_FILE_NAME = "memory_write_protocol";
+export const WRITE_PROTOCOL_HEADING = "Memory write protocol";
+/** Triggers the OnDemandMemory list carries for this file: the words a memory-writing task uses. */
+export const WRITE_PROTOCOL_TRIGGERS = ["memory", "remember", "save", "write", "note", "changelog"];
+export const WRITE_PROTOCOL_LINES = [
+    "MEMORY WRITE PROTOCOL",
+    "1. Before writing, check whether a file already covers the fact. Update that file in",
+    "   place; never create a duplicate. Delete a memory that turns out to be wrong.",
+    "2. A long-term file holds one topic and keeps its five parts: Current state, Locked-in",
+    "   decisions, Gotchas, Open items, Changelog. A new fact goes into the section it belongs",
+    "   to. It never goes at the end as narrative.",
+    "3. The Changelog takes one line per date: date, what changed, branch or commit, status.",
+    "   Never a session diary. Never repeated verification boilerplate.",
+    "4. Dated status, open items, and changelogs never go into the short-term layer. A line",
+    "   that carries a date or a status word belongs in a long-term file whatever its heading",
+    "   says.",
+    "5. Convert relative dates to absolute dates. Write the fact, not the transcript.",
+    "6. A feedback rule records the rule, then Why, then How to apply.",
+    "7. When a file is restructured, its full prior text is archived verbatim first. The archive",
+    "   is never indexed and is read only when a \"why\" is needed.",
+    "8. Every long-term file has exactly one OnDemandMemory list line: a hook of at most 120",
+    "   characters that says when to open it, not what it says.",
+    "9. Link related files by name with [[name]]. A link to a file that does not exist yet",
+    "   marks something worth writing, not an error.",
+    "10. Never write a credential, token, or key into memory.",
+    "11. Do not save what the repository already records (structure, git history, past fixes)",
+    "    or what only matters to the current conversation. If asked to remember one of those,",
+    "    ask what was non-obvious about it and save that instead.",
+];
+/** The OnDemandMemory file's markdown: one heading, then the protocol text exactly as the doc states it. */
+export function renderWriteProtocolFile() {
+    return `## ${WRITE_PROTOCOL_HEADING}\n\n${WRITE_PROTOCOL_LINES.join("\n")}`;
+}

package/examples/CLAUDE.md

@@ -0,0 +1,75 @@
+# Ledger API
+
+Ledger is a small double-entry bookkeeping service: a Fastify HTTP API over Postgres, with a
+nightly reconciliation worker. Single package, TypeScript throughout.
+
+## Current status
+
+As of 2026-08-30 the billing rewrite is in progress and blocked on review of the new posting
+rules. The flaky reconciliation test is still skipped. Next steps: land the posting rules, then
+unskip the test, then cut 1.4.0.
+
+## Conventions
+
+- All money is stored as integer cents. Never use floats for currency anywhere.
+- Every write goes through a repository function. Route handlers never touch the database.
+- Errors thrown across a service boundary are typed. No bare `throw new Error`.
+- Prefer small pull requests. One behaviour change per PR.
+
+## Architecture
+
+Requests enter through `src/http/`, which validates and hands off to `src/services/`. Services
+compose repository calls from `src/repo/` inside a single transaction per request. The worker in
+`src/worker/` reuses the same services and runs on a cron schedule. There is no message queue.
+
+## Layout
+
+```
+src/
+├── http/
+│   ├── routes/
+│   ├── schemas/
+│   └── errorMap.ts
+├── services/
+├── repo/
+├── worker/
+└── errors.ts
+```
+
+## Authentication
+
+Bearer tokens are verified against the auth service on every request, cached for sixty seconds
+by token hash. Service-to-service calls use a signed header, not a bearer token. Never log a
+token, even truncated.
+
+## Error handling
+
+Every service throws one of the typed errors in `src/errors.ts`. The HTTP layer maps them to
+status codes in exactly one place, `src/http/errorMap.ts`. Unknown errors become a 500 with a
+correlation id and are never surfaced to the client with their message.
+
+## Testing
+
+Unit tests run with `npm test`. Integration tests need a database: `npm run db:up` then
+`npm run test:integration`. The reconciliation suite is slow and lives behind
+`npm run test:reconcile`. Always run the integration suite before opening a pull request that
+touches `src/repo/`.
+
+## Deployment
+
+Pushing to main builds a container and deploys to staging automatically. Production is a
+manual promotion from the staging build. Migrations run before the new version starts; a
+migration that cannot roll back must be split into two deploys.
+
+## Common tasks
+
+- Add an endpoint: schema in `src/http/schemas/`, handler in `src/http/routes/`, service call.
+- Add a migration: `npm run migrate:new <name>`, then edit the generated file.
+- Rotate the signing key: update the secret, deploy, then revoke the old key after one hour.
+
+## Changelog
+
+- 2026-08-28 posting rules draft merged behind a flag
+- 2026-08-21 reconciliation worker moved to the shared services layer
+- 2026-08-14 typed errors introduced, error map centralised
+- 2026-08-07 v1.3.0 released

package/examples/README.md

@@ -0,0 +1,7 @@
+# examples/
+
+This folder holds fixtures shipped in the npm package. `CLAUDE.md` here is a fictional
+project's memory file, used by the README walkthrough, the test suite, and the npm smoke test.
+
+It is not instructions for this repo. Do not edit it without updating the tests that assert
+on it.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "minnimemory",
+  "version": "1.0.0-beta.1",
+  "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.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "MinniAI",
+  "homepage": "https://minniai.com",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "minnimemory": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "llm",
+    "agent",
+    "context",
+    "tokens",
+    "memory",
+    "claude",
+    "mcp",
+    "prompt-caching"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^5.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.0"
+  }
+}