pi-memory-evolution 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to pi-memory-evolution are documented here.
 
+## [0.2.2](https://github.com/btnalit/pi-memory-evolution/compare/v0.2.1...v0.2.2) (2026-09-08)
+
+
+### Bug Fixes
+
+* support npm 12 pack output and gate CLI compatibility ([#7](https://github.com/btnalit/pi-memory-evolution/issues/7)) ([4fde298](https://github.com/btnalit/pi-memory-evolution/commit/4fde29844b6d2c9e9497a656f75d8655e812d4c6))
+
+
+### Maintenance
+
+* **deps-dev:** bump the development-minor-patch group across 1 directory with 3 updates ([#9](https://github.com/btnalit/pi-memory-evolution/issues/9)) ([03ef2be](https://github.com/btnalit/pi-memory-evolution/commit/03ef2beed637cfaa5c9dae22b26060c6f330d754))
+* **deps-dev:** bump typescript from 5.9.3 to 7.0.2 ([#5](https://github.com/btnalit/pi-memory-evolution/issues/5)) ([dc97e2c](https://github.com/btnalit/pi-memory-evolution/commit/dc97e2c3306a0c1b07c34675d1eebaa7c73aaa8d))
+
+## [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,128 @@
+# 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 with explicit npm 10 and 12: checks, native installation and package builds;
+  both npm compatibility lanes are mandatory parts of the gate.
+- 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.
+GitHub can additionally create a bot-PR run with `action_required`. If that run blocks
+PR checks, a maintainer must review the changes and approve that run in Actions;
+a successful dispatch alone does not override GitHub's platform approval policy.
+The initial rollout required this approval. The workflow does not self-approve or
+delete blocked checks to bypass it.
+
+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,14 +9,49 @@ 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.
 
 `check:package` inspects `npm pack --dry-run --json`; it does not publish to npm.
 
+## npm CLI compatibility
+
+All consumers of `npm pack --json` share `scripts/lib/npm-pack.mjs`. npm 10/11
+return an array; npm 12 returns a package-name map. The helper accepts both and
+rejects invalid, empty, multi-package or mismatched results rather than picking an
+arbitrary package. It is development tooling, not part of the runtime tarball.
+
+CI explicitly installs and verifies npm majors **10 and 12** on Node 24, and runs
+checks, installation and packaging in both lanes. The ordinary Node 22/24 jobs
+also exercise their bundled npm. Node version alone does not define coverage of an
+npm major. The pinned setup-node action has no `npm-version` input, so selecting
+npm uses an explicit `npm install --global --ignore-scripts` step instead.
+
+For local reproduction without changing the global npm installation:
+
+```bash
+npx --yes npm@12 run check
+npx --yes npm@12 run test:install
+npx --yes npm@10 run check
+npx --yes npm@10 run test:install
+```
+
+For an older checkout whose pack parser still fails under npm 12, the npm 10
+commands are a temporary workaround until you update. `npm run` retains the npx
+npm shim on PATH, so nested `execFileSync('npm', ...)` calls use the selected CLI;
+the installation test prints the actual Node/Pi/npm versions. Declaring npm in
+`engines` can document a requirement, but does not replace compatible parsing or
+explicit version testing.
+
+npm 12 also gates dependency lifecycle scripts through its script-allow policy.
+This repository installs with `--ignore-scripts`; do not turn on all scripts merely
+to make an installation pass. If a future dependency requires postinstall compilation,
+review that dependency and update the isolated tests/policy explicitly. Pi's bundled
+runtime and currently tested dependencies work with scripts disabled.
+
 ## Installation smoke test
 
 ```bash
@@ -44,6 +79,10 @@ host explicitly. The script prints the tested host version. The test:
 6. Serves the actual tarball through a loopback npm registry, with a fresh cache,
    then checks native `pi install npm:pi-memory-evolution`, repeat installation,
    normal loading and removal. No host peer packages are served or installed.
+7. Intentionally installs local and npm copies together, reproduces the host's
+   duplicate `memory_recall` failure, removes the unwanted source through the CLI,
+   and verifies startup and unchanged memory/history. This is configuration recovery,
+   not silently choosing which installed version should win.
 
 The test whitelists child environment variables, gives Pi a fresh agent directory
 and HOME, disables startup network operations, and uses private npm caches/config with
@@ -98,5 +137,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/docs/usage.md

@@ -57,6 +57,31 @@ the old source before switching between npm/Git/local forms, which Pi treats as
 different package identities. `pi remove <source>` does not erase memory state.
 Restart or `/reload` all sessions using the extension after changing versions.
 
+### Recovering from duplicate installation sources
+
+Pi treats npm, Git and local paths as different package identities. Installing the
+same source twice is idempotent, but keeping both a dev checkout and an npm copy can
+register `memory_recall` twice and prevent Pi from starting. Updating either copy
+does not remove the other. This is not a failure of a single-source upgrade.
+
+Use terminal commands, not commands inside the broken Pi session:
+
+```bash
+pi list
+# Keep npm; remove the local source shown by pi list:
+pi remove /absolute/path/to/pi-memory-evolution
+# Or keep the checkout; remove npm instead:
+# pi remove npm:pi-memory-evolution
+```
+
+Choose only the removal matching your intended source. If installed project-locally,
+run `pi list --approve` and `pi remove <source> -l --approve` from that trusted project.
+A manually configured `extensions` entry is not a package entry: remove that explicit
+entry from the appropriate settings file as well. Then restart Pi and run
+`/memory status`. Package CLI operations work without loading the conflicting
+extensions, and removal leaves memory data intact. Do not delete the database or
+rename the tool to hide the conflict; an old installation would still run its hooks.
+
 ## What happens automatically
 
 - A successful `session_compact` saves a sanitized source and extracts up to 16

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-memory-evolution",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"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",
-		"typescript": "5.9.3",
-		"typebox": "1.3.7"
+		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@types/node": "22.20.1",
+		"typebox": "1.3.27",
+		"typescript": "7.0.2",
+		"yaml": "2.9.0"
 	}
 }