@chendpoc/pi-memory 0.3.1 → 0.3.2

package/README.md

@@ -437,7 +437,7 @@ The sidecar IPC test opens a Unix domain socket. If it fails with `listen EPERM`
 
 - [Chinese README](./doc/README-zh.md)
 - [Roadmap](./doc/ROADMAP.md)
-- [Architecture refactor plan](./dev-doc/architecture-refactor-plan.md)
+- [Launch kit](./doc/LAUNCH-KIT.md)
 - [UBIQUITOUS_LANGUAGE.md](./UBIQUITOUS_LANGUAGE.md) - domain glossary
 
 ## 📜 License

package/doc/LAUNCH-KIT.md

@@ -0,0 +1,229 @@
+# @chendpoc/pi-memory Launch Kit
+
+This document is copy-ready material for sharing `@chendpoc/pi-memory`.
+Before each launch, re-check the package version and public links.
+
+## Public Links
+
+- GitHub: https://github.com/chendpoc/pi-memory
+- npm: https://www.npmjs.com/package/@chendpoc/pi-memory
+- Pi package page: https://pi.dev/packages/@chendpoc/pi-memory
+- Install command:
+
+```bash
+pi install npm:@chendpoc/pi-memory
+```
+
+## Positioning
+
+One-liner:
+
+> Local-first Markdown memory for the Pi coding agent: remember preferences, project conventions, decisions, and todos across sessions without making a hosted database the source of truth.
+
+Short pitch:
+
+> `pi-memory` gives Pi cross-session memory that stays local and inspectable. It writes durable facts to `MEMORY.md`, recalls relevant entries before Pi answers, redacts common secrets before saving, and degrades gracefully when recall is unavailable.
+
+Longer pitch:
+
+> Pi compaction helps a long conversation continue, but it does not make future sessions remember stable preferences, project rules, prior decisions, or unresolved todos. `pi-memory` fills that gap with a local-first loop: explicit `/remember` notes, durable memory export from compaction and shutdown maintenance, `MEMORY.md` as the editable ground truth, and bounded pre-answer recall through a sidecar-derived index.
+
+## Proof Points
+
+Lead with behavior, not architecture:
+
+- A new Pi session can answer from previously saved preferences instead of asking the user to repeat context.
+- `/remember` writes user-authored entries that consolidation must preserve.
+- `MEMORY.md` remains editable, greppable, copyable, and versionable.
+- Common secrets are redacted before durable memory writes.
+- Recall has a bounded preflight budget and falls back instead of blocking the agent turn.
+- Maintenance runs outside ordinary interactive turns.
+
+## Two-Minute Demo
+
+Use a fresh memory directory for recording so the demo does not expose personal memory:
+
+```bash
+export PI_MEMORY_AGENT_DIR="$(mktemp -d)"
+pi install npm:@chendpoc/pi-memory
+```
+
+In Pi:
+
+```text
+/remember Preferences Prefer pnpm over npm in JavaScript projects.
+/remember Conventions Public docs should be English-first, with Chinese docs under doc/.
+/memory-status expand
+```
+
+Show the ground-truth file:
+
+```bash
+cat "$PI_MEMORY_AGENT_DIR/MEMORY.md"
+```
+
+Start a new Pi session and ask:
+
+```text
+For this package, which package manager should I use, and where should Chinese docs live?
+```
+
+The expected story is not "magic memory". The expected story is:
+
+1. The user explicitly saved stable preferences.
+2. The memory is visible in Markdown.
+3. A later session can use it before answering.
+4. If recall is unavailable, Pi still answers without memory injection.
+
+## Demo Asset Checklist
+
+The launch posts should link to the repo, but the repo alone is not enough for cold readers. Prepare one short visual proof before posting outside the Pi community.
+
+Recommended asset:
+
+- Length: 30-60 seconds.
+- Format: GIF or short MP4.
+- First frame: package name, install command, and the phrase "local Markdown memory for Pi".
+- Main sequence: `/remember` -> `MEMORY.md` -> new Pi session -> recalled answer -> `/memory-status`.
+- Final frame: GitHub URL and `pi install npm:@chendpoc/pi-memory`.
+
+Recording script:
+
+```text
+1. Open a clean terminal with PI_MEMORY_AGENT_DIR pointing at a temp directory.
+2. Install or show the installed package.
+3. In Pi, run two /remember commands.
+4. Open MEMORY.md and show the exact saved bullets.
+5. Start a new Pi session and ask a question that depends on those bullets.
+6. Show /memory-status expand.
+```
+
+Do not record a personal `MEMORY.md`. Do not show real API keys, private repo names, or private session paths.
+
+## Copy Blocks
+
+### X / Bluesky
+
+```text
+I shipped @chendpoc/pi-memory: local-first Markdown memory for the Pi coding agent.
+
+It keeps preferences, project conventions, decisions, and todos in MEMORY.md, recalls relevant entries before Pi answers, and redacts common secrets before saving.
+
+Install:
+pi install npm:@chendpoc/pi-memory
+
+https://github.com/chendpoc/pi-memory
+```
+
+### Hacker News / Reddit
+
+Title:
+
+```text
+Show HN: pi-memory - local Markdown memory for the Pi coding agent
+```
+
+Body:
+
+```text
+I built pi-memory because Pi compaction helps continue one long session, but I wanted future sessions to remember stable preferences, project conventions, decisions, and open todos.
+
+The design is intentionally local and inspectable:
+
+- MEMORY.md is the ground truth.
+- /remember writes explicit user notes.
+- compaction and shutdown maintenance can export durable facts.
+- a sidecar builds a derived index for pre-answer recall.
+- common secrets are redacted before durable memory writes.
+- recall is best-effort, so the agent still runs if memory is slow or unavailable.
+
+Install:
+pi install npm:@chendpoc/pi-memory
+
+GitHub:
+https://github.com/chendpoc/pi-memory
+
+npm:
+https://www.npmjs.com/package/@chendpoc/pi-memory
+
+I would especially like feedback on recall quality, memory review UX, and whether hybrid lexical + vector recall should be the next milestone.
+```
+
+### Pi Community
+
+```text
+I published @chendpoc/pi-memory for Pi.
+
+It adds local cross-session memory: /remember, editable MEMORY.md ground truth, pre-answer recall, compaction/shutdown export, status diagnostics, and secret redaction before durable writes.
+
+Install:
+pi install npm:@chendpoc/pi-memory
+
+Pi package page:
+https://pi.dev/packages/@chendpoc/pi-memory
+
+GitHub:
+https://github.com/chendpoc/pi-memory
+
+Feedback I am looking for: install friction, recall quality, and what memory review/edit commands should look like.
+```
+
+### Chinese Short Post
+
+```text
+我做了一个 Pi 插件 @chendpoc/pi-memory：给 Pi 加 local-first 跨会话记忆。
+
+核心不是把聊天记录塞进数据库，而是把稳定偏好、项目约定、决策和 TODO 写进可编辑的 MEMORY.md；每次回答前尽量召回相关记忆；写入前会对常见 token/secret 做脱敏；召回失败也不会阻塞正常对话。
+
+安装：
+pi install npm:@chendpoc/pi-memory
+
+GitHub:
+https://github.com/chendpoc/pi-memory
+```
+
+## Launch Sequence
+
+This material can improve conversion, but it will not create demand by itself. The highest-leverage launch path is narrow first, then broader technical audiences.
+
+| Step | Channel | Goal | Success signal |
+| --- | --- | --- | --- |
+| 1 | GitHub repo metadata | Make the first click understandable | Description, topics, README, and demo asset all tell the same story |
+| 2 | Pi community / Discord | Find install friction quickly | 3-5 people try `pi install npm:@chendpoc/pi-memory` |
+| 3 | X / Bluesky | Lightweight awareness | Clicks, stars, replies asking what Pi memory does |
+| 4 | Reddit / HN | Technical feedback | Comments about design tradeoffs, recall quality, local-first boundary |
+| 5 | Technical article | Durable search traffic | People arrive via "Pi agent memory", "local agent memory", or "Markdown memory" searches |
+
+Suggested order:
+
+1. Update the GitHub repo description to the one-liner above.
+2. Add one demo GIF/MP4 or screenshot to the README near the top.
+3. Share in the Pi package/community channel first, because the install path is Pi-specific.
+4. Fix install friction reported by early users before posting broadly.
+5. Post the Show HN / Reddit version after the README and demo are stable.
+6. Follow up with a technical post comparing local Markdown ground truth, sidecar-derived indexes, and hosted memory APIs.
+
+Track these numbers for one week:
+
+- npm downloads.
+- GitHub stars / forks.
+- Pi community installs or replies.
+- Issues filed about install, recall quality, or memory review UX.
+- Number of users who complete the two-minute demo.
+
+## Do Not Claim
+
+- Do not call it a full session search product.
+- Do not imply it stores or indexes full chat transcripts as memory.
+- Do not claim perfect privacy; the accurate claim is local-first memory files plus redaction before durable memory writes.
+- Do not pitch it as a Mem0/Zep replacement; it is a Pi-native, Markdown-first memory loop.
+- Do not promise multi-hop graph reasoning or autonomous memory editing before those features ship.
+- Do not lead with future cloud sync; for the current product, lead with local-first Ground Truth and optional derived indexes.
+
+## Feedback Questions
+
+- Did install work with `pi install npm:@chendpoc/pi-memory`?
+- Was `MEMORY.md` created where you expected?
+- Did `/memory-status expand` explain the state clearly?
+- Did recall retrieve the memory you expected in a new session?
+- Would you rather edit memory through Markdown, commands, or a TUI review panel?

