@graphorin/memory 0.5.0

package/dist/search/types.d.ts

@@ -0,0 +1,50 @@
+import { MemoryHit, MemoryRecord } from "@graphorin/core";
+
+//#region src/search/types.d.ts
+
+/**
+ * Pluggable reranker contract. Concrete implementations live in
+ * `@graphorin/memory/search` (the built-in `RRFReranker`) and the
+ * Phase 16 optional packages (`@graphorin/reranker-transformersjs`,
+ * `@graphorin/reranker-llm`).
+ *
+ * The reranker accepts one or more parallel ranked lists (vector +
+ * FTS5 + optional entity boost) and produces a single fused ranking.
+ * Implementations MUST be pure (no I/O outside `signal`-aware
+ * dependencies) so the agent runtime can call them mid-stream without
+ * deadlocking the main loop.
+ *
+ * @stable
+ */
+interface ReRanker {
+  /** Stable lowercase identifier surfaced on every span. */
+  readonly id: string;
+  /**
+   * Rerank one or more parallel ranked lists and return the fused
+   * top-K (default `topK = 10`). Each input list must already be
+   * sorted by `score` descending.
+   */
+  rerank<TRecord extends MemoryRecord>(query: string, lists: ReadonlyArray<ReadonlyArray<MemoryHit<TRecord>>>, options?: ReRankOptions): Promise<ReadonlyArray<MemoryHit<TRecord>>>;
+}
+/**
+ * Per-call reranker options. `topK` defaults to `10`; `signal` is
+ * propagated to any async work the reranker performs.
+ *
+ * @stable
+ */
+interface ReRankOptions {
+  readonly topK?: number;
+  readonly signal?: AbortSignal;
+  /**
+   * Stable per-list labels for the explanation signals (MRET-13) —
+   * `rrf.<label>` instead of the ephemeral `rrf.list_<index>`. Callers
+   * that fan lists out conditionally (multi-query, HyDE, graph) pass
+   * retriever-kind labels so X-3 consumers can identify which leg a
+   * contribution came from across calls. Missing entries fall back to
+   * the positional key.
+   */
+  readonly labels?: ReadonlyArray<string>;
+}
+//#endregion
+export { ReRankOptions, ReRanker };
+//# sourceMappingURL=types.d.ts.map

package/dist/search/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../src/search/types.ts"],"sourcesContent":[],"mappings":";;;;;;AAgBA;;;;;;;;;;;;AAqBiB,UArBA,QAAA,CAqBa;;;;;;;;yBAbL,oCAEd,cAAc,cAAc,UAAU,sBACnC,gBACT,QAAQ,cAAc,UAAU;;;;;;;;UASpB,aAAA;;oBAEG;;;;;;;;;oBASA"}

package/dist/tiers/episodic-memory.d.ts

@@ -0,0 +1,142 @@
+import { MemoryStoreAdapter } from "../internal/storage-adapter.js";
+import { EmbedderProvider, Episode, MemoryHit, MemoryProvenance, MemoryStatus, Sensitivity, SessionScope, Tracer } from "@graphorin/core";
+
+//#region src/tiers/episodic-memory.d.ts
+
+/**
+ * Author-time episode payload. The framework derives `id`,
+ * `kind: 'episodic'`, `userId`, `createdAt`, `updatedAt`, and the
+ * `embedder_id` from the surrounding `EpisodicMemory.record(...)`
+ * call.
+ *
+ * @stable
+ */
+interface EpisodeInput {
+  readonly summary: string;
+  readonly startedAt: string;
+  readonly endedAt: string;
+  /** Optional importance score in `[0, 1]`. */
+  readonly importance?: number;
+  readonly sensitivity?: Sensitivity;
+  readonly tags?: ReadonlyArray<string>;
+  /**
+   * Trust-provenance tag (P1-4). Episodes auto-formed by the
+   * consolidator pass `'extraction'` so they land quarantined; omit
+   * (defaults to first-party `active`) for user-authored episodes.
+   */
+  readonly provenance?: MemoryProvenance;
+  /**
+   * Retrieval-trust state (P1-4). Defaults to `active`; the
+   * consolidator records auto-formed episodes as `'quarantined'` so
+   * they are excluded from action-driving recall until validated.
+   */
+  readonly status?: MemoryStatus;
+}
+/**
+ * Triple-signal episode retrieval weights. Defaults match DEC-105:
+ * `recency 0.3`, `relevance 0.5`, `importance 0.2`. Implementations
+ * normalize the weighted sum back to `[0, 1]`.
+ *
+ * @stable
+ */
+interface EpisodeRetrievalWeights {
+  readonly recency: number;
+  readonly relevance: number;
+  readonly importance: number;
+}
+/**
+ * Per-call options accepted by {@link EpisodicMemory.search}.
+ *
+ * @stable
+ */
+interface EpisodeSearchOptions {
+  readonly topK?: number;
+  readonly signal?: AbortSignal;
+  readonly weights?: EpisodeRetrievalWeights;
+  readonly dateRange?: {
+    readonly from?: string;
+    readonly to?: string;
+  };
+  /**
+   * Point-in-time ("as of") read. When set, only episodes that had
+   * started by this instant (`started_at <= asOf`) are returned.
+   * ISO-8601. Absent ⇒ current behaviour is unchanged. P0-2.
+   *
+   * @stable
+   */
+  readonly asOf?: string;
+  /**
+   * Include quarantined episodes in the result set (P1-4). Defaults to
+   * `false`: action-driving recall never returns quarantined rows. Set
+   * `true` only for the validation / inspector path — never for
+   * auto-recall fed back into the model. Auto-formed episodes (P1-2)
+   * land quarantined, so this is how an operator surfaces them for
+   * review.
+   *
+   * @stable
+   */
+  readonly includeQuarantined?: boolean;
+}
+/**
+ * `EpisodicMemory` — record + retrieve summarized stretches of past
+ * activity. Stored embeddings power triple-signal retrieval (recency
+ * × relevance × importance).
+ *
+ * @stable
+ */
+declare class EpisodicMemory {
+  #private;
+  constructor(args: {
+    store: MemoryStoreAdapter;
+    tracer: Tracer;
+    embedder: EmbedderProvider | null;
+    embedderIdProvider: () => string | null;
+  });
+  /** Persist an episode + its embedding (when an embedder is configured). */
+  record(scope: SessionScope, input: EpisodeInput): Promise<Episode>;
+  /** Lookup a single episode by id. */
+  get(id: string): Promise<Episode | null>;
+  /**
+   * Triple-signal episode retrieval (`recency × relevance ×
+   * importance`). The vector signal is computed on demand when an
+   * embedder is configured AND the storage adapter exposes
+   * `searchVector`; otherwise the FTS5 BM25 score is fed into the
+   * relevance term as a normalized fallback.
+   */
+  search(scope: SessionScope, query: string, opts?: EpisodeSearchOptions): Promise<ReadonlyArray<MemoryHit<Episode>>>;
+  /**
+   * Soft-archive an episode. Storage adapters that implement
+   * `EpisodicMemoryStoreExt.archive(...)` mark the row archived in
+   * place. Adapters that do not expose the extension surface a
+   * friendly `TypeError` so the operator can opt the storage layer
+   * in (or call `episodic.put(...)` with the archived state set
+   * manually).
+   */
+  archive(scope: SessionScope, episodeId: string, reason?: string): Promise<void>;
+  /**
+   * Most-recent episodes by end time (newest first), with no embedding / FTS
+   * query (MCON-1). Requires `EpisodicMemoryStoreExt.listRecent` — the default
+   * `@graphorin/store-sqlite` adapter implements it. Optionally includes
+   * quarantined episodes (the importance source for the reflection gate).
+   */
+  listRecent(scope: SessionScope, limit: number, opts?: {
+    includeQuarantined?: boolean;
+  }): Promise<ReadonlyArray<Episode>>;
+  /** List the most recent episodes (no embedding required). */
+  recent(scope: SessionScope, opts?: {
+    topK?: number;
+  }): Promise<ReadonlyArray<Episode>>;
+  /**
+   * Promote a quarantined episode into default recall (MCON-2). Mirrors
+   * {@link SemanticMemory.validate}: re-derives the injection verdict from the
+   * stored summary and **refuses** promotion of an injection-flagged episode
+   * (`QuarantinePromotionRefusedError`) unless an operator passes
+   * `{ force: true }` from a trusted, non-agent context.
+   */
+  validate(scope: SessionScope, episodeId: string, reason?: string, options?: {
+    readonly force?: boolean;
+  }): Promise<void>;
+}
+//#endregion
+export { EpisodeInput, EpisodeRetrievalWeights, EpisodeSearchOptions, EpisodicMemory };
+//# sourceMappingURL=episodic-memory.d.ts.map

