anno-extension 0.1.0

package/src/reconsolidate-v2.ts

@@ -0,0 +1,145 @@
+/**
+ * [WHO]: reconsolidateV2Memories
+ * [FROM]: Depends on ./scoring.js, ./types-v2.js
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/reconsolidate-v2.ts - lightweight reconsolidation rules for NanoMem v2 memories
+ */
+
+import { extractTags, tagOverlap } from "./scoring.js";
+import type { EpisodeFacet, EpisodeMemory, ProceduralMemory } from "./types-v2.js";
+
+function mergeUnique<T>(values: T[]): T[] {
+	return [...new Set(values)];
+}
+
+function textForProcedure(entry: ProceduralMemory): string {
+	return [entry.name, entry.searchText, entry.summary, entry.contextText ?? "", entry.boundaries ?? ""]
+		.filter(Boolean)
+		.join(" ")
+		.toLowerCase();
+}
+
+function shouldMergeProcedures(a: ProceduralMemory, b: ProceduralMemory): boolean {
+	if (a.id === b.id) return false;
+	const tagScore = tagOverlap(a.tags, b.tags);
+	if (tagScore >= 0.7) return true;
+	const aText = textForProcedure(a);
+	const bText = textForProcedure(b);
+	return aText.includes(b.searchText.toLowerCase()) || bText.includes(a.searchText.toLowerCase());
+}
+
+export function reconsolidateV2Memories(
+	episodes: EpisodeMemory[],
+	facets: EpisodeFacet[],
+	procedural: ProceduralMemory[],
+	recalledEpisodeIds: string[],
+	recalledFacetIds: string[],
+	recalledProcedureIds: string[],
+	now = new Date().toISOString(),
+): {
+	episodes: EpisodeMemory[];
+	facets: EpisodeFacet[];
+	procedural: ProceduralMemory[];
+	changes: { promotedProcedures: number; mergedProcedures: number; stabilizedEpisodes: number; stabilizedFacets: number };
+} {
+	let promotedProcedures = 0;
+	let mergedProcedures = 0;
+	let stabilizedEpisodes = 0;
+	let stabilizedFacets = 0;
+
+	const recalledEpisodeSet = new Set(recalledEpisodeIds);
+	const recalledFacetSet = new Set(recalledFacetIds);
+	const recalledProcedureSet = new Set(recalledProcedureIds);
+
+	for (const episode of episodes) {
+		if (!recalledEpisodeSet.has(episode.id)) continue;
+		episode.reconsolidatedAt = now;
+		if (episode.accessCount >= 3 && episode.retention !== "key-event") {
+			episode.retention = "key-event";
+			stabilizedEpisodes++;
+		}
+		if (episode.accessCount >= 4 && episode.stability !== "stable") {
+			episode.stability = "stable";
+			stabilizedEpisodes++;
+		}
+		episode.tags = mergeUnique(extractTags(`${episode.title ?? ""} ${episode.summary} ${episode.userGoal ?? ""} ${episode.outcome ?? ""}`));
+	}
+
+	for (const facet of facets) {
+		if (!recalledFacetSet.has(facet.id)) continue;
+		if (facet.accessCount >= 3 && facet.retention !== "key-event") {
+			facet.retention = "key-event";
+			stabilizedFacets++;
+		}
+		if (facet.accessCount >= 4 && facet.stability !== "stable") {
+			facet.stability = "stable";
+			stabilizedFacets++;
+		}
+		facet.tags = mergeUnique(extractTags(`${facet.searchText} ${facet.summary ?? ""} ${facet.anchorText ?? ""}`));
+	}
+
+	const sortedProcedural = [...procedural].sort((a, b) => (b.accessCount ?? 0) - (a.accessCount ?? 0));
+	const keptProcedural: ProceduralMemory[] = [];
+	const supersededProcedural: ProceduralMemory[] = [];
+
+	for (const procedure of sortedProcedural) {
+		if (recalledProcedureSet.has(procedure.id) && procedure.status === "draft" && procedure.accessCount >= 2) {
+			procedure.status = "active";
+			procedure.version = Math.max(1, procedure.version);
+			procedure.confidence = Math.max(procedure.confidence, 0.82);
+			promotedProcedures++;
+		}
+
+		procedure.tags = mergeUnique(
+			extractTags(
+				`${procedure.name} ${procedure.searchText} ${procedure.summary} ${procedure.contextText ?? ""} ${procedure.steps.map((step) => step.text).join(" ")}`,
+			),
+		);
+
+		const keeper = keptProcedural.find((candidate) => shouldMergeProcedures(candidate, procedure));
+		if (!keeper) {
+			keptProcedural.push(procedure);
+			continue;
+		}
+
+		keeper.steps = mergeUnique([...keeper.steps.map((step) => step.text), ...procedure.steps.map((step) => step.text)]).map(
+			(text, index) => ({
+				id: `${keeper.id}:step:${index + 1}`,
+				text,
+				kind: keeper.steps[index]?.kind ?? procedure.steps[index]?.kind ?? "step",
+			}),
+		);
+		keeper.tags = mergeUnique([...(keeper.tags ?? []), ...(procedure.tags ?? [])]);
+		keeper.sourceEpisodeIds = mergeUnique([...(keeper.sourceEpisodeIds ?? []), ...(procedure.sourceEpisodeIds ?? [])]);
+		keeper.sourceFacetIds = mergeUnique([...(keeper.sourceFacetIds ?? []), ...(procedure.sourceFacetIds ?? [])]);
+		keeper.supersedesIds = mergeUnique([...(keeper.supersedesIds ?? []), procedure.id]);
+		keeper.version = Math.max(keeper.version, procedure.version) + 1;
+		keeper.updatedAt = now;
+		keeper.confidence = Math.max(keeper.confidence, procedure.confidence);
+		keeper.salience = Math.max(keeper.salience, procedure.salience);
+		keeper.importance = Math.max(keeper.importance, procedure.importance);
+		if (keeper.status === "draft" && procedure.status === "active") {
+			keeper.status = "active";
+		}
+
+		supersededProcedural.push({
+			...procedure,
+			status: "superseded",
+			supersededById: keeper.id,
+			updatedAt: now,
+		});
+		mergedProcedures++;
+	}
+
+	return {
+		episodes,
+		facets,
+		procedural: [...keptProcedural, ...supersededProcedural],
+		changes: {
+			promotedProcedures,
+			mergedProcedures,
+			stabilizedEpisodes,
+			stabilizedFacets,
+		},
+	};
+}

