@yandy0725/pi-memory 1.2.1 → 1.3.1

package/README.md

@@ -6,11 +6,11 @@ Aligned with Claude Code's auto memory mechanism: per-topic MEMORY.md index, aut
 
 ## 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)
+- **One `memory` tool**, three actions: `add` (append entry), `remove` (delete entry by title), `search` (query memory or session history)
 - **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.
+- **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 `read` needed — use the built-in `read` tool to inspect memory files. 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
@@ -44,11 +44,16 @@ Create `memory.json` in the agent directory (`~/.pi/agent/memory.json`) or the p
   "memoryDir": "~/.pi/memory",
   "memIndexMaxLines": 200,
   "memIndexMaxBytes": 25600,
+  "defaults": {
+    "model": "deepseek/deepseek-v4-flash",
+    "sessionPersistence": { "enabled": false }
+  },
   "dream": {
     "nudgeAfterSessions": 5,
     "nudgeAfterHours": 24,
     "model": "auto",
-    "thinkLevel": "high"
+    "thinkLevel": "high",
+    "sessionPersistence": { "enabled": false }
   },
   "sessionSearch": {
     "maxSessions": 10,
@@ -60,13 +65,15 @@ Create `memory.json` in the agent directory (`~/.pi/agent/memory.json`) or the p
     "thinkLevel": "off",
     "maxFiles": 5,
     "maxTopicBytes": 4096,
-    "maxInjectionBytes": 20480
+    "maxInjectionBytes": 20480,
+    "sessionPersistence": { "enabled": false }
   },
   "extractMemories": {
     "enabled": true,
     "model": "auto",
     "thinkLevel": "high",
-    "maxContextTokens": 2000
+    "maxContextTokens": 2000,
+    "sessionPersistence": { "enabled": false }
   }
 }
 ```
@@ -77,21 +84,28 @@ Create `memory.json` in the agent directory (`~/.pi/agent/memory.json`) or the p
 | `memoryDir` | `~/.pi/memory` | Root directory for all memory data |
 | `memIndexMaxLines` | `200` | Max lines in `MEMORY.md` before capacity errors |
 | `memIndexMaxBytes` | `25600` | Max bytes in `MEMORY.md` before capacity errors |
+| `defaults.model` | — | Shared model fallback for all sub-tasks. Per-task `model` overrides |
+| `defaults.sessionPersistence.enabled` | `false` | Shared session persistence fallback (default: in-memory). Per-task overrides |
+| `defaults.sessionPersistence.sessionDir` | `memoryDir/sessions/` | Custom session directory for persisted headless agent sessions |
 | `dream.nudgeAfterSessions` | `5` | Sessions since last dream before nudge is shown |
 | `dream.nudgeAfterHours` | `24` | Hours since last dream before nudge is shown |
-| `dream.model` | `"auto"` | Model for dream consolidation (`"auto"` = same as current, or `"provider/id"`) |
+| `dream.model` | — | Model for dream consolidation (`"provider/id"`). Falls back to `defaults.model` → parent model |
 | `dream.thinkLevel` | `"high"` | Thinking effort for dream subagent: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"` |
+| `dream.sessionPersistence.enabled` | `false` | Persist dream agent sessions to disk (debug/audit). Falls back to `defaults.sessionPersistence.enabled` |
+| `dream.sessionPersistence.sessionDir` | `memoryDir/sessions/` | Custom session directory for dream sessions |
 | `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.model` | — | ⭐ Model for side-query relevance selection. Falls back to `defaults.model` → parent model |
 | `autoSurfacing.thinkLevel` | `"off"` | ⭐ Thinking effort for side-query (recommended: `"off"` for lightweight selection) |
+| `autoSurfacing.sessionPersistence.enabled` | `false` | Persist side-query agent sessions to disk. Falls back to `defaults.sessionPersistence.enabled` |
 | `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.model` | — | ⭐ Model for the extraction subagent. Falls back to `defaults.model` → parent model |
 | `extractMemories.thinkLevel` | `"high"` | ⭐ Thinking effort for extraction: `"off"` / `"minimal"` / `"low"` / `"medium"` / `"high"` / `"xhigh"` |
+| `extractMemories.sessionPersistence.enabled` | `false` | Persist extract agent sessions to disk. Falls back to `defaults.sessionPersistence.enabled` |
 | `extractMemories.maxContextTokens` | `2000` | ⭐ Max tokens of conversation to analyze |
 
 Project-level config (`.pi/memory.json`) is only loaded when the project is trusted.