package/dist/tiers/episodic-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodic-memory.d.ts","names":[],"sources":["../../src/tiers/episodic-memory.ts"],"sourcesContent":[],"mappings":";;;;;;;AAwBA;;;;;;AA6BiB,UA7BA,YAAA,CA6BuB;EAiBvB,SAAA,OAAA,EAAA,MAAoB;EAiCxB,SAAA,SAAc,EAAA,MAAA;EAOhB,SAAA,OAAA,EAAA,MAAA;EACC;EACE,SAAA,UAAA,CAAA,EAAA,MAAA;EAUQ,SAAA,WAAA,CAAA,EA5FG,WA4FH;EAAqB,SAAA,IAAA,CAAA,EA3FzB,aA2FyB,CAAA,MAAA,CAAA;EAAuB;;;;;EA+DxD,SAAA,UAAA,CAAA,EApJc,gBAoJd;EAC2B;;;;;EA8DqC,SAAA,MAAA,CAAA,EA7MtD,YA6MsD;;;;;;;;;AAwD/D,UA3PM,uBAAA,CA2PN;EAIN,SAAA,OAAA,EAAA,MAAA;EAAO,SAAA,SAAA,EAAA,MAAA;;;;;;;;UA9OK,oBAAA;;oBAEG;qBACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA8BR,cAAA;;;WAOF;YACC;cACE;;;;gBAUQ,qBAAqB,eAAe,QAAQ;;mBAiDzC,QAAQ;;;;;;;;gBAYtB,oCAED,uBACL,QAAQ,cAAc,UAAU;;;;;;;;;iBA8Dd,mDAAmD;;;;;;;oBAyB/D;;MAGN,QAAQ,cAAc;;gBAgBL;;MAA6C,QAAQ,cAAc;;;;;;;;kBAY9E;;MAIN"}

package/dist/tiers/episodic-memory.js

