@yandy0725/pi-memory 0.1.0

package/README.md

@@ -0,0 +1,143 @@
+# pi-memory
+
+File-system driven persistent memory layer for pi coding agent. Stores project knowledge across sessions — facts, preferences, debugging history — in plain Markdown files under `~/.pi/memory/<project-hash>/`.
+
+## Features
+
+- **One `memory` tool**, four actions: `add` (store knowledge), `replace` (edit existing), `remove` (delete), `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
+- **`/dream` command**: launches a headless agent to deduplicate, merge, and consolidate all memory files
+- **Dream nudge**: after N sessions or N hours, a gentle notification suggests running `/dream`
+- **`/memory` command**: show status, toggle on/off, inspect index and topic files
+- **Session search**: the `memory search scope=sessions` action queries past conversation history
+- **Branch-safe**: memory directory is keyed by the git root (or absolute path), so forks share memory naturally
+- **Path traversal protection**: topic files are validated against escaping the memory directory
+
+## Install
+
+```bash
+pi install npm:@yandy0725/pi-memory
+```
+
+Or add to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["npm:@yandy0725/pi-memory"]
+}
+```
+
+## Configuration
+
+Create `pi-memory.json` in the agent directory (`~/.pi/agent/pi-memory.json`) or the project `.pi/` directory (if trusted):
+
+```json
+{
+  "enabled": true,
+  "memoryDir": "~/.pi/memory",
+  "memIndexMaxLines": 200,
+  "memIndexMaxBytes": 25600,
+  "dream": {
+    "nudgeAfterSessions": 5,
+    "nudgeAfterHours": 24,
+    "model": "auto"
+  },
+  "sessionSearch": {
+    "maxSessions": 10,
+    "maxMatches": 5
+  }
+}
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enabled` | `true` | Toggle the entire memory system on/off |
+| `memoryDir` | `~/.pi/memory` | Root directory for all memory data |
+| `memIndexMaxLines` | `200` | Max lines in `MEMORY.md` before capacity errors |
+| `memIndexMaxBytes` | `25600` | Max bytes in `MEMORY.md` before capacity errors |
+| `dream.nudgeAfterSessions` | `5` | Sessions since last dream before nudge is shown |
+| `dream.nudgeAfterHours` | `24` | Hours since last dream before nudge is shown |
+| `dream.model` | `"auto"` | Model for dream consolidation (`"auto"` = same as current, or `"provider/id"`) |
+| `sessionSearch.maxSessions` | `10` | Max sessions to scan when searching history |
+| `sessionSearch.maxMatches` | `5` | Max matches to return from history search |
+
+Project-level config (`.pi/pi-memory.json`) is only loaded when the project is trusted.
+
+## Tool reference
+
+```
+memory(action: "add" | "replace" | "remove" | "search",
+        content?, topic?, title?, description?,
+        old_text?, query?, scope?)
+```
+
+### `add`
+
+Stores content under a topic file and upserts the MEMORY.md index.
+
+- **`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)
+
+### `replace`
+
+Locates `old_text` as a substring and replaces it with `content`.
+
+- **`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
+
+### `remove`
+
+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.
+
+- **`old_text`** (required) — substring to delete
+- **`topic`** (optional) — narrow search to a specific file
+
+### `search`
+
+Queries either memory files or session history.
+
+- **`query`** (required) — search keyword
+- **`scope`** (optional) — `"memory"` (default, scans topic files) or `"sessions"` (scans session history)
+
+## Commands
+
+### `/memory`
+
+Show memory status (enabled/disabled, directory, index line count, topic files, last dream timestamp).
+
+```
+/memory        — show status
+/memory on     — enable memory
+/memory off    — disable memory
+```
+
+### `/dream`
+
+Launch a headless agent that reads all memory files, deduplicates entries, merges contradictions, updates outdated info, and reorganizes `MEMORY.md` to be concise. The model used can be configured via `dream.model` in `pi-memory.json` (`"auto"` uses the current conversation model; `"provider/id"` picks a specific model).
+
+A confirmation dialog is shown before the consolidation begins. The result summary is shown as a notification when done.
+
+Dream meta (timestamp, session count at dream) is persisted in `.dream-meta.json` inside the memory directory.
+
+## File layout
+
+```
+~/.pi/memory/
+  <12-char-sha256>/
+    MEMORY.md            — index: one line per topic file
+    .dream-meta.json     — last dream timestamp + session count
+    debugging.md         — user-created topic files
+    preferences.md
+    ...
+```
+
+The hash is derived from the project's git root (or absolute path), ensuring each project gets its own memory namespace.
+
+## Snapshot semantics
+
+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; changes made via the `memory` tool during a session do not update the snapshot for that session, but take effect on the next one.

