@yandy0725/pi-memory 0.1.0 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ File-system driven persistent memory layer for pi coding agent. Stores project k
 
 ## Features
 
-- **One `memory` tool**, four actions: `add` (store knowledge), `replace` (edit existing), `remove` (delete), `search` (query memory or session history)
+- **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
@@ -68,38 +68,35 @@ Project-level config (`.pi/pi-memory.json`) is only loaded when the project is t
 ## Tool reference
 
 ```
-memory(action: "add" | "replace" | "remove" | "search",
-        content?, topic?, title?, description?,
-        old_text?, query?, scope?)
+memory(action: "add" | "remove" | "search" | "read",
+        content?, topic?, title?,
+        entry?, query?, scope?)
 ```
 
 ### `add`
 
-Stores content under a topic file and upserts the MEMORY.md index.
+Appends an entry to a topic file and adds a new line to the MEMORY.md index (no upsert — multiple entries per topic).
 
 - **`content`** (required) — knowledge text to persist
 - **`topic`** (required) — target filename, e.g. `"debugging.md"`. Auto-created if new
-- **`title`** (optional) — short title for the index line (defaults to topic stem)
-- **`description`** (optional) — one-line description (defaults to first ~80 chars of content)
+- **`title`** (required) — short title for the index line and entry heading
 
-### `replace`
+### `remove`
 
-Locates `old_text` as a substring and replaces it with `content`.
+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.
 
-- **`old_text`** (required) — substring to find
-- **`content`** (required) — replacement text
-- **`topic`** (optional) — narrow search to a specific file; required when text appears in multiple locations
+- **`entry`** (required) — exact entry title to remove
 
-### `remove`
+### `read`
 
-Locates `old_text` and deletes it. When the last content in a topic file is removed, the file and its index entry are cleaned up.
+Loads memory content. Either an entire topic file or a single entry block.
 
-- **`old_text`** (required) — substring to delete
-- **`topic`** (optional) — narrow search to a specific file
+- **`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.
+Queries either memory files or session history. Memory search returns the full entry block (entire `##` section) for each match.
 
 - **`query`** (required) — search keyword
 - **`scope`** (optional) — `"memory"` (default, scans topic files) or `"sessions"` (scans session history)

package/README.zh.md

@@ -4,7 +4,7 @@
 
 ## 功能
 
-- **一个 `memory` 工具**，四种操作：`add`（存储知识）、`replace`（编辑现有内容）、`remove`（删除）、`search`（查询记忆或会话历史）
+- **一个 `memory` 工具**，四种操作：`add`（追加条目）、`remove`（按标题删除条目）、`read`（加载主题或条目）、`search`（查询记忆或会话历史）
 - **基于主题的文件组织**：每次 `memory add` 都会向项目记忆目录下指定名称的 `.md` 文件写入内容
 - **`MEMORY.md` 索引**：自动生成的目录，带有行数/字节容量限制
 - **快照注入**：每个新会话启动时，记忆索引会追加到系统提示中，让代理始终感知过往工作
@@ -68,38 +68,35 @@ pi install npm:@yandy0725/pi-memory
 ## 工具参考
 
 ```
-memory(action: "add" | "replace" | "remove" | "search",
-        content?, topic?, title?, description?,
-        old_text?, query?, scope?)
+memory(action: "add" | "remove" | "search" | "read",
+        content?, topic?, title?,
+        entry?, query?, scope?)
 ```
 
 ### `add`
 
-将内容存储到主题文件并更新 MEMORY.md 索引。
+向主题文件追加条目，并向 MEMORY.md 索引添加新行（不更新已有行——一个主题可以有多个条目）。
 
 - **`content`**（必填）— 要持久化的知识文本
 - **`topic`**（必填）— 目标文件名，如 `"debugging.md"`，不存在则自动创建
-- **`title`**（可选）— 索引行的短标题（默认取 topic 的文件名部分）
-- **`description`**（可选）— 一行描述（默认取内容前 ~80 字符）
+- **`title`**（必填）— 索引行和条目标题
 
