{"_id":"@4242labs/pi-memento","_rev":"2-80c45dfb31aed1c3e4e7c9edc7f95108","name":"@4242labs/pi-memento","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@4242labs/pi-memento","version":"0.1.0","keywords":["pi-package","pi-extension","pi","memento","memory","session-memory"],"author":{"name":"42labs"},"license":"Apache-2.0","_id":"@4242labs/pi-memento@0.1.0","maintainers":[{"name":"42piratas","email":"anderson@42labs.io"}],"homepage":"https://github.com/4242labs/memento-pi","bugs":{"url":"https://github.com/4242labs/memento-pi/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"b3a482298f9566201e0906aa89a4112e911676b8","tarball":"https://registry.npmjs.org/@4242labs/pi-memento/-/pi-memento-0.1.0.tgz","fileCount":10,"integrity":"sha512-uCzIiwQ2ETlcP+dZCSZOsTfvadL/QXAAOiHLCKQs0P5bY34rQoJZIo6gOCMkTlH5ZTCOTzszzWKDam5gIu4exg==","signatures":[{"sig":"MEQCICcsoY/dI6AC6I8BcJYTmJzUaYV3yP2UgY2eqXoNuWLrAiB8XDhJAdnHJijdE1S3HuVZYqcvS9IH6bxX228PeGrhqA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":59962},"type":"module","exports":{".":{"types":"./src/index.ts","default":"./src/index.ts"}},"gitHead":"070ca5df6f154479b3980eaa43d5ecf9a1d63f8b","scripts":{"test":"node --import tsx/esm --test ./test/*.test.ts","check":"biome check --vcs-use-ignore-file=false src test package.json tsconfig.json","format":"biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json","typecheck":"tsc --noEmit","pack:check":"node scripts/check-tarball.mjs"},"_npmUser":{"name":"42piratas","email":"anderson@42labs.io"},"repository":{"url":"git+https://github.com/4242labs/memento-pi.git","type":"git"},"_npmVersion":"11.11.0","description":"MEMENTO for Pi — persistent memory for a Pi session: recall at start, journal as you go, consolidate on exit.","directories":{},"piExtension":{"lifecycle":"experimental"},"_nodeVersion":"25.8.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"4.23.12","typescript":"7.0.2","@types/node":"26.2.0","@biomejs/biome":"2.5.8","@earendil-works/pi-coding-agent":"0.84.1"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"_npmOperationalInternal":{"tmp":"tmp/pi-memento_0.1.0_1786733270891_0.3265032082248831","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@4242labs/pi-memento","version":"0.1.1","description":"MEMENTO for Pi — persistent memory for a Pi session: recall at start, journal as you go, consolidate on exit.","type":"module","license":"Apache-2.0","author":{"name":"42labs"},"homepage":"https://github.com/4242labs/memento-pi","repository":{"type":"git","url":"git+https://github.com/4242labs/memento-pi.git"},"bugs":{"url":"https://github.com/4242labs/memento-pi/issues"},"keywords":["pi-package","pi-extension","pi","memento","memory","session-memory"],"pi":{"extensions":["./src/index.ts"]},"publishConfig":{"access":"public"},"scripts":{"typecheck":"tsc --noEmit","check":"biome check --vcs-use-ignore-file=false src test package.json tsconfig.json","format":"biome check --write --vcs-use-ignore-file=false src test package.json tsconfig.json","test":"node --import tsx/esm --test ./test/*.test.ts","pack:check":"node scripts/check-tarball.mjs"},"peerDependencies":{"@earendil-works/pi-coding-agent":"*"},"devDependencies":{"@biomejs/biome":"2.5.8","@earendil-works/pi-coding-agent":"0.84.1","@types/node":"26.2.0","tsx":"4.23.12","typescript":"7.0.2"},"exports":{".":{"types":"./src/index.ts","default":"./src/index.ts"}},"gitHead":"0d2e8b2bc01183df5df8af8042b22ac6c7d8eb4f","_id":"@4242labs/pi-memento@0.1.1","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-qfGpqkubyLIF1hs9K4KYbauUE6ynXAPZlb7Ijk2wWVAw5h6CBTuR6ueFiuwVtPK71SbOZZ3pMAsrcEz5fks0yg==","shasum":"68bd4e5abf8f8af451d69050249ad20643920e6a","tarball":"https://registry.npmjs.org/@4242labs/pi-memento/-/pi-memento-0.1.1.tgz","fileCount":10,"unpackedSize":60514,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIB9/FmQNlg8ikZlOpCdw8TqLrjXP6s33kxx05G+EpPXnAiEAoPd4IG/P/v41LsIh2s8Y89rNM60MD1rKONSlddrEHgg="}]},"_npmUser":{"name":"42piratas","email":"anderson@42labs.io"},"directories":{},"maintainers":[{"name":"42piratas","email":"anderson@42labs.io"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-memento_0.1.1_1786741669254_0.4885648798796507"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-14T18:47:50.706Z","modified":"2026-08-14T21:07:49.552Z","0.1.0":"2026-08-14T18:47:51.038Z","0.1.1":"2026-08-14T21:07:49.395Z"},"bugs":{"url":"https://github.com/4242labs/memento-pi/issues"},"author":{"name":"42labs"},"license":"Apache-2.0","homepage":"https://github.com/4242labs/memento-pi","keywords":["pi-package","pi-extension","pi","memento","memory","session-memory"],"repository":{"type":"git","url":"git+https://github.com/4242labs/memento-pi.git"},"description":"MEMENTO for Pi — persistent memory for a Pi session: recall at start, journal as you go, consolidate on exit.","maintainers":[{"name":"42piratas","email":"anderson@42labs.io"}],"readme":"# @4242labs/pi-memento\n\n[![Project Status: WIP](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![Maintenance](https://img.shields.io/badge/maintenance-passively--maintained-yellowgreen.svg)](CONTRIBUTING.md)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)\n[![npm](https://img.shields.io/npm/v/@4242labs/pi-memento)](https://www.npmjs.com/package/@4242labs/pi-memento)\n\nMEMENTO for [Pi](https://github.com/earendil-works/pi-mono) — persistent memory for a Pi\nsession. Recall what matters at session start, journal decisions as they are made,\nconsolidate later so the next session starts where this one ended.\n\n> **Pre-v1.** The lifecycle is wired and tested against a scripted engine. It has not yet run a\n> live consolidation end to end — that is the specific thing still missing.\n\n## What it wraps\n\nThe [MEMENTO](https://github.com/4242labs/memento) engine — a file-backed memory store with\nan explicit consolidation loop. This package is a thin lifecycle wrapper: it owns *when* the\nloop runs inside a Pi session, never *how* the store works. The engine is a separate\nprogram, invoked as a subprocess through its `memento` CLI. It is not bundled, linked, or\nvendored here.\n\nTwo things in that CLI are contractual — the **exit code** and the `--json` **payload** — and\nthis wrapper reads nothing else. Console prose is never parsed, never matched, and never\nsurfaced as a reason.\n\n## The lifecycle\n\n| When | What happens |\n|:--|:--|\n| session start | provenance check → crash recovery → read the prefix |\n| first request | the prefix is injected in front of the conversation |\n| during | `/memento journal <text>` appends to this session's pile |\n| `/memento consolidate` | one bounded pass over the oldest pending session |\n| session exit | `enqueue`, and nothing else — no distillation, no git |\n\nSession exit is deliberately the cheap half. An exit that does real work is an exit the\noperator waits on.\n\n### The consolidation pass\n\nIn the engine's order, and no other:\n\n```\ngate-check → claim → prefix + journal + fingerprint → distill → consolidate --expect\n           → commit → done → release\n```\n\n- **The gate check is mandatory.** Exit 7 means later, not louder. The wrapper never passes\n  `--prefix-materialized` it did not observe, and never lowers the idle bar to get past a\n  refusal.\n- **The compare-and-swap is not optional.** Every submission carries `--expect`;\n  `--unchecked` is not reachable from this wrapper at all.\n- **The claim always comes back.** The pass is bounded at ten minutes against a TTL of an\n  hour, and every exit path releases. A release that is refused is reported as a FLAG, never\n  swallowed.\n- **The marker is last** — after the commit, so a crash between them loses the marker (cheap\n  to redo) rather than the backup (not).\n\n### What each exit code does\n\n| Code | Meaning | This wrapper |\n|:--|:--|:--|\n| 0 | fine | continue |\n| 1 | usage / IO | surface it; never retry blind |\n| 2 | malformed | report — it never reached the gates |\n| 3 | gates rejected | **one** corrected resubmit with the violations as the brief, then leave it pending |\n| 4 | secrets | never retried, in any form |\n| 5 | stale | re-read and redrive **once** against the new fingerprint |\n| 6 | claimed | skip it; another front-end holds it |\n| 7 | gate refuses | come back later |\n\n### Who distils\n\nYou do — the host session's own model. It is handed the current prefix, this session's\njournal, and (on a correction) the gates' own violations, and it replies with a proposal.\nThat makes it precisely the writer the gates were built to distrust, which is why the\ncompare-and-swap and the anti-erosion floor apply to it exactly as they do to anyone else.\n\n## Provenance\n\nThe engine is installed from a git pin, and the pin is where its identity comes from:\n\n```bash\nuv tool install \"memento @ git+https://github.com/4242labs/memento@<sha>\"\n```\n\nAt session start the wrapper reads uv's own install receipt and reports the commit. If your\nproject pins `expectedRev` and the installed engine is a different commit — or cannot be\ntraced to one at all — the wrapper refuses to consolidate rather than gating your memory\nwith an engine you did not ask for.\n\n## Configuration\n\n`.pi/memento.json`, all optional:\n\n```json\n{\n  \"store\": \"./memento\",\n  \"queue\": \"./memento/.queue\",\n  \"adapterFile\": \"./adapter.json\",\n  \"minIdleSeconds\": 5,\n  \"journalTurns\": true,\n  \"expectedRev\": \"02a31e8d1fdce1616bba3cfbca60f8af5eae8e4a\",\n  \"binary\": \"memento\"\n}\n```\n\nAn unknown field is refused, never ignored: a typo must not silently disable the thing it\nwas meant to declare. Gitignore the store — it is your memory, not the repository's.\n\n## Install\n\n```bash\npi install npm:@4242labs/pi-memento\n```\n\nRequires the MEMENTO CLI on `PATH` (see Provenance above).\n\n## As a library\n\nThe same code is importable, for a supervisor that wants the loop without the Pi extension:\n\n```ts\nimport { MementoCli, consolidateOnce } from \"@4242labs/pi-memento\";\n```\n\n## Requirements\n\n- pi **0.84.1** or later\n- MEMENTO engine **0.1.0** or later\n\n## The engine's own terms\n\nThe MEMENTO engine this wrapper invokes is licensed separately (AGPL-3.0-only, commercial on\nrequest). Installing it is your choice and its terms are its own; this package is the wrapper\nonly.\n\n## License\n\nOpen source — [Apache-2.0](LICENSE).\n\n---\nIf it earned its keep, [coffee is appreciated](https://buymeacoffee.com/42piratas). ☕\n","readmeFilename":"README.md"}