package/README.zh.md

@@ -0,0 +1,143 @@
+# pi-memory
+
+基于文件系统的持久化记忆层，为 pi 编程代理提供跨会话的项目记忆。事实、偏好、调试历史等知识以纯 Markdown 文件形式存储在 `~/.pi/memory/<项目哈希>/` 下。
+
+## 功能
+
+- **一个 `memory` 工具**，四种操作：`add`（存储知识）、`replace`（编辑现有内容）、`remove`（删除）、`search`（查询记忆或会话历史）
+- **基于主题的文件组织**：每次 `memory add` 都会向项目记忆目录下指定名称的 `.md` 文件写入内容
+- **`MEMORY.md` 索引**：自动生成的目录，带有行数/字节容量限制
+- **快照注入**：每个新会话启动时，记忆索引会追加到系统提示中，让代理始终感知过往工作
+- **`/dream` 命令**：启动无头代理，对记忆文件进行去重、合并和整理
+- **梦醒提醒**：经过 N 个会话或 N 小时后，温和通知建议运行 `/dream`
+- **`/memory` 命令**：查看状态、开关记忆、检查索引和主题文件
+- **会话搜索**：`memory search scope=sessions` 操作可检索过往对话历史
+- **分支安全**：记忆目录以 git 根目录（或绝对路径）为键，分叉仓库自然共享记忆
+- **路径穿越防护**：主题文件路径会验证是否逃逸记忆目录
+
+## 安装
+
+```bash
+pi install npm:@yandy0725/pi-memory
+```
+
+或在 `~/.pi/agent/settings.json` 中添加：
+
+```json
+{
+  "packages": ["npm:@yandy0725/pi-memory"]
+}
+```
+
+## 配置
+
+在代理目录（`~/.pi/agent/pi-memory.json`）或项目的 `.pi/` 目录（需受信任）中创建 `pi-memory.json`：
+
+```json
+{
+  "enabled": true,
+  "memoryDir": "~/.pi/memory",
+  "memIndexMaxLines": 200,
+  "memIndexMaxBytes": 25600,
+  "dream": {
+    "nudgeAfterSessions": 5,
+    "nudgeAfterHours": 24,
+    "model": "auto"
+  },
+  "sessionSearch": {
+    "maxSessions": 10,
+    "maxMatches": 5
+  }
+}
+```
+
+| 配置项 | 默认值 | 说明 |
+|--------|--------|------|
+| `enabled` | `true` | 开关整个记忆系统 |
+| `memoryDir` | `~/.pi/memory` | 所有记忆数据的根目录 |
+| `memIndexMaxLines` | `200` | `MEMORY.md` 的最大行数，超限报容量错误 |
+| `memIndexMaxBytes` | `25600` | `MEMORY.md` 的最大字节数，超限报容量错误 |
+| `dream.nudgeAfterSessions` | `5` | 距离上次整理经过的会话数，达到后展示提醒 |
+| `dream.nudgeAfterHours` | `24` | 距离上次整理经过的小时数，达到后展示提醒 |
+| `dream.model` | `"auto"` | 整理使用的模型（`"auto"` 使用当前模型，或 `"provider/id"` 指定模型） |
+| `sessionSearch.maxSessions` | `10` | 搜索历史会话时最多扫描的会话数 |
+| `sessionSearch.maxMatches` | `5` | 历史搜索最多返回的匹配数 |
+
+项目级配置（`.pi/pi-memory.json`）仅在项目受信任时加载。
+
+## 工具参考
+
+```
+memory(action: "add" | "replace" | "remove" | "search",
+        content?, topic?, title?, description?,
+        old_text?, query?, scope?)
+```
+
+### `add`
+
+将内容存储到主题文件并更新 MEMORY.md 索引。
+
+- **`content`**（必填）— 要持久化的知识文本
+- **`topic`**（必填）— 目标文件名，如 `"debugging.md"`，不存在则自动创建
+- **`title`**（可选）— 索引行的短标题（默认取 topic 的文件名部分）
+- **`description`**（可选）— 一行描述（默认取内容前 ~80 字符）
+
+### `replace`
+
+定位 `old_text` 子串并替换为 `content`。
+
+- **`old_text`**（必填）— 要查找的子串
+- **`content`**（必填）— 替换文本
+- **`topic`**（可选）— 限定搜索范围到指定文件；当文本在多个位置出现时必须提供
+
+### `remove`
+
+定位 `old_text` 并删除。当主题文件的全部内容被删除后，文件及其索引条目会被自动清理。
+
+- **`old_text`**（必填）— 要删除的子串
+- **`topic`**（可选）— 限定搜索范围到指定文件
+
+### `search`
+
+查询记忆文件或会话历史。
+
+- **`query`**（必填）— 搜索关键词
+- **`scope`**（可选）— `"memory"`（默认，扫描主题文件）或 `"sessions"`（扫描会话历史）
+
+## 命令
+
+### `/memory`
+
+显示记忆状态（启用/禁用、目录、索引行数、主题文件、上次整理时间戳）。
+
+```
+/memory        — 显示状态
+/memory on     — 启用记忆
+/memory off    — 禁用记忆
+```
+
+### `/dream`
+
+启动无头代理，读取所有记忆文件，去重、合并矛盾、更新过时信息、重组 `MEMORY.md`。使用的模型可通过 `pi-memory.json` 的 `dream.model` 配置（`"auto"` 使用当前会话模型；`"provider/id"` 指定特定模型）。
+
+开始整理前会弹出确认对话框。完成时在通知中显示结果摘要。
+
+整理元数据（时间戳、整理时会话计数）持久化在记忆目录下的 `.dream-meta.json` 中。
+
+## 文件布局
+
+```
+~/.pi/memory/
+  <12位sha256哈希>/
+    MEMORY.md            — 索引：每个主题文件一行
+    .dream-meta.json     — 上次整理的时间戳和会话计数
+    debugging.md         — 用户创建的主题文件
+    preferences.md
+    ...
+```
+
+哈希值由项目的 git 根目录（或绝对路径）派生，确保每个项目拥有独立的记忆命名空间。
+
+## 快照语义
+
+每次 `session_start` 时读取 `MEMORY.md` 索引，通过 `before_agent_start` 追加到系统提示中。如果索引超过 `memIndexMaxLines` 或 `memIndexMaxBytes`，将被截断并添加 `[truncated]` 标记——代理仍能获取到最相关的部分。此快照是会话开始时的静态副本；会话中通过 `memory` 工具所做的变更不会影响当次会话的快照，而是在下次会话中生效。

