pi-memoria 0.3.1 → 0.3.2

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Working on pi-memoria
 
 This is a TypeScript Pi extension with five tools and **one global memory store**.
-README.md documents the product; this file documents how to change and release the repository.
+README.md documents the product; this file documents how to change this package. Read the [monorepo instructions](https://github.com/rcsaquino/pi-extensions/blob/main/AGENTS.md) and [release process](https://github.com/rcsaquino/pi-extensions/blob/main/RELEASING.md) for shared tooling and authorized publication.
 
 ## North star
 
@@ -13,7 +13,9 @@ README.md documents the product; this file documents how to change and release t
 
 ## Commands
 
-- `npm ci --ignore-scripts`: install the locked development dependencies.
+From this package directory; from the monorepo root, use `npm --prefix packages/pi-memoria` before the same operation.
+
+- `npm install --ignore-scripts --legacy-peer-deps --workspaces=false`: install package-local development dependencies. No lockfile is currently committed; use `npm ci` only after a usable lock is deliberately supplied.
 - `npm run check`: strict TypeScript checking.
 - `npm test`: storage, concurrency, retrieval, and Pi integration tests; uses temporary directories.
 - `npm run verify`: typecheck and tests.
@@ -51,59 +53,22 @@ README.md documents the product; this file documents how to change and release t
 
 ## Development conventions
 
-Use explicit `.ts` imports, strict types, Node built-ins, and small modules. Pi loads TypeScript directly; there is no build step. Keep the peer dependency ranges required by Pi packaging; pin the tested Pi version in devDependencies. Update package-lock.json through npm when dependencies change.
+Use explicit `.ts` imports, strict types, Node built-ins, and small modules. Pi loads TypeScript directly; there is no build step. Keep the peer dependency ranges required by Pi packaging; pin the tested Pi version in devDependencies. If maintaining a lockfile, update it through npm when dependencies change; never edit it manually or introduce root dependency hoisting as an unrelated fix.
 
-Read the installed Pi documentation and relevant examples before changing integration code. The reference installation for this workspace is `/home/rcsaquino/.npm-global/lib/node_modules/@earendil-works/pi-coding-agent/`; resolve `docs/...` and `examples/...` there, not here. Read referenced Markdown files completely. Check exported declarations for exact API signatures.
+Read the installed Pi documentation and relevant examples before changing integration code. Locate the host with `npm root -g`, then its `@earendil-works/pi-coding-agent` package (or the configured `PI_HOST_PACKAGE_DIR` for development tooling); resolve `docs/...` and `examples/...` there, not here. Read referenced Markdown files completely. Check exported declarations for exact API signatures.
 
 Add meaningful regression tests for cap boundaries, races, durable retrieval, pagination, and error paths when changing them. Run `npm run verify` before delivery. Benchmark claims must state corpus size and distinguish indexed SQLite lookups from linear session scans.
 
 ## Releasing
 
-Start a release only when the user decides to bump the version. Tags, GitHub releases, and npm versions are public and are not cleanly removable.
-
-1. Bump `version` in `package.json`, then run `npm run verify`. A version-only bump does not change dependencies, so `package-lock.json` needs no update.
-2. Commit as `Release X.Y.Z` and push `main`.
-3. Create an annotated tag `vX.Y.Z` with the message `pi-memoria X.Y.Z` (the convention for `v0.2.0` and later) and push it with the commit:
-
-    ```sh
-    git tag -a vX.Y.Z -m "pi-memoria X.Y.Z"
-    git push origin main vX.Y.Z
-    ```
-
-4. Create the GitHub release after the tag exists. Publishing the release triggers
-   `.github/workflows/npm-publish.yml`, which checks the tag against `package.json`, runs
-   `npm run verify`, and publishes to npm. `gh` is installed and authenticated as
-   `rcsaquino`:
-
-    ```sh
-    gh release create vX.Y.Z --title "pi-memoria X.Y.Z" --notes-file - <<'EOF'
-    ...
-    EOF
-    ```
-
-    Keep notes factual: what changed, requirements, and limits. Do not restate the README.
-
-5. Watch the workflow and confirm the registry:
-
-    ```sh
-    gh run list --workflow npm-publish.yml --limit 4
-    npm view pi-memoria version dist-tags
-    ```
-
-    - The workflow authenticates with npm trusted publishing (OIDC). The trusted publisher
-      on npmjs.com must name the repository `rcsaquino/pi-memoria` and the workflow file
-      `npm-publish.yml`. The package's publishing access disallows traditional tokens,
-      so OIDC is the only automated publish path.
-    - The `files` field in `package.json` controls the tarball; inspect it with
-      `npm pack --dry-run` first.
-    - The registry can accept the tarball (`HTTP 202`, "being processed") and take a few
-      minutes to expose it. Confirm with `npm view` before reporting success.
-    - Fallback only if the workflow is unavailable: `npm publish` locally. Writes require
-      2FA, so it starts the npmjs web-auth flow and needs a real terminal or pseudo-TTY to
-      open the browser; without one it fails with `EOTP`. An automation token with 2FA
-      bypass also works.
-
-Only push tags, create releases, or publish to npm for a user-requested version bump.
+Follow the [monorepo release process](https://github.com/rcsaquino/pi-extensions/blob/main/RELEASING.md) only after explicit approval. Version 0.3.2 is the patch after the public 0.3.1 release; it is not published by editing this file.
+
+- Verify this package and the root suite, inspect `npm pack --dry-run --ignore-scripts --workspaces=false`, and check the chosen version is not already on npm.
+- Use package-specific tags such as `pi-memoria-v0.3.2`, not a shared root `v0.3.2` tag. Commit, push, tag, release creation, and npm publication remain separately authorized actions; pushing a `pi-memoria-v<version>` tag is the publication authorization for the workflow.
+- `.github/workflows/publish-pi-memoria.yml` publishes this package on a `pi-memoria-v<version>` tag after the full suite verifies, using npm trusted publishing (OIDC) with automatic provenance. Creating a GitHub release does not itself publish npm packages.
+- The old trusted-publisher configuration targeting the standalone `rcsaquino/pi-memoria` repository does not apply. The npm trusted publisher must target `rcsaquino/pi-extensions` with workflow filename `publish-pi-memoria.yml` and allow `npm publish`; verify it on npm before the first tagged release and never claim it is configured until then.
+- Manual publication needs the account's current npm authorization and any required interactive 2FA. A dry run cannot verify those permissions. Never include credentials in commands, documentation, logs, or model context.
+- Confirm the exact published version and dist-tag from the public registry before reporting success. Keep release notes factual and specific to this package.
 
 ## Files and data to protect
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Rey Christian
+Copyright (c) 2026 rcsaquino
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -5,7 +5,6 @@
 
 **Global memory for [Pi](https://github.com/earendil-works/pi): startup rules in `MEMORY.md`, durable facts in SQLite FTS5, and cited search across every past conversation.**
 
-[![GitHub release](https://img.shields.io/github/v/release/rcsaquino/pi-memoria?style=flat-square)](https://github.com/rcsaquino/pi-memoria/releases)
 [![Node.js >= 22.19](https://img.shields.io/badge/Node.js-%3E%3D22.19-3c873a?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org)
 [![TypeScript](https://img.shields.io/badge/TypeScript-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org)
 [![MIT license](https://img.shields.io/badge/license-MIT-yellow?style=flat-square)](LICENSE)
@@ -18,8 +17,8 @@ pi-memoria gives Pi one memory shared across every project: instructions that mu
 
 ## Requirements
 
-- **Node.js 22.19+** (uses `node:sqlite`; tested on 22.19 and 24.20).
-- **Pi** with the current extension API (tested with 0.87.1), Node-based. Standalone/Bun builds are not validated with `node:sqlite`.
+- **Node.js 22.19+** (uses `node:sqlite`; earlier baselines 22.19/24.20, maintained suite 26.10.0).
+- A Node-based **Pi** host. The pinned development baseline is 1.0.0, the maintained Pi host. Standalone/Bun builds are not validated with `node:sqlite`.
 - **ripgrep (`rg`) on PATH** for session search.
 
 ## Installation
@@ -28,20 +27,24 @@ pi-memoria gives Pi one memory shared across every project: instructions that mu
 pi install npm:pi-memoria
 ```
 
-Restart Pi or run `/reload`. To uninstall, run `pi remove npm:pi-memoria`; stored memory remains until you delete its directory.
+This installs the current public npm release. This checkout contains version **0.3.2**, the patch after the public 0.3.1 release.
+
+Activate with `/reload` in an idle session when intended, or a separately approved restart. To uninstall, run `pi remove npm:pi-memoria`; stored memory remains until you delete its directory.
 
 <details>
 <summary><strong>Install from a local checkout</strong></summary>
 
+From the monorepo root:
+
 ```sh
-npm ci --ignore-scripts
-pi install /absolute/path/to/pi-memoria
+npm --prefix packages/pi-memoria install --ignore-scripts --legacy-peer-deps --workspaces=false
+pi install /absolute/path/to/pi-extensions/packages/pi-memoria
 ```
 
 Keep the checkout in place: a local install references it directly. To try it without installing:
 
 ```sh
-pi -e /absolute/path/to/pi-memoria/index.ts
+pi -e /absolute/path/to/pi-extensions/packages/pi-memoria/index.ts
 ```
 
 </details>
@@ -168,12 +171,17 @@ The default session root is `<agent-dir>/sessions`; roots Pi uses are remembered
 
 ## Development
 
+From the monorepo root:
+
 ```sh
-npm ci --ignore-scripts
-npm run verify
-npm run bench
+npm --prefix packages/pi-memoria install --ignore-scripts --legacy-peer-deps --workspaces=false
+npm run link-host
+npm --prefix packages/pi-memoria run verify
+npm --prefix packages/pi-memoria run bench
 ```
 
+No package lockfile is currently committed, so `npm ci` is not a fresh-checkout setup command. The shared host-link helper preserves working dependencies and only repairs missing/broken links.
+
 There is no build step: Pi loads `index.ts` directly. `src/database.ts`, `src/hot-memory.ts`, and `src/sessions.ts` own the storage layers; `index.ts` wires them to lifecycle events and the tool schemas. Tests use temporary directories, real SQLite FTS5, real `rg`, concurrent writers, and Pi's extension loader. See [AGENTS.md](AGENTS.md) for architecture and contribution rules.
 
 ## Support and contact

package/index.ts

@@ -15,7 +15,7 @@ import { chunk, HOT_LIMIT, MEMORY_LIMIT } from "./src/text.ts";
 const SAVE_GUIDANCE = "Before saving a durable fact, search SQLite with memoria_search using topic keywords and aliases, and inspect relevant matches. If the same fact is already stored, do not add it again; use memoria_edit with its ID only when information changes or useful detail is missing. Different wording can express the same fact. For hot memory, check the injected MEMORY.md before adding a bullet.";
 
 export const MEMORY_GUIDANCE = `You have global, persistent memory shared across all projects.
-- MEMORY.md below is working memory, available before every user prompt. Store only requirements needed without a retrieval cue, e.g. "Start every sentence with beep_boop." Topic-triggered facts such as liking apples belong in SQLite, tagged with useful retrieval cues such as fruit and preferences.
+- The hot_memory block contains standing instructions from MEMORY.md, available before every user prompt, not merely quoted reference material. Follow them subject to higher-priority instructions and the conflict guidance below. Store only requirements needed without a retrieval cue, e.g. "Start every sentence with beep_boop." Topic-triggered facts such as liking apples belong in SQLite, tagged with useful retrieval cues such as fruit and preferences.
 - Proactively save durable user instructions, preferences, and decisions with memoria_add; update corrections with memoria_edit and remove obsolete facts with memoria_delete. Do not save guesses as facts or secrets unless explicitly requested. Use the memory tools for writes, not direct file/database edits.
 - ${SAVE_GUIDANCE}
 - For hot writes use store="hot", content, and optional priority. Hot content must be one line and internal spacing is preserved. Tags and source are SQLite metadata; omit them for hot memory.
@@ -116,21 +116,23 @@ export default function memoria(pi: ExtensionAPI) {
   });
 
   pi.on("before_agent_start", async (event, ctx) => {
-    let text = MEMORY_GUIDANCE;
+    let text = `<instructions>\n${MEMORY_GUIDANCE}\n</instructions>`;
+    const status: string[] = [];
     const current = stores(ctx);
     try {
       const snapshot = await current.hot.load();
-      text += `\n\nGlobal MEMORY.md (${snapshot.characters}/${HOT_LIMIT} characters; ${current.config.hotPath}):\n${snapshot.text || "(empty)"}`;
+      text += `\n\n<hot_memory>\nGlobal MEMORY.md (${snapshot.characters}/${HOT_LIMIT} characters; ${current.config.hotPath}):\n${snapshot.text || "(empty)"}\n</hot_memory>`;
       for (const repaired of [startupRepair, snapshot]) {
-        if (repaired?.archived.length) text += `\nRepaired an oversized manual edit: ${repaired.archived.length} bullets archived to SQLite; original backup: ${repaired.backup}.`;
+        if (repaired?.archived.length) status.push(`Repaired an oversized manual edit: ${repaired.archived.length} bullets archived to SQLite; original backup: ${repaired.backup}.`);
       }
       startupRepair = undefined;
     } catch (error) {
-      text += `\n\nMEMORY UNAVAILABLE: ${(error as Error).message}. Hot instructions were not loaded; tell the user and do not assume that memory is empty.`;
+      status.push(`MEMORY UNAVAILABLE: ${(error as Error).message}. Hot instructions were not loaded; tell the user and do not assume that memory is empty.`);
     }
     if (!current.database && current.databaseError !== undefined) {
-      text += `\n\nSQLITE LONG-TERM MEMORY UNAVAILABLE: ${(current.databaseError as Error).message}. Hot memory above remains valid; SQLite add/edit/delete/search and archive operations fail until the store is fixed. Session search uses default, configured, and current roots only, so remembered custom roots may be missing.`;
+      status.push(`SQLITE LONG-TERM MEMORY UNAVAILABLE: ${(current.databaseError as Error).message}. Any successfully loaded hot memory remains valid; SQLite add/edit/delete/search and archive operations fail until the store is fixed. Session search uses default, configured, and current roots only, so remembered custom roots may be missing.`);
     }
+    if (status.length) text += `\n\n<status>\n${status.join("\n")}\n</status>`;
     event.systemPromptOptions.sections.pi_memoria = text;
     // Respect earlier extensions that supply an opaque, complete system prompt.
     if (event.systemPromptOptions.forceSystemPrompt !== undefined) {

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "pi-memoria",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Global working memory, SQLite FTS5 recall, and complete Pi session search",
   "type": "module",
   "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/rcsaquino/pi-memoria.git" },
+  "repository": { "type": "git", "url": "git+https://github.com/rcsaquino/pi-extensions.git", "directory": "packages/pi-memoria" },
+  "homepage": "https://github.com/rcsaquino/pi-extensions/tree/main/packages/pi-memoria#readme",
+  "bugs": { "url": "https://github.com/rcsaquino/pi-extensions/issues" },
+  "publishConfig": { "access": "public" },
   "keywords": ["pi-package", "pi-extension", "memory", "sqlite", "fts5"],
   "files": ["index.ts", "src", "README.md", "AGENTS.md", "LICENSE"],
   "pi": { "extensions": ["./index.ts"] },
@@ -21,7 +24,7 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.87.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
     "@types/node": "^22.19.0",
     "@types/proper-lockfile": "^4.1.4",
     "tsx": "^4.20.0",