@dyyz1993/pi-coding-agent 0.74.24 → 0.74.27

package/dist/extensions/auto-memory/prompts.ts

@@ -0,0 +1,202 @@
+export const MEMORY_SYSTEM_PROMPT = (memoryDir: string, memoryContent: string): string => `# auto memory
+
+You have a persistent memory system at \`${memoryDir}\`.
+
+## Types of memory
+- user     — user's role, goals, preferences, knowledge
+- feedback — guidance about how to approach work (both corrections AND confirmations)
+- project  — ongoing work, deadlines, decisions not derivable from code
+- reference — pointers to external systems (dashboards, issue trackers)
+- bookmark — user-bookmarked chat messages with LLM summaries (user-managed, never auto-delete)
+
+## What NOT to save
+- Code patterns, architecture, file paths (derivable from code)
+- Git history (derivable from git)
+- Debug solutions (the fix is in the code)
+- Anything already in CLAUDE.md or system instructions
+
+## How to save
+Step 1 — Write memory file with frontmatter:
+---
+name: {{memory name}}
+description: {{one-line description}}
+type: {{user, feedback, project, reference}}
+---
+{{content with Why: and How to apply: lines for feedback/project types}}
+
+Step 2 — Add pointer in MEMORY.md (one line, ~150 chars):
+- [Title](file.md) — one-line hook
+
+## When to access
+- Read memory files when you need user context or project history
+- Proactively save important information you learn about the user or project
+
+## MEMORY.md
+${memoryContent || "Your memory is currently empty."}`;
+
+export const SELECT_MEMORIES_PROMPT = `你是记忆系统的文件选择器 + 关键词净化器。
+
+## 任务 1：文件选择
+根据用户查询选择相关记忆文件。
+- 只选择确定有用的
+- 最多 5 个
+- 不确定就不选
+
+## 任务 2：关键词净化
+
+### 规则类型
+- exact:    精确匹配（查询整句 === 关键词）
+- prefix:   开头匹配（查询以关键词开头）
+- contains: 包含匹配（查询中包含关键词，易误判，慎用）
+- regex:    正则匹配（复杂模式）
+
+### 规则动作
+- skip:  命中 → 跳过 Prefetch
+- guard: 命中 → 不跳过（拦截 skip，优先级最高）
+
+### 正向净化（添加 skip 规则）
+如果本次 selected 与上次相同 → 用户在延续话题
+→ 提取 skip 规则
+
+### 反向净化（添加 guard 规则 或 删除 skip 规则）
+分析 history 中被跳过的条目（skipped=true）。
+看该条目的 selected 是否合理：
+- 如果被跳过的那条 selected 和它前后的非 skip 条目 selected 不同
+  → 说明那次跳过是误判
+  → 标记为 bad_skip，提供修正建议
+- 如果被跳过的那条 selected 合理
+  → 该关键词可以保留
+
+## 回复格式（JSON only）
+{
+  "selected": ["file1.md"],
+  "purification": {
+    "add_rules": [
+      { "pattern": "继续吧", "mode": "exact", "action": "skip" },
+      { "pattern": "^跑一下.{0,5}$", "mode": "regex", "action": "skip" }
+    ],
+    "remove_rules": [
+      { "pattern": "好的", "mode": "exact" }
+    ],
+    "bad_skips": [
+      {
+        "query": "好的",
+        "matched_rules": ["好的(exact)"],
+        "reason": "'好的'太泛，单独出现也可能是新话题开头",
+        "suggestion": "remove"
+      }
+    ]
+  }
+}
+
+无需净化时不包含 purification 字段。`;
+
+export const EXTRACTION_PROMPT = (
+	manifest: string,
+): string => `You are the memory extraction subagent. Analyze the recent conversation
+and determine what should be persisted to memory.
+
+## Available memory files
+${manifest}
+
+Check this list — update existing rather than creating duplicates.
+
+## Types of memory
+user     — user's role, goals, preferences, knowledge
+feedback — guidance about how to approach work (corrections AND confirmations)
+project  — ongoing work, deadlines, decisions not derivable from code
+reference — pointers to external systems
+
+## What NOT to save
+- Code patterns, architecture, file paths (derivable from code)
+- Git history (derivable from git)
+- Debug solutions (the fix is in the code)
+- Anything obvious from reading the codebase
+
+Respond with JSON only:
+{
+  "actions": [
+    {
+      "op": "create",
+      "filename": "feedback_testing.md",
+      "name": "Testing Policy",
+      "description": "Never mock the database in integration tests",
+      "type": "feedback",
+      "content": "Integration tests must hit a real database...\\n\\n**Why:** ...\\n\\n**How to apply:** ..."
+    },
+    {
+      "op": "update",
+      "filename": "user_role.md",
+      "append": "\\n\\nAlso prefers TypeScript over JavaScript."
+    },
+    { "op": "skip" }
+  ]
+}`;
+
+export const DREAM_PROMPT = (
+	allContent: string,
+	indexContent: string,
+	memoryDir: string,
+): string => `You are performing a dream — a reflective pass over memory files.
+Analyze all memories and determine what to consolidate.
+
+Memory directory: ${memoryDir}
+
+## Phase 1 — Orient
+Understand the current MEMORY.md index and existing topic files.
+
+## Phase 2 — Gather signal
+Check for:
+- Duplicated information across files
+- Contradicted facts (old info vs new)
+- Stale information (outdated deadlines, completed projects)
+- Related topics that should be merged
+
+## Phase 3 — Consolidate
+Decide what to merge, delete, or update.
+
+## ⚠️ Bookmark protection rules (type=bookmark)
+- **NEVER delete** bookmark files — they are user-managed and must be preserved
+- **NEVER merge** bookmark files into other files unless they are duplicates of each other
+- You MAY update/refine the summary content of a bookmark to make it more concise
+- You MAY update tags of a bookmark if they have become stale or incomplete
+- If two bookmarks cover the exact same topic, you may merge them but MUST preserve sourceSession/sourceMessageIds references
+
+## Phase 4 — Prune
+Generate a new MEMORY.md index (≤ 200 lines, ≤ 25KB).
+
+All memories:
+${allContent}
+
+Current MEMORY.md:
+${indexContent}
+
+Respond with JSON only:
+{
+  "merges": [
+    { "sources": ["file1.md", "file2.md"], "target": "merged.md", "content": "..." }
+  ],
+  "deletions": ["stale_file.md"],
+  "updates": [
+    { "filename": "existing.md", "newContent": "..." }
+  ],
+  "newIndex": "- [Title1](file1.md) — desc\\n- [Title2](file2.md) — desc\\n..."
+}`;
+
+export const BOOKMARK_SUMMARY_PROMPT = (
+	messageContent: string,
+	existingManifest: string,
+): string => `You are creating a bookmark summary for chat messages the user has explicitly saved.
+
+## The bookmarked content:
+${messageContent}
+
+${existingManifest ? `## Existing bookmarks (avoid duplicate titles):\n${existingManifest}` : ""}
+
+Generate a structured bookmark document. Respond with JSON only:
+{
+  "title": "Short descriptive title (≤50 chars)",
+  "description": "One-line description of what this covers",
+  "summary": "A well-structured markdown summary (2-5 paragraphs). Extract key insights, decisions, code patterns, or solutions. Preserve important details.",
+  "tags": ["tag1", "tag2", "tag3"]
+}`;

package/dist/extensions/auto-memory/skip-rules.ts

@@ -0,0 +1,297 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface SkipRule {
+	pattern: string;
+	mode: "exact" | "prefix" | "contains" | "regex";
+	action: "skip" | "guard";
+	builtin?: boolean;
+}
+
+export interface HistoryEntry {
+	query: string;
+	selected: string[];
+	skipped: boolean;
+	skip_hits: string[];
+	guard_hits: string[];
+	timestamp: number;
+}
+
+export interface SkipWordStore {
+	version: number;
+	rules: SkipRule[];
+	history: HistoryEntry[];
+	lastPurifyTimestamp: number;
+}
+
+export interface PurificationResult {
+	add_rules?: Array<{ pattern: string; mode: SkipRule["mode"]; action: SkipRule["action"] }>;
+	remove_rules?: Array<{ pattern: string; mode: SkipRule["mode"] }>;
+	bad_skips?: Array<{
+		query: string;
+		matched_rules: string[];
+		reason: string;
+		suggestion: "remove" | "add_guard";
+	}>;
+}
+
+const MAX_HISTORY = 20;
+const MAX_SKIP_RULES = 50;
+const MAX_GUARD_RULES = 30;
+const STORE_FILENAME = ".prefetch-skip-words.json";
+
+export function getGlobalMemoryDir(): string {
+	return join(homedir(), ".pi", "agent", "memory");
+}
+
+export function getDefaultRules(): SkipRule[] {
+	const skipPatterns: Array<{ pattern: string; mode: SkipRule["mode"] }> = [
+		{ pattern: "继续", mode: "exact" },
+		{ pattern: "continue", mode: "exact" },
+		{ pattern: "好的", mode: "exact" },
+		{ pattern: "ok", mode: "exact" },
+		{ pattern: "OK", mode: "exact" },
+		{ pattern: "yes", mode: "exact" },
+		{ pattern: "y", mode: "exact" },
+		{ pattern: "是", mode: "exact" },
+		{ pattern: "对", mode: "exact" },
+		{ pattern: "嗯", mode: "exact" },
+		{ pattern: "继续", mode: "prefix" },
+		{ pattern: "谢谢", mode: "exact" },
+		{ pattern: "感谢", mode: "exact" },
+		{ pattern: "thanks", mode: "exact" },
+		{ pattern: "thx", mode: "exact" },
+		{ pattern: "收到", mode: "exact" },
+		{ pattern: "明白", mode: "exact" },
+		{ pattern: "了解", mode: "exact" },
+		{ pattern: "知道了", mode: "exact" },
+		{ pattern: "行", mode: "exact" },
+		{ pattern: "可以", mode: "exact" },
+		{ pattern: "没问题", mode: "exact" },
+		{ pattern: "不用了", mode: "exact" },
+		{ pattern: "算了", mode: "exact" },
+		{ pattern: "稍等", mode: "exact" },
+		{ pattern: "等一下", mode: "exact" },
+		{ pattern: "好的谢谢", mode: "exact" },
+		{ pattern: "好", mode: "exact" },
+		{ pattern: "done", mode: "exact" },
+		{ pattern: "got it", mode: "exact" },
+		{ pattern: "right", mode: "exact" },
+		{ pattern: "sure", mode: "exact" },
+		{ pattern: "no", mode: "exact" },
+		{ pattern: "nope", mode: "exact" },
+		{ pattern: "嗯嗯", mode: "exact" },
+		{ pattern: "哦", mode: "exact" },
+		{ pattern: "啊", mode: "exact" },
+		{ pattern: "哈哈", mode: "exact" },
+		{ pattern: "懂了", mode: "exact" },
+		{ pattern: "没错", mode: "exact" },
+		{ pattern: "对的", mode: "exact" },
+		{ pattern: "那就这样", mode: "exact" },
+		{ pattern: "可以的", mode: "exact" },
+		{ pattern: "差不多", mode: "exact" },
+		{ pattern: "看起来不错", mode: "exact" },
+		{ pattern: "就这样吧", mode: "exact" },
+	];
+
+	const guardPatterns: Array<{ pattern: string; mode: SkipRule["mode"] }> = [
+		{ pattern: "?", mode: "contains" },
+		{ pattern: "？", mode: "contains" },
+		{ pattern: "怎么", mode: "prefix" },
+		{ pattern: "如何", mode: "prefix" },
+		{ pattern: "为什么", mode: "prefix" },
+		{ pattern: "什么", mode: "prefix" },
+		{ pattern: "哪", mode: "prefix" },
+		{ pattern: "吗", mode: "contains" },
+		{ pattern: "呢", mode: "contains" },
+		{ pattern: "帮", mode: "prefix" },
+		{ pattern: "帮我", mode: "prefix" },
+		{ pattern: "请", mode: "prefix" },
+		{ pattern: "麻烦", mode: "prefix" },
+		{ pattern: "\n", mode: "contains" },
+		{ pattern: "看看", mode: "contains" },
+		{ pattern: "查看", mode: "prefix" },
+		{ pattern: "查一下", mode: "prefix" },
+		{ pattern: "找", mode: "prefix" },
+		{ pattern: "搜", mode: "prefix" },
+		{ pattern: "分析", mode: "prefix" },
+		{ pattern: "解释", mode: "prefix" },
+		{ pattern: "写", mode: "prefix" },
+		{ pattern: "改", mode: "prefix" },
+		{ pattern: "修", mode: "prefix" },
+		{ pattern: "删", mode: "prefix" },
+		{ pattern: "新增", mode: "prefix" },
+		{ pattern: "优化", mode: "prefix" },
+		{ pattern: "重构", mode: "prefix" },
+		{ pattern: "设计", mode: "prefix" },
+		{ pattern: "实现", mode: "prefix" },
+		{ pattern: "创建", mode: "prefix" },
+	];
+
+	return [
+		...skipPatterns.map((p) => ({ ...p, action: "skip" as const, builtin: true })),
+		...guardPatterns.map((p) => ({ ...p, action: "guard" as const, builtin: true })),
+	];
+}
+
+export function matchRule(query: string, rule: SkipRule): boolean {
+	if (!query || !rule.pattern) return false;
+	const q = query.toLowerCase();
+	const p = rule.pattern.toLowerCase();
+
+	switch (rule.mode) {
+		case "exact":
+			return q === p;
+		case "prefix":
+			return q.startsWith(p);
+		case "contains":
+			return q.includes(p);
+		case "regex": {
+			try {
+				const re = new RegExp(rule.pattern);
+				return re.test(query);
+			} catch (err) {
+				console.debug("[auto-memory] regex evaluation failed:", err instanceof Error ? err.message : err);
+				return false;
+			}
+		}
+	}
+}
+
+export function evaluateRules(
+	query: string,
+	rules: SkipRule[],
+): { shouldSkip: boolean; skipHits: string[]; guardHits: string[] } {
+	const skipHits: string[] = [];
+	const guardHits: string[] = [];
+
+	for (const rule of rules) {
+		if (matchRule(query, rule)) {
+			if (rule.action === "skip") {
+				skipHits.push(rule.pattern);
+			} else {
+				guardHits.push(rule.pattern);
+			}
+		}
+	}
+
+	return {
+		shouldSkip: skipHits.length > 0 && guardHits.length === 0,
+		skipHits,
+		guardHits,
+	};
+}
+
+export function getDefaultStore(): SkipWordStore {
+	return {
+		version: 1,
+		rules: getDefaultRules(),
+		history: [],
+		lastPurifyTimestamp: 0,
+	};
+}
+
+export function loadSkipWordStore(dir: string): SkipWordStore {
+	const filePath = join(dir, STORE_FILENAME);
+	if (!existsSync(filePath)) {
+		return getDefaultStore();
+	}
+	try {
+		const raw = readFileSync(filePath, "utf-8");
+		const parsed = JSON.parse(raw) as SkipWordStore;
+		if (parsed.history.length > MAX_HISTORY) {
+			parsed.history = parsed.history.slice(-MAX_HISTORY);
+		}
+		return parsed;
+	} catch (err) {
+		console.debug("[auto-memory] skip word store load failed:", err instanceof Error ? err.message : err);
+		return getDefaultStore();
+	}
+}
+
+export async function saveSkipWordStore(dir: string, store: SkipWordStore): Promise<void> {
+	mkdirSync(dir, { recursive: true });
+	const filePath = join(dir, STORE_FILENAME);
+	const tmpPath = filePath + ".tmp";
+	const data = JSON.stringify(store, null, 2);
+	writeFileSync(tmpPath, data, "utf-8");
+	renameSync(tmpPath, filePath);
+}
+
+export function addHistoryEntry(store: SkipWordStore, entry: HistoryEntry): SkipWordStore {
+	const history = [...store.history, entry];
+	if (history.length > MAX_HISTORY) {
+		history.splice(0, history.length - MAX_HISTORY);
+	}
+	return { ...store, history };
+}
+
+export function applyPurification(store: SkipWordStore, result: PurificationResult): SkipWordStore {
+	const rules = [...store.rules];
+
+	if (result.add_rules) {
+		for (const add of result.add_rules) {
+			const exists = rules.some((r) => r.pattern === add.pattern && r.mode === add.mode && r.action === add.action);
+			if (!exists) {
+				rules.push({ pattern: add.pattern, mode: add.mode, action: add.action, builtin: false });
+			}
+		}
+	}
+
+	if (result.remove_rules) {
+		for (const rem of result.remove_rules) {
+			const idx = rules.findIndex((r) => r.pattern === rem.pattern && r.mode === rem.mode && !r.builtin);
+			if (idx !== -1) {
+				rules.splice(idx, 1);
+			}
+		}
+	}
+
+	if (result.bad_skips) {
+		for (const bad of result.bad_skips) {
+			for (const matchedPattern of bad.matched_rules) {
+				const idx = rules.findIndex((r) => r.pattern === matchedPattern && r.action === "skip" && !r.builtin);
+				if (idx !== -1) {
+					if (bad.suggestion === "remove") {
+						rules.splice(idx, 1);
+					}
+				} else {
+					const builtinRule = rules.find((r) => r.pattern === matchedPattern && r.action === "skip" && r.builtin);
+					if (builtinRule && bad.suggestion === "add_guard") {
+						rules.push({
+							pattern: builtinRule.pattern,
+							mode: builtinRule.mode,
+							action: "guard",
+							builtin: false,
+						});
+					}
+				}
+			}
+		}
+	}
+
+	const nonBuiltinSkips = rules.filter((r) => r.action === "skip" && !r.builtin);
+	if (nonBuiltinSkips.length > MAX_SKIP_RULES) {
+		const toRemove = nonBuiltinSkips.slice(0, nonBuiltinSkips.length - MAX_SKIP_RULES);
+		for (const r of toRemove) {
+			const idx = rules.indexOf(r);
+			if (idx !== -1) rules.splice(idx, 1);
+		}
+	}
+
+	const nonBuiltinGuards = rules.filter((r) => r.action === "guard" && !r.builtin);
+	if (nonBuiltinGuards.length > MAX_GUARD_RULES) {
+		const toRemove = nonBuiltinGuards.slice(0, nonBuiltinGuards.length - MAX_GUARD_RULES);
+		for (const r of toRemove) {
+			const idx = rules.indexOf(r);
+			if (idx !== -1) rules.splice(idx, 1);
+		}
+	}
+
+	return {
+		...store,
+		rules,
+		lastPurifyTimestamp: Date.now(),
+	};
+}

package/dist/extensions/auto-memory/utils.ts

@@ -0,0 +1,208 @@
+import { execSync } from "node:child_process";
+import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, resolve } from "node:path";
+
+export const ENTRYPOINT_NAME = "MEMORY.md";
+export const MAX_ENTRYPOINT_LINES = 200;
+export const MAX_ENTRYPOINT_BYTES = 25_000;
+export const MAX_MEMORY_FILES = 200;
+export const MAX_RELEVANT_MEMORIES = 5;
+export const MAX_MEMORY_BYTES_PER_FILE = 8000;
+export const DREAM_MIN_HOURS = 24;
+export const DREAM_MIN_SESSIONS = 5;
+
+export type MemoryType = "user" | "feedback" | "project" | "reference" | "bookmark";
+
+export interface MemoryHeader {
+	filename: string;
+	filePath: string;
+	mtimeMs: number;
+	description: string | null;
+	type: MemoryType | undefined;
+	sourceSession?: string | null;
+	tags?: string[] | null;
+}
+
+export function getProjectRoot(cwd: string): string {
+	if (!existsSync(join(cwd, ".git"))) {
+		return cwd;
+	}
+	try {
+		const result = execSync("git rev-parse --git-common-dir", {
+			cwd,
+			encoding: "utf-8",
+			stdio: ["pipe", "pipe", "pipe"],
+		}).trim();
+		if (result && isAbsolute(result)) {
+			return realpathSync(resolve(result, ".."));
+		}
+		if (result) {
+			return realpathSync(resolve(cwd, result, ".."));
+		}
+	} catch (err) {
+		console.debug("[auto-memory] git rev-parse failed:", err instanceof Error ? err.message : err);
+	}
+	return cwd;
+}
+
+ function encodeCwd(cwd: string): string {
+	let resolved = cwd;
+	try {
+		resolved = realpathSync(cwd);
+	} catch (err) {
+		console.debug("[auto-memory] realpathSync failed:", err instanceof Error ? err.message : err);
+	}
+	return `--${resolved.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-")}--`;
+}
+
+export function getMemoryDir(cwd: string): string {
+	const agentDir = join(homedir(), ".pi", "agent");
+	return join(agentDir, "memory", encodeCwd(getProjectRoot(cwd)));
+}
+
+export function getEntrypointPath(cwd: string): string {
+	return join(getMemoryDir(cwd), ENTRYPOINT_NAME);
+}
+
+export function getSubagentDir(cwd: string): string {
+	return join(getMemoryDir(cwd), "..", "subagent");
+}
+
+export function isMemoryPath(absolutePath: string, cwd: string): boolean {
+	const memoryDir = normalize(getMemoryDir(cwd));
+	const normalized = normalize(absolutePath);
+	return normalized.startsWith(`${memoryDir}/`) || normalized.startsWith(`${memoryDir}\\`);
+}
+
+export function parseFrontmatter(content: string): { frontmatter: Record<string, string>; body: string } {
+	const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "");
+
+	if (!normalized.startsWith("---")) {
+		return { frontmatter: {}, body: normalized };
+	}
+
+	const endIndex = normalized.indexOf("\n---", 3);
+	if (endIndex === -1) {
+		return { frontmatter: {}, body: normalized };
+	}
+
+	const yamlString = normalized.slice(4, endIndex);
+	const body = normalized.slice(endIndex + 4).trim();
+
+	const frontmatter: Record<string, string> = {};
+	for (const line of yamlString.split("\n")) {
+		const colonIndex = line.indexOf(":");
+		if (colonIndex === -1) continue;
+		const key = line.slice(0, colonIndex).trim();
+		const value = line.slice(colonIndex + 1).trim();
+		if (key) {
+			frontmatter[key] = value;
+		}
+	}
+
+	return { frontmatter, body };
+}
+
+export function isBookmarkType(header: MemoryHeader): boolean {
+	return header.type === "bookmark";
+}
+
+export function buildFrontmatter(fields: { name: string; description: string; type: MemoryType }): string {
+	return `---\nname: ${fields.name}\ndescription: ${fields.description}\ntype: ${fields.type}\n---`;
+}
+
+export interface BookmarkFrontmatterFields {
+	name: string;
+	description: string;
+	sourceSession: string;
+	sourceMessageIds: string[];
+	tags: string[];
+	createdAt: string;
+}
+
+export function buildBookmarkFrontmatter(fields: BookmarkFrontmatterFields): string {
+	const tagsStr = fields.tags.join(", ");
+	return `---\nname: ${fields.name}\ndescription: ${fields.description}\ntype: bookmark\nsourceSession: ${fields.sourceSession}\nsourceMessageIds: ${fields.sourceMessageIds.join(", ")}\ntags: [${tagsStr}]\ncreatedAt: ${fields.createdAt}\n---`;
+}
+
+export function truncateEntrypoint(raw: string): { content: string; wasTruncated: boolean } {
+	if (!raw) {
+		return { content: "", wasTruncated: false };
+	}
+
+	let lines = raw.split("\n");
+	let truncated = false;
+
+	if (lines.length > MAX_ENTRYPOINT_LINES) {
+		lines = lines.slice(0, MAX_ENTRYPOINT_LINES);
+		truncated = true;
+	}
+
+	let content = lines.join("\n");
+
+	if (Buffer.byteLength(content, "utf-8") > MAX_ENTRYPOINT_BYTES) {
+		truncated = true;
+		const bytes = Buffer.from(content, "utf-8");
+		content = bytes.slice(0, MAX_ENTRYPOINT_BYTES).toString("utf-8");
+		const lastNewline = content.lastIndexOf("\n");
+		if (lastNewline !== -1) {
+			content = content.slice(0, lastNewline);
+		}
+	}
+
+	return { content, wasTruncated: truncated };
+}
+
+export async function scanMemoryFiles(memoryDir: string): Promise<MemoryHeader[]> {
+	if (!existsSync(memoryDir)) {
+		return [];
+	}
+
+	const entries = readdirSync(memoryDir);
+	const headers: MemoryHeader[] = [];
+
+	for (const entry of entries) {
+		if (entry.startsWith(".")) continue;
+		if (entry === ENTRYPOINT_NAME) continue;
+		if (!entry.endsWith(".md")) continue;
+
+		const filePath = join(memoryDir, entry);
+		const stat = statSync(filePath);
+		if (!stat.isFile()) continue;
+
+		const content = await readFile(filePath, "utf-8");
+		const { frontmatter } = parseFrontmatter(content);
+
+		headers.push({
+			filename: entry,
+			filePath,
+			mtimeMs: stat.mtimeMs,
+			description: frontmatter.description ?? null,
+			type: frontmatter.type as MemoryType | undefined,
+			sourceSession: frontmatter.sourceSession ?? null,
+			tags: frontmatter.tags
+				? frontmatter.tags
+						.replace(/^\[|\]$/g, "")
+						.split(",")
+						.map((t) => t.trim())
+						.filter(Boolean)
+				: null,
+		});
+	}
+
+	headers.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	return headers;
+}
+
+export function formatManifest(headers: MemoryHeader[]): string {
+	return headers
+		.map((h) => {
+			const parts = [h.filename];
+			if (h.description) parts.push(h.description);
+			if (h.type) parts.push(`[${h.type}]`);
+			return parts.join(" — ");
+		})
+		.join("\n");
+}