-### `replace`
+### `remove`
 
-定位 `old_text` 子串并替换为 `content`。
+按标题精确匹配删除条目。同时删除索引行和主题文件中对应的 `##` 区块。当主题文件中的最后一条被删除后，主题文件会被清理。
 
-- **`old_text`**（必填）— 要查找的子串
-- **`content`**（必填）— 替换文本
-- **`topic`**（可选）— 限定搜索范围到指定文件；当文本在多个位置出现时必须提供
+- **`entry`**（必填）— 要删除的条目标题
 
-### `remove`
+### `read`
 
-定位 `old_text` 并删除。当主题文件的全部内容被删除后，文件及其索引条目会被自动清理。
+加载记忆内容。可以是整个主题文件或单个条目区块。
 
-- **`old_text`**（必填）— 要删除的子串
-- **`topic`**（可选）— 限定搜索范围到指定文件
+- **`topic`**（可选）— 主题名称，如 `"debugging"` 或 `"debugging.md"`。加载整个主题文件
+- **`entry`**（可选）— 条目标题。返回对应的 `## 条目标题` 区块
 
 ### `search`
 
-查询记忆文件或会话历史。
+查询记忆文件或会话历史。记忆搜索返回匹配条目的完整区块（整个 `##` 区域）。
 
 - **`query`**（必填）— 搜索关键词
 - **`scope`**（可选）— `"memory"`（默认，扫描主题文件）或 `"sessions"`（扫描会话历史）

package/package.json

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

package/src/dream.ts

@@ -11,20 +11,22 @@ import { mkdtemp } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import type { MemoryConfig } from "./config";
 
-export const DREAM_SYSTEM_PROMPT = `You are a memory consolidation agent. Your job: read all memory files in the given directory, deduplicate entries, merge contradictions, update outdated info, and reorganize the MEMORY.md index to be concise and accurate.
+export const DREAM_SYSTEM_PROMPT = `You are a memory consolidation agent. Your job: read all memory files in the given directory, consolidate entries within each topic (merge duplicates, resolve contradictions, update outdated info), and rebuild the MEMORY.md index to be concise and accurate.
 Rules:
+- Each topic file contains entries as \`## Entry Title\` blocks.
 - Only modify files under the given directory. Never touch anything else.
-- Preserve all valuable knowledge; only remove true duplicates or outdated facts.
-- Keep MEMORY.md within the stated line limit; each line: - [Title](file.md) — description.
-- Write specific descriptions so the index alone tells what each file holds.
-- When done, output a concise summary of changes (merged N, removed N, updated N).`;
+- Deduplicate entries: if two entries in the same topic contain the same info, merge them.
+- If entries across different topics overlap, move the content to the more appropriate topic.
+- Rebuild MEMORY.md index: list entries you deem valuable (not necessarily every entry). Each line: - [Entry Title](topic.md). Accuracy matters more than completeness.
+- When done, output a concise summary of changes (merged N, removed N, moved N, updated N).`;
 
 export function buildDreamTask(memoryDir: string, maxLines: number): string {
-	return `Consolidate the memory files under ${memoryDir}. Read every .md file (including MEMORY.md), then:
-1. Deduplicate entries that say the same thing.
+  return `Consolidate the memory files under ${memoryDir}. Read every .md file (including MEMORY.md), then:
+1. Deduplicate entries within each topic that say the same thing.
 2. Merge contradictory or overlapping entries into one accurate entry.
 3. Update outdated information.
-4. Reorganize MEMORY.md so it stays <= ${maxLines} lines, one pointer per topic file: - [Title](file.md) — description.
+4. Move entries to more appropriate topic files when needed.
+5. Rebuild MEMORY.md (max ${maxLines} lines): - [Entry Title](topic.md) per entry you deem valuable (not necessarily every entry). Entries use ## Entry Title format.
 Only edit files under ${memoryDir}. When finished, print a one-line summary of changes.`;
 }
 

package/src/index-file.ts

