@yandy0725/pi-memory 1.3.0 → 1.3.2

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
@@ -121,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
 
@@ -164,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.
@@ -174,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?)
 ```
@@ -194,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.
@@ -251,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`
@@ -121,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 文件格式
 
@@ -174,7 +174,7 @@ staging 上连接超时 30s
 ## 工具参考
 
 ```
-memory(action: "add" | "remove" | "search" | "read",
+memory(action: "add" | "remove" | "search",
         content?, topic?, title?, type?,
         entry?, query?, scope?)
 ```
@@ -194,13 +194,6 @@ memory(action: "add" | "remove" | "search" | "read",
 
 - **`entry`**（必填）— 要删除的条目标题
 
-### `read`
-
-加载记忆内容。可以是整个 topic 文件或单个条目区块。
-
-- **`topic`**（可选）— 主题名称，如 `"debugging"` 或 `"debugging.md"`。加载整个 topic 文件
-- **`entry`**（可选）— 条目标题。返回对应的 `## 条目标题` 区块
-
 ### `search`
 
 查询记忆文件或会话历史。记忆搜索返回匹配条目的完整区块（整个 `##` 区域）。
@@ -249,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

@@ -12,7 +12,7 @@ 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";
@@ -156,6 +156,10 @@ export default function (pi: ExtensionAPI) {
 			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

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "1.3.0",
+	"version": "1.3.2",
 	"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

@@ -8,8 +8,9 @@ import {
 	getAgentDir,
 	SessionManager,
 	SettingsManager,
+	type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
-import { MEMORY_AGENT_TOOLS } from "./agent-config";
+import { FILE_IO_TOOLS } from "./agent-config";
 import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 import { resolveModel } from "./model-resolver";
 
@@ -25,6 +26,10 @@ export interface HeadlessAgentOpts {
 	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;
@@ -67,7 +72,8 @@ export async function runHeadlessAgent(opts: HeadlessAgentOpts): Promise<string>
 
 	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,

package/src/dream.ts

@@ -3,7 +3,7 @@ import type { ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { runHeadlessAgent } from "./agent-runner";
 import type { SessionPersistenceConfig, ThinkLevel } from "./config";
 
-/** Build dream consolidation task. (unchanged) */
+/** Build dream consolidation task. */
 export function buildDreamTask(memoryDir: string, maxLines: number): string {
 	return `You are a memory consolidation agent. Your job is to read all memory files
 and consolidate them into a clean, deduplicated memory store.
@@ -33,6 +33,8 @@ Phase 4 — Prune & Index:
   description: specific summary that helps LLM match queries (be specific!)
   type: one of user, feedback, project, reference
   updated: today's date
+- Ensure entry titles are self-contained and descriptive
+  (only titles appear in future sessions' index, not the entry body)
 - Generate a compact hook (~150 chars) for each topic summarizing its entries
 - Rebuild MEMORY.md with one line per topic file (max ${maxLines} lines):
   - [Name](file.md) — hook
@@ -47,7 +49,13 @@ CRITICAL for hooks and descriptions:
 - Good: "SSH port 2222 on staging; MySQL 30s timeout; Redis auth fix"
 - Each topic file's \`## Entry Title\` blocks contain the actual memory entries.
   The MEMORY.md line is just a pointer — only ONE line per topic file.
-- When done, output a concise summary of changes (merged N, removed N, moved N, updated N).`;
+
+IMPORTANT — Do not prune process rules:
+- "Always do X" / "Never do Y" rules and workflow discipline entries are
+  as valuable as technical facts. Do not delete them as "obsolete"
+  just because they look like meta-instructions.
+
+When done, output a concise summary of changes (merged N, removed N, moved N, updated N).`;
 }
 
 export interface RunDreamOpts {

package/src/extract.ts

@@ -1,5 +1,5 @@
 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 { SessionPersistenceConfig, ThinkLevel } from "./config";
 
@@ -12,9 +12,10 @@ export interface RunExtractOpts {
 	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 }>,
@@ -30,46 +31,42 @@ 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",
-		"---",
+		"## Tools",
+		"- ls — list files in the memory directory",
+		"- read — read MEMORY.md and topic files to check for existing topics",
+		"- memory_search — full-text search across all memory files for related entries",
+		"- memory_add — persist a new memory entry to a topic file (creates the topic if new)",
 		"",
-		"## Entry Title",
-		"Entry content here.",
-		"```",
+		"Do NOT use 'bash', 'write', 'edit', or any other tools.",
 		"",
-		"And MEMORY.md index:",
-		"- [Name](file.md) — one-line hook summary",
+		"## Workflow",
+		"1. Use ls + read to survey existing topic files and MEMORY.md index.",
+		"2. Use memory_search to check for overlapping or related entries.",
+		"3. Use memory_add to write new memories — only if the information is novel and valuable.",
 		"",
-		"Worth remembering:",
-		"- User preferences, coding style choices, tooling preferences",
-		"- Project conventions, architecture decisions, naming patterns",
-		"- Debugging insights, workarounds, gotchas discovered",
-		'- "Always do X" / "Never do Y" rules',
-		"- References to external systems or documentation",
+		"## What to Remember",
+		"- Process rules: \"Always do X\" / \"Never do Y\" directives, workflow discipline, reporting standards, self-check habits — treat these as seriously as technical facts",
+		"- User preferences: coding style, tool choices, naming conventions, workflow habits",
+		"- Project conventions: architecture decisions, file organization, tech stack choices",
+		"- Discoveries: debugging workarounds, gotchas, configuration quirks, undocumented behavior",
+		"- References: external docs, APIs, or systems the user treats as important",
 		"",
-		"NOT worth remembering:",
+		"## What to Skip",
 		"- One-time task instructions or ephemeral details",
 		"- Code snippets or file paths derivable from the project",
-		"- Information already captured in CLAUDE.md or AGENTS.md",
+		"- Information already captured in AGENTS.md",
 		"- Git history or recent changes",
+		"- Obvious or trivial observations",
 		"",
-		"When writing memories:",
-		"- 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"',
-		"- Be concise but complete",
-		"- If unsure, do NOT write anything",
-		"- Use the write/edit tools to directly modify topic files and MEMORY.md",
+		"## Memory Entry Guidelines",
+		"- Entry titles must be self-contained and descriptive (only titles appear in future sessions' index)",
+		'- Choose the appropriate type: user, feedback, project, or reference (default "feedback")',
+		"- Be concise but complete — one clear point per entry",
+		"- When in doubt, skip it",
 		"",
 		"=== Conversation ===",
 		`User: ${truncatedUser}`,
@@ -91,6 +88,9 @@ 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

@@ -60,25 +60,7 @@ export async function scanTopics(memoryDir: string): Promise<TopicManifest[]> {
 	return manifests.sort((a, b) => b.mtimeMs - a.mtimeMs);
 }
 
-function buildSurfacingPrompt(manifest: TopicManifest[], userPrompt: string): string {
-	const lines = manifest.map((t) => {
-		return `[${t.type}] ${t.filename} — ${t.description.slice(0, 80)}`;
-	});
 
-	return [
-		"You are a memory relevance selector. Below is a list of memory topic files and a user message.",
-		"Select up to N topic files that are relevant to the user's current query.",
-		"Response format: JSON with a 'selected_files' array of filenames.",
-		"",
-		"=== Topic Files ===",
-		...lines,
-		"",
-		"=== User Message ===",
-		userPrompt,
-		"",
-		'Return: {"selected_files": ["a.md", "b.md"]}',
-	].join("\n");
-}
 
 export async function injectSurfacedContent(
 	memoryDir: string,
@@ -107,18 +89,27 @@ export async function injectSurfacedContent(
 	return `<relevant_memories>\n${blocks.join("\n\n")}\n</relevant_memories>`;
 }
 
-/** Build the side-query task prompt. Extracted for testability. */
-export function buildSideQueryTask(prompt: string, maxFiles: number): string {
+/** Build the side-query task prompt. */
+export function buildSideQueryTask(
+	manifest: TopicManifest[],
+	userPrompt: string,
+	maxFiles: number,
+): string {
+	const lines = manifest.map((t) =>
+		`[${t.type}] ${t.filename} — ${t.description.slice(0, 80)}`,
+	);
+
 	return [
-		"Respond with ONLY a JSON object.",
+		`You are a memory relevance selector. Select up to ${maxFiles} topic files most relevant to the user query.`,
+		"If nothing matches, select none.",
 		"",
-		"Below is a list of memory topic files and a user query.",
-		`Select up to ${maxFiles} topic files MOST relevant to the user's current query.`,
-		'If nothing is relevant, return {"selected_files": []}.',
+		"=== Topic Files ===",
+		...lines,
 		"",
-		prompt,
+		"=== User Query ===",
+		userPrompt,
 		"",
-		'Respond with EXACTLY: {"selected_files": [...]}',
+		'Respond with ONLY a JSON object: {"selected_files": ["filename.md", ...]}',
 	].join("\n");
 }
 
@@ -151,8 +142,7 @@ export async function runSideQuery(
 ): Promise<string[]> {
 	const candidates = manifest.filter((t) => !injectedTopics.has(t.filename));
 	if (candidates.length === 0) return [];
-	const surfacingPrompt = buildSurfacingPrompt(candidates, userPrompt);
-	const task = buildSideQueryTask(surfacingPrompt, maxFiles);
+	const task = buildSideQueryTask(candidates, userPrompt, maxFiles);
 	try {
 		const result = await runHeadlessAgent({
 			task,
@@ -163,6 +153,7 @@ export async function runSideQuery(
 			thinkLevel,
 			maxTurns: 1,
 			timeoutMs: 30_000,
+			tools: [],
 			sessionPersistence,
 		});
 		return parseSelectedFiles(result, candidates, maxFiles);

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