@@ -107,7 +121,7 @@ MEMORY.md is a compact **pointer index** — one line per topic file, not per en
 - [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`.
+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 the built-in `read` tool.
 
 ### Topic file format
 
@@ -150,9 +164,9 @@ On every user message (`before_agent_start` hook):
 ### 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
+1. An async headless subagent is spawned with the conversation transcript
+2. It uses `ls` and `read` to check existing topic files and MEMORY.md, then `memory_add` to persist learnings
+3. If it finds learnings worth persisting, it writes them — 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.
@@ -160,7 +174,7 @@ Memory extraction is selective: it ignores one-time tasks, code snippets derivab
 ## Tool reference
 
 ```
-memory(action: "add" | "remove" | "search" | "read",
+memory(action: "add" | "remove" | "search",
         content?, topic?, title?, type?,
         entry?, query?, scope?)
 ```
@@ -180,13 +194,6 @@ Deletes an entry by title. Searches across all topic files for the matching `##`
 
 - **`entry`** (required) — exact entry title to remove
 
-### `read`
-
-Loads memory content. Either an entire topic file or a single entry block.
-
-- **`topic`** (optional) — topic name, e.g. `"debugging"` or `"debugging.md"`. Loads the entire topic file
-- **`entry`** (optional) — entry title. Returns the specific `## Entry Title` block
-
 ### `search`
 
 Queries either memory files or session history. Memory search returns the full entry block (entire `##` section) for each match.
@@ -237,4 +244,4 @@ The hash is derived from the project's git root (or absolute path), ensuring eac
 
 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`.
+Topic file content is surfaced separately via **auto-surfacing** (automatic, per-turn, relevance-based) or the built-in `read` tool.

package/README.zh.md

@@ -6,12 +6,12 @@
 
 ## 功能
 
-- **一个 `memory` 工具**，四种操作：`add`（追加条目）、`remove`（按标题删除条目）、`read`（加载主题或条目）、`search`（查询记忆或会话历史）
+- **一个 `memory` 工具**，三种操作：`add`（追加条目）、`remove`（按标题删除条目）、`search`（查询记忆或会话历史）
 - **基于主题的文件组织**：每次 `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 — 偏好、约定、调试心法等
+- **Auto-surfacing** ⭐：每次用户发消息时，side-query LLM 自动选出最多 N 个相关 topic 文件并将其内容注入 agent context。无需手动 `read` — 用内置 `read` 工具即可查看记忆文件。Session 内去重防止同一 topic 重复注入
+- **Extract memories** ⭐：每次 agent 运行结束后，异步无头子 agent 分析对话内容，用 `ls`/`read` 检查已有 topic 文件，再用 `memory_add` 写入新记忆 — 偏好、约定、调试心法等
 - **快照注入**：每个新会话启动时，MEMORY.md 索引追加到系统提示中
 - **`/dream` 命令**：四阶段（Orient → Gather → Consolidate → Prune）无头代理整理，去重、合并、重建全部记忆文件
 - **梦醒提醒**：经过 N 个会话或 N 小时后，温和通知建议运行 `/dream`
@@ -44,11 +44,16 @@ pi install npm:@yandy0725/pi-memory
   "memoryDir": "~/.pi/memory",
   "memIndexMaxLines": 200,
   "memIndexMaxBytes": 25600,
+  "defaults": {
+    "model": "deepseek/deepseek-v4-flash",
+    "sessionPersistence": { "enabled": false }
+  },
   "dream": {
     "nudgeAfterSessions": 5,
     "nudgeAfterHours": 24,
     "model": "auto",
-    "thinkLevel": "high"
+    "thinkLevel": "high",
+    "sessionPersistence": { "enabled": false }
   },
   "sessionSearch": {
     "maxSessions": 10,
@@ -60,13 +65,15 @@ pi install npm:@yandy0725/pi-memory
     "thinkLevel": "off",
     "maxFiles": 5,
     "maxTopicBytes": 4096,
-    "maxInjectionBytes": 20480
+    "maxInjectionBytes": 20480,
+    "sessionPersistence": { "enabled": false }
   },
   "extractMemories": {
     "enabled": true,
     "model": "auto",
     "thinkLevel": "high",
-    "maxContextTokens": 2000
+    "maxContextTokens": 2000,
+    "sessionPersistence": { "enabled": false }
   }
 }
 ```
@@ -77,21 +84,28 @@ pi install npm:@yandy0725/pi-memory
 | `memoryDir` | `~/.pi/memory` | 所有记忆数据的根目录 |
 | `memIndexMaxLines` | `200` | `MEMORY.md` 最大行数 |
 | `memIndexMaxBytes` | `25600` | `MEMORY.md` 最大字节数 |
+| `defaults.model` | — | 所有子任务共享的模型回退值。per-task `model` 会覆盖 |
+| `defaults.sessionPersistence.enabled` | `false` | 共享的 session 持久化回退（默认不持久化）。per-task 可覆盖 |
+| `defaults.sessionPersistence.sessionDir` | `memoryDir/sessions/` | 自定义持久化目录 |
 | `dream.nudgeAfterSessions` | `5` | 触发提醒需经过的会话数 |
 | `dream.nudgeAfterHours` | `24` | 触发提醒需经过的小时数 |
-| `dream.model` | `"auto"` | 整理使用的模型（`"auto"` = 当前模型，或 `"provider/id"`） |
+| `dream.model` | — | 整理使用的模型（`"provider/id"`）。回退链：per-task → `defaults.model` → 父模型 |
 | `dream.thinkLevel` | `"high"` | 整理子 agent 的思考深度：`"off"` / `"minimal"` / `"low"` / `"medium"` / `"high"` / `"xhigh"` |
+| `dream.sessionPersistence.enabled` | `false` | 持久化 dream agent 的 session 到磁盘（调试/审计）。回退到 `defaults.sessionPersistence.enabled` |
+| `dream.sessionPersistence.sessionDir` | `memoryDir/sessions/` | dream session 自定义目录 |
 | `sessionSearch.maxSessions` | `10` | 搜索历史时最多扫描的会话数 |
 | `sessionSearch.maxMatches` | `5` | 历史搜索最多返回的匹配数 |
 | `autoSurfacing.enabled` | `true` | ⭐ 启用 per-turn topic 文件自动注入 |
-| `autoSurfacing.model` | `"auto"` | ⭐ side-query 相关性选择模型 |
+| `autoSurfacing.model` | — | ⭐ side-query 相关性选择模型。回退链：per-task → `defaults.model` → 父模型 |
 | `autoSurfacing.thinkLevel` | `"off"` | ⭐ side-query 思考深度（推荐 `"off"`，轻量选择任务） |
+| `autoSurfacing.sessionPersistence.enabled` | `false` | 持久化 side-query agent 的 session。回退到 `defaults.sessionPersistence.enabled` |
 | `autoSurfacing.maxFiles` | `5` | ⭐ 每轮最多注入的 topic 文件数 |
 | `autoSurfacing.maxTopicBytes` | `4096` | ⭐ 单个注入 topic 文件最大字节数（截断） |
 | `autoSurfacing.maxInjectionBytes` | `20480` | ⭐ 每轮注入内容总字节数上限 |
 | `extractMemories.enabled` | `true` | ⭐ 启用 per-turn 记忆自动提取 |
-| `extractMemories.model` | `"auto"` | ⭐ 提取子 agent 使用的模型 |
+| `extractMemories.model` | — | ⭐ 提取子 agent 使用的模型。回退链：per-task → `defaults.model` → 父模型 |
 | `extractMemories.thinkLevel` | `"high"` | ⭐ 提取的思考深度：`"off"` / `"minimal"` / `"low"` / `"medium"` / `"high"` / `"xhigh"` |
+| `extractMemories.sessionPersistence.enabled` | `false` | 持久化 extract agent 的 session。回退到 `defaults.sessionPersistence.enabled` |
 | `extractMemories.maxContextTokens` | `2000` | ⭐ 分析对话的最大 token 数 |
 
 项目级配置（`.pi/memory.json`）仅在项目受信任时加载。
@@ -107,7 +121,7 @@ MEMORY.md 是一个**紧凑指针索引** — 每个 topic 文件一行，而非
 - [API Conventions](api.md) — REST handlers 在 src/api/handlers/；使用标准错误格式
 ```
 
-每次会话只有索引被注入系统提示（前 200 行 / 25KB）。Topic 文件内容**不会**在启动时加载 — 通过 auto-surfacing 按需注入或显式 `memory read`。
+每次会话只有索引被注入系统提示（前 200 行 / 25KB）。Topic 文件内容**不会**在启动时加载 — 通过 auto-surfacing 按需注入或内置 `read` 工具显式加载。
 
 ### Topic 文件格式
 
@@ -160,7 +174,7 @@ staging 上连接超时 30s
 ## 工具参考
 
 ```
-memory(action: "add" | "remove" | "search" | "read",
+memory(action: "add" | "remove" | "search",
         content?, topic?, title?, type?,
         entry?, query?, scope?)
 ```
@@ -180,13 +194,6 @@ memory(action: "add" | "remove" | "search" | "read",
 
 - **`entry`**（必填）— 要删除的条目标题
 
-### `read`
-
-加载记忆内容。可以是整个 topic 文件或单个条目区块。
-
-- **`topic`**（可选）— 主题名称，如 `"debugging"` 或 `"debugging.md"`。加载整个 topic 文件
-- **`entry`**（可选）— 条目标题。返回对应的 `## 条目标题` 区块
-
 ### `search`
 
 查询记忆文件或会话历史。记忆搜索返回匹配条目的完整区块（整个 `##` 区域）。
@@ -235,4 +242,4 @@ memory(action: "add" | "remove" | "search" | "read",
 
 每次 `session_start` 读取 `MEMORY.md` 索引，通过 `before_agent_start` 追加到系统提示中。超限则截断并标记 `[truncated]`。此快照是会话开始时的静态副本。
 
-Topic 文件内容通过 **auto-surfacing**（自动、per-turn、基于相关性）或显式 `memory read` 按需加载。
+Topic 文件内容通过 **auto-surfacing**（自动、per-turn、基于相关性）或内置 `read` 工具按需加载。

package/index.ts

@@ -2,7 +2,7 @@ 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 { loadConfig, type MemoryConfig } from "./src/config";
+import { loadConfig, type MemoryConfig, type SessionPersistenceConfig } from "./src/config";
 import { runDream } from "./src/dream";
 import { runExtract } from "./src/extract";
 import {
@@ -12,11 +12,19 @@ import {
 	runSideQuery,
 	scanTopics,
 } from "./src/inject";
-import { createMemoryTool } from "./src/memory-tool";
+import { createMemoryTool, createMemoryTools } from "./src/memory-tool";
 import { readDreamMeta, shouldNudge, writeDreamMeta } from "./src/nudge";
 import { resolveMemoryDir } from "./src/paths";
 import { searchSessions } from "./src/session-search";
 
+function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "model"): string | undefined;
+function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "sessionPersistence"): SessionPersistenceConfig | undefined;
+function resolveDefault(cfg: MemoryConfig, task: "dream" | "autoSurfacing" | "extractMemories", key: "model" | "sessionPersistence"): string | SessionPersistenceConfig | undefined {
+	const perTask = cfg[task][key];
+	if (perTask !== undefined) return perTask;
+	return cfg.defaults?.[key];
+}
+
 export default function (pi: ExtensionAPI) {
 	let memoryDir: string | null = null;
 	let config: MemoryConfig | null = null;
@@ -54,7 +62,7 @@ export default function (pi: ExtensionAPI) {
 				if (ok) {
 					// Fire-and-forget: does not block session_start. The headless
 					// dream agent runs independently; completion notifies the user.
-					const dreamModel = config.dream.model;
+					const dreamModel = resolveDefault(config, "dream", "model");
 					const dreamThinkLevel = config.dream.thinkLevel;
 					const dir = memoryDir;
 					ctx.ui.setStatus("dream", "Consolidating memory...");
@@ -64,6 +72,7 @@ export default function (pi: ExtensionAPI) {
 						memoryDir: dir,
 						modelRegistry: ctx.modelRegistry,
 						parentModel: ctx.model,
+						sessionPersistence: resolveDefault(config, "dream", "sessionPersistence"),
 					})
 						.then(async (summary) => {
 							await writeDreamMeta(dir, sessions);
@@ -103,10 +112,11 @@ export default function (pi: ExtensionAPI) {
 						injectedTopics,
 						autoSurfacing.maxFiles,
 						autoSurfacing.thinkLevel,
-						autoSurfacing.model,
+						resolveDefault(config, "autoSurfacing", "model"),
 						ctx.modelRegistry,
 						ctx.model,
 						memoryDir,
+						resolveDefault(config, "autoSurfacing", "sessionPersistence"),
 					);
 					if (selected.length > 0) {
 						const content = await injectSurfacedContent(
@@ -141,11 +151,16 @@ export default function (pi: ExtensionAPI) {
 		if (!extractConfig?.enabled) return;
 		if (!event.messages || event.messages.length === 0) return;
 		runExtract({
-			model: extractConfig.model,
+			model: resolveDefault(config, "extractMemories", "model"),
 			thinkLevel: extractConfig.thinkLevel,
 			memoryDir,
 			modelRegistry: ctx.modelRegistry,
 			parentModel: ctx.model,
+			customTools: createMemoryTools(memoryDir, {
+				maxLines: config.memIndexMaxLines,
+				maxBytes: config.memIndexMaxBytes,
+			}),
+			sessionPersistence: resolveDefault(config, "extractMemories", "sessionPersistence"),
 			messages: event.messages.map((m) => ({
 				// biome-ignore lint/suspicious/noExplicitAny: pi event message union type
 				role: String((m as any).role ?? ""),
@@ -206,11 +221,12 @@ export default function (pi: ExtensionAPI) {
 			const dir = memoryDir;
 			ctx.ui.setStatus("dream", "Consolidating memory...");
 			runDream({
-				model: config.dream.model,
+				model: resolveDefault(config, "dream", "model"),
 				thinkLevel: config.dream.thinkLevel,
 				memoryDir,
 				modelRegistry: ctx.modelRegistry,
 				parentModel: ctx.model,
+				sessionPersistence: resolveDefault(config, "dream", "sessionPersistence"),
 			})
 				.then(async (summary) => {
 					const sessions = (await SessionManager.list(ctx.cwd)).length;

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "1.2.1",
+	"version": "1.3.1",
 	"description": "File-system driven persistent memory layer for pi coding agent",
 	"license": "MIT",
 	"repository": {

package/src/agent-config.ts

@@ -1,2 +1,2 @@
-/** Tools available to the headless memory-agent sub-session (file I/O only). */
-export const MEMORY_AGENT_TOOLS = ["read", "write", "edit", "ls"] as const;
+/** Default built-in tools for headless agents (file I/O only, no bash). */
+export const FILE_IO_TOOLS = ["read", "write", "edit", "ls"] as const;

package/src/agent-runner.ts

@@ -1,4 +1,5 @@
 import type { Model } from "@earendil-works/pi-ai";
+import { join } from "node:path";
 import {
 	type AgentSession,
 	type AgentSessionEvent,
@@ -7,9 +8,10 @@ import {
 	getAgentDir,
 	SessionManager,
 	SettingsManager,
+	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { MEMORY_AGENT_TOOLS } from "./agent-config";
-import type { ThinkLevel } from "./config";
+import { FILE_IO_TOOLS } from "./agent-config";
+import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 import { resolveModel } from "./model-resolver";
 
 export interface HeadlessAgentOpts {
@@ -22,13 +24,20 @@ export interface HeadlessAgentOpts {
 	maxTurns?: number;
 	signal?: AbortSignal;
 	timeoutMs?: number;
+	/** Session persistence config. When enabled, sessions are written to disk. */
+	sessionPersistence?: SessionPersistenceConfig;
+	/** Built-in tool name allowlist. Defaults to FILE_IO_TOOLS. Pass [] for no built-in tools. */
+	tools?: string[];
+	/** Custom tool definitions. Defaults to []. */
+	customTools?: ToolDefinition[];
 }
 
 const GRACE_TURNS = 1;
 
 /**
- * Run a headless memory-agent sub-session: create an in-memory, resource-free
- * session, drive the turn loop, collect the assistant response text, and dispose.
+ * Run a headless memory-agent sub-session: create a session (in-memory by default,
+ * persisted to disk when sessionPersistence.enabled is true), drive the turn loop,
+ * collect the assistant response text, and dispose.
  *
  * Does NOT call bindExtensions — no extension hooks fire in the sub-session,
  * so pi-memory's own before_agent_start cannot recurse.
@@ -53,25 +62,32 @@ export async function runHeadlessAgent(opts: HeadlessAgentOpts): Promise<string>
 	});
 	await loader.reload();
 
-	// 3. Forward abort signal BEFORE createAgentSession (handle early abort)
-	let session: AgentSession | undefined;
-	const onAbort = (): void => {
-		void session?.abort();
-	};
-	opts.signal?.addEventListener("abort", onAbort, { once: true });
+	// 3. Create session (in-memory or persisted based on config)
+	const sessionManager = opts.sessionPersistence?.enabled
+		? SessionManager.create(
+				opts.cwd,
+				opts.sessionPersistence.sessionDir ?? join(opts.cwd, "sessions"),
+			)
+		: SessionManager.inMemory(opts.cwd);
 
-	// 4. Create the in-memory session (no bindExtensions)
 	const created = await createAgentSession({
 		cwd: opts.cwd,
-		tools: [...MEMORY_AGENT_TOOLS],
+		tools: opts.tools ?? [...FILE_IO_TOOLS],
+		customTools: opts.customTools ?? [],
 		model: resolvedModel as any,
 		thinkingLevel: opts.thinkLevel as any,
 		modelRegistry: opts.modelRegistry,
-		sessionManager: SessionManager.inMemory(opts.cwd),
+		sessionManager,
 		settingsManager,
 		resourceLoader: loader,
 	});
-	session = created.session as AgentSession;
+
+	// 4. Forward abort signal after session exists (avoid listener leak if creation throws)
+	let session: AgentSession | undefined = created.session as AgentSession;
+	const onAbort = (): void => {
+		void session?.abort();
+	};
+	opts.signal?.addEventListener("abort", onAbort, { once: true });
 
 	// 5. Collect response text + enforce turn limits
 	let text = "";

package/src/config.ts

@@ -5,6 +5,20 @@ import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
 
 export type ThinkLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
+/** Session persistence configuration for headless memory-agent sub-sessions. */
+export interface SessionPersistenceConfig {
+	/** Enable disk persistence (default: false = in-memory). */
+	enabled: boolean;
+	/** Custom session directory. Defaults to memoryDir/sessions/. */
+	sessionDir?: string;
+}
+
+/** Shared defaults that per-task configs inherit. Per-task fields override these. */
+export interface DefaultsConfig {
+	model?: string;
+	sessionPersistence?: SessionPersistenceConfig;
+}
+
 export interface AutoSurfacingConfig {
 	enabled: boolean;
 	model?: string;
@@ -23,13 +37,25 @@ export interface ExtractMemoriesConfig {
 
 export interface MemoryConfig {
 	enabled: boolean;
+	/** Shared defaults for model and sessionPersistence. Per-task configs override. */
+	defaults?: DefaultsConfig;
 	memoryDir: string;
 	memIndexMaxLines: number;
 	memIndexMaxBytes: number;
-	dream: { nudgeAfterSessions: number; nudgeAfterHours: number; model?: string; thinkLevel: ThinkLevel };
+	dream: {
+		nudgeAfterSessions: number;
+		nudgeAfterHours: number;
+		model?: string;
+		thinkLevel: ThinkLevel;
+		sessionPersistence?: SessionPersistenceConfig;
+	};
 	sessionSearch: { maxSessions: number; maxMatches: number };
-	autoSurfacing: AutoSurfacingConfig;
-	extractMemories: ExtractMemoriesConfig;
+	autoSurfacing: AutoSurfacingConfig & {
+		sessionPersistence?: SessionPersistenceConfig;
+	};
+	extractMemories: ExtractMemoriesConfig & {
+		sessionPersistence?: SessionPersistenceConfig;
+	};
 }
 
 export const DEFAULT_CONFIG: MemoryConfig = {

package/src/dream.ts

@@ -1,7 +1,7 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { runHeadlessAgent } from "./agent-runner";
-import type { ThinkLevel } from "./config";
+import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 
 /** Build dream consolidation task. (unchanged) */
 export function buildDreamTask(memoryDir: string, maxLines: number): string {
@@ -56,6 +56,7 @@ export interface RunDreamOpts {
 	memoryDir: string;
 	modelRegistry: ModelRegistry;
 	parentModel?: Model<any>;
+	sessionPersistence?: SessionPersistenceConfig;
 }
 
 /** Run dream consolidation via a headless agent. Fire-and-forget (caller decides await). */
@@ -70,5 +71,6 @@ export async function runDream(opts: RunDreamOpts): Promise<string> {
 		thinkLevel: opts.thinkLevel,
 		maxTurns: undefined,
 		timeoutMs: 600_000,
+		sessionPersistence: opts.sessionPersistence,
 	});
 }

package/src/extract.ts

@@ -1,7 +1,7 @@
 import type { Model } from "@earendil-works/pi-ai";
-import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { ModelRegistry, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { runHeadlessAgent } from "./agent-runner";
-import type { ThinkLevel } from "./config";
+import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 
 export interface RunExtractOpts {
 	model?: string;
@@ -11,9 +11,11 @@ export interface RunExtractOpts {
 	maxContextTokens: number;
 	modelRegistry: ModelRegistry;
 	parentModel?: Model<any>;
+	sessionPersistence?: SessionPersistenceConfig;
+	customTools?: ToolDefinition[];
 }
 
-/** Build extraction task prompt. (unchanged) */
+/** Build extraction task prompt using memory tools instead of raw file I/O. */
 export function buildExtractTask(
 	memoryDir: string,
 	messages: Array<{ role: string; content: string }>,
@@ -29,25 +31,16 @@ export function buildExtractTask(
 	const truncatedAssistant = assistantText.slice(0, maxChars / 2);
 
 	return [
-		`You are a memory extraction agent. Your cwd is the memory directory at ${memoryDir}.`,
+		`You are a memory extraction agent. Your working directory is the memory directory at ${memoryDir}.`,
 		"",
-		"Analyze the conversation snippet below. If you find valuable learnings, write them to topic files in this directory using ONLY file read/write/edit tools. Do NOT use bash, web search, or any other tools.",
-		"The memory directory contains topic files with this frontmatter format:",
+		"Analyze the conversation snippet below. If you find valuable learnings, persist them using the memory tools.",
 		"",
-		"```yaml",
-		"---",
-		"name: Topic Name",
-		"description: Brief summary for relevance matching",
-		"type: feedback  # one of: user, feedback, project, reference",
-		"updated: 2026-07-13",
-		"---",
+		"You have these tools available:",
+		"- 'ls' and 'read': list files and read topic files in the memory directory to check for existing topics",
+		"- memory_search: search across all memory files for relevant existing entries",
+		"- memory_add: persist a new memory entry to a topic file (creates the topic if new)",
 		"",
-		"## Entry Title",
-		"Entry content here.",
-		"```",
-		"",
-		"And MEMORY.md index:",
-		"- [Name](file.md) — one-line hook summary",
+		"Use 'ls' to list files and 'read' to inspect MEMORY.md and topic files. Use memory_search to find related entries. Use memory_add to write new memories. Do NOT use 'bash', 'write', 'edit', or any other tools.",
 		"",
 		"Worth remembering:",
 		"- User preferences, coding style choices, tooling preferences",
@@ -63,12 +56,12 @@ export function buildExtractTask(
 		"- Git history or recent changes",
 		"",
 		"When writing memories:",
+		"- Use 'ls' and 'read' first to check for existing topic files and MEMORY.md index",
+		"- Use memory_search to find overlapping or related memories before adding",
 		"- Use descriptive, self-contained entry titles (only index lines are injected into future sessions)",
-		"- Choose the appropriate type: user, feedback, project, reference",
-		'- Default type is "feedback"',
+		'- Choose the appropriate type: user, feedback, project, reference (default "feedback")',
 		"- Be concise but complete",
 		"- If unsure, do NOT write anything",
-		"- Use the write/edit tools to directly modify topic files and MEMORY.md",
 		"",
 		"=== Conversation ===",
 		`User: ${truncatedUser}`,
@@ -90,6 +83,10 @@ export async function runExtract(opts: RunExtractOpts): Promise<void> {
 		thinkLevel: opts.thinkLevel,
 		maxTurns: 5,
 		timeoutMs: 120_000,
+
+		tools: ["read", "ls"],
+		customTools: opts.customTools ?? [],
+		sessionPersistence: opts.sessionPersistence,
 	}).catch(() => {
 		/* silently ignore extract errors */
 	});

package/src/inject.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { runHeadlessAgent } from "./agent-runner";
-import type { ThinkLevel } from "./config";
+import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 import { truncateForInjection } from "./index-file";
 import { parseFrontmatter } from "./topic-file";
 
@@ -147,6 +147,7 @@ export async function runSideQuery(
 	modelRegistry: ModelRegistry,
 	parentModel: Model<any> | undefined,
 	memoryDir: string,
+	sessionPersistence?: SessionPersistenceConfig,
 ): Promise<string[]> {
 	const candidates = manifest.filter((t) => !injectedTopics.has(t.filename));
 	if (candidates.length === 0) return [];
@@ -162,6 +163,8 @@ export async function runSideQuery(
 			thinkLevel,
 			maxTurns: 1,
 			timeoutMs: 30_000,
+			tools: [],
+			sessionPersistence,
 		});
 		return parseSelectedFiles(result, candidates, maxFiles);
 	} catch {

package/src/memory-tool.ts

@@ -1,7 +1,7 @@
 import { mkdir, readdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { StringEnum } from "@earendil-works/pi-ai";
-import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
+import { withFileMutationQueue, type ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
@@ -21,6 +21,7 @@ import {
 	hasEntries,
 	parseEntries,
 	removeEntrySection,
+	replaceFrontmatterField,
 	updateFrontmatterDate,
 } from "./topic-file";
 
@@ -35,15 +36,6 @@ export interface AddParams {
 export interface RemoveParams {
 	entry: string;
 }
-export interface ReadParams {
-	topic?: string;
-	entry?: string;
-}
-export interface ReadResult {
-	ok: boolean;
-	error?: string;
-	content?: string;
-}
 export interface ActionResult {
 	ok: boolean;
 	error?: string;
@@ -102,18 +94,19 @@ export async function doAdd(memoryDir: string, p: AddParams): Promise<ActionResu
 			const topicContent = appendContent(fm, p.title, p.content);
 			await writeFile(topicPath, topicContent, "utf8");
 		} else {
-			// Existing topic: append entry, then regenerate hook from ALL entry titles
+			// Existing topic: append entry, then regenerate hook + description from ALL entry titles
 			const raw = await readFile(topicPath, "utf8");
 			const refreshed = updateFrontmatterDate(raw, today());
 			const topicContent = appendContent(refreshed, p.title, p.content);
-			await writeFile(topicPath, topicContent, "utf8");
 
-			// Build hook from all entries (comma-separated titles, trimmed to ~150 chars)
+			// Build hook + description from all entries
 			const allEntries = parseEntries(topicContent);
 			const hook = allEntries
 				.map((e) => e.title)
 				.join("; ")
 				.slice(0, 150);
+			const withDesc = replaceFrontmatterField(topicContent, "description", hook);
+
 			next = updateHook(entries, topic, hook);
 			if (!checkCapacity(next, p.maxLines, p.maxBytes)) {
 				return {
@@ -121,6 +114,7 @@ export async function doAdd(memoryDir: string, p: AddParams): Promise<ActionResu
 					error: `MEMORY.md capacity exceeded (max ${p.maxLines} lines / ${p.maxBytes} bytes). Current entries: ${serializeIndex(entries)}`,
 				};
 			}
+			await writeFile(topicPath, withDesc, "utf8");
 		}
 
 		// write index
@@ -165,12 +159,13 @@ export async function doRemove(memoryDir: string, p: RemoveParams): Promise<Acti
 			const afterRemoval = removeEntrySection(raw, p.entry);
 
 			if (hasEntries(afterRemoval)) {
-				// Still has entries: update hook to remaining first entry, refresh date
+				// Still has entries: update hook + description from remaining entries, refresh date
 				const remaining = parseEntries(afterRemoval);
-				const newHook = remaining.length > 0 ? remaining[0].title : "";
+				const newHook = remaining.map((e) => e.title).join("; ").slice(0, 150);
 				const nextEntries = updateHook(entries, topicFile, newHook);
-				const refreshed = updateFrontmatterDate(afterRemoval, today());
-				await writeFile(topicPath, refreshed, "utf8");
+				const withDate = updateFrontmatterDate(afterRemoval, today());
+				const withDesc = replaceFrontmatterField(withDate, "description", newHook);
+				await writeFile(topicPath, withDesc, "utf8");
 				await writeFile(join(memoryDir, MEMORY_MD), `${serializeIndex(nextEntries)}\n`, "utf8");
 			} else {
 				// Last entry removed: delete topic file and remove from index
@@ -188,38 +183,6 @@ export async function doRemove(memoryDir: string, p: RemoveParams): Promise<Acti
 	});
 }
 
-export async function doRead(memoryDir: string, p: ReadParams): Promise<ReadResult> {
-	if (p.topic) {
-		const topicName = p.topic.endsWith(".md") ? p.topic : `${p.topic}.md`;
-		let topicPath: string;
-		try {
-			topicPath = safeTopicPath(memoryDir, topicName);
-			// biome-ignore lint/suspicious/noExplicitAny: error catch
-		} catch (e: any) {
-			return { ok: false, error: e.message };
-		}
-		try {
-			const content = await readFile(topicPath, "utf8");
-			return { ok: true, content };
-		} catch {
-			return { ok: false, error: `Topic "${p.topic}" not found` };
-		}
-	}
-	if (p.entry) {
-		const files = (await readdir(memoryDir).catch(() => [])).filter((f) => f.endsWith(".md") && f !== MEMORY_MD);
-		for (const f of files) {
-			const raw = await readFile(join(memoryDir, f), "utf8").catch(() => "");
-			const entries = parseEntries(raw);
-			const found = entries.find((e) => e.title === p.entry);
-			if (found) {
-				return { ok: true, content: `## ${found.title}\n\n${found.content}` };
-			}
-		}
-		return { ok: false, error: `Entry "${p.entry}" not found in any topic` };
-	}
-	return { ok: false, error: "Either topic or entry must be provided" };
-}
-
 export async function searchMemory(memoryDir: string, query: string): Promise<string> {
 	const files = (await readdir(memoryDir).catch(() => [])).filter((f) => f.endsWith(".md") && f !== MEMORY_MD);
 	const q = query.toLowerCase();
@@ -248,23 +211,94 @@ export interface MemoryToolDeps {
 	cwd: () => string;
 }
 
+export function createMemoryTools(
+	memoryDir: string,
+	cfg: { maxLines: number; maxBytes: number },
+): ToolDefinition[] {
+	return [
+		{
+			name: "memory_add",
+			label: "Memory Add",
+			description:
+				"Add a new memory entry to a topic file. Creates the topic if it doesn't exist. Use memory_search and the 'ls'/'read' tools to check for existing topics first.",
+			parameters: Type.Object({
+				content: Type.String({ description: "Knowledge text to store." }),
+				topic: Type.String({ description: "Target topic filename, e.g. 'debugging.md'." }),
+				title: Type.String({
+					description:
+						"Descriptive, self-contained title. Only index lines are injected into prompts — make titles self-descriptive.",
+				}),
+				type: Type.Optional(
+					StringEnum(["user", "feedback", "project", "reference"] as const),
+				),
+			}),
+			async execute(
+				_id: string,
+				params: any,
+				_signal: AbortSignal | undefined,
+				_onUpdate: any,
+				_ctx: any,
+			) {
+				if (!params.content) throw new Error("content is required");
+				if (!params.topic) throw new Error("topic is required");
+				if (!params.title) throw new Error("title is required");
+				const r = await doAdd(memoryDir, {
+					content: params.content,
+					topic: params.topic,
+					title: params.title,
+					type: params.type,
+					maxLines: cfg.maxLines,
+					maxBytes: cfg.maxBytes,
+				});
+				if (!r.ok) throw new Error(r.error);
+				return {
+					details: {},
+					content: [{
+						type: "text",
+						text: `Added "${params.title}" to ${params.topic}. Index has ${r.entries?.length ?? 0} entries.`,
+					}],
+				};
+			},
+		},
+		{
+			name: "memory_search",
+			label: "Memory Search",
+			description:
+				"Search all memory topic files for entries matching a query. Case-insensitive. Use this to find related memories before adding new ones.",
+			parameters: Type.Object({
+				query: Type.String({ description: "Search query." }),
+			}),
+			async execute(
+				_id: string,
+				params: any,
+				_signal: AbortSignal | undefined,
+				_onUpdate: any,
+				_ctx: any,
+			) {
+				if (!params.query) throw new Error("query is required");
+				const text = await searchMemory(memoryDir, params.query);
+				return { details: {}, content: [{ type: "text", text }] };
+			},
+		},
+	];
+}
+
 export function createMemoryTool(deps: MemoryToolDeps) {
 	return {
 		name: "memory",
 		label: "Memory",
 		description:
-			"Read/write project memory across sessions. action 'add' appends content under a topic (auto-created) as an entry; 'remove' deletes an entry by title; 'read' loads a topic or entry; 'search' queries memory files or history sessions. IMPORTANT: only MEMORY.md index lines are injected into system prompts — entry titles must be self-contained and descriptive (topic file content is NOT injected automatically — it is auto-surfaced for relevant queries).",
+			"Read/write project memory across sessions. action 'add' appends content under a topic (auto-created) as an entry; 'remove' deletes an entry by title; 'search' queries memory files or history sessions. IMPORTANT: only MEMORY.md index lines are injected into system prompts — entry titles must be self-contained and descriptive (topic file content is NOT injected automatically — it is auto-surfaced for relevant queries). Use built-in 'read' and 'ls' tools to read topic files and MEMORY.md.",
 		promptSnippet:
-			"Read/write project memory across sessions (add/remove/search/read). Only index titles are injected — make titles self-descriptive.",
+			"Read/write project memory across sessions (add/remove/search). Only index titles are injected — make titles self-descriptive.",
 		promptGuidelines: [
 			"Use memory to persist project facts, user preferences, and lessons learned across sessions.",
 			"Use memory action 'add' with an explicit topic filename and a descriptive, self-contained entry title — only the index line (title + topic) is injected into future prompts, NOT the topic file content. The title alone must convey what was learned.",
 			"Use memory action 'search' with scope='sessions' to find past work in history sessions.",
-			"Use memory action 'read' with topic or entry to load stored knowledge.",
-			"Auto-surfacing: relevant topic files are automatically selected and their content injected into the conversation context. Use 'read' to load additional topics when needed — you don't need to read what's already been surfaced.",
+			"Auto-surfacing: relevant topic files are automatically selected and their content injected into the conversation context. Use built-in 'read' and 'ls' to load additional topics when needed — you don't need to read what's already been surfaced.",
 		],
 		parameters: Type.Object({
-			action: StringEnum(["add", "remove", "search", "read"] as const),
+			action: StringEnum(["add", "remove", "search"] as const),
 			// add
 			content: Type.Optional(Type.String({ description: "Knowledge text to store (add)." })),
 			topic: Type.Optional(
@@ -342,14 +376,6 @@ export function createMemoryTool(deps: MemoryToolDeps) {
 					}
 					break;
 				}
-				case "read": {
-					if (!params.topic && !params.entry) throw new Error("topic or entry is required for read");
-					const r = await doRead(dir, { topic: params.topic, entry: params.entry });
-					if (!r.ok) throw new Error(r.error);
-					// biome-ignore lint/style/noNonNullAssertion: content assertion
-					text = r.content!;
-					break;
-				}
 				default:
 					throw new Error(`Unknown action: ${params.action}`);
 			}

package/src/topic-file.ts

@@ -45,6 +45,11 @@ export function updateFrontmatterDate(raw: string, date: string): string {
 	return raw.replace(/^(---\n(?:.*\n)*?)updated: .+(\n---)/m, `$1updated: ${date}$2`);
 }
 
+export function replaceFrontmatterField(raw: string, field: string, value: string): string {
+	const regex = new RegExp(`^(---\n(?:.*\n)*?)${field}: .+(\n)`, "m");
+	return raw.replace(regex, (_full: string, prefix: string, nl: string) => `${prefix}${field}: ${value}${nl}`);
+}
+
 export function removeEntrySection(raw: string, title: string): string {
 	const marker = `## ${title}`;
 	// find start of this entry block