@qltk/pi-mnemo 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 0.1.0 — 2026-09-05
+
+初始版本：mnemo（opencode 版，@qltk/mnemo 0.5.9）的 pi coding agent 移植。
+
+### 三段架构（pi 版实现）
+- **Recall**：`before_agent_start` 钩子，每轮把 inject.md + global/project 双 scope `MEMORY.md` 索引追加进 system prompt。
+- **Extract**：`agent_settled` + 节流（最小新增行数 + 最小间隔）→ spawn 分离无头 worker（`pi -p --no-session --no-extensions -t …`），worker 自读父会话 JSONL 从行号游标起抽取。
+- **Dream**：`agent_settled` + 24h per-slug 节流 + 夜间窗口（默认 18:30-08:30）+ 文件锁 → 无头 worker 合并/去重/软删（deprecated_by）/索引清理。
+
+### 新增（相对 mnemo 的机制差异）
+- Worker 是独立 OS 进程（`--no-session` 不落盘、退出即清理），替代 opencode 的 fork session——无泄漏、无卡死检测/清理需求。
+- Citation 闭环改扫会话 JSONL 文件的 `toolCall` 行（`read` 读过 topic → bump usage_count），替代拉取 server transcript。
+- Extract 游标从 message id 改为 JSONL 行号（天然增量、断点续扫）。
+- `session_shutdown` 钩子兜底 citation flush。
+- `/mnemo` 命令（status / extract / dream）。
+
+### 继承（从 mnemo 原样）
+- 11 个纯函数模块：slug / prompt / citation-parser / frontmatter / sanitizer / atomic-writer / memory-index / state-store / dream-lock / dream-safety / extract-success。
+- 三份 prompt seam（inject / extract / dream），extract 改为自读 SESSION_FILE 模式，dream 会话存储路径改 `~/.pi/agent/sessions/`。
+- 四类型（user/feedback/project/reference）→ 双 scope；配置 seam 全 env 覆盖（前缀 `PI_MNEMO_`）。
+
+### 未接线（后续版本）
+- dream-safety / extract-success / citation-parser 三个模块暂未被 orchestrator 引用（沿用 mnemo 的深化方向，待实测后接线）。

package/README.md