package/doc/ROADMAP-zh.md

@@ -0,0 +1,114 @@
+# @chendpoc/pi-memory 路线图
+
+<p align="center">
+  <a href="ROADMAP.md">English</a> |
+  <a href="ROADMAP-zh.md">简体中文</a>
+</p>
+
+这是 `@chendpoc/pi-memory` 的公开产品路线图。它聚焦用户可感知的结果，不链接未随 npm 包发布的内部 `dev-doc/` 设计笔记。
+
+## 版本规划
+
+| 版本 | 主题 | 用户可感知结果 |
+| --- | --- | --- |
+| **0.3.x** | 信任与安全 | 记忆写入更安全、有边界，也更容易诊断。 |
+| **0.4.x** | 召回质量 | Pi 在 Preflight 预算内更常召回正确记忆。 |
+| **0.5.x** | 记忆生命周期 | 用户能审查、淘汰、纠正长期记忆，减少手动清理。 |
+| **0.6.x** | 可观测 + 控制面 | 用户能检查、排障、编辑、审查，并在本地迁移 Pi 记忆。 |
+| **0.7.x** | 可选同步 | 在不强制上云的前提下，支持多 agent / 多设备协同记忆。 |
+
+进入 **0.7** 之前，必须先完成三件事：debug/trace、memory edit/review、本地 import/export。Cloud 或多 agent 同步应保持可选，并默认 local-first。
+
+## 产品原则
+
+- `MEMORY.md` 继续作为可编辑的 Ground Truth。
+- derived index、sidecar、trace、未来 sync state 都必须能从本地记忆工件重建。
+- 召回应改善普通 agent 行为，但不能给每轮对话加入多秒级反思。
+- 安全能力对记忆写入应 fail closed；对 agent 回答应 fail open。
+- `pi-memory` 不应变成完整 transcript search 产品；旧会话搜索应由专门的 session-search 包负责。
+
+## 当前基础
+
+- 带 overflow 的 `MEMORY.md` Ground Truth。
+- `/remember` 和 `/memory-status`。
+- 基于 UDS JSONL 的 sidecar。
+- `memory.vec.sqlite` 向量索引。
+- QueryIntent + raw-query fallback。
+- 800ms 共享 Preflight 预算，sidecar query 支持 AbortSignal 取消。
+- sidecar warm、intent cache、query cache。
+- dual-purpose compaction summary。
+- Shutdown Queue + `maintenance`。
+- Consolidate + reindex。
+- Subagent Memory Cap + Compact Delta。
+- Ground Truth 写入前 secret 脱敏。
+- `MemoryRuntime` 扩展生命周期与重构后的 store/sidecar 模块。
+
+## P0：信任与安全
+
+**目标版本：0.3.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/1)
+
+用户目标：记忆能力足够安全，可以默认开启。
+
+- ✅ durable memory 写入前做 secret/token redaction — **0.3.0 已交付**。
+- ✅ 拆小并澄清 store、ingest、status、lifecycle、sidecar 等运行模块 — **0.3.0 已交付**。
+- 为 LLM 生成的 Memory Export 增加 prompt-injection guardrails。
+- 针对用户明确纠正做 correction detector，优先限定在 `/remember` 链路。
+- 为跳过写入和 fallback 决策提供轻量 reason code；完整 trace UX 放在 **0.6**。
+
+## P1：召回质量
+
+**目标版本：0.4.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/2)
+
+用户目标：Pi 更常召回正确的稳定事实，同时保持交互轮次足够快。
+
+- 对 `MEMORY.md` 条目做 lexical + vector 混合召回：SQLite FTS5 + 现有 vector chunks，RRF merge 后再 MMR。
+- 为常见 coding-agent 问题建立 recall eval fixtures。
+- debug metrics 拆分 intent、embed、scan、MMR、render、fallback、总 Preflight 时间。
+- 改进 Ollama 之外的 embedding provider，在可行时支持免费/开源 embedding API。
+- sidecar 检索优化：增量 reindex、batch embed、更清晰的 reindex/query 隔离。
+- 只有在延迟预算允许时，才在 MMR 后加入可选 reranker。
+
+## P2：记忆生命周期
+
+**目标版本：0.5.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/3)
+
+用户目标：长期记忆保持有用，而不是变成不断增长的过期事实堆。
+
+- 增加 failure 和 tool-quirk 类别。
+- 晋升前提供人类可审查的 memory draft 或 diary。
+- 基于使用信号的晋升和裁剪。
+- rewrite 前提供更安全的 consolidate preview。
+- 显式处理 stale / superseded fact，而不是只做简单 TODO 清理。
+- lifecycle 事件进入共享 debug/trace event schema；面向用户的 trace surface 在 **0.6** 交付。
+
+## P3：可观测 + 控制面
+
+**目标版本：0.6.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/4)
+
+用户目标：当记忆行为不符合预期时，用户能看懂原因并修正，而不必阅读底层内部状态。
+
+必须完成的出口标准：
+
+- 本地 trace ring buffer，例如 `logs/trace.jsonl`，包含稳定 event name 和 reason code。
+- `pi-memory status --verbose` 与 `/memory-status` 能总结最近 skip、fallback、write、reindex、recall 事件。
+- memory edit/review 命令，并配合 **0.5** 的 stale/supersede 语义。
+- 不同 Pi 安装之间的本地 import/export，并提供 dry-run，为未来 sync 做准备。
+
+0.6 可选 backlog：
+
+- 更好的 TUI status panel。
+- 常见 Pi 配置的文档 recipes。
+- 剩余 sidecar tuning，例如并行 raw+intent recall、MMR lambda 调参、consolidate 后 recall 抽检，由 p99 延迟和 eval 数据驱动。
+
+## P4：可选同步
+
+**目标版本：0.7.x**
+
+用户目标：跨多个 Pi agent 或设备工作时，可以协同记忆，但不放弃本地控制权。
+
+- 多 agent 跨 session 记忆协同。
+- 可选 cloud Pi agent <-> local Pi agent session-memory sync。
+- `MEMORY.md` 仍是 source of truth；vector index 在各设备本地 rebuild。
+- 默认不自动上传。
+- sync 设计必须先定义冲突处理、trust boundary、redaction guarantee、rollback，再进入实现。
+- 前置条件：injection + redaction 闭环、stale/edit 语义、本地 import/export、debug/trace 能排障跨进程写入。

