pi-memoria 0.1.2 → 0.2.0

package/src/sessions.ts

@@ -25,7 +25,7 @@
 
 import { spawn } from "node:child_process";
 import { accessSync, constants, existsSync } from "node:fs";
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { basename, delimiter, join, relative, resolve, sep } from "node:path";
 import { isCjkChar, stem, tokenize } from "./tokenize.ts";
 import { oneLine, truncateChars } from "./util.ts";
@@ -765,8 +765,29 @@ export class SessionStore {
 	 */
 	async readWindow(path: string, line: number, windowSize = 6): Promise<SessionReadResult | undefined> {
 		const target = resolve(path);
-		const root = this.roots.find((candidate) => target === resolve(candidate) || target.startsWith(`${resolve(candidate)}${sep}`));
-		if (!root || !existsSync(target)) return undefined;
+		if (!target.endsWith(".jsonl")) return undefined;
+		let realTarget: string;
+		let stats;
+		try {
+			[realTarget, stats] = await Promise.all([realpath(target), stat(target)]);
+		} catch {
+			return undefined;
+		}
+		if (!stats.isFile() || stats.size > MAX_FILE_BYTES) return undefined;
+		let root: string | undefined;
+		for (const candidate of this.roots) {
+			let realRoot: string;
+			try {
+				realRoot = await realpath(candidate);
+			} catch {
+				continue;
+			}
+			if (target.startsWith(`${resolve(candidate)}${sep}`) && realTarget.startsWith(`${realRoot}${sep}`)) {
+				root = candidate;
+				break;
+			}
+		}
+		if (!root) return undefined;
 		if (!Number.isFinite(line) || line < 1) return undefined;
 		const size = Math.max(0, Math.min(40, Math.floor(windowSize)));
 		const from = Math.max(1, Math.floor(line) - size);

package/src/store.ts

@@ -5,8 +5,7 @@
  * pure and testable.
  */
 
-import { existsSync } from "node:fs";
-import { mkdir, readdir, readFile, rm, stat } from "node:fs/promises";
+import { mkdir, readdir, readFile, realpath, rm, stat } from "node:fs/promises";
 import { basename, join, relative, resolve } from "node:path";
 import { parseDateValue, splitFrontmatter, stringifyWithFrontmatter } from "./frontmatter.ts";
 import { accumulateTokens, stem, tokenize, tokenizeRaw } from "./tokenize.ts";
@@ -1090,8 +1089,8 @@ export interface MoveMemoryInput {
 	/** Target category folder. Defaults to the note's current category. */
 	category?: string;
 	/**
-	 * When the target topic already exists: true (default) merges this note into
-	 * it, false refuses and reports the conflict.
+	 * When the target topic already exists: true explicitly merges this note into
+	 * it; omitted or false refuses and reports the conflict.
 	 */
 	merge?: boolean;
 	/** Record the note's previous names as aliases of the target (default true). */
@@ -1147,17 +1146,33 @@ export async function moveMemory(
 	}
 
 	const target = await readMemoryDoc(root, targetPath);
-	if (target && input.merge === false) {
+	if (target && input.merge !== true) {
 		throw new Error(
 			`${targetRelPath} already exists (topic "${target.topic}"), so moving ${doc.relPath} there would either overwrite or mix two subjects. Re-run with merge: true to combine them, or pick a different topic.`,
 		);
 	}
 	const previousAliases = target ? normalizeAliases([...target.aliases, ...parseStringList(target.frontmatter.aliases)]) : [];
+	const historicalIds = normalizeAliases([...(target ? [doc.id] : []), ...previousAliases, ...doc.aliases].filter((alias) => alias.startsWith("mem_")));
+	if (target && historicalIds.length >= MAX_ALIASES) {
+		throw new Error(`Cannot merge ${doc.relPath}: the target has reached the ${MAX_ALIASES}-alias limit for historical ids.`);
+	}
 	const aliases = normalizeAliases([
+		...historicalIds,
+		...(target ? [doc.id] : []),
 		...previousAliases,
 		...doc.aliases,
 		...(keepAlias ? [doc.topic, doc.title, basename(doc.relPath).replace(/\.md$/i, "")] : []),
 	]);
+	const requiredAliases = [
+		...(target ? [doc.id] : []), ...previousAliases, ...doc.aliases,
+		...(keepAlias ? [doc.topic, doc.title, basename(doc.relPath).replace(/\.md$/i, "")] : []),
+	];
+	if (requiredAliases.some((alias) => {
+		const normalized = normalizeAliases([alias])[0];
+		return normalized && !aliases.some((saved) => saved.toLowerCase() === normalized.toLowerCase());
+	})) {
+		throw new Error(`Cannot move ${doc.relPath}: keeping its former names would exceed the ${MAX_ALIASES}-alias limit.`);
+	}
 	const aliasesAdded = aliases.filter((alias) => !previousAliases.some((previous) => previous.toLowerCase() === alias.toLowerCase()));
 
 	if (target) {
@@ -1173,14 +1188,28 @@ export async function moveMemory(
 		}
 		const tags = [...new Set([...target.tags, ...doc.tags])];
 		const priority = priorityRank(doc.priority) > priorityRank(target.priority) ? doc.priority : target.priority;
+		const related = normalizeLinks([...target.related, ...doc.related]);
+		const supersedes = normalizeLinks([...target.supersedes, ...doc.supersedes]);
+		const linksFit = (required: string[], saved: string[]): boolean => required.every((link) => {
+			const normalized = normalizeLinks([link])[0];
+			return !normalized || saved.some((entry) => entry.toLowerCase() === normalized.toLowerCase());
+		});
+		if (!linksFit([...target.related, ...doc.related], related) || !linksFit([...target.supersedes, ...doc.supersedes], supersedes)) {
+			throw new Error(`Cannot merge ${doc.relPath}: keeping its links would exceed the ${MAX_LINKS}-link limit.`);
+		}
+		// The journal must exist before the target changes. Recovery only removes
+		// the source after it verifies that the target contains all its facts and
+		// its former id; an interrupted target write therefore cannot lose data.
+		await writeJournal(root, { op: "move", from: doc.relPath, to: target.relPath, merge: true, at: Date.now() });
 		const updated = await updateMemory(root, target, {
 			content: body,
 			tags,
 			aliases,
+			related,
+			supersedes,
 			summary: extendSummary(target.summary, doc.summary),
 			priority,
 		});
-		await writeJournal(root, { op: "move", from: doc.relPath, to: updated.relPath, at: Date.now() });
 		const trashPath = await deleteMemory(root, doc);
 		await clearJournal(root).catch(() => {});
 		return { ...base, doc: updated, moved: true, merged: mergedFacts > 0, aliasesAdded, trashPath };
@@ -1238,6 +1267,8 @@ export function countFacts(body: string): number {
 
 export interface MoveJournalEntry {
 	op: "move";
+	/** A merge keeps the target id and must be verified before source removal. */
+	merge?: boolean;
 	/** Relative path of the source file. */
 	from: string;
 	/** Relative path of the destination file. */
@@ -1259,7 +1290,10 @@ export async function readJournal(root: string): Promise<MoveJournalEntry | unde
 	if (!raw) return undefined;
 	try {
 		const parsed = JSON.parse(raw) as MoveJournalEntry;
-		if (parsed && parsed.op === "move" && typeof parsed.from === "string" && typeof parsed.to === "string") return parsed;
+		const safe = (path: string): boolean => isIndexableRelPath(path)
+			&& !path.split("/").some((part) => part === "." || part === ".." || !part);
+		if (parsed && parsed.op === "move" && typeof parsed.from === "string" && typeof parsed.to === "string"
+			&& safe(parsed.from) && safe(parsed.to)) return parsed;
 	} catch {
 		// A corrupt journal is not worth failing over; the files themselves are
 		// authoritative and doctor reports duplicate ids.
@@ -1278,16 +1312,22 @@ export async function clearJournal(root: string): Promise<void> {
 export async function recoverJournal(root: string): Promise<string | undefined> {
 	const entry = await readJournal(root);
 	if (!entry) return undefined;
-	const fromPath = join(root, entry.from);
-	const toPath = join(root, entry.to);
+	const fromPath = await safeMemoryPath(root, entry.from);
+	const toPath = await safeMemoryPath(root, entry.to);
 	let recovered: string | undefined;
-	if (existsSync(fromPath) && existsSync(toPath)) {
+	if (fromPath && toPath) {
+		const [source, target] = await Promise.all([readMemoryDoc(root, fromPath), readMemoryDoc(root, toPath)]);
+		const complete = source && target && (entry.merge
+			? target.aliases.includes(source.id) && extractFactUnits(source.body).every((unit) => !appendFact(target.body, unit.label, unit.text).changed)
+			: source.id === target.id);
+		if (!complete) return `interrupted move kept source ${entry.from}: target is incomplete`;
 		await moveToTrash(fromPath, join(root, TRASH_DIR, "moved")).then(
 			() => {
 				recovered = `completed interrupted move ${entry.from} -> ${entry.to}`;
 			},
 			() => undefined,
 		);
+		if (!recovered) return undefined;
 	}
 	await clearJournal(root).catch(() => {});
 	return recovered;
@@ -1320,9 +1360,36 @@ export async function readHot(root: string, limit: number): Promise<HotState> {
 	return { path, content, chars, limit, over: chars > limit, exists: true };
 }
 
-/** Write MEMORY.md atomically. Callers enforce/validate the budget. */
-export async function writeHot(root: string, content: string): Promise<void> {
-	await atomicWriteFile(join(root, HOT_FILE), content.endsWith("\n") ? content : `${content}\n`);
+/** Validate the complete briefing, without silently cutting or removing facts.
+ * Semantic eligibility and correction checks remain the calling agent's job.
+ * The legacy empty/template title is accepted and removed during migration.
+ */
+export function validateHot(content: string, limit = 5000): string {
+	const prose = content.replace(/^# Memory[ \t]*(?:\r?\n|$)/, "").trim();
+	if (/^\s*(?:#{1,6}\s|[-*+]\s|\d+[.)]\s|>|```|~~~|\|)/m.test(prose) || /<!--|-->/.test(prose)) {
+		throw new Error("MEMORY.md must be plain prose: no headings, lists, tables, code fences or annotations.");
+	}
+	const normalized = prose ? `${prose}\n` : "";
+	if (normalized.length > limit) throw new Error(`MEMORY.md exceeds its ${limit}-character budget. Rewrite more tightly; no content was saved or truncated.`);
+	const seen = new Set<string>();
+	for (const paragraph of normalized.split(/\n\s*\n/)) for (const unit of splitHotUnits(paragraph)) {
+		const key = unit.toLowerCase().replace(/\s+/g, " ").trim();
+		if (key && seen.has(key)) throw new Error("MEMORY.md contains a repeated sentence. Consolidate it before saving.");
+		seen.add(key);
+	}
+	return normalized;
+}
+
+/** All supported briefing writes validate first and preserve the previous version. */
+export async function writeHot(root: string, content: string, limit = 5000): Promise<void> {
+	const next = validateHot(content, limit);
+	const path = join(root, HOT_FILE);
+	const previous = await readFileOrUndefined(path);
+	if (previous === next) return;
+	if (previous !== undefined) {
+		await atomicWriteFile(join(root, ".history", `${newMemoryId()}-MEMORY.md`), previous);
+	}
+	await atomicWriteFile(path, next);
 }
 
 /**
@@ -1426,7 +1493,8 @@ export interface HotAddResult {
  * marker or anchor text is ever written into the file.
  */
 export function addHotEntry(content: string, text: string, topic?: string): HotAddResult {
-	const sentence = oneLine(text, 1200).replace(/^[-*]\s*/, "").trim();
+	validateHot(text, Number.MAX_SAFE_INTEGER);
+	const sentence = oneLine(text).trim();
 	if (!sentence) return { content, changed: false, paragraph: "", created: false };
 	const blocks = splitHotParagraphs(content);
 	const title = blocks.find(isTitleBlock);
@@ -1602,7 +1670,7 @@ export async function ensureStore(root: string, hotLimit: number, defaultCategor
 	await mkdir(join(root, LIBRARY_DIR, defaultCategory), { recursive: true });
 	await mkdir(join(root, INDEX_DIR), { recursive: true });
 	const hot = await readHot(root, hotLimit);
-	if (!hot.exists) await writeHot(root, hotTemplate());
+	if (!hot.exists) await writeHot(root, hotTemplate(), hotLimit);
 }
 
 /** Resolve a user-supplied memory reference (id, alias, relative path, or absolute path). */
@@ -1614,8 +1682,8 @@ export async function resolveMemoryRef(
 	const trimmed = ref.trim();
 	if (!trimmed) return undefined;
 	if (trimmed.endsWith(".md")) {
-		const candidate = trimmed.startsWith("/") ? trimmed : resolve(root, trimmed);
-		const direct = await readMemoryDoc(root, candidate);
+		const candidate = await safeMemoryPath(root, trimmed);
+		const direct = candidate ? await readMemoryDoc(root, candidate) : undefined;
 		if (direct) return direct;
 	}
 	const needle = trimmed.toLowerCase();
@@ -1631,11 +1699,24 @@ export async function resolveMemoryRef(
 	return undefined;
 }
 
-/** Read a range of lines from a file path inside the store, guarding traversal. */
+/** Resolve only note files inside this store, including through symlinks. */
+async function safeMemoryPath(root: string, ref: string): Promise<string | undefined> {
+	const target = resolve(root, ref);
+	if (!isIndexableRelPath(normalizePath(relative(root, target)))) return undefined;
+	try {
+		const [realRoot, realTarget] = await Promise.all([realpath(root), realpath(target)]);
+		if (!isIndexableRelPath(normalizePath(relative(realRoot, realTarget)))) return undefined;
+		return target;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+/** Read a memory file inside this store, guarding traversal and symlinks. */
 export async function readStoreFile(root: string, relOrAbs: string, maxChars = 40_000): Promise<{ path: string; content: string; truncated: boolean }> {
-	const target = relOrAbs.startsWith("/") ? relOrAbs : resolve(root, relOrAbs);
-	const normalizedRoot = resolve(root);
-	if (!normalizePath(target).startsWith(normalizePath(normalizedRoot))) {
+	const target = await safeMemoryPath(root, relOrAbs);
+	if (!target) {
 		throw new Error(`Refusing to read outside the memoria root: ${relOrAbs}`);
 	}
 	const content = await readFile(target, "utf8");

package/src/tools.ts

@@ -6,8 +6,6 @@
  * returned when explicitly requested.
  */
 
-import { readFile } from "node:fs/promises";
-import { isAbsolute, resolve } from "node:path";
 import { Type } from "typebox";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
@@ -15,12 +13,9 @@ import type { MemoriaRuntime } from "./runtime.ts";
 import { readStoreFile } from "./store.ts";
 import { renderSessionFallback, ripgrepNotice } from "./recall.ts";
 import { formatSessionTime } from "./sessions.ts";
-import { atomicWriteFile, oneLine, truncateChars } from "./util.ts";
+import { oneLine, truncateChars } from "./util.ts";
 import type { Priority, Scope, SearchHit, SessionScanStats } from "./types.ts";
 
-/** Inline export/import payload cap; larger dumps must use a file path. */
-const MAX_INLINE_TRANSFER_CHARS = 60_000;
-
 export type RuntimeGetter = (ctx: ExtensionContext) => Promise<MemoriaRuntime>;
 
 const ScopeEnum = Type.Union([Type.Literal("primary"), Type.Literal("all"), Type.Literal("project"), Type.Literal("global")], {
@@ -103,7 +98,7 @@ const WriteParams = Type.Object({
 const HotParams = Type.Object({
 	action: Type.Union([Type.Literal("add"), Type.Literal("remove"), Type.Literal("replace"), Type.Literal("read"), Type.Literal("compact")], {
 		description:
-			"add: append a sentence to a theme paragraph. remove: delete every sentence containing a substring. replace: rewrite the whole file as prose. read: show it. compact: trim to the character budget.",
+			"add: append a sentence to a theme paragraph. remove: delete every sentence containing a substring. replace: rewrite the whole file as prose. read: show it. compact: check the budget without deleting facts; if oversized, use replace with a tighter supported briefing.",
 	}),
 	topic: Type.Optional(
 		Type.String({
@@ -138,7 +133,7 @@ const MoveParams = Type.Object({
 	category: Type.Optional(Type.String({ description: "Target category folder. Defaults to the note's current category." })),
 	merge: Type.Optional(
 		Type.Boolean({
-			description: "When a note already exists at the target topic: true (default) folds this note's facts into it, false refuses so you can choose another topic.",
+			description: "When a note already exists at the target topic: set true to fold this note's facts into it. Omitted or false refuses the merge.",
 		}),
 	),
 	keep_alias: Type.Optional(Type.Boolean({ description: "Record the note's previous topic and file name as aliases of the target (default true)." })),
@@ -169,29 +164,6 @@ const SessionsParams = Type.Object({
 	window: Type.Optional(Type.Number({ description: "For action=read: messages of context on each side (default 6, max 40)." })),
 });
 
-const ExportParams = Type.Object({
-	path: Type.Optional(
-		Type.String({
-			description: "Write the JSONL dump to this file (absolute, or relative to the working directory). Without it a bounded preview is returned inline.",
-		}),
-	),
-	include_hot: Type.Optional(Type.Boolean({ description: "Include MEMORY.md as a record (default true)." })),
-	scope: Type.Optional(ScopeEnum),
-});
-
-const ImportParams = Type.Object({
-	path: Type.Optional(Type.String({ description: "JSONL file to import (absolute, or relative to the working directory)." })),
-	content: Type.Optional(Type.String({ description: "Inline JSONL content. Prefer `path` for anything larger than a few notes." })),
-	mode: Type.Optional(
-		Type.Union([Type.Literal("merge"), Type.Literal("replace"), Type.Literal("skip")], {
-			description:
-				"merge (default): add facts that are missing from a note with the same id. replace: overwrite notes with the same id. skip: only import notes that do not exist yet.",
-		}),
-	),
-	dry_run: Type.Optional(Type.Boolean({ description: "Report what would happen without writing anything." })),
-	scope: Type.Optional(ScopeEnum),
-});
-
 const ForgetParams = Type.Object({
 	id: Type.String({ description: "Memory id to remove. The file is moved to .trash/ rather than deleted." }),
 	scope: Type.Optional(ScopeEnum),
@@ -238,10 +210,10 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 		name: "memoria_recall",
 		label: "Recalling memories",
 		description:
-			"Search long-term memory (the memoria library) for anything the user has said or that was learned in past sessions. Use this before answering questions about people, preferences, projects, decisions, past incidents or anything possibly stored earlier. Returns ranked notes with ids, paths and excerpts; call memoria_read for full text.",
-		promptSnippet: "memoria_recall: search long-term memory before answering anything possibly known from before",
+			"Search long-term memory (the memoria library) for anything the user has said or that was learned in past sessions. Use when evidence already recalled into context is insufficient for a question about prior facts. Returns ranked notes with ids, paths and excerpts; call memoria_read for full text.",
+		promptSnippet: "memoria_recall: search prior facts when recalled context is insufficient",
 		promptGuidelines: [
-			"Call memoria_recall before answering questions about people, preferences, projects, decisions or prior conversations.",
+			"Use relevant recalled context directly; call memoria_recall when it is insufficient.",
 			"Never say you do not remember without calling memoria_recall first.",
 			"Use memoria_recall with several focused queries when a first search returns nothing but the topic is likely stored.",
 		],
@@ -433,7 +405,7 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 				lines.push(`NOTE: ${result.topicNote}. Prefer a broad grouping name so related facts stay together.`);
 			}
 			lines.push(
-				`MEMORY.md is at ${hot.chars}/${hot.limit} chars${hot.over ? ' (OVER BUDGET — run memoria_hot { action: "compact" } or move detail into the library)' : ""}.`,
+				`MEMORY.md is at ${hot.chars}/${hot.limit} chars${hot.over ? ' (OVER BUDGET — rewrite with memoria_hot { action: "replace" } or move detail into the library)' : ""}.`,
 			);
 			// Housekeeping hints are best-effort: a failure must not fail the write.
 			try {
@@ -498,6 +470,8 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 			"MEMORY.md is loaded on every request, so it is only for facts that pay off that often: identity, timezone/locale, communication style, hard constraints, and the current state of active work.",
 			"Write MEMORY.md as a short, natural introduction to the user plus their standing context. Sentences and paragraphs only — no headings, no bullet lists, no 'Topic — fact' labels.",
 			"Keep occasional details (URLs, versions, file paths, history, rationale) in library notes; recall finds them when needed.",
+			"Before every edit, read the briefing. Consolidate existing statements instead of appending paraphrases. Apply explicit corrections in place; ask about ambiguous conflicts. Preserve unrelated standing facts. Eligibility and factual correctness require your judgment; deterministic validation cannot establish truth.",
+			"Do not repeat skill instructions or dated maintenance history. Every statement must be supported by the user or verified evidence.",
 			"When MEMORY.md grows past a few paragraphs, rewrite it tighter with memoria_hot { action: \"replace\" } and file the dropped detail into the library rather than appending forever.",
 		],
 		parameters: HotParams,
@@ -552,7 +526,7 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 					return {
 						content: text(
 							`MEMORY.md compacted: ${result.before} → ${result.after}/${runtime.config.hotLimit} chars.${
-								result.before === result.after ? " Already under budget." : " Least-important trailing paragraphs were dropped. Next time prefer action=replace with a tighter summary."
+								result.before === result.after ? " Already under budget." : " No facts are automatically dropped."
 							}${dropped}`,
 						),
 						details: { kind: "hot", chars: result.after, limit: runtime.config.hotLimit },
@@ -807,105 +781,6 @@ export function registerMemoriaTools(pi: ExtensionAPI, getRuntime: RuntimeGetter
 		},
 	});
 
-	pi.registerTool<typeof ExportParams, { kind: string; notes?: number; bytes?: number; path?: string }, unknown>({
-		name: "memoria_export",
-		label: "Exporting memories",
-		description:
-			"Export the memory store as JSONL (one record per line: notes plus MEMORY.md) for backup or migration. With `path` the full dump is written to that file; without it a bounded preview is returned. Pair with memoria_import to restore.",
-		promptSnippet: "memoria_export: dump the memory store to JSONL for backup or migration",
-		parameters: ExportParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx): Promise<AgentToolResult<any>> {
-			const runtime = await getRuntime(ctx);
-			const { jsonl, notes } = await runtime.exportJsonl({
-				scope: (params.scope as Scope | undefined) ?? "all",
-				includeHot: params.include_hot !== false,
-			});
-			if (params.path) {
-				const target = isAbsolute(params.path) ? params.path : resolve(ctx.cwd, params.path);
-				await atomicWriteFile(target, jsonl);
-				return {
-					content: text(`Exported ${notes} note(s) to ${target} (${jsonl.length} bytes of JSONL).`),
-					details: { kind: "export", notes, bytes: jsonl.length, path: target },
-				};
-			}
-			const preview = truncateChars(jsonl, MAX_INLINE_TRANSFER_CHARS);
-			const truncated = jsonl.length > preview.length;
-			return {
-				content: text(
-					`${notes} note(s) exported (${jsonl.length} bytes).${truncated ? `\n\nInline preview truncated at ${MAX_INLINE_TRANSFER_CHARS} chars; pass \`path\` to write the complete dump.` : ""}\n\n${preview}`,
-				),
-				details: { kind: "export", notes, bytes: jsonl.length },
-			};
-		},
-		renderCall(args, theme) {
-			return new Text(theme.fg("toolTitle", theme.bold("memoria_export ")) + theme.fg("dim", args.path ?? "inline preview"), 0, 0);
-		},
-		renderResult(result, _options, theme) {
-			const details = result.details as { notes?: number; path?: string } | undefined;
-			return new Text(theme.fg("success", `✓ exported ${details?.notes ?? 0} notes`) + theme.fg("dim", details?.path ? ` → ${details.path}` : ""), 0, 0);
-		},
-	});
-
-	pi.registerTool<typeof ImportParams, { kind: string; created?: number; updated?: number; skipped?: number; errors?: number }, unknown>({
-		name: "memoria_import",
-		label: "Importing memories",
-		description:
-			"Import notes from a JSONL file (or inline content) produced by memoria_export. Never overwrites an existing note unless mode=replace: merge adds only the facts that are missing, and a path already taken by another note gets a numbered sibling. Use dry_run first on an unfamiliar file.",
-		promptSnippet: "memoria_import: restore memories from a JSONL export",
-		promptGuidelines: [
-			"Run memoria_import with dry_run: true first when importing a file you did not create.",
-			"Prefer mode=merge (the default) when importing into a store that already has memories.",
-		],
-		parameters: ImportParams,
-		executionMode: "sequential",
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx): Promise<AgentToolResult<any>> {
-			const runtime = await getRuntime(ctx);
-			let payload = params.content ?? "";
-			if (params.path) {
-				const target = isAbsolute(params.path) ? params.path : resolve(ctx.cwd, params.path);
-				const file = await readFile(target, "utf8");
-				if (file.length > 20_000_000) throw new Error(`Refusing to import ${file.length} chars; split the file first.`);
-				payload = payload ? `${file}\n${payload}` : file;
-			}
-			if (!payload.trim()) throw new Error("Nothing to import: pass `path` or `content`.");
-			const result = await runtime.importJsonl(payload, {
-				mode: (params.mode as "merge" | "replace" | "skip" | undefined) ?? "merge",
-				scope: (params.scope as Scope | undefined) ?? "primary",
-				dryRun: params.dry_run === true,
-			});
-			const lines = [
-				`${params.dry_run ? "Dry run: would import" : "Imported"} ${result.created.length} new note(s), updated ${result.updated.length}, skipped ${result.skipped}.`,
-			];
-			if (result.hotImported) lines.push("MEMORY.md was restored from the export.");
-			if (result.errors.length > 0) lines.push(`Skipped ${result.errors.length} malformed record(s):\n${result.errors.slice(0, 10).join("\n")}`);
-			return {
-				content: text(lines.join("\n")),
-				details: {
-					kind: "import",
-					created: result.created.length,
-					updated: result.updated.length,
-					skipped: result.skipped,
-					errors: result.errors.length,
-				},
-			};
-		},
-		renderCall(args, theme) {
-			return new Text(
-				theme.fg("toolTitle", theme.bold("memoria_import ")) + theme.fg("accent", oneLine(args.path ?? "inline", 60)) + theme.fg("dim", args.mode ? ` (${args.mode})` : ""),
-				0,
-				0,
-			);
-		},
-		renderResult(result, _options, theme) {
-			const details = result.details as { created?: number; updated?: number; skipped?: number } | undefined;
-			return new Text(
-				theme.fg("success", `✓ +${details?.created ?? 0} ~${details?.updated ?? 0}`) + theme.fg("dim", ` skipped ${details?.skipped ?? 0}`),
-				0,
-				0,
-			);
-		},
-	});
-
 	pi.registerTool<typeof ForgetParams, { kind: string; id?: string; trash?: string }, unknown>({
 		name: "memoria_forget",
 		label: "Forgetting a memory",

package/src/types.ts

@@ -349,6 +349,8 @@ export interface MemoriaConfig {
 	/** Auto-recall tuning. */
 	autoRecall: boolean;
 	autoRecallLimit: number;
+	/** Minimum fraction of the strongest eligible score for automatic recall. */
+	autoRecallMinRatio: number;
 	autoRecallMinScore: number;
 	autoRecallMaxChars: number;
 	/** Number of previous user turns folded into the recall query. */
@@ -402,16 +404,6 @@ export interface MemoriaConfig {
 	rerankTopK: number;
 	/** Reranker budget in milliseconds; falls back to lexical order on timeout. */
 	rerankTimeoutMs: number;
-	/** Automatic session extraction: off, on-settle (idle) or on-shutdown. */
-	autoLearn: string;
-	/** Minimum user turns before auto-learn considers a session. */
-	autoLearnMinTurns: number;
-	/** Minimum transcript characters before auto-learn considers a session. */
-	autoLearnMinChars: number;
-	/** Minimum time between automatic extractions. */
-	autoLearnCooldownMs: number;
-	/** Characters per extraction chunk when harvesting a session. */
-	learnChunkChars: number;
 	/** Idle delay after a filesystem event before refreshing the index. */
 	watcherSettleMs: number;
 	/** Index persistence format: auto (binary above a threshold), json or binary. */

package/src/usage.ts

@@ -34,6 +34,7 @@ function coerceEntry(raw: unknown): UsageEntry | undefined {
 export class UsageStore {
 	private docs = new Map<string, UsageEntry>();
 	private changed = false;
+	private saving?: Promise<void>;
 	private lastSessionAt = 0;
 
 	constructor(root: string) {
@@ -137,10 +138,23 @@ export class UsageStore {
 	}
 
 	async save(): Promise<void> {
+		if (this.saving) {
+			await this.saving;
+			return this.save();
+		}
 		if (!this.changed) return;
 		this.changed = false;
 		const payload: UsageFile = { version: USAGE_VERSION, docs: Object.fromEntries(this.docs), lastSessionAt: this.lastSessionAt };
-		await atomicWriteFile(join(this.root, INDEX_DIR, USAGE_FILE), JSON.stringify(payload));
+		const saving = atomicWriteFile(join(this.root, INDEX_DIR, USAGE_FILE), JSON.stringify(payload));
+		this.saving = saving;
+		try {
+			await saving;
+		} catch (error) {
+			this.changed = true;
+			throw error;
+		} finally {
+			if (this.saving === saving) this.saving = undefined;
+		}
 	}
 
 	/** Notes with no recorded use in `staleMs`, oldest first. */

package/src/util.ts

@@ -92,8 +92,8 @@ export function debounce<A extends unknown[]>(fn: (...args: A) => void, waitMs:
 export async function atomicWriteFile(path: string, data: string | Uint8Array): Promise<void> {
 	await mkdir(dirname(path), { recursive: true });
 	const tmp = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
-	await (typeof data === "string" ? writeFile(tmp, data, "utf8") : writeFile(tmp, data));
 	try {
+		await (typeof data === "string" ? writeFile(tmp, data, "utf8") : writeFile(tmp, data));
 		await rename(tmp, path);
 	} catch (error) {
 		await rm(tmp, { force: true }).catch(() => {});
@@ -132,7 +132,10 @@ export async function moveToTrash(path: string, trashDir: string): Promise<strin
 	await mkdir(trashDir, { recursive: true });
 	const base = path.split("/").pop() ?? "memory.md";
 	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-	const target = join(trashDir, `${stamp}__${base}`);
+	// Different categories can contain the same basename and be removed within
+	// one millisecond. A random suffix prevents rename() from replacing the
+	// earlier trashed file on POSIX filesystems.
+	const target = join(trashDir, `${stamp}_${randomBytes(8).toString("hex")}__${base}`);
 	await rename(path, target);
 	return target;
 }