@yandy0725/pi-memory 0.3.1 → 1.0.1

package/README.md

@@ -2,13 +2,18 @@
 
 File-system driven persistent memory layer for pi coding agent. Stores project knowledge across sessions — facts, preferences, debugging history — in plain Markdown files under `~/.pi/memory/<project-hash>/`.
 
+Aligned with Claude Code's auto memory mechanism: per-topic MEMORY.md index, automatic topic file surfacing based on relevance, per-turn memory extraction, and typed memory categories.
+
 ## Features
 
 - **One `memory` tool**, four actions: `add` (append entry), `remove` (delete entry by title), `read` (load topic or entry), `search` (query memory or session history)
-- **Topic-based file organization**: each `memory add` writes to a named `.md` file under the project's memory directory
-- **`MEMORY.md` index** — auto-generated table of contents with line/byte capacity limits
-- **Snapshot injection**: on every new session, the memory index is appended to the system prompt, keeping the agent aware of past work
-- **`/dream` command**: launches a headless agent to deduplicate, merge, and consolidate all memory files
+- **Topic-based file organization**: each `memory add` writes a `## entry` block to a named `.md` file under the project's memory directory
+- **`MEMORY.md` index** — one compact line per topic file with a relevance hook: `- [Name](file.md) — summary`
+- **Memory types**: four categories — `user`, `feedback` (default), `project`, `reference` — stored in topic file frontmatter
+- **Auto-surfacing** ⭐: on every user message, a side-query LLM selects up to N relevant topic files and injects their content into the agent's context. No manual `memory read` needed. Session-level deduplication prevents re-injecting the same topic.
+- **Extract memories** ⭐: after each agent run, an async subagent analyzes the conversation and automatically writes learnings to memory — preferences, conventions, debugging insights
+- **Snapshot injection**: on every new session, the MEMORY.md index is appended to the system prompt, keeping the agent aware of past work
+- **`/dream` command**: launches a headless agent with a four-phase consolidation (Orient → Gather → Consolidate → Prune) to deduplicate, merge, and rebuild all memory files
 - **Dream nudge**: after N sessions or N hours, a gentle notification suggests running `/dream`
 - **`/memory` command**: show status, toggle on/off, inspect index and topic files
 - **Session search**: the `memory search scope=sessions` action queries past conversation history
@@ -31,7 +36,7 @@ Or add to `~/.pi/agent/settings.json`:
 
 ## Configuration
 
-Create `pi-memory.json` in the agent directory (`~/.pi/agent/pi-memory.json`) or the project `.pi/` directory (if trusted):
+Create `memory.json` in the agent directory (`~/.pi/agent/memory.json`) or the project `.pi/` directory (if trusted):
 
 ```json
 {
@@ -47,6 +52,18 @@ Create `pi-memory.json` in the agent directory (`~/.pi/agent/pi-memory.json`) or
   "sessionSearch": {
     "maxSessions": 10,
     "maxMatches": 5
+  },
+  "autoSurfacing": {
+    "enabled": true,
+    "model": "auto",
+    "maxFiles": 5,
+    "maxTopicBytes": 4096,
+    "maxInjectionBytes": 20480
+  },
+  "extractMemories": {
+    "enabled": true,
+    "model": "auto",
+    "maxContextTokens": 2000
   }
 }
 ```
@@ -62,28 +79,98 @@ Create `pi-memory.json` in the agent directory (`~/.pi/agent/pi-memory.json`) or
 | `dream.model` | `"auto"` | Model for dream consolidation (`"auto"` = same as current, or `"provider/id"`) |
 | `sessionSearch.maxSessions` | `10` | Max sessions to scan when searching history |
 | `sessionSearch.maxMatches` | `5` | Max matches to return from history search |