package/doc/ROADMAP.md

@@ -0,0 +1,114 @@
+# @chendpoc/pi-memory Roadmap
+
+<p align="center">
+  <a href="ROADMAP.md">English</a> |
+  <a href="ROADMAP-zh.md">简体中文</a>
+</p>
+
+This is the public product roadmap for `@chendpoc/pi-memory`. It focuses on user-visible outcomes and intentionally avoids linking to internal `dev-doc/` design notes that are not shipped in the npm package.
+
+## Version Map
+
+| Version | Theme | User-facing outcome |
+| --- | --- | --- |
+| **0.3.x** | Trust and safety | Memory writes are safer, bounded, and easier to diagnose. |
+| **0.4.x** | Recall quality | Pi retrieves the right memory more often under the Preflight budget. |
+| **0.5.x** | Memory lifecycle | Users can review, age out, and correct long-lived memory with less manual cleanup. |
+| **0.6.x** | Observability + controls | Users can inspect, debug, edit, review, and locally move memory between Pi installs. |
+| **0.7.x** | Optional sync | Local-first memory can coordinate across agents or devices without making cloud sync mandatory. |
+
+Before **0.7**, three things must be real: debug/trace, memory edit/review, and local import/export. Cloud or multi-agent sync should remain optional and local-first by default.
+
+## Product Principles
+
+- `MEMORY.md` remains the editable Ground Truth.
+- Derived indexes, sidecars, traces, and future sync state must be rebuildable from local memory artifacts.
+- Recall should improve ordinary agent behavior without adding multi-second thinking to every turn.
+- Safety features should fail closed for memory writes and fail open for agent turns.
+- `pi-memory` should not become a full transcript search product; that belongs in a dedicated session-search package.
+
+## Current Foundation
+
+- `MEMORY.md` Ground Truth with overflow.
+- `/remember` and `/memory-status`.
+- Sidecar over UDS JSONL.
+- `memory.vec.sqlite` vector index.
+- QueryIntent with raw-query fallback.
+- 800ms shared Preflight budget with AbortSignal-aware sidecar query.
+- Warm sidecar, intent cache, query cache.
+- Dual-purpose compaction summary.
+- Shutdown Queue + `maintenance`.
+- Consolidate + reindex.
+- Subagent Memory Cap + Compact Delta.
+- Secret redaction before Ground Truth writes.
+- `MemoryRuntime` extension lifecycle and refactored store/sidecar modules.
+
+## P0: Trust And Safety
+
+**Target: 0.3.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/1)
+
+User-facing goal: memory should be safe enough to keep enabled by default.
+
+- ✅ Secret and token redaction before durable memory writes — **shipped in 0.3.0**.
+- ✅ Smaller, clearer runtime modules for store, ingest, status, lifecycle, and sidecar behavior — **shipped in 0.3.0**.
+- Prompt-injection guardrails for LLM-generated Memory Export.
+- Correction detector for explicit user corrections, scoped first to the `/remember` path.
+- Lightweight reason codes for skipped writes and fallback decisions; full trace UX is planned for **0.6**.
+
+## P1: Recall Quality
+
+**Target: 0.4.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/2)
+
+User-facing goal: Pi should recall the right stable facts more often, while staying fast enough for interactive turns.
+
+- Hybrid lexical + vector recall for `MEMORY.md` entries: SQLite FTS5 plus existing vector chunks, RRF merge, then MMR.
+- Recall eval fixtures for common coding-agent questions.
+- Debug metrics split by intent, embed, scan, MMR, render, fallback, and total Preflight time.
+- Embedding provider improvements beyond Ollama, including free/open-source embedding APIs where practical.
+- Sidecar retrieval optimizations: incremental reindex, batch embed, and clearer reindex/query isolation.
+- Optional reranker after MMR only when it fits the latency budget.
+
+## P2: Memory Lifecycle
+
+**Target: 0.5.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/3)
+
+User-facing goal: long-lived memory should stay useful instead of becoming a growing pile of stale facts.
+
+- Failure and tool-quirk categories.
+- Human-reviewable memory draft or diary before promotion.
+- Usage-weighted promotion and pruning.
+- Safer consolidate preview before rewrite.
+- Explicit stale/superseded fact handling instead of simple TODO pruning.
+- Lifecycle events feed the shared debug/trace event schema; the user-facing trace surfaces ship in **0.6**.
+
+## P3: Observability + Controls
+
+**Target: 0.6.x** · [GitHub milestone](https://github.com/chendpoc/pi-memory/milestone/4)
+
+User-facing goal: when memory behaves unexpectedly, users can see why and fix it without reading raw internals.
+
+Required exit criteria:
+
+- Local trace ring buffer, for example `logs/trace.jsonl`, with stable event names and reason codes.
+- `pi-memory status --verbose` and `/memory-status` surfaces that summarize recent skip, fallback, write, reindex, and recall events.
+- Memory edit/review commands paired with stale/supersede semantics from **0.5**.
+- Local import/export between Pi installations, with a dry-run mode before any future sync work.
+
+Optional backlog for 0.6:
+
+- Better TUI status panel.
+- Documentation recipes for common Pi setups.
+- Remaining sidecar tuning such as parallel raw+intent recall, MMR lambda tuning, and post-consolidate recall spot checks, driven by p99 latency and eval data.
+
+## P4: Optional Sync
+
+**Target: 0.7.x**
+
+User-facing goal: users who work across multiple Pi agents or devices can coordinate memory without giving up local control.
+
+- Multi-agent cross-session memory coordination.
+- Optional cloud Pi agent <-> local Pi agent session-memory sync.
+- `MEMORY.md` remains the source of truth; vector indexes are rebuilt per device.
+- No automatic upload by default.
+- Sync design must define conflict handling, trust boundaries, redaction guarantees, and rollback before implementation.
+- Prerequisites: injection + redaction closed loop, stale/edit semantics, local import/export, and debug/trace for cross-process write troubleshooting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chendpoc/pi-memory",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Cross-session episodic memory for Pi agent — MEMORY.md ground truth, JSONL sidecar retrieval, and Preflight injection",
   "type": "module",
   "main": "./dist/index.js",
@@ -39,6 +39,9 @@
   "files": [
     "dist",
     "doc/README-zh.md",
+    "doc/ROADMAP.md",
+    "doc/ROADMAP-zh.md",
+    "doc/LAUNCH-KIT.md",
     "templates/MEMORY.md.example",
     "templates/com.pi.memory.consolidate.plist.example",
     "templates/consolidate.cmd.example",
@@ -60,6 +63,11 @@
     "pi-extension",
     "pi-agent",
     "episodic-memory",
+    "agent-memory",
+    "local-memory",
+    "markdown-memory",
+    "coding-agent",
+    "ai-memory",
     "recent-memory",
     "memory-recall"
   ],