package/src/scoring.ts

@@ -0,0 +1,156 @@
+/**
+ * [WHO]: daysSince, decay, extractTags, tagOverlap, scoreEntry, scoreWork, ScoreWeights
+ * [FROM]: Depends on ./config.js, ./types.js
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/scoring.ts - core ranking algorithm (Recency + Importance + Relevance), Ebbinghaus spaced repetition
+ */
+
+
+import type { Episode, InjectionLevel, MemoryEntry, WorkEntry } from "./types.js";
+import type { ProgressiveRecallConfig } from "./config.js";
+
+export function daysSince(iso: string): number {
+	return Math.max(0, (Date.now() - new Date(iso).getTime()) / 86_400_000);
+}
+
+/** Ebbinghaus decay: R = e^(-t * ln2 / S) where S = per-entry strength */
+export function decay(ageDays: number, strength: number): number {
+	return Math.exp((-ageDays * Math.LN2) / Math.max(1, strength));
+}
+
+export function extractTags(text: string): string[] {
+	return [...new Set(text.toLowerCase().match(/[a-z0-9\u4e00-\u9fff_.-]{2,}/g) || [])].slice(0, 30);
+}
+
+export function tagOverlap(a: string[], b: string[]): number {
+	if (!a.length || !b.length) return 0;
+	const setB = new Set(b);
+	return a.filter((t) => setB.has(t)).length / Math.max(a.length, b.length);
+}
+
+export interface ScoreWeights {
+	recency: number;
+	importance: number;
+	relevance: number;
+}
+
+export function scoreEntry(
+	e: MemoryEntry,
+	project: string,
+	ctx: string[],
+	defaultHalfLife: Record<string, number>,
+	weights: ScoreWeights,
+): number {
+	const strength = e.strength || defaultHalfLife[e.type] || 30;
+	const recency = decay(daysSince(e.created), strength);
+	const importanceNorm = Math.min(1, e.importance / 10);
+	const salienceNorm = Math.min(1, (e.salience ?? e.importance) / 10);
+	const projectMatch = e.project === project ? 1 : 0.5;
+	const relevance = projectMatch * (0.3 + 0.7 * tagOverlap(e.tags, ctx));
+	const retentionBoost =
+		e.retention === "core" ? 0.2 : e.retention === "key-event" ? 0.25 : 0;
+	const stabilityBoost = e.stability === "stable" ? 0.08 : -0.12;
+	const situationalPenalty =
+		e.stability === "situational" && daysSince(e.created) > 10 ? 0.18 : 0;
+	return (
+		weights.recency * recency +
+		weights.importance * importanceNorm +
+		weights.relevance * relevance +
+		salienceNorm * 0.25 +
+		retentionBoost +
+		stabilityBoost -
+		situationalPenalty
+	);
+}
+
+export function scoreEpisode(
+	ep: Episode,
+	project: string,
+	ctx: string[],
+	defaultHalfLife: Record<string, number>,
+	weights: ScoreWeights,
+): number {
+	const strength = defaultHalfLife.episode || 14;
+	const recency = decay(daysSince(ep.date), strength);
+	const importanceNorm = Math.min(1, ep.importance / 10);
+	const projectMatch = ep.project === project ? 1 : 0.5;
+	const relevance = projectMatch * (0.3 + 0.7 * tagOverlap(ep.tags, ctx));
+	return weights.recency * recency + weights.importance * importanceNorm + weights.relevance * relevance;
+}
+
+export function scoreWorkEntry(
+	w: WorkEntry,
+	project: string,
+	ctx: string[],
+	defaultHalfLife: Record<string, number>,
+	weights: ScoreWeights,
+): number {
+	const strength = w.strength || defaultHalfLife.work || 45;
+	const recency = decay(daysSince(w.created), strength);
+	const importanceNorm = Math.min(1, w.importance / 10);
+	const projectMatch = w.project === project ? 1 : 0.5;
+	const relevance = projectMatch * (0.3 + 0.7 * tagOverlap(w.tags, ctx));
+	return weights.recency * recency + weights.importance * importanceNorm + weights.relevance * relevance;
+}
+
+/** Budget-constrained top-k selection by score */
+export function pickTop<T>(items: T[], scoreFn: (t: T) => number, lenFn: (t: T) => number, budget: number): T[] {
+	const scored = items.map((t) => ({ item: t, score: scoreFn(t) })).sort((a, b) => b.score - a.score);
+	const result: T[] = [];
+	let used = 0;
+	for (const { item } of scored) {
+		const len = lenFn(item);
+		if (used + len > budget) continue;
+		used += len;
+		result.push(item);
+	}
+	return result;
+}
+
+// ─── Progressive Recall ─────────────────────────────────────
+
+/** Determine the injection tier for a single entry based on its score and config */
+export function getInjectionLevel(
+	entry: MemoryEntry,
+	score: number,
+	cfg: ProgressiveRecallConfig,
+): InjectionLevel {
+	const hoursSinceCreation = (Date.now() - new Date(entry.created).getTime()) / 3_600_000;
+
+	// Force Active for very recent or critical entries
+	if (hoursSinceCreation <= cfg.forceRecentHours) return "active";
+	if (entry.importance >= cfg.forceImportanceMin) return "active";
+	if (entry.retention === "key-event" && (entry.salience ?? entry.importance) >= 7) return "active";
+	if (entry.retention === "core" && score >= cfg.thresholdCue) return "active";
+	if (score >= cfg.thresholdActive) return "active";
+	if (score >= cfg.thresholdCue) return "cue";
+	return "dormant";
+}
+
+/** Classify entries into Active / Cue / Dormant tiers, each sorted by score descending */
+export function tierEntries(
+	entries: MemoryEntry[],
+	project: string,
+	contextTags: string[],
+	halfLife: Record<string, number>,
+	weights: ScoreWeights,
+	prCfg: ProgressiveRecallConfig,
+): { active: MemoryEntry[]; cue: MemoryEntry[]; dormant: MemoryEntry[] } {
+	const active: Array<{ entry: MemoryEntry; score: number }> = [];
+	const cue: Array<{ entry: MemoryEntry; score: number }> = [];
+	const dormant: Array<{ entry: MemoryEntry; score: number }> = [];
+
+	for (const entry of entries) {
+		const score = scoreEntry(entry, project, contextTags, halfLife, weights);
+		const level = getInjectionLevel(entry, score, prCfg);
+
+		if (level === "active") active.push({ entry, score });
+		else if (level === "cue") cue.push({ entry, score });
+		else dormant.push({ entry, score });
+	}
+
+	const sortDesc = (arr: Array<{ entry: MemoryEntry; score: number }>) =>
+		arr.sort((a, b) => b.score - a.score).map((x) => x.entry);
+
+	return { active: sortDesc(active), cue: sortDesc(cue), dormant: sortDesc(dormant) };
+}