+| `autoSurfacing.enabled` | `true` | ⭐ Enable per-turn topic file auto-injection |
+| `autoSurfacing.model` | `"auto"` | ⭐ Model for side-query relevance selection |
+| `autoSurfacing.maxFiles` | `5` | ⭐ Max topic files to inject per turn |
+| `autoSurfacing.maxTopicBytes` | `4096` | ⭐ Max bytes per injected topic file (truncated) |
+| `autoSurfacing.maxInjectionBytes` | `20480` | ⭐ Max total bytes of injected content per turn |
+| `extractMemories.enabled` | `true` | ⭐ Enable per-turn memory extraction |
+| `extractMemories.model` | `"auto"` | ⭐ Model for the extraction subagent |
+| `extractMemories.maxContextTokens` | `2000` | ⭐ Max tokens of conversation to analyze |
+
+Project-level config (`.pi/memory.json`) is only loaded when the project is trusted.
+
+## How it works
+
+### MEMORY.md index
+
+MEMORY.md is a compact **pointer index** — one line per topic file, not per entry:
+
+```
+- [Debugging](debugging.md) — SSH uses port 2222; MySQL 30s timeout on staging
+- [API Conventions](api.md) — REST handlers in src/api/handlers/; standard error format
+```
+
+Only the index is injected into the system prompt on every session (first 200 lines / 25KB). Topic file content is **not** loaded at session start — it's surfaced on demand via auto-surfacing or explicit `memory read`.
+
+### Topic file format
+
+Each topic file uses YAML frontmatter with four fields:
+
+```yaml
+---
+name: Debugging Tips
+description: Common debugging patterns, SSH ports, MySQL timeout configs
+type: feedback
+updated: 2026-07-13
+---
 
-Project-level config (`.pi/pi-memory.json`) is only loaded when the project is trusted.
+## SSH Gotcha
+staging uses port 2222, key at ~/.ssh/staging
+
+## MySQL Timeout
+connection timeout after 30s on staging
+```
+
+The `description` field is critical — the auto-surfacing side-query uses it to determine relevance. Make it specific.
+
+### Memory types
+
+| Type | Meaning | Example |
+|------|---------|---------|
+| `user` | User role, preferences, knowledge | "User is a data scientist focused on observability" |
+| `feedback` | Lessons, corrections, confirmations (default) | "Use real DB not mocks — burned last quarter" |
+| `project` | Project state, deadlines, incidents | "Merge freeze starts 2026-03-05 for mobile release" |
+| `reference` | Pointers to external systems | "Bug tracker = Linear INGEST project" |
+
+### Auto-surfacing
+
+On every user message (`before_agent_start` hook):
+1. Scan all topic files, extract their frontmatter metadata
+2. A side-query LLM selects up to `maxFiles` relevant topic files based on the user's query
+3. Already-injected topics are skipped (session-level dedup)
+4. Selected topic file content is injected as context — the agent sees relevant memories automatically
+
+### Extract memories
+
+After each agent run (`agent_end` hook):
+1. An async subagent is forked with the conversation transcript
+2. It analyzes whether there are learnings worth persisting
+3. If yes, it writes directly to memory files — preferences, conventions, debugging insights
+4. The subagent runs independently; its results benefit future sessions
+
+Memory extraction is selective: it ignores one-time tasks, code snippets derivable from the project, and anything already in CLAUDE.md.
 
 ## Tool reference
 
 ```
 memory(action: "add" | "remove" | "search" | "read",
-        content?, topic?, title?,
+        content?, topic?, title?, type?,
         entry?, query?, scope?)
 ```
 
 ### `add`
 
-Appends an entry to a topic file and adds a new line to the MEMORY.md index (no upsert — multiple entries per topic).
+Appends a `## entry` block to a topic file. If the topic already exists in the index, the MEMORY.md hook is updated to summarize all entries. For new topics, a new index line is created.
 
 - **`content`** (required) — knowledge text to persist
 - **`topic`** (required) — target filename, e.g. `"debugging.md"`. Auto-created if new
-- **`title`** (required) — short title for the index line and entry heading
+- **`title`** (required) — descriptive, self-contained title for the entry. Only the MEMORY.md index line is injected into future prompts (topic file content is NOT), so the title alone must convey what was learned
+- **`type`** (optional) — memory category: `"user"`, `"feedback"` (default), `"project"`, `"reference"`
 
 ### `remove`
 
-Deletes an entry by exact title match on the MEMORY.md index. Removes both the index line and the corresponding `##` block from the topic file. When the last entry in a topic is removed, the topic file is deleted.
+Deletes an entry by title. Searches across all topic files for the matching `##` block. Updates the MEMORY.md hook for the affected topic. When the last entry in a topic is removed, the topic file and its index line are deleted.
 
 - **`entry`** (required) — exact entry title to remove
 
