pi-memoria 0.1.2 → 0.1.3

package/README.md

@@ -1,4 +1,4 @@
-# memoria
+# pi-memoria
 
 Agent-first long-term memory for [pi](https://github.com/badlogic/pi-mono).
 
@@ -17,8 +17,8 @@ a millisecond.
 - **Broad topics, never fact files.** `likes-apples.md` is a defect; facts
   accumulate in `food-preferences.md`.
 - **Names are handles.** Aliases make every nickname, full name or former name
-  resolve to the same note, and notes can be re-filed later without breaking
-  references.
+  resolve to the same note. Re-filing or consolidating notes also keeps retired
+  note ids usable as references.
 - **Zero runtime dependencies.** No database, no server, no embedding service, no
   build step. Retrieval is a BM25 index kept in memory.
 
@@ -83,11 +83,11 @@ Pi discovers `extensions/memoria/index.ts` on the next start (or after
 ### Install as a pi package
 
 ```bash
-pi install git:github.com/rcsaquino/pi-memoria@v0.1.1
+pi install git:github.com/rcsaquino/pi-memoria@v0.1.3
 pi install npm:pi-memoria                 # if published to npm
 pi install ./path/to/pi-memoria           # or from a local checkout
 pi list
-pi remove git:github.com/rcsaquino/pi-memoria@v0.1.1
+pi remove git:github.com/rcsaquino/pi-memoria@v0.1.3
 ```
 
 `pi install` records the package in `~/.pi/agent/settings.json` (or
@@ -233,9 +233,10 @@ When the better name *is* known, `memoria_move` re-files the note:
 
 - Target free → the file is **renamed**; the note keeps its `id`, so ids read
   earlier in the session stay valid.
-- Target exists → facts are **merged** in (duplicates skipped, nothing
-  overwritten) and the old file goes to `.trash/`. `merge: false` reports the
-  conflict instead.
+- Target exists → the move reports a conflict. Set `merge: true` to combine the
+  facts and links (duplicates skipped, nothing overwritten) and move the old
+  file to `.trash/`. A merge refuses to discard aliases or links when their
+  limits are full.
 - The previous topic, title and file name are added to the target's aliases, so
   old references keep working.
 
@@ -308,7 +309,7 @@ folder). Unknown keys are preserved verbatim through updates.
 | `memoria_recall` | Search long-term memory. Filters by category, tags, priority, recency, scope; options for `include_body`, `min_score`, `explain`, `rerank`, `drop_superseded`, prefix/fuzzy control. |
 | `memoria_write` | Add a fact to a broad **topic note** (`topic`, `content`, optional `label`, category, tags, aliases, related, supersedes, summary, priority). Creates the note on first use and appends afterwards. |
 | `memoria_read` | Read a full note by id, path or alias, with its aliases, related notes and superseding notes. |
-| `memoria_move` | Re-file a note under a better broad topic (`from`, `topic`, optional `category`, `merge`, `keep_alias`). Renames when the target is free, merges when it is not. |
+| `memoria_move` | Re-file a note under a better broad topic (`from`, `topic`, optional `category`, `merge`, `keep_alias`). Renames when the target is free; set `merge: true` to combine with an occupied target. |
 | `memoria_sessions` | Search the transcripts of earlier conversations (`action: "search"`, plus `since_days`, `project`, `include_tools`, `user_only`) and read the surrounding dialogue (`action: "read"`, `path`, `line`, `window`) before quoting it. |
 | `memoria_hot` | Read/add/remove/replace/compact `MEMORY.md`, the always-in-context briefing. |
 | `memoria_list` | Browse categories, titles, ids, tags, aliases and summaries. |
@@ -326,7 +327,7 @@ have to ask.
 /memoria search <query>      Ranked results with snippets (--primary/--project/--all)
 /memoria store <text>        Quick capture into library/inbox
 /memoria read <id|path>      Print a full note
-/memoria move <ref> <topic>  Re-file a note under a better broad topic
+/memoria move <ref> <topic> [--merge]  Re-file a note; opt into merging an occupied target
 /memoria hot                 Show MEMORY.md
 /memoria topics              Review notes: facts, size, usage, merge candidates
 /memoria diff [days]         Memories created or updated recently (default 7 days)
@@ -571,10 +572,13 @@ a burst of edits costs one refresh.
 - **Files, not a database.** Memoria never owns your data: notes are markdown
   with frontmatter, deletes are soft (moved to `.trash/`), and the index is
   derived and can be rebuilt with `/memoria reindex`.
-- **Crash-safe moves.** Category moves and renames are journaled, so an
-  interrupted move is completed on the next start instead of leaving two copies.
+- **Crash-safe moves.** Category moves, renames and merges are journaled. On
+  restart, a merge only removes its source after the target has all its facts
+  and the source's former id.
 - **Atomic writes.** Every write goes through a temp file and rename; there is no
   window where a note is half-written.
+- **Scoped reads.** `memoria_read` only follows paths inside the memory library;
+  transcript window reads refuse paths or symlinks outside configured roots.
 - **Secrets:** memoria does not scan for credentials, and the learn prompt tells
   the model not to store them. If you keep secrets in the store anyway, remember
   that recall may surface them in model context — treat the store like your shell
@@ -600,7 +604,7 @@ a burst of edits costs one refresh.
 
 ```bash
 npm install            # dev-only: pi host packages + typescript
-npm test               # 144 tests, node:test, no build step
+npm test               # node:test, no build step
 npm run typecheck      # tsc --noEmit
 npm run eval           # recall@1/@5/MRR over the fixture corpus
 npm run bench          # latency at 1k and 5k notes
@@ -647,8 +651,8 @@ src/commands.ts     /memoria subcommands
    `"optional": true` in `peerDependenciesMeta`, keeping them in
    `devDependencies` for local tests only. Without that, npm installs a ~450 MB
    duplicate of pi into the package.
-4. Tag releases (`git tag v0.1.1 && git push --tags`) and install by tag:
-   `pi install git:github.com/<you>/pi-memoria@v0.1.1`.
+4. Tag releases (`git tag v<version> && git push --tags`) and install by tag:
+   `pi install git:github.com/<you>/pi-memoria@v<version>`.
 5. `npm pack --dry-run` should list only `index.ts`, `src/**`, `skills/**`,
    `README.md`, `LICENSE` and `package.json`.
 

package/index.ts

@@ -29,14 +29,14 @@ import { RECALL_CUSTOM_TYPE, buildRecallParts, renderRecallBlock, renderStatusLi
 import { buildTranscriptText, harvestSession } from "./src/learn.ts";
 import { createModelReranker } from "./src/rerank.ts";
 import { tokenizeRaw } from "./src/tokenize.ts";
-import { oneLine } from "./src/util.ts";
+import { KeyedMutex, oneLine } from "./src/util.ts";
 
 const RECENT_PROMPT_LIMIT = 6;
 
 export default function memoria(pi: ExtensionAPI) {
 	let runtime: MemoriaRuntime | undefined;
 	let runtimeCwd: string | undefined;
-	let initPromise: Promise<void> | undefined;
+	const runtimeLock = new KeyedMutex();
 	let hotCache: { content: string; chars: number; limit: number; over: boolean; mtimeMs: number } | undefined;
 	let recentPrompts: string[] = [];
 	/** The missing-ripgrep warning is shown once per session, not on every prompt. */
@@ -47,27 +47,31 @@ export default function memoria(pi: ExtensionAPI) {
 	let learnInFlight = false;
 
 	/** Resolve (and lazily initialize) the runtime for this working directory. */
-	const getRuntime = async (ctx: ExtensionContext): Promise<MemoriaRuntime> => {
+	const getRuntime = (ctx: ExtensionContext): Promise<MemoriaRuntime> => runtimeLock.run("runtime", async () => {
 		if (!runtime || runtimeCwd !== ctx.cwd) {
-			await runtime?.dispose().catch(() => {});
+			const previous = runtime;
+			runtime = undefined;
+			runtimeCwd = undefined;
+			await previous?.dispose().catch(() => {});
 			// Follow pi's own agent directory (honours PI_CODING_AGENT_DIR) so the
 			// store lives at `<agent dir>/memoria`.
-			runtime = new MemoriaRuntime(ctx.cwd, { agentDir: getAgentDir() });
+			const next = new MemoriaRuntime(ctx.cwd, { agentDir: getAgentDir() });
+			try {
+				await next.init(true);
+			} catch (error) {
+				await next.dispose().catch(() => {});
+				throw error;
+			}
+			runtime = next;
 			runtimeCwd = ctx.cwd;
 			hotCache = undefined;
 			recentPrompts = [];
 			turnsSinceLearn = 0;
 			lastLearnAt = 0;
 			learnInFlight = false;
-			initPromise = runtime.init(true).catch((error) => {
-				// Allow a later attempt to retry instead of caching the rejection forever.
-				initPromise = undefined;
-				throw error;
-			});
 		}
-		await initPromise;
 		return runtime;
-	};
+	});
 
 	/** Read MEMORY.md, reusing the cached copy until its mtime changes. */
 	const readHotCached = async (memoria: MemoriaRuntime): Promise<{ content: string; chars: number; limit: number; over: boolean }> => {
@@ -237,13 +241,14 @@ export default function memoria(pi: ExtensionAPI) {
 		} catch {
 			// Shutdown must never throw.
 		}
-		await runtime?.flushUsageNow().catch(() => {});
-		await runtime?.dispose().catch(() => {});
-		runtime = undefined;
-		runtimeCwd = undefined;
-		initPromise = undefined;
-		hotCache = undefined;
-		recentPrompts = [];
+		await runtimeLock.run("runtime", async () => {
+			await runtime?.flushUsageNow().catch(() => {});
+			await runtime?.dispose().catch(() => {});
+			runtime = undefined;
+			runtimeCwd = undefined;
+			hotCache = undefined;
+			recentPrompts = [];
+		});
 	});
 
 	pi.registerMessageRenderer(RECALL_CUSTOM_TYPE, (message, options, theme) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-memoria",
-	"version": "0.1.2",
+	"version": "0.1.3",
 	"description": "Agent-first long-term memory for pi: a categorized markdown library with automatic, sub-millisecond recall.",
 	"type": "module",
 	"license": "MIT",

package/src/commands.ts

@@ -26,7 +26,7 @@ const SUBCOMMANDS: Array<{ value: string; label: string; description: string }>
 	{ value: "search", label: "search <query>", description: "Search long-term memory" },
 	{ value: "store", label: "store <text>", description: "Quickly save a memory to the inbox" },
 	{ value: "read", label: "read <id|path>", description: "Read a full memory note" },
-	{ value: "move", label: "move <ref> <topic>", description: "Re-file a note under a better broad topic" },
+	{ value: "move", label: "move <ref> <topic> [--merge]", description: "Re-file a note under a better broad topic" },
 	{ value: "hot", label: "hot", description: "Show MEMORY.md and its budget" },
 	{ value: "reindex", label: "reindex", description: "Rebuild the search index from disk" },
 	{ value: "index", label: "index", description: "Regenerate library/INDEX.md table of contents" },
@@ -183,12 +183,13 @@ export function registerMemoriaCommand(pi: ExtensionAPI, getRuntime: RuntimeGett
 				}
 				case "move": {
 					const [ref, ...rest] = remainder.split(/\s+/).filter(Boolean);
-					const topic = rest.join(" ").trim();
+					const merge = rest.includes("--merge");
+					const topic = rest.filter((word) => word !== "--merge").join(" ").trim();
 					if (!ref || !topic) {
-						ctx.ui.notify("Usage: /memoria move <id|path|alias> <new broad topic>", "warning");
+						ctx.ui.notify("Usage: /memoria move <id|path|alias> <new broad topic> [--merge]", "warning");
 						return;
 					}
-					const moved = await runtime.move(ref, { topic }, "all");
+					const moved = await runtime.move(ref, { topic, merge }, "all");
 					if (!moved) {
 						ctx.ui.notify(`Memory not found: ${ref}`, "error");
 						return;
@@ -272,7 +273,7 @@ export function registerMemoriaCommand(pi: ExtensionAPI, getRuntime: RuntimeGett
 						lines.push("**Merge candidates** (same subject, two files):");
 						for (const merge of merges) {
 							lines.push(
-								`- \`${merge.a.relPath}\` ↔ \`${merge.b.relPath}\` (${Math.round(merge.score * 100)}% overlap: ${merge.shared.join(", ")}) → \`/memoria move ${merge.b.id} ${merge.a.title}\``,
+								`- \`${merge.a.relPath}\` ↔ \`${merge.b.relPath}\` (${Math.round(merge.score * 100)}% overlap: ${merge.shared.join(", ")}) → \`/memoria move ${merge.b.id} ${merge.a.title} --merge\``,
 							);
 						}
 					}

package/src/index-engine.ts

@@ -150,6 +150,8 @@ export class MemoryIndex {
 
 	private termIds = new Map<string, number>();
 	private idToIdx = new Map<string, number>();
+	/** Built only for lookups that miss canonical ids; aliases are not the hot path. */
+	private aliasToIdx: Map<string, number> | undefined;
 	private relPathToIdx = new Map<string, number>();
 	private bodyCache: BodyCache;
 	private trigramIndex: Map<string, number[]> | undefined;
@@ -237,7 +239,20 @@ export class MemoryIndex {
 	}
 
 	idxForId(id: string): number | undefined {
-		return this.idToIdx.get(id);
+		const direct = this.idToIdx.get(id);
+		if (direct !== undefined) return direct;
+		// Imports may have ids that do not use the mem_ prefix. A merge records the
+		// retired id as an alias, so every former id must remain usable.
+		if (!this.aliasToIdx) {
+			this.aliasToIdx = new Map();
+			for (let idx = 0; idx < this.docs.length; idx += 1) {
+				if (!this.alive[idx]) continue;
+				for (const alias of this.docs[idx].aliases) {
+					if (!this.aliasToIdx.has(alias)) this.aliasToIdx.set(alias, idx);
+				}
+			}
+		}
+		return this.aliasToIdx.get(id);
 	}
 
 	idxForRelPath(relPath: string): number {
@@ -323,6 +338,7 @@ export class MemoryIndex {
 		this.docTfs.push(tfs);
 		this.alive.push(true);
 		this.idToIdx.set(doc.id, idx);
+		this.aliasToIdx = undefined;
 		this.relPathToIdx.set(meta.relPath, idx);
 		this.bodyCache.set(doc.path, doc.body);
 		this.linkCache = undefined;
@@ -335,6 +351,7 @@ export class MemoryIndex {
 		const doc = this.docs[idx];
 		this.alive[idx] = false;
 		this.idToIdx.delete(doc.id);
+		this.aliasToIdx = undefined;
 		this.relPathToIdx.delete(doc.relPath);
 		this.bodyCache.delete(doc.path);
 		const termIds = this.docTerms[idx] ?? [];
@@ -414,6 +431,7 @@ export class MemoryIndex {
 		this.docTfs = newDocTfs;
 		this.alive = new Array(newDocs.length).fill(true);
 		this.idToIdx = new Map();
+		this.aliasToIdx = undefined;
 		this.relPathToIdx = new Map();
 		for (let i = 0; i < newDocs.length; i += 1) {
 			this.idToIdx.set(newDocs[i].id, i);
@@ -437,6 +455,7 @@ export class MemoryIndex {
 		this.alive = [];
 		this.termIds = new Map();
 		this.idToIdx = new Map();
+		this.aliasToIdx = undefined;
 		this.relPathToIdx = new Map();
 		this.trigramIndex = undefined;
 		this.fuzzyCache.clear();
@@ -505,10 +524,8 @@ export class MemoryIndex {
 		const resolve = (ref: string): number | undefined => {
 			const trimmed = ref.trim();
 			if (!trimmed) return undefined;
-			if (trimmed.startsWith("mem_")) {
-				const idx = this.idToIdx.get(trimmed);
-				if (idx !== undefined) return idx;
-			}
+			const byId = this.idxForId(trimmed);
+			if (byId !== undefined) return byId;
 			const byPath = this.relPathToIdx.get(normalizeRelPath(trimmed));
 			if (byPath !== undefined) return byPath;
 			return titles.get(trimmed.toLowerCase());
@@ -542,7 +559,7 @@ export class MemoryIndex {
 		const titles = this.links().titles;
 		const trimmed = ref.trim();
 		if (!trimmed) return undefined;
-		const byId = this.idToIdx.get(trimmed);
+		const byId = this.idxForId(trimmed);
 		if (byId !== undefined && this.alive[byId]) return byId;
 		const byPath = this.relPathToIdx.get(normalizeRelPath(trimmed));
 		if (byPath !== undefined && this.alive[byPath]) return byPath;
@@ -827,6 +844,7 @@ export class MemoryIndex {
 		}
 		this.alive = new Array(docCount).fill(true);
 		this.idToIdx = new Map();
+		this.aliasToIdx = undefined;
 		this.relPathToIdx = new Map();
 		for (let i = 0; i < docCount; i += 1) {
 			this.idToIdx.set(this.docs[i].id, i);
@@ -935,6 +953,14 @@ export class MemoryIndex {
 	async search(query: string, options: SearchOptions = {}): Promise<SearchResult> {
 		const started = performance.now();
 		await this.refresh(false);
+		const result = this.searchWarm(query, options);
+		this.lastSearchMs = Math.round((performance.now() - started) * 100) / 100;
+		return result;
+	}
+
+	/** Score an index the caller has already refreshed. */
+	searchWarm(query: string, options: SearchOptions = {}): SearchResult {
+		const started = performance.now();
 		const result = searchIndex(this, query, options);
 		this.lastSearchMs = Math.round((performance.now() - started) * 100) / 100;
 		return result;

package/src/runtime.ts

@@ -143,6 +143,8 @@ export class MemoriaRuntime {
 	config: MemoriaConfig = { ...DEFAULT_CONFIG };
 	roots: ResolvedRoots;
 	private stores = new Map<string, StoreState>();
+	/** Share one first load per root; callers never see a half-loaded index. */
+	private loadingStores = new Map<string, Promise<StoreState>>();
 	/** Serializes read-modify-write sequences per store root. */
 	private locks = new KeyedMutex();
 	private initialized = false;
@@ -262,27 +264,39 @@ export class MemoriaRuntime {
 			if (startWatcher) this.ensureWatcher(state);
 			return state;
 		}
-		const index = new MemoryIndex(root, {
-			bodyCacheBytes: this.config.bodyCacheBytes,
-			maxScanIntervalMs: this.config.scanIntervalMs,
-			exclude: this.config.exclude,
-			indexFormat: this.config.indexFormat,
-		});
-		const saver = createIndexSaver(index);
-		state = {
-			root,
-			index,
-			saver,
-			usageSaver: debounce(() => {
-				void this.flushUsage(root, state!).catch(() => {});
-			}, 4000),
-			pendingTouch: new Set(),
-		};
-		this.stores.set(root, state);
-		const recovered = await recoverJournal(root).catch(() => undefined);
-		if (recovered) state.recovered = recovered;
-		await index.load();
-		if (this.config.usageTracking) state.usage = await UsageStore.load(root).catch(() => undefined);
+		let loading = this.loadingStores.get(root);
+		if (!loading) {
+			loading = (async (): Promise<StoreState> => {
+				const index = new MemoryIndex(root, {
+					bodyCacheBytes: this.config.bodyCacheBytes,
+					maxScanIntervalMs: this.config.scanIntervalMs,
+					exclude: this.config.exclude,
+					indexFormat: this.config.indexFormat,
+				});
+				const saver = createIndexSaver(index);
+				const loaded: StoreState = {
+					root,
+					index,
+					saver,
+					usageSaver: debounce(() => {
+						void this.flushUsage(root, loaded).catch(() => {});
+					}, 4000),
+					pendingTouch: new Set(),
+				};
+				const recovered = await recoverJournal(root).catch(() => undefined);
+				if (recovered) loaded.recovered = recovered;
+				await index.load();
+				if (this.config.usageTracking) loaded.usage = await UsageStore.load(root).catch(() => undefined);
+				this.stores.set(root, loaded);
+				return loaded;
+			})();
+			this.loadingStores.set(root, loading);
+		}
+		try {
+			state = await loading;
+		} finally {
+			if (this.loadingStores.get(root) === loading) this.loadingStores.delete(root);
+		}
 		if (startWatcher) this.ensureWatcher(state);
 		return state;
 	}
@@ -338,6 +352,11 @@ export class MemoriaRuntime {
 		this.searchCache.clear();
 	}
 
+	/** Every refresh that changes an index must also invalidate cached recall. */
+	private async refreshIndex(index: MemoryIndex, force = false): Promise<void> {
+		if (await index.refresh(force)) this.bumpCacheGeneration();
+	}
+
 	/* ---------------------------------------------------------------- */
 	/* Search                                                            */
 	/* ---------------------------------------------------------------- */
@@ -358,6 +377,12 @@ export class MemoriaRuntime {
 			return { hits: [], total: 0, tookMs: 0, truncated: false, missing: [], byRoot: [] };
 		}
 		const limit = Math.max(1, options.limit ?? 8);
+		// A cached result is only valid after each root has had a chance to observe
+		// watcher events or its periodic freshness scan. Both checks are cheap when
+		// the index is already fresh.
+		const states = await Promise.all(roots.map((root) => this.storeFor(root)));
+		await Promise.all(states.map((state) => this.refreshIndex(state.index, options.refresh === true)));
+		const synonymTables = await Promise.all(states.map((state) => this.synonymsFor(state.root)));
 		const cacheKey = this.searchCacheKey(query, options);
 		const cached = this.lookupCache(cacheKey);
 		if (cached) {
@@ -367,16 +392,13 @@ export class MemoriaRuntime {
 		}
 
 		const perRoot = await Promise.all(
-			roots.map(async (root) => {
-				const state = await this.storeFor(root);
+			states.map(async (state, indexInRoots) => {
+				const root = state.root;
 				const index = state.index;
-				const refreshed = options.refresh ? await index.refresh(true) : await index.refresh(false);
-				if (refreshed) this.bumpCacheGeneration();
-				const synonyms = await this.synonymsFor(root);
-				const result = await index.search(query, {
+				const result = index.searchWarm(query, {
 					...options,
 					limit: Math.max(limit, 8),
-					synonyms,
+					synonyms: synonymTables[indexInRoots],
 					synonymWeight: this.config.synonymWeight,
 					snippetChars: this.config.snippetChars,
 					relatedHits: options.relatedHits ?? this.config.relatedHits,
@@ -474,7 +496,9 @@ export class MemoriaRuntime {
 	private searchCacheKey(query: string, options: SearchOptions & { scope?: Scope }): string {
 		const normalized = {
 			q: query,
+			parts: options.parts ?? [],
 			limit: options.limit ?? 8,
+			root: options.root ?? "",
 			category: options.category ?? "",
 			tags: options.tags ?? [],
 			anyTags: options.anyTags ?? [],
@@ -485,6 +509,10 @@ export class MemoriaRuntime {
 			prefix: options.prefix !== false,
 			fuzzy: options.fuzzy !== false,
 			expandRelated: options.expandRelated !== false,
+			relatedHits: options.relatedHits ?? this.config.relatedHits,
+			relatedBoost: options.relatedBoost ?? this.config.relatedBoost,
+			dropSuperseded: options.dropSuperseded === true,
+			timeHints: options.timeHints ?? this.config.timeHints,
 			explain: Boolean(options.explain),
 			scope: options.scope ?? "all",
 		};
@@ -967,7 +995,7 @@ export class MemoriaRuntime {
 		const out: Array<{ root: string; files: number }> = [];
 		for (const root of roots) {
 			const index = await this.indexFor(root);
-			await index.refresh(true);
+			await this.refreshIndex(index, true);
 			const docs: IndexListingDoc[] = index.liveDocs().map(({ meta }) => ({
 				relPath: meta.relPath,
 				title: meta.title,
@@ -994,9 +1022,10 @@ export class MemoriaRuntime {
 	async synonymsFor(root: string): Promise<Record<string, string[]>> {
 		const state = await this.storeFor(root);
 		const now = Date.now();
-		if (state.synonyms && now - state.synonyms.loadedAt < 30_000 && Object.keys(this.config.synonyms).length === 0) return state.synonyms.table;
+		if (state.synonyms && now - state.synonyms.loadedAt < 30_000) return state.synonyms.table;
 		const file = await loadSynonymsFile(root).catch(() => ({}));
 		const table = expandSynonymTable(mergeSynonymTables(this.config.synonyms, file));
+		if (state.synonyms && JSON.stringify(state.synonyms.table) !== JSON.stringify(table)) this.bumpCacheGeneration();
 		state.synonyms = { table, loadedAt: now };
 		return table;
 	}
@@ -1038,7 +1067,7 @@ export class MemoriaRuntime {
 		const out: MergeSuggestion[] = [];
 		for (const root of this.activeRoots(scope)) {
 			const index = await this.indexFor(root);
-			await index.refresh(false);
+			await this.refreshIndex(index);
 			out.push(...suggestMerges(this.similarityDocs(index), { threshold: this.config.dedupeThreshold, limit }));
 		}
 		return out.sort((a, b) => b.score - a.score).slice(0, limit);
@@ -1109,7 +1138,7 @@ export class MemoriaRuntime {
 		const out: Contradiction[] = [];
 		for (const root of this.activeRoots(scope)) {
 			const index = await this.indexFor(root);
-			await index.refresh(false);
+			await this.refreshIndex(index);
 			const units: Array<{ id: string; relPath: string; label?: string; text: string }> = [];
 			for (const { idx, meta } of index.liveDocs()) {
 				// Reading every body would make doctor O(store). A contradiction needs
@@ -1167,7 +1196,7 @@ export class MemoriaRuntime {
 		const out: TopicReportEntry[] = [];
 		for (const root of this.activeRoots(scope)) {
 			const state = await this.storeFor(root);
-			await state.index.refresh(false);
+			await this.refreshIndex(state.index);
 			const staleThreshold = this.config.staleAfterDays * 86_400_000;
 			const now = Date.now();
 			for (const { idx, meta } of state.index.liveDocs()) {
@@ -1208,7 +1237,7 @@ export class MemoriaRuntime {
 		state.usageSaver();
 		if (!previous) return undefined;
 		const index = state.index;
-		await index.refresh(false);
+		await this.refreshIndex(index);
 		const created: DiffEntry[] = [];
 		const updated: DiffEntry[] = [];
 		for (const { meta } of index.liveDocs()) {
@@ -1237,7 +1266,7 @@ export class MemoriaRuntime {
 		const updated: DiffEntry[] = [];
 		for (const root of this.activeRoots(scope)) {
 			const index = await this.indexFor(root);
-			await index.refresh(false);
+			await this.refreshIndex(index);
 			for (const { meta } of index.liveDocs()) {
 				const entry: DiffEntry = {
 					id: meta.id,
@@ -1266,7 +1295,7 @@ export class MemoriaRuntime {
 		let notes = 0;
 		for (const root of roots) {
 			const state = await this.storeFor(root);
-			await state.index.refresh(false);
+			await this.refreshIndex(state.index);
 			const hot = await readHot(root, this.config.hotLimit);
 			if (options.includeHot !== false && hot.exists && hot.content.trim()) {
 				lines.push(encodeJsonl({ type: "hot", root: this.displayPath(root), content: hot.content }));
@@ -1311,24 +1340,34 @@ export class MemoriaRuntime {
 		const records = decodeJsonl(text);
 		const result = { created: [] as string[], updated: [] as string[], skipped: 0, errors: records.errors, hotImported: false };
 		return this.locks.run(root, async () => {
-			for (const record of records.records) {
-				if (record.type === "hot") {
-					if (options.dryRun) continue;
-					// Already inside the root lock: call the store helpers directly.
-					await writeHot(root, record.content);
-					result.hotImported = true;
-					continue;
+			let changed = false;
+			let completed = false;
+			try {
+				for (const record of records.records) {
+					if (record.type === "hot") {
+						if (options.dryRun) continue;
+						// Already inside the root lock: call the store helpers directly.
+						await writeHot(root, record.content);
+						result.hotImported = true;
+						continue;
+					}
+					if (!options.dryRun) changed = true;
+					const outcome = await this.importNote(root, state, record, mode, options.dryRun === true);
+					if (!options.dryRun && outcome !== "skipped") changed = true;
+					if (outcome === "created") result.created.push(record.id);
+					else if (outcome === "updated") result.updated.push(record.id);
+					else result.skipped += 1;
+				}
+				completed = true;
+				return result;
+			} finally {
+				if (changed) {
+					this.bumpCacheGeneration();
+					if (!completed) state.index.dirty = true;
+					state.index.builtAt = Date.now();
+					state.saver.schedule();
 				}
-				const outcome = await this.importNote(root, state, record, mode, options.dryRun === true);
-				if (outcome === "created") result.created.push(record.id);
-				else if (outcome === "updated") result.updated.push(record.id);
-				else result.skipped += 1;
-			}
-			if (!options.dryRun) {
-				state.index.builtAt = Date.now();
-				state.saver.schedule();
 			}
-			return result;
 		});
 	}
 
@@ -1418,7 +1457,7 @@ export class MemoriaRuntime {
 		for (const root of this.activeRoots("all")) {
 			const state = await this.storeFor(root);
 			const index = state.index;
-			await index.refresh(true);
+			await this.refreshIndex(index, true);
 			const label = this.displayPath(root);
 			if (state.recovered) {
 				recovered.push(`${label}: ${state.recovered}`);
@@ -1512,7 +1551,7 @@ export class MemoriaRuntime {
 		let docs = 0;
 		for (const root of roots) {
 			const index = await this.indexFor(root);
-			await index.refresh(false);
+			await this.refreshIndex(index);
 			const overview = index.overview(recentLimit);
 			docs += overview.docs;
 			for (const [category, count] of overview.categories) counts.set(category, (counts.get(category) ?? 0) + count);
@@ -1532,7 +1571,7 @@ export class MemoriaRuntime {
 		const seenIds = new Set<string>();
 		for (const root of roots) {
 			const index = await this.indexFor(root);
-			await index.refresh(false);
+			await this.refreshIndex(index);
 			for (const { meta } of index.liveDocs()) {
 				// Ids are unique per store, not across stores: list a shared note once.
 				if (seenIds.has(meta.id)) continue;
@@ -1545,6 +1584,7 @@ export class MemoriaRuntime {
 
 	/** Flush pending index writes and stop watchers. Idempotent. */
 	async dispose(): Promise<void> {
+		await Promise.allSettled(this.loadingStores.values());
 		const stores = [...this.stores.values()];
 		this.stores = new Map();
 		this.initialized = false;
@@ -1636,4 +1676,3 @@ async function safeLoadConfig(root: string): Promise<MemoriaConfig> {
 		return { ...DEFAULT_CONFIG };
 	}
 }
-

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;
@@ -1614,8 +1654,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 +1671,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

@@ -138,7 +138,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)." })),

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;
 }