@yandy0725/pi-memory 1.4.0 → 2.0.0

package/src/config.ts

@@ -24,7 +24,12 @@ export interface AutoSurfacingConfig {
 	model?: string;
 	thinkLevel: ThinkLevel;
 	maxFiles: number;
-	maxTopicBytes: number;
+	/**
+	 * 单条 entry 注入正文的字节上限。
+	 * v1 叫 `maxTopicBytes`（一个 topic 文件含多个 `##` 条目）；v2 一个 entry 一个文件，故改名。
+	 * **旧键不再生效**（`deepMerge` 会把它挂到对象上，但没有任何代码读它）。
+	 */
+	maxEntryBytes: number;
 	maxInjectionBytes: number;
 }
 
@@ -33,6 +38,10 @@ export interface ExtractMemoriesConfig {
 	model?: string;
 	thinkLevel: ThinkLevel;
 	maxContextTokens: number;
+	/** 渲染进 extract prompt 时，单条 tool_result 的字符上限（spec §11.2）。 */
+	maxToolResultChars: number;
+	/** 渲染进 extract prompt 时，单条 assistant 文本的字符上限（spec §11.2）。 */
+	maxAssistantChars: number;
 }
 
 export interface MemoryConfig {
@@ -44,10 +53,20 @@ export interface MemoryConfig {
 	memIndexMaxLines: number;
 	/** Write capacity: max bytes of serialized MEMORY.md index. */
 	memIndexMaxBytes: number;
-	/** Injection truncation: max lines of MEMORY.md injected into system prompt. */
+	/**
+	 * 注入截断：`memory_index` section 最多带多少**行**索引。
+	 * 与 `memIndexMaxLines` **读写同口径**（D3）：v2 一行 = 一条 entry，注入预算若小于写入
+	 * 上限，写满的记忆就有一部分永远看不见。
+	 */
 	memIndexInjectMaxLines: number;
-	/** Injection truncation: max bytes of MEMORY.md injected into system prompt. */
+	/** 注入截断：`memory_index` section 最多带多少**字节**（与 `memIndexMaxBytes` 同口径，D3）。 */
 	memIndexInjectMaxBytes: number;
+	/**
+	 * 两级锁的参数（spec §5.2）。结构与 `StoreConfig["lock"]` 逐字一致，因此可以原样传给
+	 * `new MemoryStore({ ..., lock: config.lock })`。
+	 * **没有** ttl / 心跳 / 接管字段：跨进程 `.lock` 永远只持毫秒且永不自动回收。
+	 */
+	lock: { timeoutMs: number; snapshotKeep: number };
 	dream: {
 		nudgeAfterSessions: number;
 		nudgeAfterHours: number;
@@ -66,24 +85,30 @@ export interface MemoryConfig {
 
 export const DEFAULT_CONFIG: MemoryConfig = {
 	enabled: true,
+	// headless 子会话默认只在内存里跑：extract / dream / 侧查询都不该往用户的 sessions 目录里落盘。
+	defaults: { sessionPersistence: { enabled: false } },
 	memoryDir: join(homedir(), CONFIG_DIR_NAME, "memory"),
 	memIndexMaxLines: 200,
 	memIndexMaxBytes: 25600,
-	memIndexInjectMaxLines: 20,
-	memIndexInjectMaxBytes: 3072,
+	// 读写同口径（D3）：200 行 = 200 条记忆，写满时注入也看得到全部。
+	memIndexInjectMaxLines: 200,
+	memIndexInjectMaxBytes: 25600,
+	lock: { timeoutMs: 5000, snapshotKeep: 5 },
 	dream: { nudgeAfterSessions: 5, nudgeAfterHours: 24, thinkLevel: "high" },
 	sessionSearch: { maxSessions: 10, maxMatches: 5 },
 	autoSurfacing: {
 		enabled: true,
 		thinkLevel: "off",
 		maxFiles: 3,
-		maxTopicBytes: 3072,
+		maxEntryBytes: 3072,
 		maxInjectionBytes: 10240,
 	},
 	extractMemories: {
 		enabled: true,
 		thinkLevel: "high",
 		maxContextTokens: 2000,
+		maxToolResultChars: 500,
+		maxAssistantChars: 2000,
 	},
 };
 

package/src/dream.ts

@@ -1,84 +1,126 @@
+import { readdir } from "node:fs/promises";
+import { join } from "node:path";
 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";
+import { BACKUP_DIR, type MemoryStore } from "./memory-store";
+import { createSnapshot } from "./snapshot";
 
-/** 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.
+/** Build the dream consolidation task. dream 只有 `memory` 工具的 7 个 action，没有任何文件工具。 */
+export function buildDreamTask(maxLines: number): string {
+	return `You are a memory consolidation agent. The memory store is a flat directory: one memory per file, and MEMORY.md holds exactly one index line per memory, formatted as - [name](file.md) — description.
+
+Your ONLY tool is \`memory\`. You have no read, write, edit, ls or bash access — you cannot touch files directly, and you do not need to.
+
+memory(action="list") — every memory: name, type, modified, description, file.
+memory(action="search", query="…") — full-text search; returns the whole body of each match.
+memory(action="add", name, description, type, content) — create a memory, or overwrite the one whose name matches exactly.
+memory(action="replace", name, description, type, content) — rewrite an existing memory.
+memory(action="rename", name, new_name) — retitle a memory; its file name and index line follow.
+memory(action="remove", name) — delete a memory and its index line.
+memory(action="rebuild_index") — regenerate MEMORY.md from the directory.
 
 Phase 1 — Orient:
-- List all files in ${memoryDir}
-- Read MEMORY.md to understand current index
-- Skim each topic file to understand its contents
+- Call list to see every memory.
+- Call search (and list) to read the bodies of the memories you intend to touch. Never rewrite a memory you have not read.
 
 Phase 2 — Gather Signal:
-- Find duplicate entries within and across topic files
-- Identify contradictory information
-- Spot outdated or obsolete entries
-- Note temporal references that should be absolute dates
+- Duplicates: several memories stating the same fact.
+- Contradictions: two memories that cannot both be true. Pick the accurate one.
+- Outdated: memories superseded by later ones, or relative dates ("today", "last week") that should be absolute.
+- Merge candidates: small fragments that only make sense together.
+- Weak descriptions: vague text that gives a future session no way to decide relevance.
 
 Phase 3 — Consolidate:
-- Merge duplicates into single entries
-- Resolve contradictions — pick the most accurate version
-- Convert relative dates (today, last week) to absolute dates
-- Update outdated information
-- Move entries to more appropriate topic files when needed
-- Delete entries that are no longer relevant
+- Merge = replace(target name, the merged body) + remove(the other name). Keep the surviving name readable.
+- Retitle with rename when the name no longer matches the content, or when two names are confusable.
+- Rewrite any description that is not self-contained. It is the ONLY text a future session sees when deciding whether to recall this memory, so it must state what, where and which value.
+  Bad:  "Debugging tips"
+  Good: "staging SSH listens on 2222, not 22; MySQL pool times out after 30s"
+- Remove memories that are no longer true or no longer useful.
 
 Phase 4 — Prune & Index:
-- For each topic file, update frontmatter:
-  name: meaningful name for the topic
-  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
-- Remove topic files that have no remaining entries
+- Every memory consumes exactly one index line, and the index has a hard limit of ${maxLines} lines. Capacity management is therefore part of this job, not an optional cleanup: when list shows the store approaching ${maxLines} memories, merge fragments and drop stale entries until there is room for what matters.
+- When a write reports that MEMORY.md is over its limit, act on it in this same run.
+- Call rebuild_index once at the end if you suspect MEMORY.md drifted (missing lines, duplicates, stale links). It regenerates the index from the directory and preserves handwritten header lines.
 
-CRITICAL for hooks and descriptions:
-- Only the MEMORY.md index is injected into future coding sessions.
-  Topic file content is NOT seen by the coding agent unless explicitly
-  read or auto-surfaced. The hook and description must be specific
-  enough that the LLM can correctly decide relevance.
-- Bad: "Debugging tips"
-- 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.
+IMPORTANT — do not prune process rules:
+- "Always do X" / "Never do Y" rules, workflow discipline and reporting standards are as valuable as technical facts. Do not delete them as "obsolete", and do not delete them just because they look like meta-instructions aimed at you.
 
-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).`;
+Work only through the \`memory\` tool. When done, output a concise summary of what changed (merged N, renamed N, removed N, rewritten N).`;
 }
 
 export interface RunDreamOpts {
 	model?: string;
 	thinkLevel: ThinkLevel;
 	memoryDir: string;
+	/** 唯一写入通道。dream 的整轮互斥与快照都挂在它上面。 */
+	store: MemoryStore;
+	/** 索引行数硬上限（= `config.memIndexMaxLines`），写进 prompt 让 dream 承担容量管理。 */
+	maxLines: number;
 	modelRegistry: ModelRegistry;
 	parentModel?: Model<any>;
 	sessionPersistence?: SessionPersistenceConfig;
+	/** dream 专属的 7-action `memory` 工具（D12）：只注入这个 headless session，不进主 agent 的 schema。 */
+	customTools: ToolDefinition[];
 }
 
-/** Run dream consolidation via a headless agent. Fire-and-forget (caller decides await). */
+/**
+ * 要被快照的普通文件：目录里的**文件**，跳过一切 dotfile 与子目录。
+ *
+ * - `.backups`（目录）跳过 —— 快照不套快照；不带 `withFileTypes` 时它会被 `cp` 递归复制。
+ * - `sessions/`（目录，`sessionPersistence.enabled` 时存在）跳过 —— 同理，而且它可能很大。
+ *   `createSnapshot` 的 `cp` 遇到目录会抛 `ERR_FS_EISDIR`（非 ENOENT → fail-closed 上抛 → dream 直接失败）。
+ * - `.lock` / `.migrated` / `.dream-meta.json` 跳过（都是 dotfile）：锁记录与标记不属于记忆内容。
+ * - 其余全部 `*.md`（entry 文件 + `MEMORY.md`）都会被快照。
+ */
+async function snapshotFiles(memoryDir: string): Promise<string[]> {
+	const entries = await readdir(memoryDir, { withFileTypes: true }).catch(() => []);
+	return entries
+		.filter((entry) => entry.isFile() && !entry.name.startsWith("."))
+		.map((entry) => entry.name)
+		.sort();
+}
+
+/**
+ * 跑一轮 dream：整轮持有进程内逻辑锁 → 对整目录拍一次快照 → 起一个只有 `memory` 工具的
+ * headless agent（spec §5.2 / §6 / §12）。
+ *
+ * 整轮持锁是刻意的：dream 的多次 `replace` / `remove` 必须对同进程的 `memory add` 与 extract
+ * 呈现为**一个**原子区间，否则用户会在 dream 中途读到半合并的状态。锁在进程内（不是 `.lock`），
+ * 所以跨进程的其它 worktree 仍能正常写入 —— 它们的每次物理写入只被挡毫秒级。
+ *
+ * 其内部的每个原语调用必须传 `{ skipLogicalLock: true, skipSnapshot: true }`（由调用方构造
+ * `customTools` 时设置），否则它们会去抢自己已持有的锁而自锁到超时，并且会为同一批变更各拍一次快照。
+ */
 export async function runDream(opts: RunDreamOpts): Promise<string> {
-	const task = buildDreamTask(opts.memoryDir, 200);
-	return runHeadlessAgent({
-		task,
-		cwd: opts.memoryDir,
-		modelRegistry: opts.modelRegistry,
-		model: opts.model,
-		parentModel: opts.parentModel,
-		thinkLevel: opts.thinkLevel,
-		maxTurns: undefined,
-		timeoutMs: 600_000,
-		sessionPersistence: opts.sessionPersistence,
+	return opts.store.withLogicalLock(async () => {
+		// 启动自检：忘了包 withLogicalLock 会静默失去整轮互斥（spec §5.2 末段）。
+		if (!opts.store.logicalLockActive()) {
+			throw new Error("dream must run under the memory logical lock");
+		}
+
+		// 进入时对整目录拍一次快照；这一轮里各原语的逐文件快照被 skipSnapshot 跳过（spec §6）。
+		const files = await snapshotFiles(opts.memoryDir);
+		await createSnapshot(join(opts.memoryDir, BACKUP_DIR), "dream", files, opts.memoryDir, {
+			keep: opts.store.cfg.lock.snapshotKeep,
+		});
+
+		return runHeadlessAgent({
+			task: buildDreamTask(opts.maxLines),
+			cwd: opts.memoryDir,
+			modelRegistry: opts.modelRegistry,
+			model: opts.model,
+			parentModel: opts.parentModel,
+			thinkLevel: opts.thinkLevel,
+			maxTurns: undefined,
+			timeoutMs: 600_000,
+			// 没有裸写权限（spec §12.1）：dream 的重构能力边界由 7 个原语定义，因此首次可被单测覆盖。
+			// 必须用 noTools 而不是 tools: [] —— 后者是白名单，会把 customTools（memory 工具）一起滤掉。
+			noTools: "builtin",
+			customTools: opts.customTools,
+			sessionPersistence: opts.sessionPersistence,
+		});
 	});
 }

package/src/entry-file.ts

@@ -0,0 +1,81 @@
+export const ENTRY_TYPES = ["user", "feedback", "project", "reference"] as const;
+export type EntryType = (typeof ENTRY_TYPES)[number];
+
+export interface EntryMeta {
+	name: string;
+	description: string;
+	type: EntryType;
+	/** YYYY-MM-DD */
+	created: string;
+	/** ISO 8601 时间戳 */
+	modified: string;
+}
+
+export interface ParsedEntryFile {
+	meta: EntryMeta;
+	body: string;
+}
+
+const FIELD_RE = /^([A-Za-z_][A-Za-z0-9_]*):[ \t]*(.*)$/;
+const MD_MARKER_RE = /^\s*(#{1,6}\s+|[-*+]\s+|\d+[.)]\s+)/;
+const SENTENCE_END_RE = /[。！？!?.]/;
+
+const DESCRIPTION_MAX = 200;
+
+export function isEntryType(value: string): value is EntryType {
+	return (ENTRY_TYPES as readonly string[]).includes(value);
+}
+
+/** 序列化为「frontmatter + 空行 + 正文」的 markdown。 */
+export function serializeEntryFile(meta: EntryMeta, body: string): string {
+	const header = [
+		"---",
+		`name: ${meta.name}`,
+		`description: ${meta.description}`,
+		`type: ${meta.type}`,
+		`created: ${meta.created}`,
+		`modified: ${meta.modified}`,
+		"---",
+	].join("\n");
+	const trimmed = body.trim();
+	return trimmed.length === 0 ? `${header}\n` : `${header}\n\n${trimmed}\n`;
+}
+
+/** 解析 entry 文件。frontmatter 缺失或字段不全时返回 null。 */
+export function parseEntryFile(raw: string): ParsedEntryFile | null {
+	// CRLF 会让整份文件解析不出来（首行分隔匹配不上、字段行的值也匹配不到 \r），
+	// 该 entry 就会从清单、搜索、remove/replace 定位里一起消失 —— 静默丢记忆。
+	// 归一只在解析入口做一次，serializeEntryFile 仍然只输出 \n。
+	const text = raw.includes("\r") ? raw.replace(/\r\n?/g, "\n") : raw;
+	if (!text.startsWith("---\n")) return null;
+	const end = text.indexOf("\n---", 4);
+	if (end === -1) return null;
+
+	const fields: Record<string, string> = {};
+	for (const line of text.slice(4, end).split("\n")) {
+		const m = line.match(FIELD_RE);
+		if (m) fields[m[1]] = m[2].trim();
+	}
+
+	const name = fields.name ?? "";
+	const description = fields.description ?? "";
+	const type = fields.type ?? "";
+	const created = fields.created ?? "";
+	const modified = fields.modified ?? "";
+	// description 必须「存在」但允许为空。deriveDescription 对「首行只有 markdown 标记」的正文会返回 ""，
+	// 若把空值当成缺字段，写出的文件将永远解析不了（对 store 静默不可见）。
+	if (!name || !created || !modified || !isEntryType(type) || !("description" in fields)) return null;
+
+	const bodyStart = text.indexOf("\n", end + 1);
+	const body = bodyStart === -1 ? "" : text.slice(bodyStart + 1).trim();
+	return { meta: { name, description, type, created, modified }, body };
+}
+
+/** 从正文派生一行摘要：取首个非空行的首句，剥掉 markdown 标记。 */
+export function deriveDescription(body: string, max = DESCRIPTION_MAX): string {
+	const firstLine = body.split("\n").find((line) => line.trim().length > 0) ?? "";
+	const cleaned = firstLine.replace(MD_MARKER_RE, "").trim();
+	const stop = cleaned.search(SENTENCE_END_RE);
+	const sentence = (stop === -1 ? cleaned : cleaned.slice(0, stop + 1)).trim();
+	return sentence.length <= max ? sentence : `${sentence.slice(0, max - 1)}…`;
+}

package/src/entry-index.ts

@@ -0,0 +1,112 @@
+// name 与 file 两组都必须是**非贪婪**的：(1) file 可能含 `)`（entryFileName 不剥括号）；
+// (2) name 可能含 `]`。贪婪组会把分割点吃掉，[^\]]+ / [^)]+ 则表示这两种行根本匹配不上。
+const LINE_RE = /^-\s+\[(.+?)\]\((.+?)\)\s*—\s*(.*)$/;
+
+export interface IndexLineEntry {
+	name: string;
+	file: string;
+	description: string;
+	lineNo: number;
+}
+
+export interface ParsedEntryIndex {
+	lines: string[];
+	entries: IndexLineEntry[];
+	/** 非空但无法识别的行数（标题、分组、注释等）。 */
+	unrecognized: number;
+}
+
+/**
+ * 索引唯一的按行拆分入口（解析与写入必须共用它，否则同一个 `lineNo` 在两处含义不同）。
+ *
+ * CRLF（以及老 Mac 的单独 CR）必须在这里归一：JS 的 `.` 不匹配 `\r`，且无 `m` 标志的 `$`
+ * 也无法在一个 `\r` 之前成立 —— `LINE_RE` 对 CRLF 行会**完全匹配不上**，于是每一行都被计成
+ * `unrecognized`：删除变成空操作（留下死链）、追加变成重复行、`rebuildIndex` 把整块当成手写头部。
+ * 归一之后写回仍只输出 `\n`（`joinLines`），因此对 CRLF 文件的首次写入会把它转成 LF ——
+ * 这是有意的，它消除的是「混合行尾」这个更糟的中间态。
+ */
+function splitLines(raw: string): string[] {
+	const text = raw.includes("\r") ? raw.replace(/\r\n?/g, "\n") : raw;
+	if (text.length === 0) return [];
+	const lines = text.split("\n");
+	if (lines[lines.length - 1] === "") lines.pop();
+	return lines;
+}
+
+function joinLines(lines: string[]): string {
+	return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+
+export function parseEntryIndex(raw: string): ParsedEntryIndex {
+	const lines = splitLines(raw);
+	const entries: IndexLineEntry[] = [];
+	let unrecognized = 0;
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line.trim().length === 0) continue;
+		const m = line.match(LINE_RE);
+		if (m) entries.push({ name: m[1].trim(), file: m[2].trim(), description: m[3].trim(), lineNo: i });
+		else unrecognized++;
+	}
+	return { lines, entries, unrecognized };
+}
+
+export function formatIndexLine(name: string, file: string, description: string): string {
+	return `- [${name}](${file}) — ${description}`;
+}
+
+/**
+ * 外科式写入：只改目标行，其余行（标题、分组、注释、空行）逐字保留。
+ * 新增时插到最后一条已识别行之后；`atLineNo` 用于改名时保持行位置。
+ */
+export function upsertIndexLine(
+	raw: string,
+	entry: { name: string; file: string; description: string },
+	options?: { atLineNo?: number },
+): string {
+	const parsed = parseEntryIndex(raw);
+	const line = formatIndexLine(entry.name, entry.file, entry.description);
+	const lines = splitLines(raw);
+
+	if (options?.atLineNo !== undefined) {
+		lines[options.atLineNo] = line;
+		return joinLines(lines);
+	}
+
+	const existing = parsed.entries.find((e) => e.file === entry.file);
+	if (existing) {
+		lines[existing.lineNo] = line;
+		return joinLines(lines);
+	}
+
+	const last = parsed.entries[parsed.entries.length - 1];
+	if (last) lines.splice(last.lineNo + 1, 0, line);
+	else lines.push(line);
+	return joinLines(lines);
+}
+
+/**
+ * 只删匹配到的那一行，其余行（含手写标题、分组、注释）逐字保留。
+ * 没匹配上时**原样返回输入**，不做任何重写（否则一次「无操作的删除」也会补上一个尾换行、
+ * 或把 CRLF 文件转成 LF，让调用方在无意间改动用户的文件）。
+ */
+export function removeIndexLine(raw: string, file: string): string {
+	const target = parseEntryIndex(raw).entries.find((e) => e.file === file);
+	if (!target) return raw;
+	const lines = splitLines(raw);
+	lines.splice(target.lineNo, 1);
+	return joinLines(lines);
+}
+
+export interface IndexCapacity {
+	lineCount: number;
+	byteLength: number;
+	ok: boolean;
+}
+
+export function indexCapacity(raw: string, maxLines: number, maxBytes: number): IndexCapacity {
+	// 与解析共用同一切分口径，避开「同一规则在三处各自实现」的漂移
+	const lineCount = splitLines(raw).filter((line) => line.trim().length > 0).length;
+	const byteLength = Buffer.byteLength(raw, "utf8");
+	return { lineCount, byteLength, ok: lineCount <= maxLines && byteLength <= maxBytes };
+}