@@ -0,0 +1,93 @@
+# pi-mnemo
+
+pi coding agent 的持久记忆扩展。[mnemo](https://gitee.com/liubola/mnemo)（opencode 版）的 pi 移植：文件式、四类型、`MEMORY.md` 索引 + topic 文件、三段全自动。
+
+纯 TypeScript 扩展，无 native 依赖、无 Docker、不用 RAG/向量检索。相关性靠 LLM-judge（注入索引 → agent 扫标题 → 按需读 topic）。
+
+## 工作机制（三段）
+
+| 段 | 触发 | 机制 |
+|---|---|---|
+| **Recall** | 每次用户提交 prompt（`before_agent_start`） | 把 `inject.md` 指令 + global/project 两个 `MEMORY.md` 索引追加进 system prompt |
+| **Extract** | 会话安定（`agent_settled`），节流后 | spawn 分离的无头 worker `pi -p --no-session`，自读会话 JSONL、抽取新记忆写 topic 文件 |
+| **Dream** | 会话安定 + 24h 节流 + 夜间窗口 | 无头 worker 合并/去重/软删（`deprecated_by`）/修正漂移/清理索引 |
+
+另有 **citation 闭环**：主 agent 用 `read` 工具读过某 topic 文件 → 自动 bump 该 topic 的 `usage_count` / `last_used`（不依赖模型自觉）；dream 据此修剪长期未引用的过期 topic。
+
+主 agent 只在用户显式说"记住"时直接写；其余抽取由后台 worker 负责。
+
+## 安装
+
+```bash
+# npm（推荐；pi.dev gallery 自动收录带 pi-package 关键字的包）
+pi install npm:@qltk/pi-mnemo
+
+# git 源
+pi install git:gitee.com/liubola/pi-mnemo
+
+# 本地开发（放自动发现目录，支持 /reload 热重载）
+ln -s /path/to/pi-mnemo ~/.pi/agent/extensions/pi-mnemo
+```
+
+## 使用
+
+装好后全自动。命令：
+
+- `/mnemo` — 状态（memory root、slug、topic 数、上次 dream 时间）
+- `/mnemo extract` — 手动触发本会话抽取
+- `/mnemo dream` — 手动触发整理
+
+对模型说"记住 …"会立即写入（见 inject.md 指令）。
+
+## 记忆落盘位置
+
+```
+~/.pi/agent/mnemo/            ← memoryRoot
+├── MEMORY.md                 global 索引（user 类型，跨项目）
+├── <topic>.md                user 类型 topic
+├── projects/<slug>/          per-project（slug 由项目路径生成）
+│   ├── MEMORY.md             project 索引
+│   └── <topic>.md            project/feedback/reference 类型
+├── .plugin.log               调试日志
+├── .state.json               extract/dream 节流游标
+└── .dream.lock               dream 互斥锁
+```
+
+## 四类型 → scope
+
+| type | scope | 记什么 |
+|------|-------|--------|
+| user | global | 用户角色、跨项目偏好 |
+| feedback | project | 协作纠正（规则 + 原因 + 适用范围） |
+| project | project | 代码/git 推导不出的背景、决策、约束 |
+| reference | project | 外部系统链接 |
+
+## 配置（环境变量，全部可选）
+
+| env | 默认 | 说明 |
+|---|---|---|
+| `PI_MNEMO_ROOT` | `~/.pi/agent/mnemo` | 记忆根目录 |
+| `PI_MNEMO_EXTRACT_MODEL` | （pi 默认模型） | extract worker 模型（`provider/id`） |
+| `PI_MNEMO_DREAM_MODEL` | 同 extract | dream worker 模型（可换大窗口） |
+| `PI_MNEMO_DREAM_INTERVAL_MS` | `86400000` | dream 节流（per-slug） |
+| `PI_MNEMO_DREAM_WINDOW_START/END` | `18:30` / `08:30` | dream 夜间窗口（置空 = 全天） |
+| `PI_MNEMO_EXTRACT_MIN_NEW_MESSAGES` | `5` | 触发 extract 的最小新增行数 |
+| `PI_MNEMO_EXTRACT_MIN_INTERVAL_MS` | `1800000` | 同一会话两次 extract 最小间隔 |
+| `PI_MNEMO_WORKER_TIMEOUT_MS` | `600000` | worker 卡住强杀阈值 |
+| `PI_MNEMO_DISABLED` | `0` | `1` = 关后台（只留 recall + 手动命令） |
+| `PI_MNEMO_PI_BIN` | `pi` | pi 可执行文件路径 |
+
+## 与 mnemo（opencode 版）的差异
+
+| | mnemo | pi-mnemo |
+|---|---|---|
+| Recall 钩子 | `experimental.chat.system.transform` | `before_agent_start`（每轮注入最新索引） |
+| Extract 执行 | opencode server fork session + `promptAsync` | 分离进程 `pi -p --no-session`，自读会话 JSONL |
+| 会话泄漏防护 | forkSessions Map + `session.delete` | 不需要（`--no-session` 不落盘，进程退出即清理） |
+| Citation 观测 | 拉取 server transcript | 直接扫会话 JSONL 文件的 `toolCall` 行 |
+| Extract 游标 | message id | JSONL 行号（天然增量和断点） |
+| 额外钩子 | — | `session_shutdown` 兜底 flush |
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,88 @@
+// index.ts — pi-mnemo extension entry.
+//
+// Three segments, mirroring mnemo for opencode:
+//   Recall  — before_agent_start: append memory block (inject.md + indexes) to the system prompt.
+//   Extract — agent_settled: spawn a detached headless `pi -p --no-session` worker
+//             that reads the session JSONL and writes topic files.
+//   Dream   — agent_settled: 24h-throttled consolidation worker (merge/dedupe/prune).
+//
+// Plus a citation loop: read-tool calls on memory topics bump usage_count.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import { CONFIG } from "./src/config.js";
+import { projectSlug } from "./src/slug.js";
+import { buildRecallBlock } from "./src/recall.js";
+import { Orchestrator } from "./src/orchestrator.js";
+import { FileDreamStateStore } from "./src/state-store.js";
+import { FileDreamLock } from "./src/dream-lock.js";
+import { log } from "./src/log.js";
+
+export default function mnemo(pi: ExtensionAPI) {
+  // Worker processes set PI_MNEMO_WORKER=1 and run with --no-extensions,
+  // but be defensive anyway: never schedule work from inside a worker.
+  if (process.env.PI_MNEMO_WORKER === "1") return;
+
+  const stateStore = new FileDreamStateStore(join(CONFIG.memoryRoot, ".state.json"));
+  const lock = new FileDreamLock(CONFIG.memoryRoot);
+  const orch = new Orchestrator({ stateStore, lock });
+
+  // ---------- Recall ----------
+  // Fired on every user prompt; the memory block reflects the latest state on disk.
+  pi.on("before_agent_start", async (event, ctx) => {
+    try {
+      const slug = projectSlug(ctx.cwd, ctx.cwd);
+      const block = buildRecallBlock(slug);
+      if (!block) return;
+      return { systemPrompt: event.systemPrompt + "\n\n" + block };
+    } catch (e: any) {
+      log("recall failed:", e?.message ?? e);
+    }
+  });
+
+  // ---------- Extract / Dream / Citations ----------
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (CONFIG.disabled) return;
+    try {
+      const slug = projectSlug(ctx.cwd, ctx.cwd);
+      const sessionFile = ctx.sessionManager.getSessionFile() ?? null;
+      await orch.bumpCitations(sessionFile, slug);
+      await orch.maybeExtract(sessionFile, slug, ctx.cwd);
+      await orch.maybeDream(slug, ctx.cwd);
+    } catch (e: any) {
+      log("settled handler failed:", e?.message ?? e);
+    }
+  });
+
+  // Last-chance flush before the process exits.
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (CONFIG.disabled) return;
+    try {
+      const slug = projectSlug(ctx.cwd, ctx.cwd);
+      const sessionFile = ctx.sessionManager.getSessionFile() ?? null;
+      await orch.bumpCitations(sessionFile, slug);
+    } catch { /* best-effort */ }
+  });
+
+  // ---------- /mnemo command ----------
+  pi.registerCommand("mnemo", {
+    description: "pi-mnemo memory: status / extract / dream",
+    handler: async (args, ctx) => {
+      const slug = projectSlug(ctx.cwd, ctx.cwd);
+      const sub = (args || "").trim().split(/\s+/)[0] ?? "";
+      const sessionFile = ctx.sessionManager.getSessionFile() ?? null;
+      if (sub === "extract") {
+        const ok = await orch.extractNow(sessionFile, slug, ctx.cwd);
+        ctx.ui.notify(ok ? `extract worker spawned (${slug})` : "extract failed — no session file or missing prompt", ok ? "info" : "error");
+      } else if (sub === "dream") {
+        const ok = await orch.dreamNow(slug, ctx.cwd);
+        ctx.ui.notify(ok ? `dream worker spawned (${slug})` : "dream lock busy — try again later", ok ? "info" : "error");
+      } else {
+        const text = await orch.status(slug);
+        ctx.ui.notify(text, "info");
+      }
+    },
+  });
+
+  log("pi-mnemo loaded. root:", CONFIG.memoryRoot);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@qltk/pi-mnemo",
+  "version": "0.1.0",
+  "description": "Persistent memory for the pi coding agent — auto recall/extract/dream, file-based (MEMORY.md index + topic files), global + project dual scope. Port of mnemo (opencode).",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "memory",
+    "agent",
+    "persistent-memory"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/liubola/pi-mnemo.git"
+  },
+  "exports": "./index.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "prompts/**/*",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@types/node": "^24",
+    "typescript": "^5"
+  }
+}