package/index.ts

@@ -0,0 +1,105 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, type MemoryConfig } from "./src/config";
+import { resolveMemoryDir } from "./src/paths";
+import { loadIndexSnapshot, buildInjection } from "./src/inject";
+import { createMemoryTool } from "./src/memory-tool";
+import { searchSessions } from "./src/session-search";
+import { runDream, resolveDreamModel } from "./src/dream";
+import { shouldNudge, writeDreamMeta, readDreamMeta } from "./src/nudge";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export default function (pi: ExtensionAPI) {
+	let memoryDir: string | null = null;
+	let config: MemoryConfig | null = null;
+	let indexSnapshot = "";
+	let toolRegistered = false;
+
+	pi.on("session_start", async (_event, ctx) => {
+		config = await loadConfig(ctx);
+		if (!config.enabled) return;
+		memoryDir = await resolveMemoryDir(config, ctx.cwd);
+		indexSnapshot = await loadIndexSnapshot(memoryDir, config.memIndexMaxLines, config.memIndexMaxBytes);
+
+		// register memory tool once
+		if (!toolRegistered) {
+			pi.registerTool(
+				createMemoryTool({
+					getMemoryDir: () => memoryDir,
+					getConfig: () => config!,
+					getEnabled: () => config?.enabled ?? false,
+					searchSessions,
+					cwd: () => ctx.cwd,
+				}) as any,
+			);
+			toolRegistered = true;
+		}
+
+		// nudge
+		if (ctx.hasUI) {
+			const { nudge, message } = await shouldNudge(memoryDir, config, ctx.cwd);
+			if (nudge) ctx.ui.notify(message, "info");
+		}
+	});
+
+	pi.on("before_agent_start", async (event) => {
+		if (!config?.enabled || !indexSnapshot) return;
+		return { systemPrompt: buildInjection(event.systemPrompt, indexSnapshot) };
+	});
+
+	pi.registerCommand("memory", {
+		description: "Show memory status, toggle enabled, or open files",
+		handler: async (args, ctx) => {
+			if (!config || !memoryDir) {
+				ctx.ui.notify("Memory not initialized.", "info");
+				return;
+			}
+			if (args === "off" || args === "on") {
+				config = { ...config, enabled: args === "on" };
+				ctx.ui.notify(`Memory ${args}`, "info");
+				return;
+			}
+			const files = (await readdir(memoryDir).catch(() => [])).filter((f) => f.endsWith(".md"));
+			const indexRaw = await readFile(join(memoryDir, "MEMORY.md"), "utf8").catch(() => "");
+			const lineCount = indexRaw ? indexRaw.split("\n").filter(Boolean).length : 0;
+			const meta = await readDreamMeta(memoryDir);
+			const summary = [
+				`Memory: ${config.enabled ? "enabled" : "disabled"}`,
+				`Dir: ${memoryDir}`,
+				`Index: ${lineCount}/${config.memIndexMaxLines} lines`,
+				`Topic files: ${files.filter((f) => f !== "MEMORY.md").join(", ") || "none"}`,
+				`Last dream: ${meta?.lastDreamAt ?? "never"}`,
+			].join("\n");
+			ctx.ui.notify(summary, "info");
+		},
+	});
+
+	pi.registerCommand("dream", {
+		description: "Consolidate all memory files via a headless agent",
+		handler: async (_args, ctx) => {
+			if (!config || !memoryDir) {
+				ctx.ui.notify("Memory not initialized.", "info");
+				return;
+			}
+			const ok = await ctx.ui.confirm("Dream", "Consolidate all memory files? This rewrites them in-place.");
+			if (!ok) return;
+			const model = resolveDreamModel(config, ctx);
+			if (!model) {
+				ctx.ui.notify("No model available for dream (check dream.model config / API key).", "error");
+				return;
+			}
+			ctx.ui.setStatus("dream", "Consolidating memory...");
+			try {
+				const summary = await runDream({ model, memoryDir, cwd: memoryDir, signal: ctx.signal });
+				const sessions = (await SessionManager.list(ctx.cwd)).length;
+				await writeDreamMeta(memoryDir, sessions);
+				ctx.ui.notify(summary, "info");
+			} catch (e: any) {
+				ctx.ui.notify(`Dream failed: ${e.message}`, "error");
+			} finally {
+				ctx.ui.setStatus("dream", undefined);
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+	"name": "@yandy0725/pi-memory",
+	"publishConfig": {
+		"access": "public"
+	},
+	"version": "0.1.0",
+	"description": "File-system driven persistent memory layer for pi coding agent",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/yandy/pi-packages",
+		"directory": "pi-memory"
+	},
+	"type": "module",
+	"keywords": [
+		"pi-package"
+	],
+	"files": [
+		"index.ts",
+		"src/"
+	],
+	"scripts": {
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"typecheck": "tsc --noEmit",
+		"lint": "biome lint .",
+		"format": "biome format --write ."
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": ">=0.80.2",
+		"@earendil-works/pi-coding-agent": ">=0.80.2",
+		"@earendil-works/pi-tui": ">=0.80.2",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"typebox": "^1.1.38"
+	}
+}

package/src/config.ts

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export interface MemoryConfig {
+	enabled: boolean;
+	memoryDir: string;
+	memIndexMaxLines: number;
+	memIndexMaxBytes: number;
+	dream: { nudgeAfterSessions: number; nudgeAfterHours: number; model: string };
+	sessionSearch: { maxSessions: number; maxMatches: number };
+}
+
+export const DEFAULT_CONFIG: MemoryConfig = {
+	enabled: true,
+	memoryDir: join(homedir(), CONFIG_DIR_NAME, "memory"),
+	memIndexMaxLines: 200,
+	memIndexMaxBytes: 25600,
+	dream: { nudgeAfterSessions: 5, nudgeAfterHours: 24, model: "auto" },
+	sessionSearch: { maxSessions: 10, maxMatches: 5 },
+};
+
+function expandTilde(p: string): string {
+	if (p === "~") return homedir();
+	if (p.startsWith("~/")) return join(homedir(), p.slice(2));
+	return p;
+}
+
+function deepMerge<T>(base: T, over: Partial<T>): T {
+	const out: any = { ...base };
+	for (const k of Object.keys(over) as (keyof T)[]) {
+		const ov = over[k] as any;
+		if (ov && typeof ov === "object" && !Array.isArray(ov) && typeof (out as any)[k] === "object") {
+			(out as any)[k] = deepMerge((out as any)[k], ov);
+		} else if (ov !== undefined) {
+			(out as any)[k] = ov;
+		}
+	}
+	return out;
+}
+
+function readJsonSafe(path: string): Partial<MemoryConfig> {
+	try {
+		if (existsSync(path)) return JSON.parse(readFileSync(path, "utf-8")) as Partial<MemoryConfig>;
+	} catch {
+		// ignore malformed
+	}
+	return {};
+}
+
+export interface LoadConfigContext {
+	cwd: string;
+	isProjectTrusted(): boolean;
+	_globalDir?: string;
+	_configDirName?: string;
+}
+
+export async function loadConfig(ctx: LoadConfigContext): Promise<MemoryConfig> {
+	const agentDir = ctx._globalDir ?? getAgentDir();
+	const configDirName = ctx._configDirName ?? CONFIG_DIR_NAME;
+	let cfg: MemoryConfig = { ...DEFAULT_CONFIG };
+
+	const globalFile = join(agentDir, "pi-memory.json");
+	cfg = deepMerge(cfg, readJsonSafe(globalFile));
+
+	if (ctx.isProjectTrusted()) {
+		const projectFile = join(ctx.cwd, configDirName, "pi-memory.json");
+		cfg = deepMerge(cfg, readJsonSafe(projectFile));
+	}
+
+	cfg.memoryDir = expandTilde(cfg.memoryDir);
+	return cfg;
+}

package/src/dream.ts

@@ -0,0 +1,111 @@
+import {
+	createAgentSession,
+	SessionManager,
+	DefaultResourceLoader,
+	SettingsManager,
+	AuthStorage,
+	ModelRegistry,
+} from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+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.
+Rules:
+- 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).`;
+
+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.
+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.
+Only edit files under ${memoryDir}. When finished, print a one-line summary of changes.`;
+}
+
+export function resolveDreamModel(config: MemoryConfig, ctx: { model: any; modelRegistry: any }): any | null {
+	if (config.dream.model === "auto") return ctx.model;
+	const slash = config.dream.model.indexOf("/");
+	if (slash === -1) return null;
+	const provider = config.dream.model.slice(0, slash);
+	const id = config.dream.model.slice(slash + 1);
+	return ctx.modelRegistry?.find(provider, id) ?? null;
+}
+
+export function extractSummary(messages: any[]): string {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const m = messages[i];
+		if (m.role === "assistant") {
+			if (typeof m.content === "string") return m.content;
+			const t = (m.content || []).find((b: any) => b.type === "text");
+			if (t) return t.text;
+		}
+	}
+	return "Dream completed.";
+}
+
+interface RunDreamOpts {
+	model: any;
+	memoryDir: string;
+	cwd: string;
+	signal?: AbortSignal;
+	createSession?: typeof createAgentSession;
+}
+
+export async function runDream(opts: RunDreamOpts): Promise<string> {
+	const createSession = opts.createSession ?? createAgentSession;
+	// DI: when opts.createSession is provided (test path), skip real loader/auth construction.
+	// When not provided (production), build the real isolated DefaultResourceLoader + AuthStorage.
+	const useReal = !opts.createSession;
+	const loader = useReal
+		? await (async () => {
+				const isolatedAgentDir = await mkdtemp(join(tmpdir(), "pi-dream-"));
+				const l = new DefaultResourceLoader({
+					cwd: opts.memoryDir,
+					agentDir: isolatedAgentDir,
+					settingsManager: SettingsManager.inMemory({}),
+					systemPromptOverride: () => DREAM_SYSTEM_PROMPT,
+				});
+				await l.reload();
+				return l;
+			})()
+		: undefined;
+	const authStorage = useReal ? AuthStorage.create() : undefined;
+
+	const { session } = await createSession({
+		model: opts.model,
+		...(authStorage ? { authStorage } : {}),
+		...(useReal ? { modelRegistry: ModelRegistry.create(authStorage!) } : {}),
+		tools: ["read", "edit", "write"],
+		cwd: opts.memoryDir,
+		sessionManager: useReal ? SessionManager.inMemory(opts.memoryDir) : undefined,
+		...(loader ? { resourceLoader: loader } : {}),
+	});
+
+	let summary = "Dream completed.";
+	const unsub = session.subscribe((e: any) => {
+		if (e.type === "agent_end") {
+			summary = extractSummary(session.messages);
+		}
+	});
+
+	const onAbort = () => session.abort?.();
+	opts.signal?.addEventListener("abort", onAbort);
+	try {
+		await session.prompt(buildDreamTask(opts.memoryDir, 200));
+		// Extract from messages as fallback when agent_end didn't fire (test path / edge case).
+		if (summary === "Dream completed." && session.messages?.length) {
+			summary = extractSummary(session.messages);
+		}
+		return summary;
+	} finally {
+		opts.signal?.removeEventListener("abort", onAbort);
+		unsub();
+		session.dispose();
+	}
+}