@@ -1,60 +1,82 @@
 export interface IndexEntry {
-	title: string;
-	topic: string;
-	description: string;
-	raw: string;
+  title: string;
+  topic: string;
+  raw: string;
 }
 export interface IndexFile {
-	entries: IndexEntry[];
-	raw: string;
+  entries: IndexEntry[];
+  raw: string;
 }
 
-// Matches: - [Title](topic.md) — description  (em-dash U+2014 or --)
-const LINE_RE = /^-\s+\[([^\]]+)\]\(([^)]+)\)\s*[—-]{1,2}\s*(.+)$/;
+// Matches: - [Title](topic.md)
+const LINE_RE = /^-\s+\[([^\]]+)\]\(([^)]+)\)\s*$/;
 
 export function parseIndex(content: string): IndexFile {
-	const entries: IndexEntry[] = [];
-	for (const line of content.split("\n")) {
-		const m = line.match(LINE_RE);
-		if (m) entries.push({ title: m[1].trim(), topic: m[2].trim(), description: m[3].trim(), raw: line });
-	}
-	return { entries, raw: content };
+  const entries: IndexEntry[] = [];
+  for (const line of content.split("\n")) {
+    const m = line.match(LINE_RE);
+    if (m) entries.push({ title: m[1].trim(), topic: m[2].trim(), raw: line });
+  }
+  return { entries, raw: content };
 }
 
 export function serializeIndex(entries: IndexEntry[]): string {
-	return entries.map((e) => `- [${e.title}](${e.topic}) — ${e.description}`).join("\n");
-}
-
-export function upsertEntry(entries: IndexEntry[], entry: IndexEntry): IndexEntry[] {
-	const idx = entries.findIndex((e) => e.topic === entry.topic);
-	if (idx === -1) return [...entries, entry];
-	const next = [...entries];
-	next[idx] = { ...entry };
-	return next;
-}
-
-export function truncateForInjection(content: string, maxLines: number, maxBytes: number): { ok: boolean; content: string; truncated: boolean } {
-	const lines = content.split("\n");
-	let out = content;
-	let truncated = false;
-	if (lines.length > maxLines) {
-		out = lines.slice(0, maxLines).join("\n");
-		truncated = true;
-	}
-	if (Buffer.byteLength(out, "utf8") > maxBytes) {
-		// cut by bytes
-		let cut = out;
-		while (Buffer.byteLength(cut, "utf8") > maxBytes && cut.length > 0) cut = cut.slice(0, -1);
-		out = cut;
-		truncated = true;
-	}
-	if (truncated) out += `\n[truncated: memory index exceeds injection limit]`;
-	return { ok: !truncated, content: out, truncated };
-}
-
-export function checkCapacity(entries: IndexEntry[], maxLines: number, maxBytes: number): boolean {
-	const serialized = serializeIndex(entries);
-	if (entries.length > maxLines) return false;
-	if (Buffer.byteLength(serialized, "utf8") > maxBytes) return false;
-	return true;
+  return entries.map((e) => `- [${e.title}](${e.topic})`).join("\n");
+}
+
+export function addEntry(entries: IndexEntry[], entry: IndexEntry): IndexEntry[] {
+  return [...entries, entry];
+}
+
+export function removeEntryByTitle(entries: IndexEntry[], title: string): IndexEntry[] {
+  const idx = entries.findIndex((e) => e.title === title);
+  if (idx === -1) throw new Error(`Entry "${title}" not found in index`);
+  const next = [...entries];
+  next.splice(idx, 1);
+  return next;
+}
+
+export interface MatchResult {
+  entry: IndexEntry | null;
+  unique: boolean;
+}
+
+export function matchEntryByTitle(entries: IndexEntry[], title: string): MatchResult {
+  const matches = entries.filter((e) => e.title === title);
+  if (matches.length === 0) return { entry: null, unique: false };
+  if (matches.length === 1) return { entry: matches[0], unique: true };
+  return { entry: matches[0], unique: false };
+}
+
+export function truncateForInjection(
+  content: string,
+  maxLines: number,
+  maxBytes: number,
+): { ok: boolean; content: string; truncated: boolean } {
+  const lines = content.split("\n");
+  let out = content;
+  let truncated = false;
+  if (lines.length > maxLines) {
+    out = lines.slice(0, maxLines).join("\n");
+    truncated = true;
+  }
+  if (Buffer.byteLength(out, "utf8") > maxBytes) {
+    let cut = out;
+    while (Buffer.byteLength(cut, "utf8") > maxBytes && cut.length > 0) cut = cut.slice(0, -1);
+    out = cut;
+    truncated = true;
+  }
+  if (truncated) out += `\n[truncated: memory index exceeds injection limit]`;
+  return { ok: !truncated, content: out, truncated };
+}
+
+export function checkCapacity(
+  entries: IndexEntry[],
+  maxLines: number,
+  maxBytes: number,
+): boolean {
+  const serialized = serializeIndex(entries);
+  if (entries.length > maxLines) return false;
+  if (Buffer.byteLength(serialized, "utf8") > maxBytes) return false;
+  return true;
 }