package/prompts/dream.md

@@ -0,0 +1,59 @@
+# Dream: Memory Consolidation
+
+You are performing a dream — a reflective pass over the memory files. Synthesize what's been learned recently into durable, well-organized memories so future sessions orient quickly.
+
+## Two scopes
+- **Global** (`user` type): `{{GLOBAL_DIR}}/`
+- **This project** (`{{PROJECT_SLUG}}`): `{{PROJECT_DIR}}/`
+
+Both directories already exist. Consolidate each scope separately — they have independent MEMORY.md indexes.
+
+Session transcripts (if present): `~/.pi/agent/sessions/` — large JSONL files; grep narrowly, never read whole.
+
+## Phase 1 — Orient
+- `ls` both directories; read each MEMORY.md.
+- Browse existing topic files. Prefer improving old files over creating new ones. Avoid duplicates.
+
+## Phase 2 — Gather recent signal
+
+> Note: this is an independent dream session with **no transcript of its own** (not a fork of any conversation). Drift detection relies on what extract has recorded into topic files + your own read of current topic content + cross-references between topics. If a topic explicitly references a session, you may narrow-grep transcripts under `~/.pi/agent/sessions/` — but don't expect a transcript to be "your" conversation.
+
+1. Drifted memories — old topic entries that current topic content (or cross-references between topics) contradicts.
+2. Specific confirmations: only grep for things you already suspect matter.
+
+Form a suspicion first, then search for evidence.
+
+## Phase 3 — Consolidate (per scope)
+For each piece worth keeping, in the matching scope:
+- Create or update topic files.
+- Prefer merging into existing files; avoid near-duplicates.
+- Convert relative dates ("yesterday", "last week", "last month", "recently", "this week") to **absolute ISO dates (YYYY-MM-DD)**. Today is **{{TODAY}}** — use it as the single reference for every conversion (e.g. "last week" → the Monday of the previous week relative to {{TODAY}}). Never leave a relative date in a topic file.
+- Correct overturned memories at the source.
+- Keep the four types and the "What NOT to save" rules from the extraction prompt.
+
+**Global scope (user type) — user-profile drift correction:** Re-read the global user topic(s). Cross-check against recent sessions: is it still accurate? Correct drifted cross-project preferences (changed role / tools / habits), drop stale ones, and merge in new cross-project preferences that extract has been recording into project scopes. Keep global a concise cross-project picture — move any project-specific detail that leaked into global back to the right project scope.
+
+**Soft delete (deprecated_by):** When merging duplicates or removing stale topics, do NOT delete the file. Instead add `deprecated_by: <merged-into-file.md>` to its frontmatter (and remove its MEMORY.md index line). Deprecated topics are filtered from recall automatically but remain on disk for audit/rollback.
+
+## Phase 4 — Prune and index (each MEMORY.md)
+
+### Index hygiene
+- ≤200 lines, ≤~25KB; one line per entry ≤~150 chars; pointers only, never body content.
+- **Index consistency**: MEMORY.md lines pointing to non-existent topic files → remove that line. Topic files on disk referenced by no MEMORY.md → either add the missing index line (if still relevant) or prune. No dangling references or orphans.
+
+### Prune signals (multi-signal; pinned always wins)
+- **Pinned protection**: topics whose frontmatter has `pinned: true` must NEVER be deleted, merged, or deprecated — skip them entirely.
+- **Age hard threshold**: topic files whose mtime is older than **{{PRUNE_AGE_DAYS}} days** AND `usage_count ≤ 1` → strong prune candidate. Verify not still-relevant before deprecating.
+- **Usage-based (secondary)**: `usage_count: 0` + stale `last_used` = likely stale; prefer removing.
+- **Cold-start gate ({{USAGE_COLD_START_UNTIL}})**: `usage_count` switched to plugin-observed Read-tool tracking on the epoch date. **Before {{USAGE_COLD_START_UNTIL}}, usage_count on old topics is unreliable** (the old text-comment mechanism barely fired). Do NOT prune based on usage_count for any topic in the cold-start window — only age + your own relevance judgment apply. After {{USAGE_COLD_START_UNTIL}}, usage_count is trustworthy and the rules above fully apply.
+- Prefer `deprecated_by` (soft delete) over file deletion unless content is clearly wrong/harmful.
+
+### Audit trail
+- Append this run's prune/deprecate decisions to `dream_log.md` in the global scope dir: list each affected file + action (deprecated_by X / index-line-removed / deleted). Keeps consolidation auditable and reversible.
+- Title your entry with the real completion timestamp — `## YYYY-MM-DDTHH:MM:SSZ (slug: ...)` (look up the actual current time, e.g. via bash `date -u +%FT%TZ`). Never write placeholders like `XX:XX`.
+
+## Tool constraints for this run
+- bash: read-only only (`ls/find/grep/cat/stat/wc/head/tail`).
+- edit/write: only inside the two memory directories.
+
+Begin now.