package/src/index-file.ts

@@ -0,0 +1,60 @@
+export interface IndexEntry {
+	title: string;
+	topic: string;
+	description: string;
+	raw: string;
+}
+export interface IndexFile {
+	entries: IndexEntry[];
+	raw: string;
+}
+
+// Matches: - [Title](topic.md) — description  (em-dash U+2014 or --)
+const LINE_RE = /^-\s+\[([^\]]+)\]\(([^)]+)\)\s*[—-]{1,2}\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 };
+}
+
+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;
+}

package/src/inject.ts

@@ -0,0 +1,18 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { truncateForInjection } from "./index-file";
+
+export async function loadIndexSnapshot(memoryDir: string, maxLines: number, maxBytes: number): Promise<string> {
+	try {
+		const raw = await readFile(join(memoryDir, "MEMORY.md"), "utf8");
+		const { content } = truncateForInjection(raw, maxLines, maxBytes);
+		return content ? `# Memory Index\n${content}` : "";
+	} catch {
+		return "";
+	}
+}
+
+export function buildInjection(systemPrompt: string, snapshot: string): string {
+	if (!snapshot) return systemPrompt;
+	return `${systemPrompt}\n\n${snapshot}`;
+}

package/src/memory-tool.ts

@@ -0,0 +1,243 @@
+import { readFile, writeFile, mkdir, readdir, unlink } from "node:fs/promises";
+import { join, dirname } from "node:path";
+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 { 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 ActionResult { ok: boolean; error?: string; entries?: IndexEntry[]; }
+
+const MEMORY_MD = "MEMORY.md";
+
+async function readIndex(memoryDir: string): Promise<IndexEntry[]> {
+	try {
+		const raw = await readFile(join(memoryDir, MEMORY_MD), "utf8");
+		return parseIndex(raw).entries;
+	} catch {
+		return [];
+	}
+}
+
+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> {
+	let topicPath: string;
+	try {
+		topicPath = safeTopicPath(memoryDir, p.topic);
+	} catch (e: any) {
+		return { ok: false, error: e.message };
+	}
+	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: "" });
+		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)}` };
+		}
+		// 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");
+		// write index
+		await writeFile(join(memoryDir, MEMORY_MD), serializeIndex(next) + "\n", "utf8");
+		return { ok: true, entries: next };
+	});
+}
+
+interface MatchSite { file: string; type: "index" | "topic"; }
+
+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;
+}
+
+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[];
+	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" }] : [];
+	}
+	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");
+			}
+		}
+		return { ok: true };
+	});
+}
+
+// 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\`\`\``);
+			}
+		}
+	}
+	return hits.length ? hits.join("\n\n") : "No matches in memory.";
+}
+
+export interface MemoryToolDeps {
+	getMemoryDir: () => string | null;
+	getConfig: () => { memIndexMaxLines: number; memIndexMaxBytes: number; sessionSearch: { maxSessions: number; maxMatches: number } };
+	getEnabled: () => boolean;
+	searchSessions: (cwd: string, query: string, cfg: { maxSessions: number; maxMatches: number }) => Promise<string>;
+	cwd: () => string;
+}
+
+export function createMemoryTool(deps: MemoryToolDeps) {
+	return {
+		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).",
+		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 'search' with scope='sessions' to find past work in history sessions.",
+		],
+		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." })),
+			query: Type.Optional(Type.String()),
+			scope: Type.Optional(StringEnum(["memory", "sessions"] as const)),
+		}),
+		renderCall(args: any, theme: any) {
+			let t = theme.fg("toolTitle", theme.bold("memory ")) + theme.fg("muted", args.action);
+			if (args.topic) t += ` ${theme.fg("accent", args.topic)}`;
+			if (args.query) t += ` ${theme.fg("dim", `"${args.query}"`)}`;
+			return new Text(t, 0, 0);
+		},
+		renderResult(result: any, { expanded }: any, theme: any) {
+			const txt = result.content?.[0];
+			const text = txt?.type === "text" ? txt.text : "";
+			if (result.details?.error) return new Text(theme.fg("error", `Error: ${result.details.error}`), 0, 0);
+			return new Text(theme.fg("success", "✓ ") + theme.fg("muted", text.split("\n")[0]), 0, 0);
+		},
+		async execute(_id: string, params: any, _signal: AbortSignal | undefined, _onUpdate: any, _ctx: any) {
+			if (!deps.getEnabled()) throw new Error("Memory is disabled (run /memory on)");
+			const dir = deps.getMemoryDir();
+			const cfg = deps.getConfig();
+			if (!dir) throw new Error("Memory not initialized (no session_start yet)");
+			let text: string;
+			let details: any = {};
+			switch (params.action) {
+				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 (!r.ok) throw new Error(r.error);
+					text = `Added 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 (!r.ok) throw new Error(r.error);
+					text = "Removed.";
+					break;
+				}
+				case "search": {
+					if (!params.query) throw new Error("query is required for search");
+					if (params.scope === "sessions") {
+						text = await deps.searchSessions(deps.cwd(), params.query, cfg.sessionSearch);
+					} else {
+						text = await searchMemory(dir, params.query);
+					}
+					break;
+				}
+				default:
+					throw new Error(`Unknown action: ${params.action}`);
+			}
+			return { content: [{ type: "text", text }], details };
+		},
+	};
+}

package/src/nudge.ts

@@ -0,0 +1,45 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+import type { MemoryConfig } from "./config";
+
+export interface DreamMeta { lastDreamAt: string; sessionCountAtDream: number; }
+
+const META_FILE = ".dream-meta.json";
+
+export async function readDreamMeta(memoryDir: string): Promise<DreamMeta | null> {
+	try {
+		const raw = await readFile(join(memoryDir, META_FILE), "utf8");
+		return JSON.parse(raw) as DreamMeta;
+	} catch {
+		return null;
+	}
+}
+
+export async function writeDreamMeta(memoryDir: string, sessionCount: number): Promise<void> {
+	const meta: DreamMeta = { lastDreamAt: new Date().toISOString(), sessionCountAtDream: sessionCount };
+	await writeFile(join(memoryDir, META_FILE), JSON.stringify(meta), "utf8");
+}
+
+export function formatNudge(sessions: number, newEntries: number): string {
+	return `💡 ${sessions} sessions, ${newEntries} new entries since last dream. /dream`;
+}
+
+export async function shouldNudge(
+	memoryDir: string,
+	config: MemoryConfig,
+	cwd: string,
+): Promise<{ nudge: boolean; message: string }> {
+	const sessions = (await SessionManager.list(cwd)).length;
+	const meta = await readDreamMeta(memoryDir);
+	const newEntries = meta ? Math.max(0, sessions - meta.sessionCountAtDream) : sessions;
+	if (meta) {
+		const hoursSince = (Date.now() - new Date(meta.lastDreamAt).getTime()) / 3600_000;
+		if (hoursSince >= config.dream.nudgeAfterHours && newEntries >= config.dream.nudgeAfterSessions) {
+			return { nudge: true, message: formatNudge(sessions, newEntries) };
+		}
+	} else if (sessions >= config.dream.nudgeAfterSessions) {
+		return { nudge: true, message: formatNudge(sessions, newEntries) };
+	}
+	return { nudge: false, message: "" };
+}

package/src/paths.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { execFile } from "node:child_process";
+import { join, resolve, normalize, sep } from "node:path";
+import { promisify } from "node:util";
+
+const execFileP = promisify(execFile);
+
+async function gitToplevel(cwd: string): Promise<string | null> {
+	try {
+		const { stdout } = await execFileP("git", ["rev-parse", "--show-toplevel"], { cwd, timeout: 3000 });
+		return stdout.trim() || null;
+	} catch {
+		return null;
+	}
+}
+
+export async function projectHash(cwd: string): Promise<string> {
+	const key = (await gitToplevel(cwd)) ?? resolve(cwd);
+	return createHash("sha256").update(key).digest("hex").slice(0, 12);
+}
+
+export async function resolveMemoryDir(
+	config: { memoryDir: string },
+	cwd: string,
+): Promise<string> {
+	const hash = await projectHash(cwd);
+	return join(config.memoryDir, hash);
+}
+
+export function safeTopicPath(memoryDir: string, topic: string): string {
+	const normalized = normalize(topic);
+	if (normalized.includes("..") || normalized.startsWith(sep)) {
+		throw new Error(`Unsafe topic path: ${topic}`);
+	}
+	const resolved = resolve(memoryDir, normalized);
+	const resolvedMemoryDir = resolve(memoryDir);
+	if (!resolved.startsWith(resolvedMemoryDir + sep) && resolved !== resolvedMemoryDir) {
+		throw new Error(`Topic escapes memory dir: ${topic}`);
+	}
+	return resolved;
+}

package/src/session-search.ts

@@ -0,0 +1,50 @@
+import { SessionManager, truncateHead } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+function extractText(content: any): string {
+	if (typeof content === "string") return content;
+	if (Array.isArray(content)) {
+		return content.filter((b: any) => b.type === "text").map((b: any) => b.text).join(" ");
+	}
+	return "";
+}
+
+export async function searchSessions(
+	cwd: string,
+	query: string,
+	config: { maxSessions: number; maxMatches: number },
+): Promise<string> {
+	const sessions = (await SessionManager.list(cwd)).slice(0, config.maxSessions);
+	const q = query.toLowerCase();
+	const hits: string[] = [];
+	for (const s of sessions) {
+		const raw = await readFile(s.path, "utf8").catch(() => "");
+		const lines = raw.split("\n").filter(Boolean);
+		// gather message texts in order for context windows
+		const msgs: { text: string; idx: number }[] = [];
+		for (const [i, line] of lines.entries()) {
+			let entry: any;
+			try { entry = JSON.parse(line); } catch { continue; }
+			if (entry.type === "message" && entry.message) {
+				const t = extractText(entry.message.content);
+				if (t) msgs.push({ text: t, idx: i });
+			}
+		}
+		for (const m of msgs) {
+			if (m.text.toLowerCase().includes(q)) {
+				const ctx = msgs
+					.filter((x) => Math.abs(x.idx - m.idx) <= 50)
+					.map((x) => `  ${x.text.slice(0, 200)}`)
+					.join("\n");
+				hits.push(`## Session ${basename(s.path)} (${s.modified.toISOString().slice(0, 10)})\n…matched: "${m.text.slice(0, 150)}"…\ncontext:\n${ctx}`);
+				if (hits.length >= config.maxMatches) break;
+			}
+		}
+		if (hits.length >= config.maxMatches) break;
+	}
+	if (!hits.length) return "No matches in sessions.";
+	const out = `Found ${hits.length} match(es):\n\n${hits.join("\n\n")}`;
+	const trunc = truncateHead(out, { maxLines: 2000, maxBytes: 50000 });
+	return trunc.content;
+}

package/src/topic-file.ts

@@ -0,0 +1,27 @@
+export interface TopicMeta {
+	name: string;
+	description: string;
+	type: string;
+	updated: string;
+}
+
+export function buildFrontmatter(meta: TopicMeta): string {
+	return `---
+name: ${meta.name}
+description: ${meta.description}
+type: ${meta.type}
+updated: ${meta.updated}
+---
+
+`;
+}
+
+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 function isEmptyAfterRemove(content: string): boolean {
+	return content.trim() === "";
+}