@@ -115,20 +202,25 @@ Show memory status (enabled/disabled, directory, index line count, topic files,
 
 ### `/dream`
 
-Launch a headless agent that reads all memory files, deduplicates entries, merges contradictions, updates outdated info, and reorganizes `MEMORY.md` to be concise. The model used can be configured via `dream.model` in `pi-memory.json` (`"auto"` uses the current conversation model; `"provider/id"` picks a specific model).
+Launch a headless agent that reads all memory files and consolidates them in four phases:
 
-A confirmation dialog is shown before the consolidation begins. The result summary is shown as a notification when done.
+1. **Orient** — list files, read MEMORY.md, skim topic files
+2. **Gather Signal** — find duplicates, contradictions, outdated entries
+3. **Consolidate** — merge duplicates, resolve contradictions, update dates
+4. **Prune & Index** — rebuild frontmatter, generate hooks, rebuild MEMORY.md
 
-Dream meta (timestamp, session count at dream) is persisted in `.dream-meta.json` inside the memory directory.
+The model used can be configured via `dream.model` in `memory.json`.
+
+A confirmation dialog is shown before the consolidation begins. The result summary is shown as a notification when done.
 
 ## File layout
 
 ```
 ~/.pi/memory/
   <12-char-sha256>/
-    MEMORY.md            — index: one line per topic file
+    MEMORY.md            — compact index: one line per topic file
     .dream-meta.json     — last dream timestamp + session count
-    debugging.md         — user-created topic files
+    debugging.md         — topic files with frontmatter + ## entries
     preferences.md
     ...
 ```
@@ -137,4 +229,6 @@ The hash is derived from the project's git root (or absolute path), ensuring eac
 
 ## Snapshot semantics
 
-On every `session_start`, the `MEMORY.md` index is read and appended to the system prompt via `before_agent_start`. If the index exceeds `memIndexMaxLines` or `memIndexMaxBytes`, it is truncated with a `[truncated]` marker — the agent still gets the most relevant portion. This snapshot is a static copy at the start of the session; changes made via the `memory` tool during a session do not update the snapshot for that session, but take effect on the next one.
+On every `session_start`, the `MEMORY.md` index is read and appended to the system prompt via `before_agent_start`. If the index exceeds `memIndexMaxLines` or `memIndexMaxBytes`, it is truncated with a `[truncated]` marker — the agent still gets the most relevant portion. This snapshot is a static copy at the start of the session.
+
+Topic file content is surfaced separately via **auto-surfacing** (automatic, per-turn, relevance-based) or explicit `memory read`.

package/README.zh.md

@@ -2,17 +2,22 @@
 
 基于文件系统的持久化记忆层，为 pi 编程代理提供跨会话的项目记忆。事实、偏好、调试历史等知识以纯 Markdown 文件形式存储在 `~/.pi/memory/<项目哈希>/` 下。
 
+对齐 Claude Code 的 auto memory 机制：每 topic 一行的 MEMORY.md 紧凑索引、基于相关性的 topic 文件自动注入、per-turn 记忆自动提取、类型化记忆分类。
+
 ## 功能
 
 - **一个 `memory` 工具**，四种操作：`add`（追加条目）、`remove`（按标题删除条目）、`read`（加载主题或条目）、`search`（查询记忆或会话历史）
-- **基于主题的文件组织**：每次 `memory add` 都会向项目记忆目录下指定名称的 `.md` 文件写入内容
-- **`MEMORY.md` 索引**：自动生成的目录，带有行数/字节容量限制
-- **快照注入**：每个新会话启动时，记忆索引会追加到系统提示中，让代理始终感知过往工作
-- **`/dream` 命令**：启动无头代理，对记忆文件进行去重、合并和整理
+- **基于主题的文件组织**：每次 `memory add` 向指定名称的 `.md` 文件写入 `## 条目` 区块
+- **`MEMORY.md` 索引**：每个 topic 文件一行紧凑指针 `- [名称](文件.md) — 摘要`，同 topic 自动合并
+- **记忆类型系统**：四种分类 — `user`（用户）、`feedback`（反馈，默认）、`project`（项目）、`reference`（引用）— 存储在 topic 文件 frontmatter 中
+- **Auto-surfacing** ⭐：每次用户发消息时，side-query LLM 自动选出最多 N 个相关 topic 文件并将其内容注入 agent context。无需手动 `memory read`。Session 内去重防止同一 topic 重复注入
+- **Extract memories** ⭐：每次 agent 运行结束后，异步子 agent 分析对话内容，自动将 learnings 写入 memory — 偏好、约定、调试心法等
+- **快照注入**：每个新会话启动时，MEMORY.md 索引追加到系统提示中
+- **`/dream` 命令**：四阶段（Orient → Gather → Consolidate → Prune）无头代理整理，去重、合并、重建全部记忆文件
 - **梦醒提醒**：经过 N 个会话或 N 小时后，温和通知建议运行 `/dream`
 - **`/memory` 命令**：查看状态、开关记忆、检查索引和主题文件
 - **会话搜索**：`memory search scope=sessions` 操作可检索过往对话历史
-- **分支安全**：记忆目录以 git 根目录（或绝对路径）为键，分叉仓库自然共享记忆
+- **分支安全**：记忆目录以 git 根目录为键，分叉仓库自然共享记忆
 - **路径穿越防护**：主题文件路径会验证是否逃逸记忆目录
 
 ## 安装
@@ -31,7 +36,7 @@ pi install npm:@yandy0725/pi-memory
 
 ## 配置
 
-在代理目录（`~/.pi/agent/pi-memory.json`）或项目的 `.pi/` 目录（需受信任）中创建 `pi-memory.json`：
+在代理目录（`~/.pi/agent/memory.json`）或项目的 `.pi/` 目录（需受信任）中创建 `memory.json`：
 
 ```json
 {
@@ -47,6 +52,18 @@ pi install npm:@yandy0725/pi-memory
   "sessionSearch": {
     "maxSessions": 10,
     "maxMatches": 5
+  },
+  "autoSurfacing": {
+    "enabled": true,
+    "model": "auto",
+    "maxFiles": 5,
+    "maxTopicBytes": 4096,
+    "maxInjectionBytes": 20480
+  },
+  "extractMemories": {
+    "enabled": true,
+    "model": "auto",
+    "maxContextTokens": 2000
   }
 }
 ```
@@ -55,43 +72,113 @@ pi install npm:@yandy0725/pi-memory
 |--------|--------|------|
 | `enabled` | `true` | 开关整个记忆系统 |
 | `memoryDir` | `~/.pi/memory` | 所有记忆数据的根目录 |
-| `memIndexMaxLines` | `200` | `MEMORY.md` 的最大行数，超限报容量错误 |
-| `memIndexMaxBytes` | `25600` | `MEMORY.md` 的最大字节数，超限报容量错误 |
-| `dream.nudgeAfterSessions` | `5` | 距离上次整理经过的会话数，达到后展示提醒 |
-| `dream.nudgeAfterHours` | `24` | 距离上次整理经过的小时数，达到后展示提醒 |
-| `dream.model` | `"auto"` | 整理使用的模型（`"auto"` 使用当前模型，或 `"provider/id"` 指定模型） |
-| `sessionSearch.maxSessions` | `10` | 搜索历史会话时最多扫描的会话数 |
+| `memIndexMaxLines` | `200` | `MEMORY.md` 最大行数 |
+| `memIndexMaxBytes` | `25600` | `MEMORY.md` 最大字节数 |
+| `dream.nudgeAfterSessions` | `5` | 触发提醒需经过的会话数 |
+| `dream.nudgeAfterHours` | `24` | 触发提醒需经过的小时数 |
+| `dream.model` | `"auto"` | 整理使用的模型（`"auto"` = 当前模型，或 `"provider/id"`） |
+| `sessionSearch.maxSessions` | `10` | 搜索历史时最多扫描的会话数 |
 | `sessionSearch.maxMatches` | `5` | 历史搜索最多返回的匹配数 |
+| `autoSurfacing.enabled` | `true` | ⭐ 启用 per-turn topic 文件自动注入 |
+| `autoSurfacing.model` | `"auto"` | ⭐ side-query 相关性选择模型 |
+| `autoSurfacing.maxFiles` | `5` | ⭐ 每轮最多注入的 topic 文件数 |
+| `autoSurfacing.maxTopicBytes` | `4096` | ⭐ 单个注入 topic 文件最大字节数（截断） |
+| `autoSurfacing.maxInjectionBytes` | `20480` | ⭐ 每轮注入内容总字节数上限 |
+| `extractMemories.enabled` | `true` | ⭐ 启用 per-turn 记忆自动提取 |
+| `extractMemories.model` | `"auto"` | ⭐ 提取子 agent 使用的模型 |
+| `extractMemories.maxContextTokens` | `2000` | ⭐ 分析对话的最大 token 数 |
+
+项目级配置（`.pi/memory.json`）仅在项目受信任时加载。
+
+## 工作原理
+
+### MEMORY.md 索引
+
+MEMORY.md 是一个**紧凑指针索引** — 每个 topic 文件一行，而非每个条目一行：
+
+```
+- [Debugging](debugging.md) — SSH 使用 2222 端口；MySQL staging 上 30s 超时
+- [API Conventions](api.md) — REST handlers 在 src/api/handlers/；使用标准错误格式
+```
+
+每次会话只有索引被注入系统提示（前 200 行 / 25KB）。Topic 文件内容**不会**在启动时加载 — 通过 auto-surfacing 按需注入或显式 `memory read`。
+
+### Topic 文件格式
+
+每个 topic 文件使用四字段 YAML frontmatter：
 
-项目级配置（`.pi/pi-memory.json`）仅在项目受信任时加载。
+```yaml
+---
+name: 调试技巧
+description: 常见调试模式、SSH 端口、MySQL 超时配置
+type: feedback
+updated: 2026-07-13
+---
+
+## SSH 踩坑
+staging 使用 2222 端口，密钥在 ~/.ssh/staging
+
+## MySQL 超时
+staging 上连接超时 30s
+```
+
+`description` 字段至关重要 — auto-surfacing 的 side-query 根据它判断相关性。描述要具体。
+
+### 记忆类型
+
+| 类型 | 含义 | 示例 |
+|------|------|------|
+| `user` | 用户角色、偏好、知识背景 | "用户是数据科学家，关注可观测性" |
+| `feedback` | 教训/纠正/确认（默认） | "用真实 DB 不用 mock—上次踩过坑" |
+| `project` | 项目状态、deadline、incident | "merge freeze 从 3 月 5 日开始" |
+| `reference` | 外部系统指针 | "bug tracker = Linear INGEST project" |
+
+### Auto-surfacing
+
+每次用户发消息时（`before_agent_start` hook）：
+1. 扫描所有 topic 文件，提取 frontmatter 元数据
+2. Side-query LLM 根据用户问题选出最多 `maxFiles` 个相关 topic 文件
+3. 已注入过的 topic 跳过（session 内去重）
+4. 选中文件内容注入 context — agent 自动看到相关记忆
+
+### Extract memories
+
+每次 agent 运行结束后（`agent_end` hook）：
+1. 异步 fork 子 agent，传入本轮对话内容
+2. 分析是否有值得持久化的 learnings
+3. 如有，直接写入 memory 文件 — 偏好、约定、调试心法等
+4. 子 agent 独立运行，结果为未来会话所用
+
+记忆提取有选择性：忽略一次性任务、可从项目推导的代码、已在 CLAUDE.md 中的内容。
 
 ## 工具参考
 
 ```
 memory(action: "add" | "remove" | "search" | "read",
-        content?, topic?, title?,
+        content?, topic?, title?, type?,
         entry?, query?, scope?)
 ```
 
 ### `add`
 
-向主题文件追加条目，并向 MEMORY.md 索引添加新行（不更新已有行——一个主题可以有多个条目）。
+向 topic 文件追加 `## 条目` 区块。若该 topic 已在索引中存在，则更新 MEMORY.md 的 hook 摘要。新建 topic 时在索引中新增一行。
 
 - **`content`**（必填）— 要持久化的知识文本
 - **`topic`**（必填）— 目标文件名，如 `"debugging.md"`，不存在则自动创建
-- **`title`**（必填）— 索引行和条目标题
+- **`title`**（必填）— 描述性、自包含的条目标题。只有 MEMORY.md 索引行被注入未来 prompt（topic 文件内容不会），所以标题必须自成一体地传达信息
+- **`type`**（可选）— 记忆分类：`"user"`、`"feedback"`（默认）、`"project"`、`"reference"`
 
 ### `remove`
 
-按标题精确匹配删除条目。同时删除索引行和主题文件中对应的 `##` 区块。当主题文件中的最后一条被删除后，主题文件会被清理。
+按标题删除条目。遍历所有 topic 文件查找匹配的 `##` 区块。更新受影响 topic 的 MEMORY.md hook。当 topic 文件中最后一条被删除后，topic 文件及其索引行均被清理。
 
 - **`entry`**（必填）— 要删除的条目标题
 
 ### `read`
 
-加载记忆内容。可以是整个主题文件或单个条目区块。
+加载记忆内容。可以是整个 topic 文件或单个条目区块。
 
-- **`topic`**（可选）— 主题名称，如 `"debugging"` 或 `"debugging.md"`。加载整个主题文件
+- **`topic`**（可选）— 主题名称，如 `"debugging"` 或 `"debugging.md"`。加载整个 topic 文件
 - **`entry`**（可选）— 条目标题。返回对应的 `## 条目标题` 区块
 
 ### `search`
@@ -99,13 +186,13 @@ memory(action: "add" | "remove" | "search" | "read",
 查询记忆文件或会话历史。记忆搜索返回匹配条目的完整区块（整个 `##` 区域）。
 
 - **`query`**（必填）— 搜索关键词
-- **`scope`**（可选）— `"memory"`（默认，扫描主题文件）或 `"sessions"`（扫描会话历史）
+- **`scope`**（可选）— `"memory"`（默认，扫描 topic 文件）或 `"sessions"`（扫描会话历史）
 
 ## 命令
 
 ### `/memory`
 
-显示记忆状态（启用/禁用、目录、索引行数、主题文件、上次整理时间戳）。
+显示记忆状态（启用/禁用、目录、索引行数、topic 文件、上次整理时间戳）。
 
 ```
 /memory        — 显示状态
@@ -115,26 +202,31 @@ memory(action: "add" | "remove" | "search" | "read",
 
 ### `/dream`
 
-启动无头代理，读取所有记忆文件，去重、合并矛盾、更新过时信息、重组 `MEMORY.md`。使用的模型可通过 `pi-memory.json` 的 `dream.model` 配置（`"auto"` 使用当前会话模型；`"provider/id"` 指定特定模型）。
+启动无头代理，四阶段整理全部记忆文件：
 
-开始整理前会弹出确认对话框。完成时在通知中显示结果摘要。
+1. **Orient** — 列出文件、读取 MEMORY.md、浏览 topic 文件
+2. **Gather Signal** — 发现重复、矛盾、过时条目
+3. **Consolidate** — 合并重复、解决矛盾、更新日期
+4. **Prune & Index** — 重建 frontmatter、生成 hook、重建 MEMORY.md
 
-整理元数据（时间戳、整理时会话计数）持久化在记忆目录下的 `.dream-meta.json` 中。
+使用的模型通过 `memory.json` 的 `dream.model` 配置。开始前弹出确认对话框，完成时通知摘要。
 
 ## 文件布局
 
 ```
 ~/.pi/memory/
   <12位sha256哈希>/
-    MEMORY.md            — 索引：每个主题文件一行
+    MEMORY.md            — 紧凑索引：每个 topic 文件一行
     .dream-meta.json     — 上次整理的时间戳和会话计数
-    debugging.md         — 用户创建的主题文件
+    debugging.md         — topic 文件（frontmatter + ## 条目）
     preferences.md
     ...
 ```
 
-哈希值由项目的 git 根目录（或绝对路径）派生，确保每个项目拥有独立的记忆命名空间。
+哈希值由项目的 git 根目录（或绝对路径）派生，每个项目拥有独立记忆命名空间。
 
 ## 快照语义
 
-每次 `session_start` 时读取 `MEMORY.md` 索引，通过 `before_agent_start` 追加到系统提示中。如果索引超过 `memIndexMaxLines` 或 `memIndexMaxBytes`，将被截断并添加 `[truncated]` 标记——代理仍能获取到最相关的部分。此快照是会话开始时的静态副本；会话中通过 `memory` 工具所做的变更不会影响当次会话的快照，而是在下次会话中生效。
+每次 `session_start` 读取 `MEMORY.md` 索引，通过 `before_agent_start` 追加到系统提示中。超限则截断并标记 `[truncated]`。此快照是会话开始时的静态副本。
+
+Topic 文件内容通过 **auto-surfacing**（自动、per-turn、基于相关性）或显式 `memory read` 按需加载。

package/index.ts

@@ -1,20 +1,33 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { ensureAgentTypes } from "./src/agent-types";
 import { loadConfig, type MemoryConfig } from "./src/config";
-import { resolveMemoryDir } from "./src/paths";
-import { loadIndexSnapshot, buildInjection } from "./src/inject";
+import { runDream } from "./src/dream";
+import { runExtract } from "./src/extract";
+import {
+	buildInjection,
+	buildSurfacingPrompt,
+	injectSurfacedContent,
+	loadIndexSnapshot,
+	runSideQuery,
+	scanTopics,
+} from "./src/inject";
 import { createMemoryTool } from "./src/memory-tool";
+import { readDreamMeta, shouldNudge, writeDreamMeta } from "./src/nudge";
+import { resolveMemoryDir } from "./src/paths";
 import { searchSessions } from "./src/session-search";
-import { runDream, resolveDreamModel } from "./src/dream";
-import { shouldNudge, writeDreamMeta, readDreamMeta } from "./src/nudge";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { readdir, readFile } from "node:fs/promises";
-import { join } from "node:path";
+
+// Register custom agent type on load (zero setup, auto-fallback on first session).
+ensureAgentTypes();
 
 export default function (pi: ExtensionAPI) {
 	let memoryDir: string | null = null;
 	let config: MemoryConfig | null = null;
 	let indexSnapshot = "";
 	let toolRegistered = false;
+	const injectedTopics = new Set<string>();
 
 	pi.on("session_start", async (_event, ctx) => {
 		config = await loadConfig(ctx);
@@ -27,10 +40,12 @@ export default function (pi: ExtensionAPI) {
 			pi.registerTool(
 				createMemoryTool({
 					getMemoryDir: () => memoryDir,
+					// biome-ignore lint/style/noNonNullAssertion: config assigned in guard above
 					getConfig: () => config!,
 					getEnabled: () => config?.enabled ?? false,
 					searchSessions,
 					cwd: () => ctx.cwd,
+					// biome-ignore lint/suspicious/noExplicitAny: pi registerTool type cast
 				}) as any,
 			);
 			toolRegistered = true;
@@ -38,14 +53,114 @@ export default function (pi: ExtensionAPI) {
 
 		// nudge
 		if (ctx.hasUI) {
-			const { nudge, message } = await shouldNudge(memoryDir, config, ctx.cwd);
-			if (nudge) ctx.ui.notify(message, "info");
+			const { nudge, message, sessions } = await shouldNudge(memoryDir, config, ctx.cwd);
+			if (nudge) {
+				const ok = await ctx.ui.confirm("Memory Consolidation", `${message}\n\nConsolidate memory files now?`);
+				if (ok) {
+					// Fire-and-forget: defers past the current macrotask so all
+					// session_start handlers (including pi-subagents') have completed.
+					// Does not block session_start.
+					const dreamModel = config.dream.model;
+					const dir = memoryDir;
+					ctx.ui.setStatus("dream", "Consolidating memory...");
+					setTimeout(async () => {
+						try {
+							const summary = await runDream({
+								model: dreamModel,
+								memoryDir: dir,
+								events: pi.events,
+							});
+							await writeDreamMeta(dir, sessions);
+							ctx.ui.notify(summary, "info");
+							// biome-ignore lint/suspicious/noExplicitAny: error catch
+						} catch (e: any) {
+							ctx.ui.notify(`Dream failed: ${e.message}`, "error");
+						} finally {
+							ctx.ui.setStatus("dream", undefined);
+						}
+					}, 0);
+				}
+			}
 		}
 	});
 
-	pi.on("before_agent_start", async (event) => {
-		if (!config?.enabled || !indexSnapshot) return;
-		return { systemPrompt: buildInjection(event.systemPrompt, indexSnapshot) };
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!config?.enabled || !indexSnapshot || !memoryDir) return;
+
+		// Auto-surfacing: select relevant topic files via LLM side-query and inject as message.
+		// Skip for subagents: pi-subagents strips "subagent" from all children's
+		// tool sets, so its absence reliably identifies subagents. Without this guard,
+		// runSideQuery's subagent spawn → before_agent_start → re-enter here → OOM.
+		const agentTools = event.systemPromptOptions?.selectedTools;
+		const isSubagent = agentTools && !agentTools.includes("subagent");
+
+		const autoSurfacing = config.autoSurfacing;
+		// biome-ignore lint/suspicious/noExplicitAny: message injection result
+		let injectedMessage: any;
+		if (autoSurfacing?.enabled && event.prompt && !isSubagent) {
+			try {
+				if (ctx.hasUI) ctx.ui.setStatus("surfacing", "Searching relevant memories…");
+				const manifest = await scanTopics(memoryDir);
+				if (manifest.length > 0) {
+					const queryPrompt = buildSurfacingPrompt(manifest, event.prompt.slice(0, 4000), injectedTopics);
+					const selected = await runSideQuery(queryPrompt, manifest, autoSurfacing.maxFiles, pi.events);
+					if (selected.length > 0) {
+						const content = await injectSurfacedContent(
+							memoryDir,
+							selected,
+							autoSurfacing.maxTopicBytes,
+							autoSurfacing.maxInjectionBytes,
+						);
+						if (content) {
+							// Track injected topics for session-level dedup
+							for (const f of selected) injectedTopics.add(f);
+							// Inject as a custom message (NOT systemPrompt)
+							injectedMessage = { customType: "memory-auto-surfacing", content, display: false };
+						}
+					}
+				}
+			} catch {
+				/* silently skip auto-surfacing on error */
+			} finally {
+				if (ctx.hasUI) ctx.ui.setStatus("surfacing", undefined);
+			}
+		}
+
+		// MEMORY.md index injection (always last after auto-surfacing)
+		return {
+			systemPrompt: buildInjection(event.systemPrompt, indexSnapshot),
+			...(injectedMessage ? { message: injectedMessage } : {}),
+		};
+	});
+
+	pi.on("agent_end", async (event) => {
+		if (!config?.enabled || !memoryDir) return;
+		const extractConfig = config.extractMemories;
+		if (!extractConfig?.enabled) return;
+		if (!event.messages || event.messages.length === 0) return;
+		// Fire-and-forget: extract memories in background
+		runExtract({
+			model: extractConfig.model,
+			memoryDir,
+			messages: event.messages.map((m) => ({
+				// biome-ignore lint/suspicious/noExplicitAny: pi event message union type
+				role: String((m as any).role ?? ""),
+				content:
+					// biome-ignore lint/suspicious/noExplicitAny: pi event message union type
+					typeof (m as any).content === "string"
+						? // biome-ignore lint/suspicious/noExplicitAny: pi event message union type
+							(m as any).content
+						: // biome-ignore lint/suspicious/noExplicitAny: pi event message union type
+							typeof (m as any).output === "string"
+							? // biome-ignore lint/suspicious/noExplicitAny: pi event message union type
+								(m as any).output
+							: // biome-ignore lint/suspicious/noExplicitAny: pi event message union type
+								JSON.stringify((m as any).content ?? ""),
+			})),
+			maxContextTokens: extractConfig.maxContextTokens,
+		}).catch(() => {
+			/* silently ignore extract errors */
+		});
 	});
 
 	pi.registerCommand("memory", {
@@ -84,17 +199,18 @@ export default function (pi: ExtensionAPI) {
 			}
 			const ok = await ctx.ui.confirm("Dream", "Consolidate all memory files? This rewrites them in-place.");
 			if (!ok) return;
-			const model = resolveDreamModel(config, ctx);
-			if (!model) {
-				ctx.ui.notify("No model available for dream (check dream.model config / API key).", "error");
-				return;
-			}
 			ctx.ui.setStatus("dream", "Consolidating memory...");
 			try {
-				const summary = await runDream({ model, memoryDir, cwd: memoryDir, signal: ctx.signal });
+				const summary = await runDream({
+					model: config.dream.model,
+					memoryDir,
+					signal: ctx.signal,
+					events: pi.events,
+				});
 				const sessions = (await SessionManager.list(ctx.cwd)).length;
 				await writeDreamMeta(memoryDir, sessions);
 				ctx.ui.notify(summary, "info");
+				// biome-ignore lint/suspicious/noExplicitAny: command handler ctx
 			} catch (e: any) {
 				ctx.ui.notify(`Dream failed: ${e.message}`, "error");
 			} finally {

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "0.3.1",
+	"version": "1.0.1",
 	"description": "File-system driven persistent memory layer for pi coding agent",
 	"license": "MIT",
 	"repository": {
@@ -35,9 +35,10 @@
 		"@earendil-works/pi-ai": ">=0.80.2",
 		"@earendil-works/pi-coding-agent": ">=0.80.2",
 		"@earendil-works/pi-tui": ">=0.80.2",
+		"@yandy0725/pi-subagents": "*",
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"typebox": "^1.1.38"
+		"typebox": "^1.3.3"
 	}
 }