package/src/store-v2.ts

@@ -0,0 +1,138 @@
+/**
+ * [WHO]: V2_PATHS, loadV2*, saveV2*, appendV2Episode, appendV2Facet
+ * [FROM]: Depends on browser-fs.ts, ./store.js, ./types.js, ./types-v2.js
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/store-v2.ts - persistence layer for NanoMem v2 layered memory (episode/facet/semantic/procedural/state/link stores)
+ */
+
+import { join } from "./browser-fs.js";
+import { readJson, writeJson } from "./store.js";
+import type {
+	EpisodeFacet,
+	EpisodeMemory,
+	MemoryLink,
+	NanoMemV2Snapshot,
+	ProceduralMemory,
+	SemanticMemory,
+	StateMemory,
+	V2Meta,
+} from "./types-v2.js";
+
+export interface NanoMemV2Paths {
+	rootDir: string;
+	episodesPath: string;
+	facetsPath: string;
+	semanticPath: string;
+	proceduralPath: string;
+	statePath: string;
+	linksPath: string;
+	metaPath: string;
+}
+
+const DEFAULT_V2_META: V2Meta = {
+	version: 2,
+};
+
+export function getV2Paths(memoryDir: string): NanoMemV2Paths {
+	const rootDir = join(memoryDir, "v2");
+	return {
+		rootDir,
+		episodesPath: join(rootDir, "episodes.json"),
+		facetsPath: join(rootDir, "facets.json"),
+		semanticPath: join(rootDir, "semantic.json"),
+		proceduralPath: join(rootDir, "procedural.json"),
+		statePath: join(rootDir, "state.json"),
+		linksPath: join(rootDir, "links.json"),
+		metaPath: join(rootDir, "meta.json"),
+	};
+}
+
+export async function loadV2Episodes(paths: NanoMemV2Paths): Promise<EpisodeMemory[]> {
+	return readJson<EpisodeMemory[]>(paths.episodesPath, []);
+}
+
+export async function saveV2Episodes(paths: NanoMemV2Paths, episodes: EpisodeMemory[]): Promise<void> {
+	await writeJson(paths.episodesPath, episodes);
+}
+
+export async function loadV2Facets(paths: NanoMemV2Paths): Promise<EpisodeFacet[]> {
+	return readJson<EpisodeFacet[]>(paths.facetsPath, []);
+}
+
+export async function saveV2Facets(paths: NanoMemV2Paths, facets: EpisodeFacet[]): Promise<void> {
+	await writeJson(paths.facetsPath, facets);
+}
+
+export async function loadV2Semantic(paths: NanoMemV2Paths): Promise<SemanticMemory[]> {
+	return readJson<SemanticMemory[]>(paths.semanticPath, []);
+}
+
+export async function saveV2Semantic(paths: NanoMemV2Paths, semantic: SemanticMemory[]): Promise<void> {
+	await writeJson(paths.semanticPath, semantic);
+}
+
+export async function loadV2Procedural(paths: NanoMemV2Paths): Promise<ProceduralMemory[]> {
+	return readJson<ProceduralMemory[]>(paths.proceduralPath, []);
+}
+
+export async function saveV2Procedural(paths: NanoMemV2Paths, procedural: ProceduralMemory[]): Promise<void> {
+	await writeJson(paths.proceduralPath, procedural);
+}
+
+export async function loadV2State(paths: NanoMemV2Paths): Promise<StateMemory[]> {
+	return readJson<StateMemory[]>(paths.statePath, []);
+}
+
+export async function saveV2State(paths: NanoMemV2Paths, state: StateMemory[]): Promise<void> {
+	await writeJson(paths.statePath, state);
+}
+
+export async function loadV2Links(paths: NanoMemV2Paths): Promise<MemoryLink[]> {
+	return readJson<MemoryLink[]>(paths.linksPath, []);
+}
+
+export async function saveV2Links(paths: NanoMemV2Paths, links: MemoryLink[]): Promise<void> {
+	await writeJson(paths.linksPath, links);
+}
+
+export async function loadV2Meta(paths: NanoMemV2Paths): Promise<V2Meta> {
+	return readJson<V2Meta>(paths.metaPath, DEFAULT_V2_META);
+}
+
+export async function saveV2Meta(paths: NanoMemV2Paths, meta: V2Meta): Promise<void> {
+	await writeJson(paths.metaPath, meta);
+}
+
+export async function loadV2Snapshot(paths: NanoMemV2Paths): Promise<NanoMemV2Snapshot> {
+	const [episodes, facets, semantic, procedural, state, links, meta] = await Promise.all([
+		loadV2Episodes(paths),
+		loadV2Facets(paths),
+		loadV2Semantic(paths),
+		loadV2Procedural(paths),
+		loadV2State(paths),
+		loadV2Links(paths),
+		loadV2Meta(paths),
+	]);
+
+	return {
+		episodes,
+		facets,
+		semantic,
+		procedural,
+		state,
+		links,
+		meta,
+	};
+}
+
+export async function saveV2Snapshot(paths: NanoMemV2Paths, snapshot: NanoMemV2Snapshot): Promise<void> {
+	await Promise.all([
+		saveV2Episodes(paths, snapshot.episodes),
+		saveV2Facets(paths, snapshot.facets),
+		saveV2Semantic(paths, snapshot.semantic),
+		saveV2Procedural(paths, snapshot.procedural),
+		saveV2State(paths, snapshot.state),
+		saveV2Links(paths, snapshot.links),
+		saveV2Meta(paths, snapshot.meta),
+	]);
+}