@@ -0,0 +1,254 @@
+import { withMemorySpan } from "../internal/spans.js";
+import { QuarantinePromotionRefusedError } from "../errors/index.js";
+import { newMemoryId } from "../internal/id.js";
+import { detectMemoryInjection } from "../internal/injection-heuristics.js";
+
+//#region src/tiers/episodic-memory.ts
+const DEFAULT_WEIGHTS = Object.freeze({
+	recency: .3,
+	relevance: .5,
+	importance: .2
+});
+/**
+* `EpisodicMemory` — record + retrieve summarized stretches of past
+* activity. Stored embeddings power triple-signal retrieval (recency
+* × relevance × importance).
+*
+* @stable
+*/
+var EpisodicMemory = class {
+	#store;
+	#tracer;
+	#embedder;
+	#embedderIdProvider;
+	constructor(args) {
+		this.#store = args.store;
+		this.#tracer = args.tracer;
+		this.#embedder = args.embedder;
+		this.#embedderIdProvider = args.embedderIdProvider;
+	}
+	/** Persist an episode + its embedding (when an embedder is configured). */
+	async record(scope, input) {
+		return withMemorySpan(this.#tracer, "memory.write.episodic", scope, {}, async (span) => {
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const episode = {
+				id: newMemoryId("ep"),
+				kind: "episodic",
+				userId: scope.userId,
+				...scope.sessionId !== void 0 ? { sessionId: scope.sessionId } : {},
+				...scope.agentId !== void 0 ? { agentId: scope.agentId } : {},
+				sensitivity: input.sensitivity ?? "internal",
+				summary: input.summary,
+				startedAt: input.startedAt,
+				endedAt: input.endedAt,
+				...input.importance !== void 0 ? { importance: input.importance } : {},
+				...input.tags !== void 0 ? { tags: Object.freeze([...input.tags]) } : {},
+				...input.provenance !== void 0 ? { provenance: input.provenance } : {},
+				...input.status !== void 0 ? { status: input.status } : {},
+				createdAt: now,
+				updatedAt: now
+			};
+			const embedderId = this.#embedderIdProvider();
+			if (this.#embedder !== null && embedderId !== null && typeof this.#store.episodic.putWithEmbedding === "function") {
+				const [vector] = await this.#embedder.embed([input.summary], { taskType: "passage" });
+				if (vector !== void 0) await this.#store.episodic.putWithEmbedding(episode, { embedding: {
+					embedderId,
+					vector
+				} });
+				else await this.#store.episodic.put(episode);
+			} else await this.#store.episodic.put(episode);
+			span.setAttributes({
+				"memory.episodic.summary_length": input.summary.length,
+				...input.importance !== void 0 ? { "memory.episodic.importance": input.importance } : {}
+			});
+			return episode;
+		});
+	}
+	/** Lookup a single episode by id. */
+	async get(id) {
+		return this.#store.episodic.get(id);
+	}
+	/**
+	* Triple-signal episode retrieval (`recency × relevance ×
+	* importance`). The vector signal is computed on demand when an
+	* embedder is configured AND the storage adapter exposes
+	* `searchVector`; otherwise the FTS5 BM25 score is fed into the
+	* relevance term as a normalized fallback.
+	*/
+	async search(scope, query, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.search.episodic", scope, { "memory.search.query_length": query.length }, async (span) => {
+			const topK = opts.topK ?? 10;
+			const weights = opts.weights ?? DEFAULT_WEIGHTS;
+			const ftsHits = await this.#store.episodic.search(scope, {
+				query,
+				topK: topK * 2,
+				...opts.asOf !== void 0 ? { asOf: opts.asOf } : {},
+				...opts.dateRange !== void 0 ? { dateRange: opts.dateRange } : {},
+				...opts.signal !== void 0 ? { signal: opts.signal } : {},
+				...opts.includeQuarantined !== void 0 ? { includeQuarantined: opts.includeQuarantined } : {}
+			});
+			const vectorHits = await this.#tryVectorSearch(scope, query, topK * 2, opts.asOf, opts.includeQuarantined);
+			const from = opts.dateRange?.from !== void 0 ? Date.parse(opts.dateRange.from) : null;
+			const to = opts.dateRange?.to !== void 0 ? Date.parse(opts.dateRange.to) : null;
+			const finalHits = mergeRecency(ftsHits, from !== null || to !== null ? vectorHits.filter((h) => {
+				if (from !== null && Date.parse(h.record.endedAt) < from) return false;
+				if (to !== null && Date.parse(h.record.startedAt) > to) return false;
+				return true;
+			}) : vectorHits, weights).slice(0, topK);
+			span.setAttributes({
+				"memory.search.episodic.fts_count": ftsHits.length,
+				"memory.search.episodic.vector_count": vectorHits.length,
+				"memory.search.episodic.final_count": finalHits.length,
+				...opts.asOf !== void 0 ? { "memory.search.episodic.as_of": opts.asOf } : {}
+			});
+			return finalHits;
+		});
+	}
+	/**
+	* Soft-archive an episode. Storage adapters that implement
+	* `EpisodicMemoryStoreExt.archive(...)` mark the row archived in
+	* place. Adapters that do not expose the extension surface a
+	* friendly `TypeError` so the operator can opt the storage layer
+	* in (or call `episodic.put(...)` with the archived state set
+	* manually).
+	*/
+	async archive(scope, episodeId, reason) {
+		await withMemorySpan(this.#tracer, "memory.write.episodic", scope, {
+			"memory.episodic.action": "archive",
+			"memory.episodic.episode_id": episodeId
+		}, async () => {
+			if (typeof this.#store.episodic.archive !== "function") throw new TypeError("[graphorin/memory] EpisodicMemory.archive(...) requires a storage adapter that implements `episodic.archive(id)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via EpisodicMemoryStoreExt.");
+			await this.#store.episodic.archive(episodeId, reason);
+		});
+	}
+	/**
+	* Most-recent episodes by end time (newest first), with no embedding / FTS
+	* query (MCON-1). Requires `EpisodicMemoryStoreExt.listRecent` — the default
+	* `@graphorin/store-sqlite` adapter implements it. Optionally includes
+	* quarantined episodes (the importance source for the reflection gate).
+	*/
+	async listRecent(scope, limit, opts = {}) {
+		return withMemorySpan(this.#tracer, "memory.read.episodic", scope, {}, async (span) => {
+			const store = this.#store.episodic;
+			if (typeof store.listRecent !== "function") throw new Error("[graphorin/memory] EpisodicMemory.listRecent requires EpisodicMemoryStoreExt.listRecent. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in.");
+			const out = await store.listRecent(scope, limit, opts);
+			span.setAttributes({ "memory.read.episodic.count": out.length });
+			return out;
+		});
+	}
+	/** List the most recent episodes (no embedding required). */
+	async recent(scope, opts = {}) {
+		return this.listRecent(scope, opts.topK ?? 10, {});
+	}
+	/**
+	* Promote a quarantined episode into default recall (MCON-2). Mirrors
+	* {@link SemanticMemory.validate}: re-derives the injection verdict from the
+	* stored summary and **refuses** promotion of an injection-flagged episode
+	* (`QuarantinePromotionRefusedError`) unless an operator passes
+	* `{ force: true }` from a trusted, non-agent context.
+	*/
+	async validate(scope, episodeId, reason, options) {
+		await withMemorySpan(this.#tracer, "memory.write.episodic", scope, {
+			"memory.episodic.action": "validate",
+			"memory.episodic.episode_id": episodeId
+		}, async (span) => {
+			const store = this.#store.episodic;
+			if (typeof store.setStatus !== "function") throw new TypeError("[graphorin/memory] EpisodicMemory.validate(...) requires a storage adapter that implements `episodic.setStatus(id, status)`. The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via EpisodicMemoryStoreExt.");
+			const force = options?.force === true;
+			const existing = await store.get(episodeId);
+			if (existing !== null && !force) {
+				const injection = detectMemoryInjection(existing.summary);
+				if (injection.flagged) {
+					span.setAttributes({ "memory.episodic.validate.refused": true });
+					throw new QuarantinePromotionRefusedError(episodeId, injection.markers);
+				}
+			}
+			span.setAttributes({ "memory.episodic.validate.forced": force });
+			await store.setStatus(episodeId, "active", reason);
+		});
+	}
+	async #tryVectorSearch(scope, query, topK, asOf, includeQuarantined) {
+		const embedderId = this.#embedderIdProvider();
+		if (this.#embedder === null || embedderId === null || typeof this.#store.episodic.searchVector !== "function") return [];
+		const [vector] = await this.#embedder.embed([query], { taskType: "query" });
+		if (vector === void 0) return [];
+		return this.#store.episodic.searchVector(scope, vector, embedderId, topK, asOf, includeQuarantined);
+	}
+};
+function mergeRecency(ftsHits, vectorHits, weights) {
+	const now = Date.now();
+	const aggregates = /* @__PURE__ */ new Map();
+	for (const hit of ftsHits) {
+		const id = hit.record.id;
+		const recency = computeRecency(now, hit.record);
+		const importance = hit.record.importance ?? 0;
+		const relevance = normalizeRelevance(hit.score);
+		const score = weights.recency * recency + weights.relevance * relevance + weights.importance * importance;
+		aggregates.set(id, {
+			record: hit.record,
+			relevance,
+			recency,
+			importance,
+			score,
+			signals: {
+				fts: relevance,
+				recency,
+				importance
+			}
+		});
+	}
+	for (const hit of vectorHits) {
+		const id = hit.record.id;
+		const cosine = clamp01(hit.score);
+		const existing = aggregates.get(id);
+		if (existing === void 0) {
+			const recency = computeRecency(now, hit.record);
+			const importance = hit.record.importance ?? 0;
+			const score = weights.recency * recency + weights.relevance * cosine + weights.importance * importance;
+			aggregates.set(id, {
+				record: hit.record,
+				relevance: cosine,
+				recency,
+				importance,
+				score,
+				signals: {
+					vector: cosine,
+					recency,
+					importance
+				}
+			});
+		} else {
+			const blended = Math.max(existing.relevance, cosine);
+			existing.relevance = blended;
+			existing.score = weights.recency * existing.recency + weights.relevance * blended + weights.importance * existing.importance;
+			existing.signals.vector = cosine;
+			existing.signals["rrf-blend"] = blended;
+		}
+	}
+	const out = Array.from(aggregates.values()).map((a) => ({
+		record: a.record,
+		score: a.score,
+		signals: Object.freeze({ ...a.signals })
+	}));
+	out.sort((a, b) => b.score - a.score);
+	return out;
+}
+function computeRecency(now, episode) {
+	const ended = Date.parse(episode.endedAt);
+	if (!Number.isFinite(ended)) return 0;
+	const elapsedDays = Math.max(0, (now - ended) / (1440 * 60 * 1e3));
+	return Math.exp(-elapsedDays / 30);
+}
+function normalizeRelevance(score) {
+	return clamp01(Math.max(0, score) / (Math.max(0, score) + 1));
+}
+function clamp01(value) {
+	if (Number.isNaN(value)) return 0;
+	if (value < 0) return 0;
+	if (value > 1) return 1;
+	return value;
+}
+
+//#endregion
+export { EpisodicMemory };
+//# sourceMappingURL=episodic-memory.js.map

