@windagency/valora-plugin-memory-vault 1.0.0

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAEjE,MAAM,CAAC,MAAM,gBAAgB,GAA6B;IACzD,YAAY,EAAE,CAAC,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,SAAS,CAAC;IACrF,WAAW,EAAE,oFAAoF;IACjG,KAAK,EAAE,cAAc;CACrB,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,GAAc;IACtC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,CAAC,CAAC;AACrE,CAAC;AAED,2FAA2F;AAC3F,oEAAoE;AAEpE,OAAO,EAAE,sBAAsB,EAAE,0BAA0B,EAA0B,MAAM,oBAAoB,CAAC;AAEhH,OAAO,EAGN,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEpF,OAAO,EAAE,yBAAyB,EAAE,mBAAmB,EAAE,MAAM,uCAAuC,CAAC;AACvG,OAAO,EAAuB,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACxF,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAoB,MAAM,8BAA8B,CAAC;AACtG,OAAO,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAC9G,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAE,wBAAwB,EAAE,MAAM,6BAA6B,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAA+C,MAAM,8BAA8B,CAAC;AAE/G,OAAO,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAEzG,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,uFAAuF;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACpF,OAAO,EACN,kBAAkB,EAElB,eAAe,EACf,mBAAmB,EACnB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAmB,UAAU,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/manager.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Memory Manager — CRUD, decay computation, queries, and retrieval strengthening.
+ *
+ * Provides the public API for the memory system. All reads compute decay on
+ * the fly; retrievals strengthen entries by extending their half-life.
+ */
+import type {
+	MemoryCategory,
+	MemoryCreateOptions,
+	MemoryEntry,
+	MemoryQueryOptions,
+	MemoryQueryResult,
+	MemoryRetentionConfig,
+	MemoryStorePort,
+	PurgeCriteria,
+	PurgeResult
+} from '@windagency/valora-plugin-api';
+import type { EmbedderPort } from './embeddings/embedder.port.js';
+import type { MemoryStore } from './store.js';
+export type { PurgeCriteria, PurgeResult };
+export declare class MemoryManager {
+	private readonly config;
+	private embedder?;
+	private readonly store;
+	constructor(store: MemoryStore | MemoryStorePort, config?: Partial<MemoryRetentionConfig>, embedder?: EmbedderPort);
+	create(category: MemoryCategory, options: MemoryCreateOptions): Promise<MemoryEntry>;
+	delete(category: MemoryCategory, id: string): Promise<boolean>;
+	findByPaths(paths: string[]): Promise<MemoryQueryResult[]>;
+	flush(): Promise<void>;
+	get(category: MemoryCategory, id: string, strengthen?: boolean): Promise<MemoryQueryResult | null>;
+	invalidateByPaths(changedPaths: string[]): Promise<number>;
+	markStaleByPaths(paths: string[]): Promise<number>;
+	promote(episodicId: string, semanticContent: string, tags?: string[]): Promise<MemoryEntry>;
+	prune(): Promise<number>;
+	pruneCategory(category: MemoryCategory): Promise<number>;
+	purge(criteria: PurgeCriteria): Promise<PurgeResult>;
+	query(options: MemoryQueryOptions): Promise<MemoryQueryResult[]>;
+	/**
+	 * Late-bind an embedder so consumers (e.g. the bundled provider) can
+	 * resolve it asynchronously after construction. Calling with `undefined`
+	 * clears it and reverts subsequent queries to lexical recall.
+	 */
+	setEmbedder(embedder: EmbedderPort | undefined): void;
+	update(
+		category: MemoryCategory,
+		id: string,
+		patch: Partial<Pick<MemoryEntry, 'confidence' | 'content' | 'relatedPaths' | 'tags'>>
+	): Promise<boolean>;
+	private collectPurgeIds;
+	private getDefaultHalfLife;
+	private incrementCoAccess;
+	private lexicalRecall;
+	private postProcess;
+	private recall;
+	/** Returns true when the entry has at least one of the requested paths (or no filter is set). */
+	private hasPathMatch;
+	/** Returns true when the entry has at least one tag from the filter list (or no filter is set). */
+	private hasTagMatch;
+	private matchesQueryOptions;
+	private strengthenEntry;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACX,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,aAAa,EACb,WAAW,EACX,MAAM,+BAA+B,CAAC;AAIvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAa9C,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,CAAC;AAI3C,qBAAa,aAAa;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,CAAe;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAkB;gBAE5B,KAAK,EAAE,WAAW,GAAG,eAAe,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAAE,QAAQ,CAAC,EAAE,YAAY;IAM5G,MAAM,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAkDpF,MAAM,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9D,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAiB1D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAItB,GAAG,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,UAAO,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAgB/F,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAkB1D,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAiBlD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA0C3F,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAQxB,aAAa,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC;IAexD,KAAK,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BpD,KAAK,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAQtE;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,GAAG,IAAI;IAI/C,MAAM,CACX,QAAQ,EAAE,cAAc,EACxB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,EAAE,YAAY,GAAG,SAAS,GAAG,cAAc,GAAG,MAAM,CAAC,CAAC,GACnF,OAAO,CAAC,OAAO,CAAC;YAKL,eAAe;IAa7B,OAAO,CAAC,kBAAkB;YASZ,iBAAiB;YA8BjB,aAAa;YAeb,WAAW;YAOX,MAAM;IAYpB,iGAAiG;IACjG,OAAO,CAAC,YAAY;IAIpB,mGAAmG;IACnG,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,mBAAmB;YAUb,eAAe;CAgB7B"}

package/dist/manager.js

@@ -0,0 +1,377 @@
+/**
+ * Memory Manager — CRUD, decay computation, queries, and retrieval strengthening.
+ *
+ * Provides the public API for the memory system. All reads compute decay on
+ * the fly; retrievals strengthen entries by extending their half-life.
+ */
+import { generateMemoryId } from '@windagency/valora-runtime';
+import {
+	DEFAULT_MEMORY_DECISION_HALF_LIFE_DAYS,
+	DEFAULT_MEMORY_EPISODIC_HALF_LIFE_DAYS,
+	DEFAULT_MEMORY_ERROR_HALF_LIFE_MULTIPLIER,
+	DEFAULT_MEMORY_PRUNE_THRESHOLD,
+	DEFAULT_MEMORY_RETRIEVAL_BOOST_DAYS,
+	DEFAULT_MEMORY_SEMANTIC_HALF_LIFE_DAYS,
+	MEMORY_HALF_LIFE_CAP_MULTIPLIER
+} from './constants.js';
+import { computeEffectiveHalfLife, computeStrength } from './decay.js';
+const ALL_CATEGORIES = ['episodic', 'semantic', 'decisions'];
+export class MemoryManager {
+	config;
+	embedder;
+	store;
+	constructor(store, config, embedder) {
+		this.store = store;
+		this.config = resolveConfig(config);
+		this.embedder = embedder;
+	}
+	async create(category, options) {
+		const id = generateMemoryId();
+		const now = new Date().toISOString();
+		const retrievalBoostDays = this.config.retrieval_boost_days ?? DEFAULT_MEMORY_RETRIEVAL_BOOST_DAYS;
+		const errorMultiplier = this.config.error_half_life_multiplier ?? DEFAULT_MEMORY_ERROR_HALF_LIFE_MULTIPLIER;
+		const defaultHalfLife = this.getDefaultHalfLife(category);
+		let halfLifeDays = computeEffectiveHalfLife(
+			defaultHalfLife,
+			0,
+			options.isError ?? false,
+			retrievalBoostDays,
+			errorMultiplier
+		);
+		if (options.halfLifeDays !== undefined) {
+			halfLifeDays = options.halfLifeDays;
+		}
+		const entry = {
+			accessCount: 0,
+			agentRole: options.agentRole,
+			category,
+			confidence: options.confidence,
+			content: options.content,
+			createdAt: now,
+			halfLifeDays,
+			id,
+			isError: options.isError ?? false,
+			lastAccessedAt: now,
+			relatedPaths: options.relatedPaths ?? [],
+			sessionId: options.sessionId,
+			source: options.source,
+			tags: options.tags,
+			updatedAt: now
+		};
+		if (options.supersedes !== undefined) {
+			entry.supersedes = options.supersedes;
+			await this.store.updateEntry(category, options.supersedes, {
+				confidence: 'stale',
+				supersededBy: id
+			});
+		}
+		await this.store.appendEntry(category, entry);
+		return entry;
+	}
+	async delete(category, id) {
+		return this.store.removeEntry(category, id);
+	}
+	async findByPaths(paths) {
+		const results = [];
+		for (const category of ALL_CATEGORIES) {
+			const entries = await this.store.getEntries(category);
+			for (const entry of entries) {
+				const hasOverlap = paths.some((p) => entry.relatedPaths.includes(p));
+				if (hasOverlap) {
+					const strength = computeStrength(entry.createdAt, entry.halfLifeDays);
+					results.push({ entry, strength });
+				}
+			}
+		}
+		return results;
+	}
+	async flush() {
+		return this.store.flush();
+	}
+	async get(category, id, strengthen = true) {
+		const entries = await this.store.getEntries(category);
+		const entry = entries.find((e) => e.id === id);
+		if (entry === undefined) {
+			return null;
+		}
+		const strength = computeStrength(entry.createdAt, entry.halfLifeDays);
+		if (strengthen) {
+			await this.strengthenEntry(category, entry);
+		}
+		return { entry, strength };
+	}
+	async invalidateByPaths(changedPaths) {
+		let count = 0;
+		for (const category of ALL_CATEGORIES) {
+			const entries = await this.store.getEntries(category);
+			for (const entry of entries) {
+				const hasOverlap = changedPaths.some((p) => entry.relatedPaths.includes(p));
+				if (hasOverlap) {
+					const newHalfLife = Math.max(1, entry.halfLifeDays / 2);
+					await this.store.updateEntry(category, entry.id, { halfLifeDays: newHalfLife });
+					count++;
+				}
+			}
+		}
+		return count;
+	}
+	async markStaleByPaths(paths) {
+		let count = 0;
+		for (const category of ALL_CATEGORIES) {
+			const entries = await this.store.getEntries(category);
+			for (const entry of entries) {
+				const hasOverlap = paths.some((p) => entry.relatedPaths.includes(p));
+				if (hasOverlap) {
+					await this.store.updateEntry(category, entry.id, { confidence: 'stale' });
+					count++;
+				}
+			}
+		}
+		return count;
+	}
+	async promote(episodicId, semanticContent, tags) {
+		const entries = await this.store.getEntries('episodic');
+		const episodicEntry = entries.find((e) => e.id === episodicId);
+		if (episodicEntry === undefined) {
+			throw new Error(`Episodic entry not found: ${episodicId}`);
+		}
+		const mergedTags = tags !== undefined ? [...new Set([...episodicEntry.tags, ...tags])] : episodicEntry.tags;
+		const newEntry = await this.create('semantic', {
+			agentRole: episodicEntry.agentRole,
+			confidence: episodicEntry.confidence,
+			content: semanticContent,
+			relatedPaths: episodicEntry.relatedPaths,
+			sessionId: episodicEntry.sessionId,
+			source: episodicEntry.source,
+			tags: mergedTags
+		});
+		// Mark the source episodic stale and record the cross-category
+		// supersession. `create()` above only handles same-category cases.
+		await this.store.updateEntry('episodic', episodicId, {
+			confidence: 'stale',
+			supersededBy: newEntry.id
+		});
+		// Persist the supersedes wikilink/edge via the port. Backends with
+		// graph support (vault) overwrite the entry's file with the new
+		// supersedes field set and store the outbound edge for audit traversal.
+		// Backends without graph support safely ignore the `links` argument;
+		// the `appendEntry` contract is idempotent on entry id, so the second
+		// call replaces the first instead of duplicating. The supersedes edge
+		// is one-way authorial intent and is intentionally not traversed by
+		// spreading activation (see TRAVERSAL_KINDS in retrieval/spreading-activation.ts).
+		const supersededEntry = { ...newEntry, supersedes: episodicId };
+		await this.store.appendEntry('semantic', supersededEntry, [
+			{ fromId: newEntry.id, kind: 'supersedes', toId: episodicId }
+		]);
+		return supersededEntry;
+	}
+	async prune() {
+		let total = 0;
+		for (const category of ALL_CATEGORIES) {
+			total += await this.pruneCategory(category);
+		}
+		return total;
+	}
+	async pruneCategory(category) {
+		const pruneThreshold = this.config.prune_threshold ?? DEFAULT_MEMORY_PRUNE_THRESHOLD;
+		const entries = await this.store.getEntries(category);
+		const idsToRemove = new Set();
+		for (const entry of entries) {
+			const strength = computeStrength(entry.createdAt, entry.halfLifeDays);
+			if (strength < pruneThreshold) {
+				idsToRemove.add(entry.id);
+			}
+		}
+		return this.store.removeEntries(category, idsToRemove);
+	}
+	async purge(criteria) {
+		const { all, categories, dryRun, olderThanMs } = criteria;
+		if (all !== true && categories === undefined && olderThanMs === undefined) {
+			throw new Error(
+				'purge requires explicit criteria: pass `all: true`, supply a `categories` array, or set `olderThanMs` to avoid accidentally deleting every memory.'
+			);
+		}
+		const targetCategories = all === true ? [...ALL_CATEGORIES] : (categories ?? [...ALL_CATEGORIES]);
+		let totalDeleted = 0;
+		let totalWouldDelete = 0;
+		for (const category of targetCategories) {
+			const idsToRemove = await this.collectPurgeIds(category, olderThanMs);
+			if (dryRun) {
+				totalWouldDelete += idsToRemove.size;
+			} else {
+				totalDeleted += await this.store.removeEntries(category, idsToRemove);
+			}
+		}
+		return { dryRun: dryRun ?? false, totalDeleted, totalWouldDelete };
+	}
+	async query(options) {
+		const limit = options.limit ?? 50;
+		const recalled = await this.recall(options, limit);
+		const results = applyTokenBudget(recalled, options.tokenBudget);
+		await this.postProcess(results, options);
+		return results;
+	}
+	/**
+	 * Late-bind an embedder so consumers (e.g. the bundled provider) can
+	 * resolve it asynchronously after construction. Calling with `undefined`
+	 * clears it and reverts subsequent queries to lexical recall.
+	 */
+	setEmbedder(embedder) {
+		this.embedder = embedder;
+	}
+	async update(category, id, patch) {
+		const now = new Date().toISOString();
+		return this.store.updateEntry(category, id, { ...patch, updatedAt: now });
+	}
+	async collectPurgeIds(category, olderThanMs) {
+		const entries = await this.store.getEntries(category);
+		const ids = new Set();
+		for (const entry of entries) {
+			if (olderThanMs !== undefined) {
+				const ageMs = Date.now() - new Date(entry.createdAt).getTime();
+				if (ageMs < olderThanMs) continue;
+			}
+			ids.add(entry.id);
+		}
+		return ids;
+	}
+	getDefaultHalfLife(category) {
+		const lookup = {
+			decisions: this.config.decision_half_life_days ?? DEFAULT_MEMORY_DECISION_HALF_LIFE_DAYS,
+			episodic: this.config.episodic_half_life_days ?? DEFAULT_MEMORY_EPISODIC_HALF_LIFE_DAYS,
+			semantic: this.config.semantic_half_life_days ?? DEFAULT_MEMORY_SEMANTIC_HALF_LIFE_DAYS
+		};
+		return lookup[category];
+	}
+	async incrementCoAccess(results) {
+		if (results.length < 2) return;
+		// Accumulate per-entry deltas in a single in-memory pass. The pair loop
+		// is still O(N²) but every disk write is deferred so we end up with at
+		// most one write per affected entry (O(N), not O(N²)). Batching also
+		// closes the lost-update window where the read-modify-write loop holds
+		// stale entry references after the underlying store has rewritten the
+		// record.
+		const deltas = new Map();
+		for (let i = 0; i < results.length; i++) {
+			for (let j = i + 1; j < results.length; j++) {
+				const a = results[i].entry;
+				const b = results[j].entry;
+				bumpDelta(deltas, a.id, b.id);
+				bumpDelta(deltas, b.id, a.id);
+			}
+		}
+		for (const result of results) {
+			const delta = deltas.get(result.entry.id);
+			if (!delta) continue;
+			const merged = { ...result.entry.coAccess };
+			for (const [peerId, count] of Object.entries(delta)) {
+				merged[peerId] = (merged[peerId] ?? 0) + count;
+			}
+			await this.store.updateEntry(result.entry.category, result.entry.id, { coAccess: merged });
+		}
+	}
+	async lexicalRecall(options, limit) {
+		const categories = options.category !== undefined ? [options.category] : ALL_CATEGORIES;
+		const allResults = [];
+		for (const category of categories) {
+			// Clone the array so callers cannot mutate the store's internal cache.
+			const entries = [...(await this.store.getEntries(category))];
+			for (const entry of entries) {
+				const strength = computeStrength(entry.createdAt, entry.halfLifeDays);
+				if (this.matchesQueryOptions(entry, options, strength)) allResults.push({ entry, strength });
+			}
+		}
+		allResults.sort((a, b) => b.strength - a.strength);
+		return allResults.slice(0, limit);
+	}
+	async postProcess(results, options) {
+		if (options.strengthen !== false) {
+			for (const result of results) await this.strengthenEntry(result.entry.category, result.entry);
+		}
+		await this.incrementCoAccess(results);
+	}
+	async recall(options, limit) {
+		// Dispatch via the port: backends that advertise `semanticRecall`
+		// (e.g. vault) own the embedding-driven graph traversal; backends
+		// that do not fall through to lexical retrieval. A null return from
+		// semanticRecall signals "no usable seeds — fall back to lexical".
+		if (options.text && this.embedder && this.store.semanticRecall) {
+			const semantic = await this.store.semanticRecall(options, limit, this.embedder, this.config.recall);
+			if (semantic !== null) return semantic;
+		}
+		return this.lexicalRecall(options, limit);
+	}
+	/** Returns true when the entry has at least one of the requested paths (or no filter is set). */
+	hasPathMatch(entry, paths) {
+		return paths === undefined || paths.length === 0 || paths.some((p) => entry.relatedPaths.includes(p));
+	}
+	/** Returns true when the entry has at least one tag from the filter list (or no filter is set). */
+	hasTagMatch(entry, tags) {
+		return tags === undefined || tags.length === 0 || tags.some((t) => entry.tags.includes(t));
+	}
+	matchesQueryOptions(entry, options, strength) {
+		if (entry.confidence === 'stale') return false;
+		const minStrength = options.minStrength ?? DEFAULT_MEMORY_PRUNE_THRESHOLD;
+		if (strength < minStrength) return false;
+		if (!this.hasTagMatch(entry, options.tags)) return false;
+		if (!this.hasPathMatch(entry, options.paths)) return false;
+		if (options.agentRole !== undefined && entry.agentRole !== options.agentRole) return false;
+		return true;
+	}
+	async strengthenEntry(category, entry) {
+		const retrievalBoostDays = this.config.retrieval_boost_days ?? DEFAULT_MEMORY_RETRIEVAL_BOOST_DAYS;
+		const cap = this.getDefaultHalfLife(category) * MEMORY_HALF_LIFE_CAP_MULTIPLIER;
+		const accessCount = entry.accessCount + 1;
+		// Heavily-queried memories would otherwise grow their half-life
+		// without bound — capping at MULT × the category default keeps decay
+		// meaningful even for hot entries.
+		const halfLifeDays = Math.min(cap, entry.halfLifeDays + retrievalBoostDays);
+		const lastAccessedAt = new Date().toISOString();
+		entry.accessCount = accessCount;
+		entry.halfLifeDays = halfLifeDays;
+		entry.lastAccessedAt = lastAccessedAt;
+		await this.store.updateEntry(category, entry.id, { accessCount, halfLifeDays, lastAccessedAt });
+	}
+}
+const TOKEN_ESTIMATE_CHARS = 4;
+/**
+ * Truncate `results` so the cumulative content size fits within `tokenBudget`.
+ * Returns the input unchanged when no budget is set (tokenBudget undefined or
+ * non-positive). Estimation uses ~4 characters per token, matching the
+ * convention in `memory-formatter.ts` so both layers agree on the cost model.
+ */
+function applyTokenBudget(results, tokenBudget) {
+	if (tokenBudget === undefined || tokenBudget <= 0) return results;
+	const charBudget = tokenBudget * TOKEN_ESTIMATE_CHARS;
+	const fitted = [];
+	let used = 0;
+	for (const result of results) {
+		const cost = result.entry.content.length;
+		if (used + cost > charBudget && fitted.length > 0) break; // always include at least one
+		used += cost;
+		fitted.push(result);
+	}
+	return fitted;
+}
+function bumpDelta(deltas, fromId, toId) {
+	const existing = deltas.get(fromId) ?? {};
+	existing[toId] = (existing[toId] ?? 0) + 1;
+	deltas.set(fromId, existing);
+}
+function resolveConfig(config) {
+	const defaults = {
+		backend: 'vault',
+		decision_half_life_days: DEFAULT_MEMORY_DECISION_HALF_LIFE_DAYS,
+		enabled: true,
+		episodic_half_life_days: DEFAULT_MEMORY_EPISODIC_HALF_LIFE_DAYS,
+		error_half_life_multiplier: DEFAULT_MEMORY_ERROR_HALF_LIFE_MULTIPLIER,
+		injection_strength_threshold: 0.2,
+		injection_token_budget: 2000,
+		max_entries_per_store: 500,
+		prune_threshold: DEFAULT_MEMORY_PRUNE_THRESHOLD,
+		retrieval_boost_days: DEFAULT_MEMORY_RETRIEVAL_BOOST_DAYS,
+		semantic_half_life_days: DEFAULT_MEMORY_SEMANTIC_HALF_LIFE_DAYS
+	};
+	return config === undefined ? defaults : { ...defaults, ...config };
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"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"}

package/dist/migration/auto-migrate.d.ts

@@ -0,0 +1,20 @@
+import { type MigrationResult } from './json-to-vault.js';
+/**
+ * Run the legacy JSON → vault migration if any legacy file is present and the
+ * vault has not yet been stamped with a schema version.
+ *
+ * The check is intentionally cheap (a few `existsSync` calls) so it can fire
+ * on every process boot without measurable overhead. The migration itself is
+ * idempotent — see `migrateJsonToVault`.
+ *
+ * Within a single process, each `vaultDir` is only checked once: subsequent
+ * calls become cache hits to keep per-stage hot paths free of stat syscalls.
+ *
+ * Returns:
+ *   - The {@link MigrationResult} when a migration ran.
+ *   - `null` when no legacy data was found and no migration was needed.
+ */
+export declare function runAutoMigrationIfNeeded(jsonDir: string, vaultDir: string): MigrationResult | null;
+/** For tests — drop the in-process cache so a re-run will recheck disk. */
+export declare function resetAutoMigrationCache(): void;
+//# sourceMappingURL=auto-migrate.d.ts.map

package/dist/migration/auto-migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-migrate.d.ts","sourceRoot":"","sources":["../../src/migration/auto-migrate.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAO9E;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAoBlG;AAED,2EAA2E;AAC3E,wBAAgB,uBAAuB,IAAI,IAAI,CAE9C"}

package/dist/migration/auto-migrate.js

@@ -0,0 +1,49 @@
+import { getLogger } from '@windagency/valora-runtime';
+import { existsSync } from 'node:fs';
+import * as path from 'node:path';
+import { migrateJsonToVault } from './json-to-vault.js';
+import { readVaultVersion } from './vault-version.js';
+const LEGACY_FILES = ['episodic.json', 'semantic.json', 'decisions.json'];
+const checked = new Set();
+/**
+ * Run the legacy JSON → vault migration if any legacy file is present and the
+ * vault has not yet been stamped with a schema version.
+ *
+ * The check is intentionally cheap (a few `existsSync` calls) so it can fire
+ * on every process boot without measurable overhead. The migration itself is
+ * idempotent — see `migrateJsonToVault`.
+ *
+ * Within a single process, each `vaultDir` is only checked once: subsequent
+ * calls become cache hits to keep per-stage hot paths free of stat syscalls.
+ *
+ * Returns:
+ *   - The {@link MigrationResult} when a migration ran.
+ *   - `null` when no legacy data was found and no migration was needed.
+ */
+export function runAutoMigrationIfNeeded(jsonDir, vaultDir) {
+	const key = `${path.resolve(jsonDir)}::${path.resolve(vaultDir)}`;
+	if (checked.has(key)) return null;
+	if (!hasLegacyFiles(jsonDir)) {
+		checked.add(key);
+		return null;
+	}
+	if (readVaultVersion(vaultDir) !== null) {
+		// Vault already stamped — assume earlier migration already handled the data.
+		checked.add(key);
+		return null;
+	}
+	getLogger().warn('Legacy JSON memory detected — auto-migrating to vault.');
+	const result = migrateJsonToVault({ jsonDir, vaultDir });
+	// Cache only after a successful migration so a thrown attempt can be
+	// retried on the next call instead of being silently swallowed by the cache.
+	checked.add(key);
+	return result;
+}
+/** For tests — drop the in-process cache so a re-run will recheck disk. */
+export function resetAutoMigrationCache() {
+	checked.clear();
+}
+function hasLegacyFiles(jsonDir) {
+	return LEGACY_FILES.some((name) => existsSync(path.join(jsonDir, name)));
+}
+//# sourceMappingURL=auto-migrate.js.map

package/dist/migration/auto-migrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-migrate.js","sourceRoot":"","sources":["../../src/migration/auto-migrate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,OAAO,EAAE,kBAAkB,EAAwB,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,MAAM,YAAY,GAAG,CAAC,eAAe,EAAE,eAAe,EAAE,gBAAgB,CAAC,CAAC;AAE1E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;AAElC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAe,EAAE,QAAgB;IACzE,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IAClE,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IAElC,IAAI,CAAC,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACb,CAAC;IACD,IAAI,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC;QACzC,6EAA6E;QAC7E,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACb,CAAC;IAED,SAAS,EAAE,CAAC,IAAI,CAAC,wDAAwD,CAAC,CAAC;IAC3E,MAAM,MAAM,GAAG,kBAAkB,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;IACzD,qEAAqE;IACrE,6EAA6E;IAC7E,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACjB,OAAO,MAAM,CAAC;AACf,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,uBAAuB;IACtC,OAAO,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC;AAED,SAAS,cAAc,CAAC,OAAe;IACtC,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AAC1E,CAAC"}

package/dist/migration/json-to-vault.d.ts

@@ -0,0 +1,10 @@
+export interface MigrationOptions {
+	jsonDir: string;
+	vaultDir: string;
+}
+export interface MigrationResult {
+	migrated: number;
+	skipped: number;
+}
+export declare function migrateJsonToVault(options: MigrationOptions): MigrationResult;
+//# sourceMappingURL=json-to-vault.d.ts.map

package/dist/migration/json-to-vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-to-vault.d.ts","sourceRoot":"","sources":["../../src/migration/json-to-vault.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,gBAAgB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CAChB;AAyBD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAgC7E"}

package/dist/migration/json-to-vault.js

@@ -0,0 +1,88 @@
+import { getLogger } from '@windagency/valora-runtime';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
+import * as path from 'node:path';
+import { atomicWriteFile, serialiseMemoryFile } from '../vault/file-format.js';
+import { writeVaultVersion } from './vault-version.js';
+const CATEGORIES = ['episodic', 'semantic', 'decisions'];
+const LOCK_FILENAME = '.migration.lock';
+export function migrateJsonToVault(options) {
+	const { jsonDir, vaultDir } = options;
+	mkdirSync(vaultDir, { recursive: true });
+	const lockPath = path.join(vaultDir, LOCK_FILENAME);
+	if (existsSync(lockPath)) {
+		throw new Error(
+			`Migration lock present at ${lockPath}. Another run is in progress, or a previous run crashed; remove the file and retry.`
+		);
+	}
+	atomicWriteFile(lockPath, new Date().toISOString());
+	try {
+		let migrated = 0;
+		let skipped = 0;
+		for (const category of CATEGORIES) {
+			const categoryResult = migrateCategory(jsonDir, vaultDir, category);
+			migrated += categoryResult.migrated;
+			skipped += categoryResult.skipped;
+		}
+		writeVaultVersion(vaultDir);
+		return { migrated, skipped };
+	} finally {
+		try {
+			rmSync(lockPath, { force: true });
+		} catch (err) {
+			getLogger().warn(`Migration: could not remove lock file ${lockPath}: ${String(err)}`);
+		}
+	}
+}
+function archiveSourceJson(jsonDir, jsonPath, category) {
+	if (!existsSync(jsonPath)) return;
+	try {
+		const legacyDir = path.join(jsonDir, '_legacy');
+		mkdirSync(legacyDir, { recursive: true });
+		const ts = new Date().toISOString().replace(/[:.]/g, '-');
+		renameSync(jsonPath, path.join(legacyDir, `${category}-${ts}.json`));
+	} catch (err) {
+		getLogger().warn(`Migration: could not archive ${category}.json: ${String(err)}`);
+	}
+}
+function buildEntryLinks(entry) {
+	const links = [];
+	if (entry.supersedes) {
+		links.push({ fromId: entry.id, kind: 'supersedes', toId: entry.supersedes });
+	}
+	return links;
+}
+function migrateCategory(jsonDir, vaultDir, category) {
+	const jsonPath = path.join(jsonDir, `${category}.json`);
+	const storeFile = readJsonStore(jsonPath);
+	if (storeFile === null) return { migrated: 0, skipped: 0 };
+	let migrated = 0;
+	let skipped = 0;
+	for (const entry of storeFile.entries) {
+		const result = migrateEntry(entry, vaultDir, category);
+		if (result === 'migrated') migrated++;
+		else skipped++;
+	}
+	archiveSourceJson(jsonDir, jsonPath, category);
+	return { migrated, skipped };
+}
+function migrateEntry(entry, vaultDir, category) {
+	const mdPath = path.join(vaultDir, category, `${entry.id}.md`);
+	if (existsSync(mdPath)) return 'skipped';
+	try {
+		const links = buildEntryLinks(entry);
+		atomicWriteFile(mdPath, serialiseMemoryFile(entry, links));
+		return 'migrated';
+	} catch (err) {
+		getLogger().warn(`Migration: skipping entry ${entry.id}: ${String(err)}`);
+		return 'skipped';
+	}
+}
+function readJsonStore(jsonPath) {
+	try {
+		const raw = readFileSync(jsonPath, 'utf-8');
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+//# sourceMappingURL=json-to-vault.js.map