package/src/store.ts

@@ -0,0 +1,137 @@
+/**
+ * [WHO]: readJson, writeJson, deriveNameFromContent, deriveSummaryFromContent, ensureDir
+ * [FROM]: Depends on browser-fs.ts and ./types.js
+ * [TO]: Consumed by packages/mem-core/src/index.ts
+ * [HERE]: packages/mem-core/src/store.ts - persistence layer for JSON storage, all other modules go through here
+ */
+
+
+import { mkdir, readdir, readFile, writeFile, dirname, join } from "./browser-fs.js";
+import type { Episode, MemoryEntry, Meta, WorkEntry } from "./types.js";
+
+async function ensureDir(dir: string): Promise<void> {
+	await mkdir(dir, { recursive: true });
+}
+
+export async function readJson<T>(path: string, fallback: T): Promise<T> {
+	try {
+		const raw = await readFile(path);
+		return JSON.parse(raw) as T;
+	} catch {
+		return fallback;
+	}
+}
+
+export async function writeJson(path: string, data: unknown): Promise<void> {
+	await ensureDir(dirname(path));
+	await writeFile(path, JSON.stringify(data, null, 2));
+}
+
+// ─── Migration helpers ──────────────────────────────────────
+
+/** Derive a short name (≤30 chars) from content text */
+function deriveNameFromContent(content: string): string {
+	if (!content) return "untitled";
+	const words = content.split(/\s+/).filter((w) => w.length > 0);
+	const name = words.slice(0, 5).join(" ");
+	return name.length > 30 ? `${name.slice(0, 27)}...` : name || "untitled";
+}
+
+/** Derive a summary (≤150 chars) from content text, breaking at sentence boundary */
+function deriveSummaryFromContent(content: string): string {
+	if (!content) return "";
+	if (content.length <= 150) return content;
+	// Try to break at a sentence boundary
+	const cut = content.slice(0, 160).search(/[。.!！?？]\s*/);
+	if (cut > 50) return content.slice(0, cut + 1);
+	return `${content.slice(0, 147)}...`;
+}
+
+/** Auto-migrate old-format entry (content only) to name/summary/detail */
+function migrateEntry(entry: MemoryEntry): MemoryEntry {
+	if (entry.name && entry.summary) return entry;
+	const content = entry.content || entry.detail || "";
+	return {
+		...entry,
+		name: entry.name || deriveNameFromContent(content),
+		summary: entry.summary || deriveSummaryFromContent(content),
+		detail: entry.detail || content,
+	};
+}
+
+// ─── MemoryEntry CRUD ───────────────────────────────────────
+
+export async function loadEntries(path: string): Promise<MemoryEntry[]> {
+	const entries = await readJson<unknown>(path, []);
+	if (!Array.isArray(entries)) return [];
+	return entries.filter(isMemoryEntryLike).map(migrateEntry);
+}
+
+function isMemoryEntryLike(value: unknown): value is MemoryEntry {
+	if (typeof value !== "object" || value === null) return false;
+	const entry = value as Partial<MemoryEntry>;
+	return (
+		typeof entry.id === "string" &&
+		typeof entry.type === "string" &&
+		Array.isArray(entry.tags) &&
+		typeof entry.project === "string" &&
+		typeof entry.importance === "number" &&
+		typeof entry.created === "string" &&
+		typeof entry.accessCount === "number"
+	);
+}
+
+export async function saveEntries(
+	path: string,
+	entries: MemoryEntry[],
+	max: number,
+	utilityFn: (e: MemoryEntry) => number,
+): Promise<void> {
+	if (entries.length > max) {
+		entries.sort((a, b) => utilityFn(b) - utilityFn(a));
+		entries.length = max;
+	}
+	// Keep content as alias of detail for backward compat with older NanoMem versions
+	const persisted = entries.map((e) => ({ ...e, content: e.detail || e.content || e.summary || "" }));
+	await writeJson(path, persisted);
+}
+
+export async function loadEpisodes(episodesDir: string): Promise<Episode[]> {
+	await ensureDir(episodesDir);
+	const files = await readdir(episodesDir);
+	const results: Episode[] = [];
+	for (const f of files) {
+		if (!f.endsWith(".json")) continue;
+		const ep = await readJson<Episode | null>(join(episodesDir, f), null);
+		if (ep) results.push(ep);
+	}
+	return results;
+}
+
+export async function saveEpisode(episodesDir: string, ep: Episode): Promise<void> {
+	await ensureDir(episodesDir);
+	await writeJson(join(episodesDir, `${ep.date}-${ep.sessionId.slice(0, 8)}.json`), ep);
+}
+
+export async function loadWork(path: string): Promise<WorkEntry[]> {
+	return readJson<WorkEntry[]>(path, []);
+}
+
+export async function saveWork(
+	path: string,
+	entries: WorkEntry[],
+	max: number,
+	utilityFn: (w: WorkEntry) => number,
+): Promise<void> {
+	if (entries.length > max) {
+		entries.sort((a, b) => utilityFn(b) - utilityFn(a));
+		entries.length = max;
+	}
+	await writeJson(path, entries);
+}
+
+export async function loadMeta(path: string): Promise<Meta> {
+	return readJson<Meta>(path, { totalSessions: 0, version: 1 });
+}
+
+export { deriveNameFromContent, deriveSummaryFromContent };