package/dist/tiers/episodic-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"episodic-memory.js","names":["DEFAULT_WEIGHTS: EpisodeRetrievalWeights","#store","#tracer","#embedder","#embedderIdProvider","episode: Episode","#tryVectorSearch"],"sources":["../../src/tiers/episodic-memory.ts"],"sourcesContent":["import type {\n  EmbedderProvider,\n  Episode,\n  MemoryHit,\n  MemoryProvenance,\n  MemoryStatus,\n  Sensitivity,\n  SessionScope,\n  Tracer,\n} from '@graphorin/core';\nimport { QuarantinePromotionRefusedError } from '../errors/index.js';\nimport { newMemoryId } from '../internal/id.js';\nimport { detectMemoryInjection } from '../internal/injection-heuristics.js';\nimport { withMemorySpan } from '../internal/spans.js';\nimport type { MemoryStoreAdapter } from '../internal/storage-adapter.js';\n\n/**\n * Author-time episode payload. The framework derives `id`,\n * `kind: 'episodic'`, `userId`, `createdAt`, `updatedAt`, and the\n * `embedder_id` from the surrounding `EpisodicMemory.record(...)`\n * call.\n *\n * @stable\n */\nexport interface EpisodeInput {\n  readonly summary: string;\n  readonly startedAt: string;\n  readonly endedAt: string;\n  /** Optional importance score in `[0, 1]`. */\n  readonly importance?: number;\n  readonly sensitivity?: Sensitivity;\n  readonly tags?: ReadonlyArray<string>;\n  /**\n   * Trust-provenance tag (P1-4). Episodes auto-formed by the\n   * consolidator pass `'extraction'` so they land quarantined; omit\n   * (defaults to first-party `active`) for user-authored episodes.\n   */\n  readonly provenance?: MemoryProvenance;\n  /**\n   * Retrieval-trust state (P1-4). Defaults to `active`; the\n   * consolidator records auto-formed episodes as `'quarantined'` so\n   * they are excluded from action-driving recall until validated.\n   */\n  readonly status?: MemoryStatus;\n}\n\n/**\n * Triple-signal episode retrieval weights. Defaults match DEC-105:\n * `recency 0.3`, `relevance 0.5`, `importance 0.2`. Implementations\n * normalize the weighted sum back to `[0, 1]`.\n *\n * @stable\n */\nexport interface EpisodeRetrievalWeights {\n  readonly recency: number;\n  readonly relevance: number;\n  readonly importance: number;\n}\n\nconst DEFAULT_WEIGHTS: EpisodeRetrievalWeights = Object.freeze({\n  recency: 0.3,\n  relevance: 0.5,\n  importance: 0.2,\n});\n\n/**\n * Per-call options accepted by {@link EpisodicMemory.search}.\n *\n * @stable\n */\nexport interface EpisodeSearchOptions {\n  readonly topK?: number;\n  readonly signal?: AbortSignal;\n  readonly weights?: EpisodeRetrievalWeights;\n  readonly dateRange?: { readonly from?: string; readonly to?: string };\n  /**\n   * Point-in-time (\"as of\") read. When set, only episodes that had\n   * started by this instant (`started_at <= asOf`) are returned.\n   * ISO-8601. Absent ⇒ current behaviour is unchanged. P0-2.\n   *\n   * @stable\n   */\n  readonly asOf?: string;\n  /**\n   * Include quarantined episodes in the result set (P1-4). Defaults to\n   * `false`: action-driving recall never returns quarantined rows. Set\n   * `true` only for the validation / inspector path — never for\n   * auto-recall fed back into the model. Auto-formed episodes (P1-2)\n   * land quarantined, so this is how an operator surfaces them for\n   * review.\n   *\n   * @stable\n   */\n  readonly includeQuarantined?: boolean;\n}\n\n/**\n * `EpisodicMemory` — record + retrieve summarized stretches of past\n * activity. Stored embeddings power triple-signal retrieval (recency\n * × relevance × importance).\n *\n * @stable\n */\nexport class EpisodicMemory {\n  readonly #store: MemoryStoreAdapter;\n  readonly #tracer: Tracer;\n  readonly #embedder: EmbedderProvider | null;\n  readonly #embedderIdProvider: () => string | null;\n\n  constructor(args: {\n    store: MemoryStoreAdapter;\n    tracer: Tracer;\n    embedder: EmbedderProvider | null;\n    embedderIdProvider: () => string | null;\n  }) {\n    this.#store = args.store;\n    this.#tracer = args.tracer;\n    this.#embedder = args.embedder;\n    this.#embedderIdProvider = args.embedderIdProvider;\n  }\n\n  /** Persist an episode + its embedding (when an embedder is configured). */\n  async record(scope: SessionScope, input: EpisodeInput): Promise<Episode> {\n    return withMemorySpan(this.#tracer, 'memory.write.episodic', scope, {}, async (span) => {\n      const now = new Date().toISOString();\n      const episode: Episode = {\n        id: newMemoryId('ep'),\n        kind: 'episodic',\n        userId: scope.userId,\n        ...(scope.sessionId !== undefined ? { sessionId: scope.sessionId } : {}),\n        ...(scope.agentId !== undefined ? { agentId: scope.agentId } : {}),\n        sensitivity: input.sensitivity ?? 'internal',\n        summary: input.summary,\n        startedAt: input.startedAt,\n        endedAt: input.endedAt,\n        ...(input.importance !== undefined ? { importance: input.importance } : {}),\n        ...(input.tags !== undefined ? { tags: Object.freeze([...input.tags]) } : {}),\n        ...(input.provenance !== undefined ? { provenance: input.provenance } : {}),\n        ...(input.status !== undefined ? { status: input.status } : {}),\n        createdAt: now,\n        updatedAt: now,\n      };\n      const embedderId = this.#embedderIdProvider();\n      if (\n        this.#embedder !== null &&\n        embedderId !== null &&\n        typeof this.#store.episodic.putWithEmbedding === 'function'\n      ) {\n        // PS-10: a stored episode summary is the `passage` role for E5.\n        const [vector] = await this.#embedder.embed([input.summary], { taskType: 'passage' });\n        if (vector !== undefined) {\n          await this.#store.episodic.putWithEmbedding(episode, {\n            embedding: { embedderId, vector },\n          });\n        } else {\n          await this.#store.episodic.put(episode);\n        }\n      } else {\n        await this.#store.episodic.put(episode);\n      }\n      span.setAttributes({\n        'memory.episodic.summary_length': input.summary.length,\n        ...(input.importance !== undefined\n          ? { 'memory.episodic.importance': input.importance }\n          : {}),\n      });\n      return episode;\n    });\n  }\n\n  /** Lookup a single episode by id. */\n  async get(id: string): Promise<Episode | null> {\n    return this.#store.episodic.get(id);\n  }\n\n  /**\n   * Triple-signal episode retrieval (`recency × relevance ×\n   * importance`). The vector signal is computed on demand when an\n   * embedder is configured AND the storage adapter exposes\n   * `searchVector`; otherwise the FTS5 BM25 score is fed into the\n   * relevance term as a normalized fallback.\n   */\n  async search(\n    scope: SessionScope,\n    query: string,\n    opts: EpisodeSearchOptions = {},\n  ): Promise<ReadonlyArray<MemoryHit<Episode>>> {\n    return withMemorySpan(\n      this.#tracer,\n      'memory.search.episodic',\n      scope,\n      { 'memory.search.query_length': query.length },\n      async (span) => {\n        const topK = opts.topK ?? 10;\n        const weights = opts.weights ?? DEFAULT_WEIGHTS;\n        const ftsHits = await this.#store.episodic.search(scope, {\n          query,\n          topK: topK * 2,\n          ...(opts.asOf !== undefined ? { asOf: opts.asOf } : {}),\n          // MRET-4: forward the date filter — it was accepted by the\n          // recall_episodes tool and silently dropped right here.\n          ...(opts.dateRange !== undefined ? { dateRange: opts.dateRange } : {}),\n          ...(opts.signal !== undefined ? { signal: opts.signal } : {}),\n          ...(opts.includeQuarantined !== undefined\n            ? { includeQuarantined: opts.includeQuarantined }\n            : {}),\n        });\n        const vectorHits = await this.#tryVectorSearch(\n          scope,\n          query,\n          topK * 2,\n          opts.asOf,\n          opts.includeQuarantined,\n        );\n        // MRET-4: the vector leg's store signature is positional (no\n        // dateRange parameter) — apply the same overlap semantics to its\n        // hits so both legs agree before the merge.\n        const from = opts.dateRange?.from !== undefined ? Date.parse(opts.dateRange.from) : null;\n        const to = opts.dateRange?.to !== undefined ? Date.parse(opts.dateRange.to) : null;\n        const rangedVectorHits =\n          from !== null || to !== null\n            ? vectorHits.filter((h) => {\n                if (from !== null && Date.parse(h.record.endedAt) < from) return false;\n                if (to !== null && Date.parse(h.record.startedAt) > to) return false;\n                return true;\n              })\n            : vectorHits;\n        const merged = mergeRecency(ftsHits, rangedVectorHits, weights);\n        const finalHits = merged.slice(0, topK);\n        span.setAttributes({\n          'memory.search.episodic.fts_count': ftsHits.length,\n          'memory.search.episodic.vector_count': vectorHits.length,\n          'memory.search.episodic.final_count': finalHits.length,\n          ...(opts.asOf !== undefined ? { 'memory.search.episodic.as_of': opts.asOf } : {}),\n        });\n        return finalHits;\n      },\n    );\n  }\n\n  /**\n   * Soft-archive an episode. Storage adapters that implement\n   * `EpisodicMemoryStoreExt.archive(...)` mark the row archived in\n   * place. Adapters that do not expose the extension surface a\n   * friendly `TypeError` so the operator can opt the storage layer\n   * in (or call `episodic.put(...)` with the archived state set\n   * manually).\n   */\n  async archive(scope: SessionScope, episodeId: string, reason?: string): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.episodic',\n      scope,\n      { 'memory.episodic.action': 'archive', 'memory.episodic.episode_id': episodeId },\n      async () => {\n        if (typeof this.#store.episodic.archive !== 'function') {\n          throw new TypeError(\n            '[graphorin/memory] EpisodicMemory.archive(...) requires a storage adapter that implements `episodic.archive(id)`. ' +\n              'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via EpisodicMemoryStoreExt.',\n          );\n        }\n        await this.#store.episodic.archive(episodeId, reason);\n      },\n    );\n  }\n\n  /**\n   * Most-recent episodes by end time (newest first), with no embedding / FTS\n   * query (MCON-1). Requires `EpisodicMemoryStoreExt.listRecent` — the default\n   * `@graphorin/store-sqlite` adapter implements it. Optionally includes\n   * quarantined episodes (the importance source for the reflection gate).\n   */\n  async listRecent(\n    scope: SessionScope,\n    limit: number,\n    opts: { includeQuarantined?: boolean } = {},\n  ): Promise<ReadonlyArray<Episode>> {\n    return withMemorySpan(this.#tracer, 'memory.read.episodic', scope, {}, async (span) => {\n      const store = this.#store.episodic;\n      if (typeof store.listRecent !== 'function') {\n        throw new Error(\n          '[graphorin/memory] EpisodicMemory.listRecent requires EpisodicMemoryStoreExt.listRecent. ' +\n            'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in.',\n        );\n      }\n      const out = await store.listRecent(scope, limit, opts);\n      span.setAttributes({ 'memory.read.episodic.count': out.length });\n      return out;\n    });\n  }\n\n  /** List the most recent episodes (no embedding required). */\n  async recent(scope: SessionScope, opts: { topK?: number } = {}): Promise<ReadonlyArray<Episode>> {\n    return this.listRecent(scope, opts.topK ?? 10, {});\n  }\n\n  /**\n   * Promote a quarantined episode into default recall (MCON-2). Mirrors\n   * {@link SemanticMemory.validate}: re-derives the injection verdict from the\n   * stored summary and **refuses** promotion of an injection-flagged episode\n   * (`QuarantinePromotionRefusedError`) unless an operator passes\n   * `{ force: true }` from a trusted, non-agent context.\n   */\n  async validate(\n    scope: SessionScope,\n    episodeId: string,\n    reason?: string,\n    options?: { readonly force?: boolean },\n  ): Promise<void> {\n    await withMemorySpan(\n      this.#tracer,\n      'memory.write.episodic',\n      scope,\n      { 'memory.episodic.action': 'validate', 'memory.episodic.episode_id': episodeId },\n      async (span) => {\n        const store = this.#store.episodic;\n        if (typeof store.setStatus !== 'function') {\n          throw new TypeError(\n            '[graphorin/memory] EpisodicMemory.validate(...) requires a storage adapter that implements `episodic.setStatus(id, status)`. ' +\n              'The default `@graphorin/store-sqlite` adapter implements it; custom adapters can opt in via EpisodicMemoryStoreExt.',\n          );\n        }\n        const force = options?.force === true;\n        const existing = await store.get(episodeId);\n        if (existing !== null && !force) {\n          const injection = detectMemoryInjection(existing.summary);\n          if (injection.flagged) {\n            span.setAttributes({ 'memory.episodic.validate.refused': true });\n            throw new QuarantinePromotionRefusedError(episodeId, injection.markers);\n          }\n        }\n        span.setAttributes({ 'memory.episodic.validate.forced': force });\n        await store.setStatus(episodeId, 'active', reason);\n      },\n    );\n  }\n\n  async #tryVectorSearch(\n    scope: SessionScope,\n    query: string,\n    topK: number,\n    asOf?: string,\n    includeQuarantined?: boolean,\n  ): Promise<ReadonlyArray<MemoryHit<Episode>>> {\n    const embedderId = this.#embedderIdProvider();\n    if (\n      this.#embedder === null ||\n      embedderId === null ||\n      typeof this.#store.episodic.searchVector !== 'function'\n    ) {\n      return [];\n    }\n    // PS-10: a search query is the `query` role for E5.\n    const [vector] = await this.#embedder.embed([query], { taskType: 'query' });\n    if (vector === undefined) return [];\n    return this.#store.episodic.searchVector(\n      scope,\n      vector,\n      embedderId,\n      topK,\n      asOf,\n      includeQuarantined,\n    );\n  }\n}\n\nfunction mergeRecency(\n  ftsHits: ReadonlyArray<MemoryHit<Episode>>,\n  vectorHits: ReadonlyArray<MemoryHit<Episode>>,\n  weights: EpisodeRetrievalWeights,\n): ReadonlyArray<MemoryHit<Episode>> {\n  const now = Date.now();\n  const aggregates = new Map<\n    string,\n    {\n      record: Episode;\n      relevance: number;\n      recency: number;\n      importance: number;\n      score: number;\n      signals: Record<string, number>;\n    }\n  >();\n  for (const hit of ftsHits) {\n    const id = hit.record.id;\n    const recency = computeRecency(now, hit.record);\n    const importance = hit.record.importance ?? 0;\n    const relevance = normalizeRelevance(hit.score);\n    const score =\n      weights.recency * recency + weights.relevance * relevance + weights.importance * importance;\n    aggregates.set(id, {\n      record: hit.record,\n      relevance,\n      recency,\n      importance,\n      score,\n      signals: { fts: relevance, recency, importance },\n    });\n  }\n  for (const hit of vectorHits) {\n    const id = hit.record.id;\n    const cosine = clamp01(hit.score);\n    const existing = aggregates.get(id);\n    if (existing === undefined) {\n      const recency = computeRecency(now, hit.record);\n      const importance = hit.record.importance ?? 0;\n      const score =\n        weights.recency * recency + weights.relevance * cosine + weights.importance * importance;\n      aggregates.set(id, {\n        record: hit.record,\n        relevance: cosine,\n        recency,\n        importance,\n        score,\n        signals: { vector: cosine, recency, importance },\n      });\n    } else {\n      const blended = Math.max(existing.relevance, cosine);\n      existing.relevance = blended;\n      existing.score =\n        weights.recency * existing.recency +\n        weights.relevance * blended +\n        weights.importance * existing.importance;\n      existing.signals.vector = cosine;\n      existing.signals['rrf-blend'] = blended;\n    }\n  }\n  const out = Array.from(aggregates.values()).map((a) => ({\n    record: a.record,\n    score: a.score,\n    signals: Object.freeze({ ...a.signals }),\n  }));\n  out.sort((a, b) => b.score - a.score);\n  return out;\n}\n\nfunction computeRecency(now: number, episode: Episode): number {\n  const ended = Date.parse(episode.endedAt);\n  if (!Number.isFinite(ended)) return 0;\n  const elapsedDays = Math.max(0, (now - ended) / (24 * 60 * 60 * 1000));\n  return Math.exp(-elapsedDays / 30);\n}\n\nfunction normalizeRelevance(score: number): number {\n  // MRET-5/MST-7: the store returns `score = -bm25(...)` — POSITIVE for\n  // every FTS match (SQLite bm25 is always negative), so the old\n  // `1 / (1 + max(0, -score))` collapsed every lexical hit to exactly\n  // 1.0 and the DEC-105 triple-signal ranking degraded to\n  // recency + importance. Saturating ratio: 0 at no signal, → 1 as the\n  // match strengthens, graduated in between (k = 1 half-point).\n  return clamp01(Math.max(0, score) / (Math.max(0, score) + 1));\n}\n\nfunction clamp01(value: number): number {\n  if (Number.isNaN(value)) return 0;\n  if (value < 0) return 0;\n  if (value > 1) return 1;\n  return value;\n}\n"],"mappings":"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"}

