@wjm200509/dsh-memory 0.0.0-stage → 0.1.1

package/lib/dream.js

@@ -0,0 +1,386 @@
+/**
+ * One dreaming run: a hidden, tool-restricted background agent that
+ * consolidates memory. A project run reviews one project's ended sessions;
+ * a cross-project run reviews every partition together and moves notes to
+ * the partition where they hold.
+ *
+ * Mechanism (verified by the 2026-11-08 spike on DSH 0.2.2-rc.1):
+ * - `ctx.agents.create()` without `parentAgent` makes a runtime root agent;
+ * - `meta: { origin: "subagent" }` without `cwd`: the session is stored under
+ *   `sessions/_no-cwd/`, never listed or searched, and hidden from the sidebar;
+ * - `agentCtx.tools.restrict({ allow: [] })` masks every global tool; the
+ *   scoped registrations below stay visible;
+ * - messages must be built with `createUserMessage()` (it sets `role`);
+ * - `sessionTitle.rename()` pins the title and stops title generation;
+ * - the loop has no turn budget: a policy must `cancel()` the agent itself.
+ *
+ * Outcome: the loop appends `turn/end` with `reason.kind` one of
+ * "completed", "error" (model/tool failure, `reason.error.message`),
+ * "aborted", "max-tokens" (output cut off) or "blocked". A completed turn,
+ * or one this module cancelled at the step budget, is a success; anything
+ * the run could not finish (tool errors, unresolved items the agent
+ * reported, a missing report, the budget) is listed in `issues`.
+ */
+import { randomUUID } from "node:crypto";
+import { stat } from "node:fs/promises";
+import { basename, dirname } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { createChangeTracker, createBackup, pruneHistory } from "./store.js";
+import { checkPartition, renderHealth } from "./health.js";
+import { memoryTools } from "./tools.js";
+import { sameProject } from "./paths.js";
+import { dreamPrompt, crossDreamPrompt } from "./prompt.js";
+
+/** Model calls one run may make before it is stopped. */
+export const MAX_STEPS = { project: 40, cross: 80 };
+/** Transcript pages one project run may read; the rest of its steps are for writing. */
+export const READ_PAGES = 20;
+/** Marker opening every dreaming prompt; also identifies old runs' sessions on disk. */
+export const DREAM_PROMPT_MARKERS = ["Memory consolidation", 'You are "dreaming"'];
+
+const TOOL_RESULT_CHARS = 400;
+const TOOL_CALL_CHARS = 200;
+const PAGE_CHARS = 12_000;
+/** Longest USER / ASSISTANT line: a pasted log must not flood the dreaming context. */
+const LINE_CHARS = 2_000;
+const SEARCH_HITS = 50;
+const ISSUE_CHARS = 200;
+const ISSUE_LIMIT = 8;
+
+const seqOf = (line) => Number(line.match(/^\[seq (\d+)\]/)?.[1] ?? 0);
+const clip = (text, max) => (text.length > max ? `${text.slice(0, max)}…` : text);
+const oneLine = (text) => text.replace(/\s+/g, " ").trim();
+
+function blockText(block, max) {
+	if (block?.type === "text") return block.text;
+	if (block?.type === "reasoning") return "";
+	return clip(`[${block?.type}] ${JSON.stringify(block)}`, max);
+}
+
+/** A tool call as `TOOL CALL <name>: <arguments>`; provider call ids are noise and dropped. */
+function toolCallLine(block) {
+	if (block.type !== "tool-call") return `TOOL CALL: ${oneLine(blockText(block, TOOL_CALL_CHARS))}`;
+	const args = typeof block.arguments === "string" ? block.arguments : JSON.stringify(block.arguments ?? {});
+	return `TOOL CALL ${block.name}: ${clip(oneLine(args), TOOL_CALL_CHARS)}`;
+}
+
+/**
+ * Render a session's events as compact transcript lines: real user input,
+ * assistant text and tool activity. Injected context (workspace instructions,
+ * reminders) and model reasoning are dropped.
+ * @param {Array<{ seq: number, type: string, data: any }>} events
+ * @returns {string} one `[seq N] ROLE: text` line per kept message.
+ */
+export function renderTranscript(events) {
+	const lines = [];
+	for (const event of events) {
+		/* A user/message event carries the message itself as `data`; assistant/message and tool/result wrap it in `data.message`. */
+		const message = event.type === "user/message" ? event.data : event.data?.message;
+		if (message === undefined || message === null) continue;
+		const content = Array.isArray(message.content) ? message.content : [];
+		if (event.type === "user/message") {
+			if (message.source?.kind !== "user") continue;
+			lines.push(`[seq ${event.seq}] USER: ${clip(oneLine(content.map((block) => blockText(block, TOOL_CALL_CHARS)).join(" ")), LINE_CHARS)}`);
+		} else if (event.type === "assistant/message") {
+			const text = oneLine(content.filter((block) => block.type === "text").map((block) => block.text).join(" "));
+			if (text !== "") lines.push(`[seq ${event.seq}] ASSISTANT: ${clip(text, LINE_CHARS)}`);
+			for (const block of content) {
+				if (block.type !== "text" && block.type !== "reasoning") lines.push(`[seq ${event.seq}] ${toolCallLine(block)}`);
+			}
+		} else if (event.type === "tool/result") {
+			const text = oneLine(content.map((block) => blockText(block, TOOL_RESULT_CHARS)).join(" "));
+			lines.push(`[seq ${event.seq}] TOOL RESULT${message.isError ? " (error)" : ""}: ${clip(text, TOOL_RESULT_CHARS)}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Whether a project directory is there, was deleted, or cannot be judged.
+ * A missing directory counts as deleted only when an ancestor exists below the
+ * filesystem root's own mount (so a drive or share that is not mounted right
+ * now is "unreachable" and its sessions wait instead of being dropped).
+ * @returns {Promise<"present" | "gone" | "unreachable">}
+ */
+export async function projectState(cwd) {
+	try {
+		await stat(cwd);
+		return "present";
+	} catch (error) {
+		if (error.code !== "ENOENT" && error.code !== "ENOTDIR") return "unreachable";
+	}
+	for (let dir = dirname(cwd); ;) {
+		if (await stat(dir).then(() => true, () => false)) return "gone";
+		const parent = dirname(dir);
+		if (parent === dir) return "unreachable";
+		dir = parent;
+	}
+}
+
+const TEXT_OUTPUT = {
+	schema: { type: "object", additionalProperties: false, properties: { text: { type: "string", required: true, description: "Result text." } } },
+	render: (_args, value) => [{ type: "text", text: value.text }]
+};
+
+/**
+ * Find a session by a full id or a unique prefix (notes written by earlier
+ * runs may cite a shortened id), limited to sessions `allowed` accepts.
+ * @returns {Promise<{ session: object, events: object[] }>}
+ */
+async function resolveSession(sessionQuery, sessionId, allowed) {
+	try {
+		return await sessionQuery.readSession(sessionId);
+	} catch (error) {
+		if (typeof sessionQuery.listSessions !== "function") throw error;
+	}
+	const wanted = sessionId.replace(/^session-/, "");
+	const matches = (await sessionQuery.listSessions()).map(({ header }) => header).filter((header) => header.id.replace(/^session-/, "").startsWith(wanted) && allowed(header));
+	if (matches.length === 1) return sessionQuery.readSession(matches[0].id);
+	if (matches.length > 1) throw new Error(`Session id "${sessionId}" is ambiguous: ${matches.slice(0, 5).map((header) => header.id).join(", ")}. Use the full id.`);
+	throw new Error(`No session "${sessionId}" here. Cite full session ids (session-<uuid>); a note whose evidence cannot be found stays unverified: list it in dream_report.`);
+}
+
+/**
+ * Read-only transcript tools for the dreaming agent. A project run reads
+ * that project's sessions and searches its batch; a cross-project run
+ * (`cwd` undefined) reads any project's session to see where a cited
+ * session belongs, and has no search.
+ * @param ctx - context providing `sessionQuery`.
+ * @param {{ cwd?: string, sessionIds: string[], progress?: Map<string, { seq: number, done: boolean }>,
+ *   fromSeqs?: Record<string, number>, readPages?: number }} job
+ *   `progress` receives, per session, how far the agent has read without skipping anything (from `fromSeqs`, where
+ *   the previous run stopped) and whether the end was reached. `readPages` limits `transcript_read` calls.
+ */
+export function transcriptTools(ctx, { cwd, sessionIds, progress = new Map(), fromSeqs = {}, readPages = Infinity }) {
+	let pagesRead = 0;
+	const cross = cwd === undefined;
+	const allowed = (header) => typeof header.cwd === "string" && (cross || sameProject(header.cwd, cwd));
+	const cache = new Map();
+	const load = async (sessionId) => {
+		if (!cache.has(sessionId)) {
+			cache.set(sessionId, resolveSession(ctx.sessionQuery, sessionId, allowed).then(({ session, events }) => {
+				if (!allowed(session)) throw new Error(`Session ${sessionId} belongs to another project; only this project's sessions can be read.`);
+				return { id: session.id, cwd: session.cwd, lines: renderTranscript(events).split("\n").filter((line) => line !== "") };
+			}));
+		}
+		return cache.get(sessionId);
+	};
+	const read = defineTool({
+		name: "transcript_read",
+		description: "Read a session transcript as `[seq N] ROLE: text` lines, one page at a time. Transcripts are the ground truth for checking memory notes. The first page names the session's full id and project.",
+		parameters: {
+			sessionId: { type: "string", required: true, description: "Full session id (session-<uuid>); a unique prefix also works." },
+			fromSeq: { type: "integer", description: "Start at this event seq; omit to start from the beginning." }
+		},
+		output: TEXT_OUTPUT,
+		isConcurrencySafe: () => true,
+		async execute(args) {
+			const { id, cwd: project, lines } = await load(args.sessionId);
+			if (++pagesRead > readPages) return { text: `Reading budget used up (${readPages} pages per run). Do not read more: write what you learned from what you read, then call dream_report. Sessions you did not finish are reviewed again by the next run.` };
+			const from = args.fromSeq ?? 0;
+			const out = from === 0 ? [`Session ${id} · project ${project}`] : [];
+			let size = 0;
+			let lastSeq = 0;
+			let more = false;
+			for (const line of lines) {
+				const seq = seqOf(line);
+				if (seq < from) continue;
+				/* A page ends only between events, never inside one, so the next page's `fromSeq` always advances. */
+				if (size > PAGE_CHARS && seq !== lastSeq) {
+					out.push(`[more: call transcript_read with fromSeq=${seq}]`);
+					more = true;
+					break;
+				}
+				out.push(line);
+				lastSeq = seq;
+				size += line.length + 1;
+			}
+			/* Only a page that continues where the agent already was counts: skipping ahead does not mark the skipped part as read. */
+			const covered = progress.get(id) ?? { seq: fromSeqs[id] ?? 0, done: false };
+			const skipped = lines.some((line) => seqOf(line) > covered.seq && seqOf(line) < from);
+			if (!skipped) progress.set(id, { seq: Math.max(covered.seq, lastSeq), done: covered.done || !more });
+			return { text: out.length === 0 ? "No transcript lines at or after that seq." : out.join("\n") };
+		}
+	});
+	if (cross) return [read];
+	return [
+		read,
+		defineTool({
+			name: "transcript_search",
+			description: "Case-insensitive literal search across the transcripts of the sessions under review.",
+			parameters: { query: { type: "string", required: true, description: "Literal text to find." } },
+			output: TEXT_OUTPUT,
+			isConcurrencySafe: () => true,
+			async execute(args) {
+				const needle = args.query.toLowerCase();
+				const hits = [];
+				for (const sessionId of sessionIds) {
+					for (const line of (await load(sessionId)).lines) {
+						if (line.toLowerCase().includes(needle)) hits.push(`${sessionId} ${line}`);
+						if (hits.length >= SEARCH_HITS) break;
+					}
+					if (hits.length >= SEARCH_HITS) break;
+				}
+				return { text: hits.length === 0 ? "No matches." : hits.join("\n") };
+			}
+		})
+	];
+}
+
+/** The closing report the agent must file; `holder.report` receives it. */
+export function reportTool(holder) {
+	return defineTool({
+		name: "dream_report",
+		description: "Call once when you are done: what you changed and why, and everything left unresolved.",
+		parameters: {
+			summary: { type: "string", required: true, description: "Short summary of what you changed and why." },
+			unresolved: { type: "string", description: "One item per line: notes you could not verify or fix, checks that failed, work you skipped, and why. Empty when none." }
+		},
+		output: TEXT_OUTPUT,
+		async execute(args) {
+			holder.report = { summary: args.summary, unresolved: (args.unresolved ?? "").split("\n").map((line) => line.trim()).filter((line) => line !== "") };
+			return { text: "Report recorded. End your turn now." };
+		}
+	});
+}
+
+/** Tool errors in the run's own events, as short issue lines. */
+function toolErrors(events) {
+	return events.filter((event) => event.type === "tool/result" && event.data?.message?.isError).map((event) => {
+		const content = Array.isArray(event.data.message.content) ? event.data.message.content : [];
+		return clip(oneLine(content.map((block) => blockText(block, ISSUE_CHARS)).join(" ")), ISSUE_CHARS);
+	})
+		/* Expected retries, not problems: a version conflict is redone on the new content, and the user-level gate redirects the note to the project partition. */
+		.filter((text) => !/^Memory conflict:|^A new user-level note needs basis/.test(text))
+		.map((text) => `tool error: ${text}`);
+}
+
+/** Pre-computed checks for the prompt; a failing check only costs the section. */
+async function healthFor(store, partitions, indexMaxBytes) {
+	try {
+		return renderHealth(await Promise.all(partitions.map(async ({ label, scope, cwd }) => ({ label, issues: await checkPartition(store, scope, cwd, indexMaxBytes) }))));
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * Run one dreaming pass.
+ * @param ctx - context providing `agents`, `sessionQuery`, and optionally `on` (step budget) and `get` (`sessionTitle`).
+ * @param {{ cwd?: string, sessionIds?: string[], projects?: Array<{ cwd: string, notes: number }>,
+ *   fromSeqs?: Record<string, number>, selection?: { provider: string, model: string, reasoningEffort?: string },
+ *   store: import("./store.js").MemoryStore, indexMaxBytes: number, signal?: AbortSignal }} job
+ *   `fromSeqs` maps a session id to the last seq an earlier run reviewed.
+ *   `projects` makes it a cross-project run; otherwise it consolidates `cwd`.
+ * @returns {Promise<{ ok: true, changes: object, issues: string[], summary?: string, dreamSessionId: string, unfinished?: Record<string, number> }
+ *   | { ok: false, error: string, dreamSessionId?: string, skipped?: boolean }>}
+ *   `unfinished` maps each session that was not read to the end (the run hit its budget) to the seq it got through.
+ *   `skipped` means the run did not start: the project directory cannot be reached right now.
+ */
+export async function runDream(ctx, { cwd, sessionIds = [], fromSeqs = {}, projects, selection, store, indexMaxBytes, signal }) {
+	if (signal?.aborted) return { ok: false, error: "cancelled before it started" };
+	const cross = projects !== undefined;
+	const maxSteps = cross ? MAX_STEPS.cross : MAX_STEPS.project;
+	const sessionId = `session-${randomUUID()}`;
+	const tracker = createChangeTracker({ backup: createBackup(store.root, sessionId) });
+	const holder = { report: undefined };
+	/** Per session: last seq shown to the agent, and whether its end was reached. */
+	const progress = new Map();
+	/* What counts as reviewed if the run is cut off: the reading progress at the agent's last note change, since reading alone consolidates nothing. */
+	let credited = new Map();
+	const record = tracker.record.bind(tracker);
+	tracker.record = (kind, path) => {
+		record(kind, path);
+		credited = new Map([...progress].map(([id, state]) => [id, { ...state }]));
+	};
+	let handle;
+	let steps = 0;
+	let budgetHit = false;
+	let stopListening;
+	try {
+		let prompt;
+		let tools;
+		if (cross) {
+			const health = await healthFor(store, [{ label: "user", scope: "user" }, ...projects.map((project) => ({ label: `project ${project.cwd}`, scope: "project", cwd: project.cwd }))], indexMaxBytes);
+			prompt = crossDreamPrompt({ projects, indexMaxBytes, maxSteps, health });
+			tools = [...memoryTools(store, { projects: projects.map((project) => project.cwd), tracker, indexMaxBytes: () => indexMaxBytes, subagentReadOnly: false }), ...transcriptTools(ctx, { sessionIds: [] })];
+		} else {
+			/* A deleted project's notes would never be loaded again: its partition turns read-only and the prompt keeps only what the user stated.
+			   A directory that cannot be reached right now (unmounted drive) is neither: the run waits. */
+			const state = await projectState(cwd);
+			if (state === "unreachable") return { ok: false, skipped: true, error: `project directory ${cwd} cannot be reached right now` };
+			const projectGone = state === "gone";
+			const health = await healthFor(store, [...(projectGone ? [] : [{ label: "project", scope: "project", cwd }]), { label: "user", scope: "user" }], indexMaxBytes);
+			prompt = dreamPrompt({ cwd, sessionIds, fromSeqs, indexMaxBytes, projectGone, maxSteps, health, readPages: READ_PAGES });
+			tools = [...memoryTools(store, { cwdOf: () => cwd, tracker, indexMaxBytes: () => indexMaxBytes, projectWritable: !projectGone, subagentReadOnly: false }), ...transcriptTools(ctx, { cwd, sessionIds, progress, fromSeqs, readPages: READ_PAGES })];
+		}
+		/* Cancelled (memory turned off, plugin stopping) while the checks ran: do not create the agent at all. */
+		if (signal?.aborted) return { ok: false, error: "cancelled before it started" };
+		handle = await ctx.agents.create({
+			sessionId,
+			meta: { origin: "subagent" },
+			agentOptions: selection === undefined ? {} : { ...selection },
+			setup(agentCtx) {
+				agentCtx.tools.restrict({ allow: [] });
+				for (const tool of [...tools, reportTool(holder)]) agentCtx.tools.register(tool);
+			}
+		});
+		const agent = handle.agent;
+		if (signal?.aborted) return { ok: false, error: "cancelled before it started", dreamSessionId: sessionId };
+		try {
+			ctx.get?.("sessionTitle")?.rename(agent.session, `记忆整理 · ${cross ? "跨项目" : basename(cwd)}`);
+		} catch {
+			/* A missing title only costs a fallback title. */
+		}
+		stopListening = ctx.on?.("session/event", (session, event) => {
+			if (session.header?.id !== sessionId || event.type !== "assistant/message") return;
+			if (++steps > maxSteps && !budgetHit) {
+				budgetHit = true;
+				agent.cancel(new Error(`dreaming step budget of ${maxSteps} reached`));
+			}
+		});
+		const onAbort = () => agent.cancel(signal.reason);
+		signal?.addEventListener("abort", onAbort, { once: true });
+		try {
+			agent.followup(createUserMessage({ content: [{ type: "text", text: prompt }], source: { kind: "user" } }));
+			await agent.whenIdle();
+		} finally {
+			signal?.removeEventListener("abort", onAbort);
+		}
+		const events = [...agent.session.snapshotEvents(0)];
+		const turnEnd = [...events].reverse().find((event) => event.type === "turn/end");
+		const reason = turnEnd?.data?.reason;
+		if (turnEnd === undefined) return { ok: false, error: "dreaming agent did not finish a turn", dreamSessionId: sessionId };
+		if (reason?.kind === "completed" || budgetHit) {
+			/* Cut off at the budget without a report: sessions not read to the end stay queued, from where this run got to. */
+			const unfinished = {};
+			if (budgetHit && holder.report === undefined) {
+				for (const id of sessionIds) if (credited.get(id)?.done !== true) unfinished[id] = credited.get(id)?.seq ?? fromSeqs[id] ?? 0;
+			}
+			const pending = Object.keys(unfinished).length;
+			const issues = [
+				...(budgetHit ? [`step budget of ${maxSteps} reached${pending > 0 ? `; ${pending} session(s) not read to the end will be reviewed again from where this run stopped` : holder.report === undefined ? "" : "; the report was already filed"}`] : []),
+				...toolErrors(events),
+				...(holder.report?.unresolved ?? []).map((item) => clip(item, ISSUE_CHARS)),
+				...(holder.report === undefined && !budgetHit ? ["ended without dream_report"] : [])
+			];
+			return {
+				ok: true,
+				changes: tracker.summary(),
+				issues: issues.length > ISSUE_LIMIT ? [...issues.slice(0, ISSUE_LIMIT), `…and ${issues.length - ISSUE_LIMIT} more`] : issues,
+				...(holder.report ? { summary: clip(holder.report.summary, 600) } : {}),
+				...(pending > 0 ? { unfinished } : {}),
+				dreamSessionId: sessionId
+			};
+		}
+		if (reason?.kind === "error") return { ok: false, error: reason.error?.message ?? "model error", dreamSessionId: sessionId };
+		return { ok: false, error: `dreaming turn ended with "${reason?.kind ?? "unknown"}"`, dreamSessionId: sessionId };
+	} catch (error) {
+		return { ok: false, error: error?.message ?? String(error), ...(handle ? { dreamSessionId: sessionId } : {}) };
+	} finally {
+		stopListening?.();
+		await handle?.dispose().catch(() => {});
+		await pruneHistory(store.root).catch(() => {});
+	}
+}

package/lib/fsutil.js

@@ -0,0 +1,24 @@
+/**
+ * Small filesystem helpers shared by the store and the dreaming state.
+ */
+import { rename } from "node:fs/promises";
+
+/** Errors Windows raises while an antivirus scanner or indexer briefly holds a file. */
+const TRANSIENT_RENAME = new Set(["EPERM", "EBUSY", "EACCES"]);
+
+/**
+ * `rename`, retried a few times on the transient errors above.
+ * @param {string} from
+ * @param {string} to
+ * @param {{ attempts?: number, delayMs?: number }} [options]
+ */
+export async function renameWithRetry(from, to, { attempts = 5, delayMs = 40 } = {}) {
+	for (let attempt = 1; ; attempt++) {
+		try {
+			return await rename(from, to);
+		} catch (error) {
+			if (attempt >= attempts || !TRANSIENT_RENAME.has(error?.code)) throw error;
+			await new Promise((resolve) => setTimeout(resolve, delayMs * attempt));
+		}
+	}
+}

package/lib/health.js

@@ -0,0 +1,66 @@
+/**
+ * Mechanical checks over a partition's notes, computed in code and put into
+ * the dreaming prompt so the model spends its steps on judgment instead:
+ * oversized or over-long INDEX.md, dangling links, notes the INDEX does not
+ * list, notes over the soft size limit.
+ */
+import { posix } from "node:path";
+import { INDEX_LINE_BYTES, NOTE_SOFT_BYTES } from "./tools.js";
+
+const LIMIT_PER_PARTITION = 12;
+const LINK = /\]\(([^)\s]+?\.md)(?:#[^)]*)?\)/gi;
+
+/** Link targets of a note, resolved against the note's own directory; web and absolute links are skipped. */
+function linkTargets(notePath, content) {
+	const targets = [];
+	for (const match of content.matchAll(LINK)) {
+		const raw = match[1];
+		if (/^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("/")) continue;
+		targets.push(posix.normalize(posix.join(posix.dirname(notePath), raw)));
+	}
+	return targets;
+}
+
+/**
+ * @param {import("./store.js").MemoryStore} store
+ * @param {"project" | "user"} scope
+ * @param {string | undefined} cwd - project directory for the project scope.
+ * @param {number} indexMaxBytes
+ * @returns {Promise<string[]>} one line per problem found.
+ */
+export async function checkPartition(store, scope, cwd, indexMaxBytes) {
+	const entries = await store.list(scope, cwd);
+	const known = new Map(entries.map((entry) => [entry.path.toLowerCase(), entry.path]));
+	const issues = [];
+	const linkedFromIndex = new Set();
+	for (const entry of entries) {
+		const note = await store.read(scope, cwd, entry.path);
+		if (note === null) continue;
+		const isIndex = entry.path === "INDEX.md";
+		if (isIndex) {
+			if (entry.bytes > indexMaxBytes) issues.push(`INDEX.md is ${entry.bytes} bytes; the limit is ${indexMaxBytes}`);
+			const long = note.content.split("\n").filter((line) => Buffer.byteLength(line) > INDEX_LINE_BYTES).length;
+			if (long > 0) issues.push(`INDEX.md has ${long} line(s) over ${INDEX_LINE_BYTES} bytes`);
+		} else if (entry.bytes > NOTE_SOFT_BYTES) issues.push(`${entry.path} is ${entry.bytes} bytes (soft limit ${NOTE_SOFT_BYTES}): split it or cut details`);
+		for (const target of linkTargets(entry.path, note.content)) {
+			const found = known.get(target.toLowerCase());
+			if (found === undefined) issues.push(`${entry.path} links to ${target}, which does not exist`);
+			else if (isIndex) linkedFromIndex.add(found);
+		}
+	}
+	if (known.has("index.md")) {
+		for (const entry of entries) {
+			if (entry.path !== "INDEX.md" && !linkedFromIndex.has(entry.path)) issues.push(`${entry.path} is not listed in INDEX.md`);
+		}
+	} else if (entries.length > 0) issues.push("there is no INDEX.md although the partition has notes");
+	return issues.length > LIMIT_PER_PARTITION ? [...issues.slice(0, LIMIT_PER_PARTITION), `…and ${issues.length - LIMIT_PER_PARTITION} more`] : issues;
+}
+
+/**
+ * Render the checks of several partitions as prompt lines.
+ * @param {Array<{ label: string, issues: string[] }>} partitions
+ * @returns {string} empty when nothing is wrong.
+ */
+export function renderHealth(partitions) {
+	return partitions.flatMap(({ label, issues }) => issues.map((issue) => `- ${label}: ${issue}`)).join("\n");
+}

package/lib/index.js

@@ -0,0 +1,147 @@
+/**
+ * dsh-memory — host half.
+ *
+ * Cross-session memory for DSH agents: notes the agent keeps in a per-project
+ * and a per-user partition, an INDEX snapshot injected into each session, and
+ * "dreaming" — a hidden background agent that corrects, merges and compacts
+ * the notes against session transcripts after a session ends.
+ *
+ * Settings channel (plan Task 0, choice B): every field is volatile. The
+ * client edits the user-facing fields and writes `dreamRequest`; only the
+ * host writes `status`, through `ctx.settings.update()`.
+ *
+ * Behavior is described in README.md.
+ */
+import z from "@deepseek-ai/schemastery";
+import { join } from "node:path";
+import { stat } from "node:fs/promises";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import { resolveMemoryRoot, sameProject } from "./paths.js";
+import { MemoryStore } from "./store.js";
+import { installMemoryTools } from "./tools.js";
+import { installIndexInjection } from "./inject.js";
+import { DreamState } from "./state.js";
+import { installTrigger, isEligible } from "./trigger.js";
+import { runDream } from "./dream.js";
+import { DreamRunner, reconcile, pruneDreamSessions } from "./runner.js";
+import { installDreamCommand } from "./command.js";
+import { createStatusPublisher } from "./status.js";
+import { resolveSelection } from "./selection.js";
+
+/** Stable Cordis plugin name; also the settings namespace. */
+const name = "memory";
+
+/** Host services this plugin needs. */
+const inject = ["tools", "systemPrompt", "agents", "sessionQuery"];
+
+/** Delay before the startup scan for sessions that ended unnoticed. */
+const RECONCILE_DELAY_MS = 30_000;
+
+/** Status snapshot shown on the settings page before the first run. */
+const EMPTY_STATUS = { paused: null, running: null, pendingCount: 0, log: [] };
+
+/**
+ * Durable settings schema. All fields are volatile so settings writes reach
+ * the running plugin without a remount.
+ */
+const Config = z.object({
+	enabled: z.boolean().default(true).volatile(),
+	autoDream: z.boolean().default(true).volatile(),
+	idleMinutes: z.natural().min(1).default(10).volatile(),
+	concurrency: z.natural().min(1).default(4).volatile(),
+	indexMaxBytes: z.natural().min(512).default(4096).volatile(),
+	dreamProvider: z.string().default("").volatile(),
+	dreamModel: z.string().default("").volatile(),
+	dreamEffort: z.string().default("").volatile(),
+	status: z.any().default(EMPTY_STATUS).volatile(),
+	dreamRequest: z.string().default("").volatile()
+});
+
+/**
+ * Wire the memory feature into the host.
+ * @param ctx - host plugin context.
+ * @param config - live volatile config reference.
+ */
+async function apply(ctx, config) {
+	const root = resolveMemoryRoot();
+	const store = new MemoryStore(root);
+	installMemoryTools(ctx, store, config);
+	installIndexInjection(ctx, store, config);
+
+	const state = new DreamState(root);
+	await state.load();
+	if (state.recovered) ctx.logger.warn("memory: state.json was unreadable and has been set aside as state.json.corrupt-*; dreaming starts from an empty queue");
+	/* Leftovers of crashed writes; best effort, off the startup path. */
+	store.sweep().catch(() => {});
+
+	/* Settings channel: the host publishes `status` (retrying writes made before the plugin is active). */
+	const status = createStatusPublisher({ name, root, warn: (message) => ctx.logger.warn(message) });
+	ctx.effect(() => () => status.detach());
+	/* Projects a cross-project run covers: every existing directory with sessions, and its note count. */
+	const listProjects = async () => {
+		const projects = [];
+		for (const { header } of await ctx.sessionQuery.listSessions()) {
+			if (!isEligible(header) || projects.some((project) => sameProject(project.cwd, header.cwd))) continue;
+			if (await stat(header.cwd).then(() => true, () => false)) projects.push({ cwd: header.cwd, notes: 0 });
+		}
+		for (const project of projects) project.notes = (await store.list("project", project.cwd)).filter((entry) => entry.path !== "INDEX.md").length;
+		return projects;
+	};
+	const pruneCache = new Map();
+	const runner = new DreamRunner({
+		state,
+		config,
+		onStatus: (snapshot) => status.publish(snapshot),
+		runDream: (job) => runDream(ctx, { ...job, store }),
+		resolveSelection: () => resolveSelection(config, ctx.get("agentDefaultModel")),
+		listProjects,
+		countUserNotes: async () => (await store.list("user")).filter((entry) => entry.path !== "INDEX.md").length,
+		afterRun: () => pruneDreamSessions(join(resolveDshHome(), "sessions"), { cache: pruneCache })
+	});
+	ctx.effect(() => () => runner.stop());
+	installTrigger(ctx, {
+		idleMs: () => config.idleMinutes.get() * 60_000,
+		onEnded: (info) => {
+			runner.onSessionEnded(info).catch((error) => ctx.logger.warn("memory: could not queue session %s: %s", info.sessionId, error?.message));
+		}
+	});
+	ctx.inject(["settings"], (child) => {
+		child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
+		runner.emit();
+		status.attach(child.settings);
+		child.effect(() => () => status.detach());
+	});
+	/* Every settings change: turning memory off cancels runs in flight, and turning on auto dreaming, memory or a higher concurrency starts the waiting queue.
+	   A changed `dreamRequest` nonce from the settings page asks for a manual run over every project (after the same catch-up scan as /dream), then a cross-project run. */
+	let lastRequest = config.dreamRequest.get();
+	let wasEnabled = config.enabled.get();
+	ctx.on("loader/volatile-update", () => {
+		const enabled = config.enabled.get();
+		if (wasEnabled && !enabled) runner.cancelAll("memory was turned off");
+		wasEnabled = enabled;
+		runner.pump();
+		const request = config.dreamRequest.get();
+		if (request === lastRequest) return;
+		lastRequest = request;
+		if (request !== "" && enabled) {
+			reconcile(ctx.sessionQuery, state)
+				.catch((error) => ctx.logger.warn("memory: catch-up scan failed: %s", error?.message))
+				.then(() => runner.runManual({ cross: true }))
+				.catch((error) => ctx.logger.warn("memory: manual dreaming failed: %s", error?.message));
+		}
+	});
+	ctx.inject(["commands"], (child) => {
+		installDreamCommand(child, { config, runner, reconcile: (scope) => reconcile(ctx.sessionQuery, state, scope) });
+	});
+	const timer = setTimeout(() => {
+		if (!config.enabled.get()) return;
+		/* Sessions that ended while the app was closed, plus whatever the last run left queued, are consolidated now (when auto dreaming is on). */
+		reconcile(ctx.sessionQuery, state).then(() => {
+			runner.emit();
+			runner.pump();
+		}, (error) => ctx.logger.warn("memory: startup scan failed: %s", error?.message));
+	}, RECONCILE_DELAY_MS);
+	ctx.effect(() => () => clearTimeout(timer));
+}
+
+export { apply, inject, name, Config, EMPTY_STATUS };