package/prompts/extract.md

@@ -0,0 +1,76 @@
+# Memory Extraction Worker
+
+You are the memory extraction worker. Read the session transcript and use it to update the user's persistent memory.
+
+## Source transcript
+
+The conversation to analyze is a pi session file (JSONL, one JSON object per line):
+
+`{{SESSION_FILE}}`
+
+How to read it:
+- Lines are session entries: user messages (`role:"user"`), assistant messages (`role:"assistant"`), tool results (`role:"toolResult"`).
+- The file may be large. **Start from line {{CURSOR_LINE}} and read forward** — lines before that were already extracted in prior runs. If the cursor is 0, read the whole file (use `read` with offset/limit, or bash `wc -l` + `tail -n +N` for large files).
+- Focus on user messages and assistant text content; tool I/O is only context.
+
+## Memory system — two scopes
+
+Memory is split into two scopes. Write each memory to the matching scope by type:
+
+- **Global** (`user` type only — who the user is, cross-project identity/preferences): `{{GLOBAL_DIR}}/`
+- **This project** (`{{PROJECT_SLUG}}` — `project`/`feedback`/`reference` types): `{{PROJECT_DIR}}/`
+
+Each scope has its own `MEMORY.md` index (one line per memory, ≤200 lines / ~25KB) and topic files alongside it.
+
+### Types → scope mapping
+| type | scope | what to record |
+|------|-------|----------------|
+| user | global | who the user is: role, experience, goals, stable cross-project preferences |
+| feedback | this project | collaboration corrections the user made for THIS project's work |
+| project | this project | background not derivable from code/git: decisions, deadlines, constraints |
+| reference | this project | external systems: boards, channels, doc links |
+
+> If a preference is clearly cross-project (e.g. "always reply in Chinese", "data-driven"), record it as `user` in **global**. If it's project-specific, record it in **this project**.
+
+### What NOT to save
+- Code patterns, conventions, architecture, file paths, project structure
+- Git history and recent code changes
+- Debugging solutions and fix recipes
+- Content already in AGENTS.md
+- Current task progress and temporary conversation state
+
+### Privacy — never record these
+- **Secrets**: API keys (`sk-`, `ghp_`, `xoxb_`, `AKIA`, ...), private keys (PEM blocks), passwords, tokens, `.env` values. If you see any in the transcript, do NOT write them to memory — skip entirely.
+- **Never restate secrets**: When explaining why you skipped a secret (in any output or tool argument), NEVER repeat the full value — use a redacted form like `sk-***` or `ghp_***`. Restating the full secret into your output is itself a leak, even if you never save it to a file.
+- **`<private>` content**: anything wrapped in `<private>...</private>` tags must NOT be recorded. Skip it.
+- **Injected context**: transcript blocks like `# AGENTS.md instructions <INSTRUCTIONS>...</INSTRUCTIONS>`, `<skill>...</skill>`, or `## Auto Memory` (the recall index injection) are system context, NOT new facts — do NOT extract them as memories (they're rules or the agent's own prior recall).
+
+### How to save
+Step 1 — write each memory into its own topic file in the **matching scope directory**:
+```
+---
+name: {{memory name}}
+description: {{one-line, used for relevance selection}}
+type: {{user|feedback|project|reference}}
+---
+{{memory content — for feedback: record the rule, the reason, and when it applies}}
+```
+Step 2 — add or update a one-line pointer in **that scope's** `MEMORY.md` (the index file MUST be named exactly `MEMORY.md`, never `INDEX.md`):
+`- [Title](file.md) — one-line hook`
+
+Check existing memories in both scopes before creating duplicates — update rather than create.
+
+### Convergence discipline — topics are living documents, not session logs
+- **NEVER create `session-*` files or diary-style topics** that narrate what happened in one session. Topics hold durable knowledge by theme, not per-session chronicles.
+- **Update existing topics instead of snapshotting.** When the transcript advances a theme already covered by a topic (e.g. a status/progress/decision topic), edit that topic to reflect the current state — replace superseded details, don't append a second copy of history. Only create a new topic when the theme itself is genuinely new.
+- One theme = one topic file. If you find yourself writing "in this session we ...", rewrite it as the resulting state/decision/constraint instead.
+
+### Size discipline
+- Single topic soft cap **{{TOPIC_SOFT_MAX_KB}} KB**. If a topic would exceed it, keep only conclusions and decision points + a pointer to the specific session/file for detail, or split into sub-topics. Never paste long transcript excerpts verbatim into a topic file.
+
+## Constraints for this run
+- Tools: read, grep, find, read-only bash (`ls/wc/tail/head`), and edit/write **only inside either memory directory**. bash `rm` not permitted.
+- Limited turn budget. **Turn 1 — read both MEMORY.md indexes (global + project) in parallel** so you know what's already recorded and can detect duplicates, plus scan the transcript from the cursor; **turn 2 — write/edit all in parallel**. edit requires a prior read of the same file. Do NOT create a new topic file before reading the indexes — duplicate detection depends on knowing what exists.
+- You MUST only use content from the transcript file above. Do not investigate the codebase.
+
+Begin now.