package/dist/tiers/index.d.ts

@@ -0,0 +1,8 @@
+import { EpisodeInput, EpisodeRetrievalWeights, EpisodeSearchOptions, EpisodicMemory } from "./episodic-memory.js";
+import { FactInput, FactRememberOptions, FactSearchOptions, FusionStrategy, FusionWeights, IterativeRecallResult, IterativeSearchOptions, RememberOutcome, SemanticMemory } from "./semantic-memory.js";
+import { InsightListOptions, InsightMemory, InsightSearchOptions, capInsightsBelowFacts } from "./insight-memory.js";
+import { InduceOptions, ProceduralMemory, RuleActivationContext, RuleInput } from "./procedural-memory.js";
+import { SessionCompactionPolicy, SessionCompactionResult, SessionMemory } from "./session-memory.js";
+import { SharedMemory } from "./shared-memory.js";
+import { BlockDefinition, BlockSpec, WorkingMemory, defineBlock } from "./working-memory.js";
+export { type BlockDefinition, type BlockSpec, type EpisodeInput, type EpisodeRetrievalWeights, type EpisodeSearchOptions, EpisodicMemory, type FactInput, type FactRememberOptions, type FactSearchOptions, type FusionStrategy, type FusionWeights, type InduceOptions, type InsightListOptions, InsightMemory, type InsightSearchOptions, type IterativeRecallResult, type IterativeSearchOptions, ProceduralMemory, type RememberOutcome, type RuleActivationContext, type RuleInput, SemanticMemory, type SessionCompactionPolicy, type SessionCompactionResult, SessionMemory, SharedMemory, WorkingMemory, capInsightsBelowFacts, defineBlock };