package/src/memory-tool.ts

@@ -4,13 +4,14 @@ import { withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Text } from "@earendil-works/pi-tui";
-import { parseIndex, serializeIndex, upsertEntry, checkCapacity, type IndexEntry } from "./index-file";
-import { buildFrontmatter, appendContent, isEmptyAfterRemove } from "./topic-file";
+import { parseIndex, serializeIndex, addEntry, removeEntryByTitle, matchEntryByTitle, checkCapacity, type IndexEntry } from "./index-file";
+import { buildFrontmatter, appendContent, updateFrontmatterDate, removeEntrySection, hasEntries, parseEntries } from "./topic-file";
 import { safeTopicPath } from "./paths";
 
-export interface AddParams { content: string; topic: string; title?: string; description?: string; maxLines: number; maxBytes: number; }
-export interface ReplaceParams { old_text: string; content: string; topic?: string; }
-export interface RemoveParams { old_text: string; topic?: string; }
+export interface AddParams { content: string; topic: string; title: string; maxLines: number; maxBytes: number; }
+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; entries?: IndexEntry[]; }
 
 const MEMORY_MD = "MEMORY.md";
@@ -24,15 +25,12 @@ async function readIndex(memoryDir: string): Promise<IndexEntry[]> {
 	}
 }
 