package/prompts/inject.md

@@ -0,0 +1,47 @@
+## Auto Memory
+
+You have a persistent, file-based memory. Build it up over time so future conversations have a complete picture of: who the user is, how they want to collaborate, what behaviors to avoid or repeat, and context behind their work.
+
+**Two scopes (write to the matching one by type):**
+- **Global** (`user` type — cross-project identity/preferences): `{{GLOBAL_DIR}}`
+- **This project** (`{{PROJECT_SLUG}}`, `project`/`feedback`/`reference` types): `{{PROJECT_DIR}}`
+
+Both directories already exist — write to them directly with the Write tool (do not run mkdir or check for their existence).
+
+**If the user explicitly says "remember"**, save immediately (write a topic file + update the scope's MEMORY.md). **If the user says "forget"**, find and remove the relevant topic file + its MEMORY.md entry. Otherwise, a background agent handles extraction after each session — you don't need to proactively record.
+
+**Do NOT save:** code patterns/architecture/file paths, git history, debug recipes, anything in AGENTS.md, temporary task state.
+
+**How to save:** (1) write a topic .md file in the matching scope (frontmatter: name/description/type); (2) add a one-line pointer to that scope's MEMORY.md (the index file MUST be named exactly `MEMORY.md`, never `INDEX.md`). Check existing first — update rather than duplicate.
+
+## Recall
+
+Each scope has a MEMORY.md index below.
+
+**When to use memory:**
+- **Skip** for clearly self-contained requests: current time/date, simple translation, one-line shell command, trivial formatting.
+- **Use** when any of these are true: the query mentions a workspace / path / file / project shown in the indexes below; the user asks for prior context / consistency / previous decisions; the task is ambiguous and could depend on earlier choices.
+- Unsure → do a quick memory pass.
+
+**Quick memory pass:**
+1. Skim the MEMORY.md indexes below; extract task-relevant keywords.
+2. Search topic files (grep `*.md`) using those keywords.
+3. Session transcripts are a last resort — large and slow; grep narrowly only if you suspect something specific.
+4. No relevant hits → stop, continue normally.
+
+**Budget:** keep memory lookup lightweight — ideally ≤4-6 search steps before main work. Use narrow search terms (error messages, file paths, function names), not broad keywords.
+
+## Staleness
+
+Topic entries below may carry a marker like "[N days old — verify against current code]". Memories are point-in-time observations, not live state.
+
+**When to verify a memory before answering:**
+- Likely to drift AND cheap to verify → verify first, then answer.
+- Likely to drift but expensive/slow to verify → you may answer from memory, but say it is memory-derived and may be stale, and offer to refresh it live.
+- Lower-drift and expensive to verify → usually fine to answer from memory directly.
+
+**When answering from unverified memory:** say briefly that the fact is memory-derived; if drift-prone, note it may be outdated; offer a live refresh for interactive questions about prior results / commands / timing. Never present unverified memory-derived facts as confirmed-current.
+
+## Usage tracking (automatic)
+
+You don't need to manually mark which memory files you used. The plugin observes your Read-tool calls and bumps `usage_count` / `last_used` on topics you actually read. Dream prunes long-uncited stale topics after a cold-start period. Just use memory naturally — read what's relevant, ignore what isn't.

package/src/atomic-writer.ts

@@ -0,0 +1,22 @@
+// atomic-writer.ts — atomic file write (tmp + rename).
+// Prevents crash corruption. Windows rename failure → fallback direct write.
+// Extracted from io.js for testability / reuse in dream/extract.
+
+import { writeFileSync, renameSync, unlinkSync } from "node:fs";
+
+/**
+ * Atomically write content to a file using tmp+rename pattern.
+ * On Windows, if rename fails, falls back to direct write.
+ */
+export function atomicWrite(filePath: string, content: string): void {
+  const tmp = filePath + ".tmp." + process.pid;
+  try {
+    writeFileSync(tmp, content);
+    renameSync(tmp, filePath);
+  } catch {
+    try { unlinkSync(tmp); } catch {
+      // best-effort cleanup
+    }
+    writeFileSync(filePath, content);
+  }
+}

package/src/citation-parser.ts

@@ -0,0 +1,11 @@
+// citation-parser.ts — extract mem-citation references from assistant text.
+// Pure function, no side effects. Extracted from fork.js for testability.
+
+/**
+ * Parse `<!-- mem-citation: filename.md -->` markers from assistant reply text.
+ * Returns deduplicated filenames (e.g. ["my-topic.md", "another.md"]).
+ */
+export function parseCitations(text: string): string[] {
+  const matches = [...text.matchAll(/<!--\s*mem-citation:\s*([^<\s>]+\.md)\s*-->/g)];
+  return [...new Set(matches.map((m) => m[1]))];
+}

package/src/config.ts

@@ -0,0 +1,90 @@
+// config.ts — configuration seam for pi-mnemo (env vars with defaults).
+
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import type { MemoryConfig, DreamWindow } from "./types.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Parse "HH:MM" → {h,m}, null if invalid. */
+function parseHM(s: string): { h: number; m: number } | null {
+  const mt = /^(\d{1,2}):(\d{2})$/.exec(s.trim());
+  if (!mt) return null;
+  const h = Number(mt[1]), m = Number(mt[2]);
+  if (h > 23 || m > 59) return null;
+  return { h, m };
+}
+
+/** Parse dream window (env override, default 18:30-08:30 crossing midnight). null = always allowed. */
+function parseDreamWindow(): DreamWindow | null {
+  const startRaw = process.env.PI_MNEMO_DREAM_WINDOW_START ?? "18:30";
+  const endRaw = process.env.PI_MNEMO_DREAM_WINDOW_END ?? "08:30";
+  if (startRaw === "" || endRaw === "") return null; // explicitly disabled
+  const start = parseHM(startRaw);
+  const end = parseHM(endRaw);
+  if (!start || !end) return null; // invalid → window off
+  const tzRaw = process.env.PI_MNEMO_DREAM_TZ;
+  let tz: string;
+  if (tzRaw) {
+    try {
+      Intl.DateTimeFormat("en-US", { timeZone: tzRaw });
+      tz = tzRaw;
+    } catch {
+      console.error(`[pi-mnemo] invalid PI_MNEMO_DREAM_TZ "${tzRaw}", falling back to local timezone`);
+      tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+    }
+  } else {
+    tz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  }
+  return { start, end, tz };
+}
+
+/** Parse comma-separated list (drop empties). */
+function parseList(s: string): string[] {
+  return s.split(",").map((x) => x.trim()).filter(Boolean);
+}
+
+/** Read env number (empty/missing/non-numeric → default; explicit 0 honored). */
+function envNum(key: string, def: number): number {
+  const v = process.env[key];
+  if (v === undefined || v === "") return def;
+  const n = Number(v);
+  return Number.isFinite(n) ? n : def;
+}
+
+function envBool(key: string): boolean {
+  const v = process.env[key];
+  return v === "1" || v === "true" || v === "yes";
+}
+
+export const CONFIG: MemoryConfig = {
+  memoryRoot:
+    process.env.PI_MNEMO_ROOT ||
+    join(homedir(), ".pi", "agent", "mnemo"),
+  promptsDir:
+    process.env.PI_MNEMO_PROMPTS_DIR || join(__dirname, "..", "prompts"),
+
+  // Headless worker model ("provider/id"; empty = pi's default model at spawn time)
+  extractModel: process.env.PI_MNEMO_EXTRACT_MODEL || "",
+  dreamModel: process.env.PI_MNEMO_DREAM_MODEL || "",
+  modelFallback: parseList(process.env.PI_MNEMO_MODEL_FALLBACK || ""),
+  workerTools: process.env.PI_MNEMO_WORKER_TOOLS || "read,grep,glob,bash",
+
+  dreamIntervalMs: envNum("PI_MNEMO_DREAM_INTERVAL_MS", 24 * 60 * 60 * 1000),
+  dreamWindow: parseDreamWindow(),
+
+  extractMinNewMessages: envNum("PI_MNEMO_EXTRACT_MIN_NEW_MESSAGES", 5),
+  extractMinIntervalMs: envNum("PI_MNEMO_EXTRACT_MIN_INTERVAL_MS", 30 * 60 * 1000),
+
+  dreamBacklogDays: envNum("PI_MNEMO_DREAM_BACKLOG_DAYS", 2),
+  dreamBacklogPerIdle: envNum("PI_MNEMO_DREAM_BACKLOG_PER_IDLE", 1),
+
+  pruneAgeDays: envNum("PI_MNEMO_PRUNE_AGE_DAYS", 30),
+  coldStartDays: envNum("PI_MNEMO_COLD_START_DAYS", 14),
+  topicSoftMaxKB: envNum("PI_MNEMO_TOPIC_SOFT_MAX_KB", 8),
+  logMaxBytes: envNum("PI_MNEMO_LOG_MAX_BYTES", 1024 * 1024),
+
+  workerTimeoutMs: envNum("PI_MNEMO_WORKER_TIMEOUT_MS", 10 * 60 * 1000),
+  disabled: envBool("PI_MNEMO_DISABLED"),
+};

package/src/dream-lock.ts

@@ -0,0 +1,67 @@
+// dream-lock.ts — DreamLock interface + default file-based implementation.
+// Prevents concurrent dream runs + crash self-healing (stale lock cleanup).
+// Interface extracted from fork.js for testability / swappability.
+// 借鉴 opencode-mem operation-lock.ts.
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DreamLock {
+  /** Try to acquire the lock. Returns true if acquired, false if another instance holds it. */
+  acquire(): boolean;
+  /** Release the lock (only if this process owns it). */
+  release(): void;
+}
+
+interface LockState {
+  pid: number;
+  ts: number;
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * File-based DreamLock (default implementation).
+ * Uses .dream.lock with PID-based ownership + stale detection.
+ */
+export class FileDreamLock implements DreamLock {
+  private lockFile: string;
+
+  constructor(memoryRoot: string) {
+    this.lockFile = join(memoryRoot, ".dream.lock");
+  }
+
+  acquire(): boolean {
+    if (existsSync(this.lockFile)) {
+      try {
+        const info: LockState = JSON.parse(readFileSync(this.lockFile, "utf-8"));
+        if (info.pid && isProcessAlive(info.pid)) return false;  // 别的实例持锁且活着
+      } catch {
+        // corrupt lock → treat as stale
+      }
+      try { unlinkSync(this.lockFile); } catch {}  // stale（PID 死/坏）→ 清
+    }
+    try {
+      writeFileSync(this.lockFile, JSON.stringify({ pid: process.pid, ts: Date.now() }), { flag: "wx" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  release(): void {
+    try {
+      const info: LockState = JSON.parse(readFileSync(this.lockFile, "utf-8"));
+      if (info.pid === process.pid) unlinkSync(this.lockFile);  // 只删自己的
+    } catch {
+      // best-effort
+    }
+  }
+}