package/src/turn-context.ts

@@ -0,0 +1,56 @@
+/**
+ * [WHO]: Provides TurnContext, MemoryRecallRecord, getTurnContext(), setTurnContext(), TURN_CONTEXT_GLOBAL_KEY
+ * [FROM]: Depends on nothing; reads/writes globalThis using the documented key
+ * [TO]: Consumed by engine-scoring-v2.ts (reads structuralAnchor), engine.ts (writes memoryRecallSnapshot)
+ * [HERE]: packages/mem-core/src/turn-context.ts - structural mirror of core/runtime/turn-context; mem-core cannot reverse-import the main app, so the contract is shared via the globalThis key string and schema, not the source file
+ *
+ * Keep this file structurally aligned with core/runtime/turn-context.ts.
+ * If the schema changes there, mirror the change here.
+ */
+
+export interface MemoryRecallRecord {
+	memoryId: string;
+	memoryKind: string;
+	anchorModule?: string;
+	anchorFile?: string;
+	scoreBreakdownStatus: "available" | "unavailable";
+	scoreRecency?: number;
+	scoreImportance?: number;
+	scoreRelevance?: number;
+	scoreStructural?: number;
+	scoreFinal: number;
+	wasInjected: boolean;
+	injectRank?: number;
+}
+
+export interface TurnContext {
+	structuralAnchor?: {
+		modulePath?: string;
+		filePath?: string;
+		candidatePaths?: string[];
+	};
+	memoryRecallSnapshot?: MemoryRecallRecord[];
+}
+
+export const TURN_CONTEXT_GLOBAL_KEY = "__catuiTurnContext";
+
+function store(): TurnContext {
+	const g = globalThis as unknown as Record<string, TurnContext | undefined>;
+	if (!g[TURN_CONTEXT_GLOBAL_KEY]) g[TURN_CONTEXT_GLOBAL_KEY] = {};
+	return g[TURN_CONTEXT_GLOBAL_KEY] as TurnContext;
+}
+
+/** Read the current value of a turn-context channel. Returns undefined when no producer has published. */
+export function getTurnContext<K extends keyof TurnContext>(key: K): TurnContext[K] {
+	return store()[key];
+}
+
+/** Publish (or clear) a turn-context channel. mem-core uses this to publish memoryRecallSnapshot. */
+export function setTurnContext<K extends keyof TurnContext>(key: K, value: TurnContext[K]): void {
+	const s = store();
+	if (value === undefined) {
+		delete s[key];
+	} else {
+		s[key] = value;
+	}
+}