-function slug(s: string): string {
-	return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "memory";
-}
-
 function today(): string {
 	return new Date().toISOString().slice(0, 10);
 }
 
 export async function doAdd(memoryDir: string, p: AddParams): Promise<ActionResult> {
+	if (!p.title) return { ok: false, error: "title is required" };
 	let topicPath: string;
 	try {
 		topicPath = safeTopicPath(memoryDir, p.topic);
@@ -42,110 +40,114 @@ export async function doAdd(memoryDir: string, p: AddParams): Promise<ActionResu
 	return withFileMutationQueue(join(memoryDir, MEMORY_MD), async () => {
 		await mkdir(dirname(topicPath), { recursive: true });
 		const entries = await readIndex(memoryDir);
-		const title = p.title ?? p.topic.replace(/\.md$/i, "");
-		const description = p.description ?? p.content.split("\n")[0].slice(0, 80);
-		const next = upsertEntry(entries, { title, topic: p.topic, description, raw: "" });
+		const next = addEntry(entries, { title: p.title, topic: p.topic, raw: "" });
 		if (!checkCapacity(next, p.maxLines, p.maxBytes)) {
-			return { ok: false, error: `MEMORY.md capacity exceeded (max ${p.maxLines} lines / ${p.maxBytes} bytes). Current entries: ${serializeIndex(entries)}` };
+			return {
+				ok: false,
+				error: `MEMORY.md capacity exceeded (max ${p.maxLines} lines / ${p.maxBytes} bytes). Current entries: ${serializeIndex(entries)}`,
+			};
 		}
 		// write topic file
 		let existing: string | null = null;
 		try { existing = await readFile(topicPath, "utf8"); } catch { existing = null; }
-		const isNew = !existing;
-		const out = isNew
-			? `${buildFrontmatter({ name: slug(title), description, type: "project", updated: today() })}${appendContent(null, title, p.content)}`
-			: appendContent(existing, title, p.content);
-		await writeFile(topicPath, out, "utf8");
+		if (!existing) {
+			const out = `${buildFrontmatter({ updated: today() })}${appendContent(null, p.title, p.content)}`;
+			await writeFile(topicPath, out, "utf8");
+		} else {
+			const updated = updateFrontmatterDate(existing, today());
+			const out = appendContent(updated, p.title, p.content);
+			await writeFile(topicPath, out, "utf8");
+		}
 		// write index
 		await writeFile(join(memoryDir, MEMORY_MD), serializeIndex(next) + "\n", "utf8");
 		return { ok: true, entries: next };
 	});
 }
 
-interface MatchSite { file: string; type: "index" | "topic"; }
+export async function doRemove(memoryDir: string, p: RemoveParams): Promise<ActionResult> {
+	return withFileMutationQueue(join(memoryDir, MEMORY_MD), async () => {
+		const entries = await readIndex(memoryDir);
+		const match = matchEntryByTitle(entries, p.entry);
+		if (!match.entry) {
+			return { ok: false, error: `Entry "${p.entry}" not found in index` };
+		}
+		if (!match.unique) {
+			const matchingTopics = entries
+				.filter((e) => e.title === p.entry)
+				.map((e) => e.topic)
+				.join(", ");
+			return { ok: false, error: `Multiple matches for entry "${p.entry}" in topics: ${matchingTopics}` };
+		}
+
+		const topicFile = match.entry.topic;
+		const topicPath = safeTopicPath(memoryDir, topicFile);
 
-async function findMatches(memoryDir: string, old_text: string, topic?: string): Promise<MatchSite[]> {
-	const sites: MatchSite[] = [];
-	// index
-	const idxRaw = await readFile(join(memoryDir, MEMORY_MD), "utf8").catch(() => "");
-	if (idxRaw.includes(old_text)) sites.push({ file: MEMORY_MD, type: "index" });
-	// topics
-	const files = topic ? [topic] : (await readdir(memoryDir).catch(() => [])).filter((f) => f.endsWith(".md") && f !== MEMORY_MD);
-	for (const f of files) {
-		const c = await readFile(join(memoryDir, f), "utf8").catch(() => "");
-		if (c.includes(old_text)) sites.push({ file: f, type: "topic" });
-	}
-	return sites;
-}
+		// remove index line
+		const updated = removeEntryByTitle(entries, p.entry);
+		await writeFile(join(memoryDir, MEMORY_MD), serializeIndex(updated) + "\n", "utf8");
+
+		// remove ## block from topic file
+		try {
+			const raw = await readFile(topicPath, "utf8");
+			const afterRemoval = removeEntrySection(raw, p.entry);
+			if (hasEntries(afterRemoval)) {
+				const refreshed = updateFrontmatterDate(afterRemoval, today());
+				await writeFile(topicPath, refreshed, "utf8");
+			} else {
+				await unlink(topicPath).catch(() => {});
+			}
+		} catch (e: any) {
+			// topic file missing — still ok, index already removed
+			if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw e;
+		}
 
-export async function doReplace(memoryDir: string, p: ReplaceParams): Promise<ActionResult> {
-	if (p.topic) {
-		try { safeTopicPath(memoryDir, p.topic); } catch { return { ok: false, error: "Unsafe topic path" }; }
-	}
-	const sites = await findMatches(memoryDir, p.old_text, p.topic);
-	if (sites.length === 0) return { ok: false, error: `No match for old_text` };
-	if (sites.length > 1) return { ok: false, error: `Multiple matches (${sites.length}); specify topic. Sites: ${sites.map((s) => s.file).join(", ")}` };
-	const site = sites[0];
-	const filePath = join(memoryDir, site.file);
-	return withFileMutationQueue(filePath, async () => {
-		const raw = await readFile(filePath, "utf8");
-		const next = raw.replace(p.old_text, p.content);
-		await writeFile(filePath, next, "utf8");
 		return { ok: true };
 	});
 }
 
-export async function doRemove(memoryDir: string, p: RemoveParams): Promise<ActionResult> {
-	// When no topic is specified, search only the index (doRemove semantics:
-	// removing an entry from MEMORY.md). When topic is given, search in
-	// that topic file plus the index.
-	let sites: MatchSite[];
+export async function doRead(memoryDir: string, p: ReadParams): Promise<ReadResult> {
 	if (p.topic) {
-		try { safeTopicPath(memoryDir, p.topic); } catch { return { ok: false, error: "Unsafe topic path" }; }
-		sites = await findMatches(memoryDir, p.old_text, p.topic);
-	} else {
-		const idxRaw = await readFile(join(memoryDir, MEMORY_MD), "utf8").catch(() => "");
-		sites = idxRaw.includes(p.old_text) ? [{ file: MEMORY_MD, type: "index" }] : [];
+		const topicName = p.topic.endsWith(".md") ? p.topic : `${p.topic}.md`;
+		let topicPath: string;
+		try {
+			topicPath = safeTopicPath(memoryDir, topicName);
+		} 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 (sites.length === 0) return { ok: false, error: `No match for old_text` };
-	if (sites.length > 1) return { ok: false, error: `Multiple matches (${sites.length}); specify topic. Sites: ${sites.map((s) => s.file).join(", ")}` };
-	const site = sites[0];
-	const filePath = join(memoryDir, site.file);
-	return withFileMutationQueue(join(memoryDir, MEMORY_MD), async () => {
-		if (site.type === "index") {
-			const raw = await readFile(filePath, "utf8");
-			const lines = raw.split("\n").filter((l) => !l.includes(p.old_text));
-			await writeFile(filePath, lines.join("\n").replace(/\n{3,}/g, "\n\n"), "utf8");
-		} else {
-			const raw = await readFile(filePath, "utf8");
-			const next = raw.replace(p.old_text, "");
-			if (isEmptyAfterRemove(next)) {
-				await unlink(filePath).catch(() => {});
-				// also drop its index line
-				const idxRaw = await readFile(join(memoryDir, MEMORY_MD), "utf8").catch(() => "");
-				if (idxRaw) {
-					const lines = idxRaw.split("\n").filter((l) => !l.includes(`](${site.file})`));
-					await writeFile(join(memoryDir, MEMORY_MD), lines.join("\n"), "utf8");
-				}
-			} else {
-				await writeFile(filePath, next, "utf8");
+	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: true };
-	});
+		return { ok: false, error: `Entry "${p.entry}" not found in any topic` };
+	}
+	return { ok: false, error: "Either topic or entry must be provided" };
 }
 
-// search memory scope — implemented fully in Task 9
 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();
 	const hits: string[] = [];
 	for (const f of files) {
-		const lines = (await readFile(join(memoryDir, f), "utf8").catch(() => "")).split("\n");
-		for (const [i, line] of lines.entries()) {
-			if (line.toLowerCase().includes(q)) {
-				const ctx = lines.slice(Math.max(0, i - 2), i + 3).join("\n");
-				hits.push(`### ${f}\n\`\`\`\n${ctx}\n\`\`\``);
+		const raw = await readFile(join(memoryDir, f), "utf8").catch(() => "");
+		const entryBlocks = parseEntries(raw);
+		for (const entry of entryBlocks) {
+			if (entry.content.toLowerCase().includes(q) || entry.title.toLowerCase().includes(q)) {
+				hits.push(`### ${f}\n\`\`\`\n## ${entry.title}\n${entry.content}\n\`\`\``);
 			}
 		}
 	}
@@ -165,20 +167,23 @@ export function createMemoryTool(deps: MemoryToolDeps) {
 		name: "memory",
 		label: "Memory",
 		description:
-			"Read/write project memory across sessions. action 'add' stores content under a topic file (auto-created) and upserts the MEMORY.md index; 'replace'/'remove' locate by substring (old_text); 'search' queries memory files or history sessions (scope: memory|sessions).",
-		promptSnippet: "Read/write project memory across sessions (add/replace/remove/search).",
+			"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.",
+		promptSnippet: "Read/write project memory across sessions (add/remove/search/read).",
 		promptGuidelines: [
 			"Use memory to persist project facts, user preferences, and lessons learned across sessions.",
-			"Use memory action 'add' with an explicit topic filename when you discover something worth remembering long-term.",
+			"Use memory action 'add' with an explicit topic filename and entry title when you discover something worth remembering long-term.",
 			"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.",
 		],
 		parameters: Type.Object({
-			action: StringEnum(["add", "replace", "remove", "search"] as const),
-			content: Type.Optional(Type.String({ description: "Knowledge text to store (add) or replacement text (replace)" })),
-			topic: Type.Optional(Type.String({ description: "Target topic filename, e.g. 'debugging.md'. Auto-created if new (add)." })),
-			title: Type.Optional(Type.String({ description: "Short title for the MEMORY.md index line (add). Defaults to topic stem." })),
-			description: Type.Optional(Type.String({ description: "One-line description for the MEMORY.md index line (add). Defaults to first line of content truncated ~80 chars." })),
-			old_text: Type.Optional(Type.String({ description: "Substring to locate (replace/remove). Matched against topic files and MEMORY.md index lines." })),
+			action: StringEnum(["add", "remove", "search", "read"] as const),
+			// add
+			content: Type.Optional(Type.String({ description: "Knowledge text to store (add)." })),
+			topic: Type.Optional(Type.String({ description: "Target topic filename, e.g. 'debugging.md'. Auto-created if new (add/read)." })),
+			title: Type.Optional(Type.String({ description: "Short title for the MEMORY.md index line (add). Required for add." })),
+			// remove
+			entry: Type.Optional(Type.String({ description: "Entry title to remove. Exact match on MEMORY.md index line (remove/read)." })),
+			// search
 			query: Type.Optional(Type.String()),
 			scope: Type.Optional(StringEnum(["memory", "sessions"] as const)),
 		}),
@@ -205,24 +210,18 @@ export function createMemoryTool(deps: MemoryToolDeps) {
 				case "add": {
 					if (!params.content) throw new Error("content is required for add");
 					if (!params.topic) throw new Error("topic is required for add");
-					const r = await doAdd(dir, { content: params.content, topic: params.topic, title: params.title, description: params.description, maxLines: cfg.memIndexMaxLines, maxBytes: cfg.memIndexMaxBytes });
+					if (!params.title) throw new Error("title is required for add");
+					const r = await doAdd(dir, { content: params.content, topic: params.topic, title: params.title, maxLines: cfg.memIndexMaxLines, maxBytes: cfg.memIndexMaxBytes });
 					if (!r.ok) throw new Error(r.error);
-					text = `Added to ${params.topic}. Index now has ${r.entries?.length ?? 0} entries.`;
+					text = `Added "${params.title}" to ${params.topic}. Index now has ${r.entries?.length ?? 0} entries.`;
 					details = { entries: r.entries?.length };
 					break;
 				}
-				case "replace": {
-					if (!params.old_text || !params.content) throw new Error("old_text and content are required for replace");
-					const r = await doReplace(dir, { old_text: params.old_text, content: params.content, topic: params.topic });
-					if (!r.ok) throw new Error(r.error);
-					text = "Replaced.";
-					break;
-				}
 				case "remove": {
-					if (!params.old_text) throw new Error("old_text is required for remove");
-					const r = await doRemove(dir, { old_text: params.old_text, topic: params.topic });
+					if (!params.entry) throw new Error("entry is required for remove");
+					const r = await doRemove(dir, { entry: params.entry });
 					if (!r.ok) throw new Error(r.error);
-					text = "Removed.";
+					text = `Removed entry "${params.entry}".`;
 					break;
 				}
 				case "search": {
@@ -234,6 +233,13 @@ 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);
+					text = r.content!;
+					break;
+				}
 				default:
 					throw new Error(`Unknown action: ${params.action}`);
 			}

package/src/topic-file.ts

@@ -1,27 +1,91 @@
 export interface TopicMeta {
-	name: string;
-	description: string;
-	type: string;
-	updated: string;
+  updated: string;
 }
 
 export function buildFrontmatter(meta: TopicMeta): string {
-	return `---
-name: ${meta.name}
-description: ${meta.description}
-type: ${meta.type}
-updated: ${meta.updated}
----
+  return `---\nupdated: ${meta.updated}\n---\n\n`;
+}
+
+export function appendContent(
+  existing: string | null,
+  entryTitle: string,
+  content: string,
+): string {
+  const section = `## ${entryTitle}\n\n${content}`;
+  if (!existing || existing.trim() === "") return section;
+  return `${existing.trimEnd()}\n\n${section}\n`;
+}
+
+export function updateFrontmatterDate(raw: string, date: string): string {
+  return raw.replace(/^(---\n)updated: .+(\n---)/m, `$1updated: ${date}$2`);
+}
+
+export function removeEntrySection(raw: string, title: string): string {
+  const marker = `## ${title}`;
+  // find start of this entry block
+  const startIdx = raw.indexOf(`\n${marker}\n`) !== -1
+    ? raw.indexOf(`\n${marker}\n`)
+    : raw.indexOf(marker);
+  if (startIdx === -1) throw new Error(`Entry "${title}" not found`);
 
-`;
+  // find start of next ## or EOF
+  const afterHeader = raw.indexOf("\n", startIdx + marker.length);
+  const nextH2 = raw.indexOf("\n## ", afterHeader + 1);
+  const endIdx = nextH2 === -1 ? raw.length : nextH2;
+
+  // remove including preceding blank lines
+  let cutStart = startIdx;
+  while (cutStart > 0 && raw[cutStart - 1] === "\n") cutStart--;
+  // also strip one more \n if present (the blank line separator)
+  if (cutStart > 0 && raw[cutStart - 1] === "\n") cutStart--;
+
+  let result = raw.slice(0, cutStart) + raw.slice(endIdx);
+  // ensure exactly one trailing newline
+  result = result.replace(/\n{3,}$/, "\n\n").replace(/\n{2,}$/, "\n");
+  if (!result.endsWith("\n")) result += "\n";
+  return result;
+}
+
+export function hasEntries(raw: string): boolean {
+  return /^## /m.test(raw);
 }
 
-export function appendContent(existing: string | null, heading: string, content: string): string {
-	const section = `## ${heading}\n\n${content}`;
-	if (!existing || existing.trim() === "") return `# ${heading}\n\n${content}`;
-	return `${existing.trimEnd()}\n\n${section}\n`;
+export interface ParsedEntry {
+  title: string;
+  content: string;
 }
 
-export function isEmptyAfterRemove(content: string): boolean {
-	return content.trim() === "";
+export function parseEntries(raw: string): ParsedEntry[] {
+  const entries: ParsedEntry[] = [];
+  const lines = raw.split("\n");
+  let currentTitle = "";
+  let currentContent: string[] = [];
+  let inEntry = false;
+  let inFrontmatter = false;
+
+  for (const line of lines) {
+    if (line === "---") {
+      inFrontmatter = !inFrontmatter;
+      continue;
+    }
+    if (inFrontmatter) continue;
+
+    const h2 = line.match(/^## (.+)$/);
+    if (h2) {
+      if (inEntry) {
+        entries.push({ title: currentTitle, content: currentContent.join("\n").trim() });
+      }
+      currentTitle = h2[1];
+      currentContent = [];
+      inEntry = true;
+      continue;
+    }
+    if (inEntry) {
+      currentContent.push(line);
+    }
+  }
+  if (inEntry) {
+    entries.push({ title: currentTitle, content: currentContent.join("\n").trim() });
+  }
+  return entries;
 }