package/dist/tiers/index.js

@@ -0,0 +1,9 @@
+import { EpisodicMemory } from "./episodic-memory.js";
+import { InsightMemory, capInsightsBelowFacts } from "./insight-memory.js";
+import { ProceduralMemory } from "./procedural-memory.js";
+import { SemanticMemory } from "./semantic-memory.js";
+import { SessionMemory } from "./session-memory.js";
+import { SharedMemory } from "./shared-memory.js";
+import { WorkingMemory, defineBlock } from "./working-memory.js";
+
+export { EpisodicMemory, InsightMemory, ProceduralMemory, SemanticMemory, SessionMemory, SharedMemory, WorkingMemory, capInsightsBelowFacts, defineBlock };

package/dist/tiers/insight-memory.d.ts

@@ -0,0 +1,71 @@
+import { MemoryStoreAdapter } from "../internal/storage-adapter.js";
+import { Fact, Insight, MemoryHit, SessionScope, Tracer } from "@graphorin/core";
+
+//#region src/tiers/insight-memory.d.ts
+
+/** Per-call options accepted by {@link InsightMemory.search}. */
+interface InsightSearchOptions {
+  readonly topK?: number;
+  /**
+   * Include quarantined insights (P1-4). Defaults to `false`. Since
+   * reflection-synthesized insights *always* land quarantined, set this
+   * `true` to surface them for the validation / inspector path — never
+   * for auto-recall fed back into the model.
+   */
+  readonly includeQuarantined?: boolean;
+  readonly signal?: AbortSignal;
+}
+/** Per-call options accepted by {@link InsightMemory.list}. */
+interface InsightListOptions {
+  readonly limit?: number;
+  /** Include quarantined insights (validation / inspector path). */
+  readonly includeQuarantined?: boolean;
+}
+/**
+ * `InsightMemory` — list / search reflection insights. A no-op (returns
+ * empty) when the storage adapter does not expose the optional
+ * `insights` surface.
+ *
+ * @stable
+ */
+declare class InsightMemory {
+  #private;
+  constructor(args: {
+    store: MemoryStoreAdapter;
+    tracer: Tracer;
+  });
+  /** FTS keyword search over insight text. */
+  search(scope: SessionScope, query: string, opts?: InsightSearchOptions): Promise<ReadonlyArray<MemoryHit<Insight>>>;
+  /** Most-recent insights for the scope (newest first). */
+  list(scope: SessionScope, opts?: InsightListOptions): Promise<ReadonlyArray<Insight>>;
+  /** Lookup a single insight by id. */
+  get(id: string): Promise<Insight | null>;
+  /**
+   * Promote a quarantined insight out of quarantine (MCON-2). Mirrors
+   * {@link SemanticMemory.validate}: re-derives the injection verdict from the
+   * stored text and **refuses** promotion of an injection-flagged insight
+   * unless an operator passes `{ force: true }` from a trusted context.
+   */
+  validate(scope: SessionScope, insightId: string, reason?: string, options?: {
+    readonly force?: boolean;
+  }): Promise<void>;
+}
+/**
+ * Enforce the P1-1 rank ceiling: an insight may never outrank a primary
+ * fact **it cites**. For each insight hit, if any fact it cites is
+ * present in `factHits`, its score is lowered to strictly below that
+ * cited fact's score — so concatenating the two lists and sorting by
+ * score descending can never place the insight above the evidence it
+ * was synthesized from. Insights whose cited facts are absent from
+ * `factHits` are returned unchanged; this is a relative, not a global,
+ * cap (per the execution plan: "never outrank the primary facts they
+ * cite").
+ *
+ * Pure + deterministic — does not mutate its inputs.
+ *
+ * @stable
+ */
+declare function capInsightsBelowFacts(factHits: ReadonlyArray<MemoryHit<Fact>>, insightHits: ReadonlyArray<MemoryHit<Insight>>): ReadonlyArray<MemoryHit<Insight>>;
+//#endregion
+export { InsightListOptions, InsightMemory, InsightSearchOptions, capInsightsBelowFacts };
+//# sourceMappingURL=insight-memory.d.ts.map

package/dist/tiers/insight-memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight-memory.d.ts","names":[],"sources":["../../src/tiers/insight-memory.ts"],"sourcesContent":[],"mappings":";;;;;;AAkGwF,UA5EvE,oBAAA,CA4EuE;EAAd,SAAA,IAAA,CAAA,EAAA,MAAA;EAAR;;;;;;EAoFlD,SAAA,kBAAqB,CAAA,EAAA,OAAA;EACD,SAAA,MAAA,CAAA,EAxJhB,WAwJgB;;;AACG,UArJtB,kBAAA,CAqJsB;EAAV,SAAA,KAAA,CAAA,EAAA,MAAA;EAAd;EACY,SAAA,kBAAA,CAAA,EAAA,OAAA;;;;;;;;;cAzId,aAAA;;;WAIgB;YAA4B;;;gBAO9C,oCAED,uBACL,QAAQ,cAAc,UAAU;;cAoCjB,qBAAoB,qBAA0B,QAAQ,cAAc;;mBAmB/D,QAAQ;;;;;;;kBAatB;;MAIN;;;;;;;;;;;;;;;;;iBAgDW,qBAAA,WACJ,cAAc,UAAU,qBACrB,cAAc,UAAU,YACpC,cAAc,UAAU"}