pi-memory-evolution 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to pi-memory-evolution are documented here.
 
+## [0.2.1](https://github.com/btnalit/pi-memory-evolution/compare/v0.2.0...v0.2.1) (2026-09-08)
+
+
+### Automation
+
+* gate changes and automate verified npm releases ([#2](https://github.com/btnalit/pi-memory-evolution/issues/2)) ([87f9245](https://github.com/btnalit/pi-memory-evolution/commit/87f9245ef799870723ef1f6478eb623d2a37a958))
+
 ## [0.2.0] - 2026-09-08
 
 ### Changed

package/README.cn.md

@@ -0,0 +1,114 @@
+# pi-memory-evolution
+
+[English](README.md) · 简体中文
+
+[![CI](https://github.com/btnalit/pi-memory-evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/btnalit/pi-memory-evolution/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-memory-evolution)](https://www.npmjs.com/package/pi-memory-evolution)
+
+为 [Pi](https://pi.dev) 提供持久记忆，让项目背景、个人偏好和工作进展能够跨会话延续。
+
+扩展自动学习值得保留的信息，在后续对话中按主题注入相关内容，也支持跨目录召回。不需要反复说“记住”，不需要维护审批队列。
+
+## 功能
+
+- **自动学习与更新**：从对话摘要、需求和纠正中提取记忆，根据实际工具结果更新已有项目状态；保留来源和变更历史，支持衰退、排序与撤销。
+- **相关内容注入**：结合当前问题和近期用户上下文选择记忆，过滤弱匹配和失效状态；没有匹配就不填充无关内容。
+- **跨会话召回**：在共享记忆库的不同会话、目录中查找背景；提供只读 `memory_recall` 工具，供助手在任务中途补查。
+
+学习使用 Pi 当前模型和已有认证，无需另配 API Key、向量数据库或嵌入服务。
+
+## 安装
+
+需要 **Pi 0.85+**，并已配置可用模型。使用 npm 版 Pi 时需要 **Node.js 22.19+**。
+
+### npm
+
+```bash
+pi install npm:pi-memory-evolution
+```
+
+### Git
+
+也可以直接安装 Git 默认分支，需要本机有 Git 和 npm：
+
+```bash
+pi install https://github.com/btnalit/pi-memory-evolution
+```
+
+**两种方式选一种**，不要重复安装。然后在 Pi 中执行：
+
+```text
+/reload
+/memory status
+```
+
+出现 `SQLite ok (schema 5)` 表示存储初始化成功。后续正常使用 Pi 即可，学习和召回会自动运行。
+
+## 使用
+
+在对话中说明需求，例如：
+
+```text
+atlas-service 的核心需求是自动备份和故障恢复。
+```
+
+之后可以在新会话中继续询问：
+
+```text
+你还记得 atlas-service 的核心需求吗？
+```
+
+学习在后台完成，并非每句话都会保存。可用以下命令查看和维护记忆：
+
+| 命令 | 用途 |
+| --- | --- |
+| `/memory list` | 浏览记忆 |
+| `/memory search <主题>` | 搜索相关内容 |
+| `/memory show <id>` | 查看内容和来源 |
+| `/memory learning` | 查看采集、更新及实际变更结果 |
+| `/memory explain` | 查看上一次自动注入的选择原因 |
+| `/memory correct <id> <内容>` | 纠正记忆 |
+| `/memory forget <id>` | 停止召回该记忆 |
+
+完整命令、安装迁移和排错方法见[使用指南](docs/usage.md)。
+
+## 更新与卸载
+
+npm 安装：
+
+```bash
+pi update npm:pi-memory-evolution
+pi remove npm:pi-memory-evolution
+```
+
+Git 安装请把上面的包来源替换为安装时使用的仓库 URL。操作后执行 `/reload` 或重启 Pi。卸载扩展不会删除记忆库；升级数据库结构前请先退出共用该库的 Pi 进程并备份。
+
+## 数据与边界
+
+数据默认保存在 `~/.pi/agent/agent-suite/memory-evolution/`，使用本地 SQLite。`PI_CODING_AGENT_DIR` 可改变存储前缀；不同工作目录默认共享记忆库。
+
+学习会将经过过滤的来源内容发送给当前模型，并消耗相应额度。记忆不是经过独立验证的事实，匹配和敏感信息过滤也并非万无一失；重要内容仍需核实。详见[存储与隐私](docs/usage.md#local-storage-and-provenance)。
+
+## 开发
+
+在源码仓库中运行：
+
+```bash
+npm ci --ignore-scripts
+npm run check
+npm run test:install
+npm run test:pi
+npm run build
+```
+
+CI 自动检查类型、回归、包内容、安装和模拟模型集成；构建产出可安装的 npm 压缩包及校验值。版本和更新记录由发布 PR 自动维护，合并且验证通过后自动发包；依赖更新也走 PR 门禁。
+
+安装测试使用隔离环境，集成测试使用真实 Pi 和模拟模型，不产生付费模型调用。详见[测试说明](docs/testing.md)和[发布流程](docs/releasing.md)。
+
+## 文档
+
+[使用指南](docs/usage.md) · [架构设计](docs/design.md) · [记忆质量](docs/core-quality.md) · [更新记录](CHANGELOG.md)
+
+## 许可证
+
+[MIT](LICENSE)

package/README.md

@@ -1,106 +1,126 @@
 # pi-memory-evolution
 
-为 [Pi](https://pi.dev) 提供持久记忆，让项目背景、个人偏好和工作进展能够跨会话延续。
+[![CI](https://github.com/btnalit/pi-memory-evolution/actions/workflows/ci.yml/badge.svg)](https://github.com/btnalit/pi-memory-evolution/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pi-memory-evolution)](https://www.npmjs.com/package/pi-memory-evolution)
+[![MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
 
-扩展自动学习值得保留的信息，在后续对话中按主题注入相关内容，也支持跨目录召回。不需要反复说“记住”，不需要维护审批队列。
+English · [简体中文](README.cn.md)
 
-## 功能
+Persistent, evidence-aware memory for [Pi](https://pi.dev). Keep useful preferences,
+project context and work progress across sessions—without repeatedly asking the
+assistant to remember them.
 
-- **自动学习与更新**：从对话摘要、需求和纠正中提取记忆，根据实际工具结果更新已有项目状态；保留来源和变更历史，支持衰退、排序与撤销。
-- **相关内容注入**：结合当前问题和近期用户上下文选择记忆，过滤弱匹配和失效状态；没有匹配就不填充无关内容。
-- **跨会话召回**：在共享记忆库的不同会话、目录中查找背景；提供只读 `memory_recall` 工具，供助手在任务中途补查。
+![Memory learning, context injection and cross-session recall](assets/overview.png)
 
-学习使用 Pi 当前模型和已有认证，无需另配 API Key、向量数据库或嵌入服务。
+## Features
 
-## 安装
+- **Learn and update automatically.** Capture requirements, corrections and compaction
+  summaries. Update tracked project states from tool observations, with provenance,
+  history, gradual decay and evidence-aware ranking.
+- **Inject relevant context.** Select memories by the current topic and recent user
+  context. Filter weak or stale matches; no relevant match means no unrelated filler.
+- **Recall across sessions.** Find background from another session or directory.
+  A read-only `memory_recall` tool lets the assistant look up missing context mid-task.
 
-需要 **Pi 0.85+**，并已配置可用模型。使用 npm 版 Pi 时需要 **Node.js 22.19+**。
+Learning uses Pi's active model and existing authentication. No separate API key,
+embedding service or vector database is required.
 
-### npm
+## Install
+
+Requires **Pi 0.85+** with a working model. npm-based Pi requires **Node.js 22.19+**.
 
 ```bash
 pi install npm:pi-memory-evolution
 ```
 
-### Git
-
-也可以直接安装 Git 默认分支，需要本机有 Git 和 npm：
+Or install the Git default branch, with Git and npm available locally:
 
 ```bash
 pi install https://github.com/btnalit/pi-memory-evolution
 ```
 
-**两种方式选一种**，不要重复安装。然后在 Pi 中执行：
+Choose **one** source, then run these commands inside Pi:
 
 ```text
 /reload
 /memory status
 ```
 
-出现 `SQLite ok (schema 5)` 表示存储初始化成功。后续正常使用 Pi 即可，学习和召回会自动运行。
+`SQLite ok (schema 5)` confirms storage initialization. Continue using Pi normally;
+learning and recall run automatically.
 
-## 使用
+## Use
 
-在对话中说明需求，例如：
+Describe your requirements in a conversation:
 
 ```text
-atlas-service 的核心需求是自动备份和故障恢复。
+Our priorities for atlas-service are automatic backups and reliable recovery.
 ```
 
-之后可以在新会话中继续询问：
+Later, in a fresh session sharing the same memory store:
 
 ```text
-你还记得 atlas-service 的核心需求吗？
+What do you remember about atlas-service's priorities?
 ```
 
-学习在后台完成，并非每句话都会保存。可用以下命令查看和维护记忆：
+Learning is asynchronous and selective—not every message becomes a memory.
 
-| 命令 | 用途 |
+| Command | Purpose |
 | --- | --- |
-| `/memory list` | 浏览记忆 |
-| `/memory search <主题>` | 搜索相关内容 |
-| `/memory show <id>` | 查看内容和来源 |
-| `/memory learning` | 查看采集、更新及实际变更结果 |
-| `/memory explain` | 查看上一次自动注入的选择原因 |
-| `/memory correct <id> <内容>` | 纠正记忆 |
-| `/memory forget <id>` | 停止召回该记忆 |
+| `/memory list` | Browse memories |
+| `/memory search <topic>` | Search relevant claims |
+| `/memory show <id>` | Inspect content and evidence |
+| `/memory learning` | Inspect capture and actual update results |
+| `/memory explain` | Explain the last automatic injection |
+| `/memory correct <id> <text>` | Correct a record |
+| `/memory forget <id>` | Suppress a record from recall |
 
-完整命令、安装迁移和排错方法见[使用指南](docs/usage.md)。
+See the [usage guide](docs/usage.md) for all commands, migration and troubleshooting.
 
-## 更新与卸载
+## Update or uninstall
 
-npm 安装：
+For the npm installation:
 
 ```bash
 pi update npm:pi-memory-evolution
 pi remove npm:pi-memory-evolution
 ```
 
-Git 安装请把上面的包来源替换为安装时使用的仓库 URL。操作后执行 `/reload` 或重启 Pi。卸载扩展不会删除记忆库；升级数据库结构前请先退出共用该库的 Pi 进程并备份。
+For Git, substitute the repository URL used during installation. Reload or restart
+Pi afterward. Uninstalling does not delete memory data. Before a schema-changing
+upgrade, stop Pi processes sharing the database and back up the state directory.
 
-## 数据与边界
+## Data and limits
 
-数据默认保存在 `~/.pi/agent/agent-suite/memory-evolution/`，使用本地 SQLite。`PI_CODING_AGENT_DIR` 可改变存储前缀；不同工作目录默认共享记忆库。
+Local SQLite state lives in `~/.pi/agent/agent-suite/memory-evolution/`.
+`PI_CODING_AGENT_DIR` changes that prefix; different working directories share the
+same store by default.
 
-学习会将经过过滤的来源内容发送给当前模型，并消耗相应额度。记忆不是经过独立验证的事实，匹配和敏感信息过滤也并非万无一失；重要内容仍需核实。详见[存储与隐私](docs/usage.md#local-storage-and-provenance)。
+Learning sends filtered source content to the active model and consumes its quota.
+Memories are historical evidence, not independently verified facts. Matching and
+secret filtering are imperfect; verify important claims. See [privacy and storage](docs/usage.md#local-storage-and-provenance).
 
-## 开发
-
-在源码仓库中运行：
+## Development
 
 ```bash
 npm ci --ignore-scripts
 npm run check
 npm run test:install
 npm run test:pi
+npm run build
 ```
 
-安装测试使用隔离环境，集成测试使用真实 Pi 和模拟模型，不产生付费模型调用。环境要求和测试范围见[测试说明](docs/testing.md)。
+CI checks types, regressions, package contents, installation and fake-model host
+integration. Builds produce an installable npm archive and checksums, not a separate
+compiled runtime. Release PRs automate versions and changelogs; merging a verified
+release PR triggers npm publication. Dependency updates arrive as gated PRs.
+
+See [testing](docs/testing.md) and [release automation](docs/releasing.md).
 
-## 文档
+## Documentation
 
-[使用指南](docs/usage.md) · [架构设计](docs/design.md) · [记忆质量](docs/core-quality.md) · [更新记录](CHANGELOG.md)
+[Usage](docs/usage.md) · [Architecture](docs/design.md) · [Memory quality](docs/core-quality.md) · [Changelog](CHANGELOG.md)
 
-## 许可证
+## License
 
 [MIT](LICENSE)

package/docs/design.md

@@ -322,7 +322,8 @@ grows until deliberately managed; no automatic purge or physical secret erasure
 Background model usage is not added to Pi's normal session token accounting.
 
 Node/npm development requires 22.19+ to match Pi 0.85's engine; the standalone Bun host is
-also tested. There is no installed GitHub Actions workflow: `npm run check` and
-`npm run test:pi` run locally. Fake-provider validation is not live-provider accuracy or a
+also tested. GitHub CI runs the regression/package checks and isolated install/host
+scripts; [release automation](releasing.md) reuses those gates before publishing.
+Fake-provider validation is not live-provider accuracy or a
 multi-day TUI trial. See [README.md](../README.md) for commands/recovery, and the historical
 [follow-up review](review-0.2.md) for previously reproduced defects and validation limits.

package/docs/releasing.md

@@ -0,0 +1,121 @@
+# CI and releases
+
+## Pull request gate
+
+Use Conventional Commit PR titles, such as `fix: retain work evidence` or
+`feat: improve recall`. Squash merges preserve that title for release automation.
+
+`CI` runs on PRs, pushes to `main`, explicit dispatch and a weekly schedule:
+
+- Node 22.19.0 and Node 24: typecheck, regression/release-policy tests, package and
+  automation assertions, and an npm audit that fails on high/critical findings.
+- Node 24: native Pi installation tests and real-host/fake-model integration.
+- Workflow syntax checks with a checksum-pinned actionlint binary.
+- Build an npm tarball, `SHA256SUMS` and a source-commit/integrity manifest. Pi loads
+  TypeScript directly, so building means packaging, not compiling a second runtime.
+
+The final **Quality gate** fails if any prerequisite fails, is cancelled or is skipped.
+`main` requires a PR, an up-to-date successful gate and resolved conversations, with
+force pushes/deletion blocked. In this single-maintainer repository, the gate does
+not require a second person's approval. It does not automatically merge arbitrary
+PRs or claim a human code review occurred.
+
+CI uses read-only GitHub tokens, no production credentials and no paid model calls.
+Actions are pinned by full commit SHA; checkouts do not persist credentials.
+Workflow policy changes still need maintainer review—tests are not a substitute
+for reviewing a malicious workflow or dependency change.
+
+## Version and publication flow
+
+1. Merge a checked change into `main`.
+2. Release Please maintains a release PR containing `package.json`, lockfile,
+   `.release-please-manifest.json` and `CHANGELOG.md` changes.
+3. Review and merge that PR. Release Please creates the version tag and GitHub
+   Release; the same workflow verifies the exact tagged commit through the full CI.
+4. Only after verification succeeds does the `npm` environment publish the built
+   archive with npm provenance and verify its public registry integrity.
+5. The tarball, checksums and manifest are attached to the GitHub Release.
+
+A GitHub tag/release can exist before npm publication succeeds. Check the **Release**
+workflow and npm registry, not just the presence of the tag. Builds are retained as
+Actions artifacts for seven days; successful release assets remain attached to the
+release. The script never rebuilds between verification and publication.
+
+Release Please uses the built-in `GITHUB_TOKEN`, not a personal GitHub credential.
+Because events generated by that token do not start normal push/PR workflows,
+it explicitly dispatches CI for its same-repository release PRs. Publication is a
+job in the same workflow, not a separate listener waiting for a suppressed event.
+
+Version behavior follows Conventional Commits. `fix` normally bumps patch, `feat`
+bumps minor, and breaking changes before 1.0 bump minor. Visible maintenance/docs/CI
+changes can also produce release notes. The bootstrap starts after the already
+published 0.2.0 commit; it does not republish 0.1 history.
+
+## Publication credentials
+
+The GitHub environment **npm** accepts deployments from `main` only. No environment
+secret is given to the reusable CI jobs or ordinary PR checks. Only the publishing
+step receives `NPM_TOKEN` when the repository variable `NPM_AUTH_MODE=token` is set.
+No personal GitHub token is stored in Actions.
+
+Prefer npm trusted publishing (OIDC): configure `btnalit/pi-memory-evolution`,
+workflow **release.yml**, environment **npm** on the package's npm settings page.
+Then set `NPM_AUTH_MODE=oidc`, verify a release, and remove the environment's
+`NPM_TOKEN`. `id-token: write` is already granted only to the publication job.
+
+The supplied npm token can publish but cannot configure trust relationships:
+npm rejects that account-management operation for granular tokens that bypass 2FA.
+Until an account owner completes trusted-publisher setup with supported interactive
+authentication, the environment-scoped token is the explicit fallback, not a claim
+that OIDC authentication is active. Use a package-scoped, short-lived token and
+rotate it before expiry. Do not commit tokens or copy local `key.conf` into CI.
+
+Repository settings must allow Actions to create pull requests. The setting also
+mentions approving PRs; this workflow creates them but does not approve them.
+
+## Retrying a release
+
+From Actions, dispatch **Release** on `main` with `tag=vX.Y.Z`, or run:
+
+```bash
+gh workflow run release.yml --ref main -f tag=v0.2.1
+```
+
+The workflow requires an existing stable GitHub Release whose commit belongs to
+`main`, reruns verification and checks the version against the archive manifest.
+An already published version is accepted only when npm's integrity matches exactly.
+It never overwrites a version or moves `latest` backwards. Existing release assets
+must have matching digests; mismatches stop rather than silently using `--clobber`.
+Retry the original failed workflow when possible so the original artifact remains
+available. Rebuilding with different tooling may legitimately produce different
+bytes and require investigation, not bypassing the integrity check.
+
+A cancelled or failed npm call is not proof nothing was published: the registry
+check on retry handles that case. Do not delete/recreate tags or edit registry
+metadata to disguise a failed release.
+
+## Dependency updates and Pi Gallery
+
+Dependabot checks npm dev dependencies and GitHub Actions weekly. Minor/patch updates
+are grouped; majors stay separate. Updates arrive as PRs and must pass the same
+gate; no blanket auto-merge is enabled. GitHub vulnerability alerts/security update
+PRs complement the scheduled audit. Transitive runtime dependencies are not bundled
+just to satisfy host-provided Pi peer APIs.
+
+The package already uses the Pi `pi` manifest and `pi-package` keyword. Distribution
+checks retain both, the English npm description/default README, `README.cn.md`,
+and a PNG overview referenced by `pi.image`. This provides Gallery discovery and
+preview metadata, not an official endorsement or a guarantee of immediate indexing.
+The overview is an architecture illustration, not a screenshot of a real user session.
+
+## Local checks
+
+```bash
+npm run check
+npm run test:install
+npm run test:pi
+bash scripts/check-workflows.sh  # Linux x86-64; downloads checksum-pinned actionlint
+npm run build
+```
+
+See [testing](testing.md) for fixture isolation and model-validation boundaries.

package/docs/testing.md

@@ -9,8 +9,8 @@ Tests use synthetic data and temporary directories, not production memories.
 npm run check
 ```
 
-This runs strict TypeScript checking, the `src/**/*.test.ts` regression suite and
-`check:package`. Package checking asserts that the Pi manifest points to the current
+This runs strict TypeScript checking, the `src/**/*.test.ts` regression suite,
+`scripts/*.test.mjs` release-policy tests, `check:package` and `check:automation`. Package checking asserts that the Pi manifest points to the current
 entry, host APIs remain peer dependencies, all production TypeScript sources are
 packed, and local documentation links resolve to packaged files. Test sources,
 helper scripts and memory state must not ship in the package.
@@ -98,5 +98,8 @@ product acceptance. Historical design/review documents describe their own tested
 revisions; see [progress pipeline](progress-pipeline.md), [core quality](core-quality.md)
 and [quality validation](quality-validation.md) for context.
 
-No GitHub Actions workflow is configured. Run the local checks before submitting
-changes; the Pi-dependent scripts are explicit commands, not part of `npm run check`.
+GitHub Actions runs these checks and the Pi-dependent scripts before the required
+Quality gate passes. The install/host scripts remain separate local commands, not
+part of `npm run check`. Release verification uses the same CI workflow on the exact
+tagged commit. See [CI and releases](releasing.md) for branch protection, dependency
+updates, publication credentials and retry behavior.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-memory-evolution",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "Automatic cross-session memory using Pi's active model, transactional local storage, and topic-based recall across directories.",
 	"license": "MIT",
 	"publishConfig": {
@@ -31,6 +31,8 @@
 		"!src/**/*.test.ts",
 		"docs",
 		"README.md",
+		"README.cn.md",
+		"assets/overview.png",
 		"CHANGELOG.md",
 		"LICENSE",
 		"package.json"
@@ -38,24 +40,28 @@
 	"pi": {
 		"extensions": [
 			"./src/index.ts"
-		]
+		],
+		"image": "https://raw.githubusercontent.com/btnalit/pi-memory-evolution/main/assets/overview.png"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-coding-agent": "*",
 		"typebox": "*"
 	},
 	"scripts": {
-		"test": "node --test \"src/**/*.test.ts\"",
+		"test": "node --test \"src/**/*.test.ts\" \"scripts/*.test.mjs\"",
 		"typecheck": "tsc --noEmit",
 		"test:pi": "node scripts/test-pi.mjs",
 		"test:install": "node scripts/test-install.mjs",
-		"check": "npm run typecheck && npm test && npm run check:package",
+		"check": "npm run typecheck && npm test && npm run check:package && npm run check:automation",
+		"check:automation": "node scripts/check-automation.mjs",
+		"build": "node scripts/build-package.mjs",
 		"check:package": "node scripts/check-package.mjs"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-coding-agent": "0.85.0",
 		"@types/node": "22.18.0",
+		"typebox": "1.3.7",
 		"typescript": "5.9.3",
-		"typebox": "1.3.7"
+		"yaml": "2.9.0"
 	}
 }