@graphrefly/graphrefly 0.47.2 → 0.48.0

package/dist/utils/memory/index.d.cts

@@ -173,6 +173,16 @@ interface FactStoreAuditRecord extends BaseAuditRecord {
     readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "decay" | "overflow";
     readonly id?: FactId;
     readonly reason?: CascadeReason;
+    /**
+     * Number of facts whose state actually changed in a batch action
+     * (post-filter — excludes no-op / non-finite / resurrection-guard
+     * skips; equals the length of the emitted `decay_processor` value
+     * array). Populated for `"decay"` (a per-tick batch over many facts
+     * with no single `id` — the bare `{action,t_ns,seq}` record was opaque
+     * to audit-log forensics). Absent for single-fact actions (`id`
+     * carries those).
+     */
+    readonly count?: number;
 }
 interface ReactiveFactStoreConfig<T> {
     readonly extractDependencies: (f: MemoryFragment<T>) => readonly FactId[];
@@ -306,29 +316,6 @@ interface ReactiveFactStoreConfig<T> {
      */
     readonly recordIngest?: boolean;
 }
-interface ReactiveFactStoreGraph<T> extends Graph {
-    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
-    readonly shards: readonly Node<FactStore<T>>[];
-    /** Unified read view across all shards (derived). */
-    readonly factStore: Node<FactStore<T>>;
-    readonly dependentsIndex: Node<DependentsIndex>;
-    readonly answer: Node<MemoryAnswer<T> | null>;
-    readonly cascade: Node<readonly CascadeEvent[]>;
-    readonly cascadeOverflow: Node<CascadeOverflow | null>;
-    readonly review: Node<ReviewRequest | null>;
-    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
-    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
-    /**
-     * Payload-carrying, replayable log of every committed fragment. Present iff
-     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
-     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
-     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
-     * replayable projection source (see `recordIngest` docs for the recipe).
-     */
-    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
-    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
-    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
-}
 /**
  * Build a static-topology reactive fact store (DS-14.7 architecture C).
  *
@@ -362,6 +349,38 @@ interface ReactiveFactStoreGraph<T> extends Graph {
  *
  * @category memory
  */
+declare class ReactiveFactStoreGraph<T> extends Graph {
+    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
+    readonly shards: readonly Node<FactStore<T>>[];
+    /** Unified read view across all shards (derived). */
+    readonly factStore: Node<FactStore<T>>;
+    readonly dependentsIndex: Node<DependentsIndex>;
+    readonly answer: Node<MemoryAnswer<T> | null>;
+    readonly cascade: Node<readonly CascadeEvent[]>;
+    readonly cascadeOverflow: Node<CascadeOverflow | null>;
+    readonly review: Node<ReviewRequest | null>;
+    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
+    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
+    /**
+     * Payload-carrying, replayable log of every committed fragment. Present iff
+     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
+     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
+     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
+     * replayable projection source (see `recordIngest` docs for the recipe).
+     */
+    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
+    constructor(config: ReactiveFactStoreConfig<T>);
+    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
+    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
+}
+/**
+ * Build a static-topology reactive fact store (DS-14.7 architecture C).
+ *
+ * Thin factory over {@link ReactiveFactStoreGraph} — see that class for the
+ * full topology / locked-decision docs and the `instanceof`-narrowable type.
+ *
+ * @category memory
+ */
 declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
 
 /**
@@ -954,6 +973,166 @@ interface ShardByTenantConfig<T> {
  */
 declare function shardByTenant<T>(tenantOf: (f: MemoryFragment<T>) => string, opts?: ShardByTenantOptions): ShardByTenantConfig<T>;
 
+/**
+ * `simpleFactStore()` — the 80%-case ergonomic wrapper over
+ * {@link reactiveFactStore} / {@link persistentReactiveFactStore}
+ * (DS-14.7 follow-up #2; design LOCKED 2026-05-17 `/dev-dispatch` Q-walk,
+ * Q1–Q6 + sub-decisions resolved).
+ *
+ * Closes the gap where a consumer wanting durable agent memory had to
+ * hand-compose: an `ingest` source + `extractDependencies` + (optionally) a
+ * `StorageBackend` + decay/consolidation recipes + the
+ * `BigInt(monotonicNs())` fragment boilerplate. `simpleFactStore` owns all
+ * of that and exposes a single ergonomic `remember(id, payload, opts?)`.
+ *
+ * **Q-walk locks (canonical: `docs/optimizations.md` DS-14.7 follow-up #2):**
+ * - **Q1** — `extractDependencies` defaults to `() => []` (flat store;
+ *   cascade inert by default — dependency-tracking is opt-in).
+ * - **Q2** — single factory, **optional `storage`**: present → wraps
+ *   {@link persistentReactiveFactStore} (durable, event-sourced); absent →
+ *   in-memory {@link reactiveFactStore}.
+ * - **Q3** — the wrapper **owns** the internal `ingest` source and exposes
+ *   {@link SimpleFactStoreGraph.remember}. `remember` `.emit`s into the
+ *   owned leaf source — this is the *sanctioned* external push that the
+ *   `reactiveFactStore` ingest contract documents (same shape as the
+ *   `decay`/replay recipes' `.emit`-into-source), **not** a spec-§5.9
+ *   imperative trigger: it feeds DATA into a source node, it does not
+ *   bypass topology for control flow. Reactive reads (`answer` / `review` /
+ *   `events`) stay the canonical observation surface.
+ * - **Q4** — auto-wire **default recipes** with internal `fromTimer`
+ *   cadences (batteries-included; user-blessed 2026-05-17). `decay` is
+ *   generically meaningful (confidence forgetting needs no domain
+ *   knowledge) → **ON by default** with conservative defaults
+ *   ({@link DEFAULT_DECAY_HALF_LIFE_NS} / {@link DEFAULT_DECAY_PERIOD_MS}),
+ *   tunable or `false` to disable. `consolidate` is **domain-bound** —
+ *   {@link consolidationRem} *requires* a `summarize` (there is no generic
+ *   default; an arbitrary `T` cannot be summarized blindly), so it is wired
+ *   **iff** the caller supplies `opts.consolidate`. This consolidation
+ *   asymmetry is dictated by the recipe's own required contract, not an
+ *   autonomous downgrade of the Q4 lock.
+ * - **Q5** — minimal input: `remember(id, payload, { tags? })` auto-fills
+ *   `t_ns = BigInt(monotonicNs())` (per the {@link MemoryFragment.t_ns}
+ *   contract + the clock-return-type rule — `monotonicNs()` is `number`,
+ *   the `BigInt(...)` wrap is load-bearing) and `confidence = 1`.
+ * - **Q6** — **wraps** the existing factories (not a parallel impl).
+ *
+ * Presentation-only (`@graphrefly/graphrefly`, `utils/memory` barrel),
+ * universal tier (`fromTimer` only, no `node:*`/DOM — the optional
+ * `StorageBackend` impl's tier is the *caller's* concern, forwarded
+ * verbatim, exactly as {@link persistentReactiveFactStore} does).
+ *
+ * @module
+ */
+
+/**
+ * Default exponential-decay half-life: **7 days** in nanoseconds. Confidence
+ * halves once per week of fact age — gentle forgetting suitable for the
+ * 80%-case agent memory. Override via `opts.decay.halfLifeNs`.
+ */
+declare const DEFAULT_DECAY_HALF_LIFE_NS = 604800000000000n;
+/**
+ * Default decay tick cadence: **1 hour** (ms). How often the forgetting pass
+ * runs. Override via `opts.decay.periodMs`.
+ */
+declare const DEFAULT_DECAY_PERIOD_MS = 3600000;
+/** Per-fact override fields accepted by {@link SimpleFactStoreGraph.remember}. */
+interface RememberOptions {
+    /** Tags. Default `[]`. */
+    readonly tags?: readonly string[];
+    /** Dependency edges (fact IDs this fact derives from). Default `[]`. */
+    readonly sources?: readonly FactId[];
+    /** Confidence 0..1. Default `1`. */
+    readonly confidence?: number;
+    /** Valid-time end — set to obsolete a fact (MEME L3 lever). */
+    readonly validTo?: bigint;
+    /** Valid-time start — `undefined` = unbounded past. */
+    readonly validFrom?: bigint;
+    /** Free-form provenance string. */
+    readonly provenance?: string;
+}
+interface SimpleFactStoreOptions<T> {
+    /**
+     * Durable backing. Present → delegates to
+     * {@link persistentReactiveFactStore} (event-sourced, replay-on-start,
+     * substrate-owned cursor). Absent → in-memory {@link reactiveFactStore}.
+     * The backend's runtime tier (node / browser) is the caller's concern —
+     * forwarded verbatim.
+     */
+    readonly storage?: StorageBackend;
+    /**
+     * Cascade dependency extractor. **Default `() => []`** — flat store, no
+     * cascade. Supply to opt into MEME L2 cascade invalidation.
+     */
+    readonly extractDependencies?: (f: MemoryFragment<T>) => readonly FactId[];
+    /**
+     * Exponential-decay forgetting. **Default: ON** with
+     * {@link DEFAULT_DECAY_HALF_LIFE_NS} / {@link DEFAULT_DECAY_PERIOD_MS}.
+     * Pass a partial to tune; pass `false` to disable. Wires an internal
+     * `fromTimer` (the user-blessed batteries-included cadence).
+     */
+    readonly decay?: false | Partial<DecayExponentialOptions>;
+    /**
+     * REM-replay consolidation. **Domain-bound** — requires a `summarize`
+     * (no generic default exists). Supply the full
+     * {@link ConsolidationRemOptions} to enable; omit to disable. Wires an
+     * internal `fromTimer` at `consolidate.periodMs`.
+     */
+    readonly consolidate?: ConsolidationRemOptions<T>;
+    /** Persistent-only: durable bucket name. Default `fact_store_ingest`. */
+    readonly persistName?: string;
+    /** Persistent-only: durable codec. Default `bigintJsonCodecFor`. */
+    readonly codec?: Codec<readonly MemoryFragment<T>[]>;
+}
+/**
+ * The ergonomic write added to every `simpleFactStore` graph. Normalizes to a
+ * {@link MemoryFragment} (auto `t_ns = BigInt(monotonicNs())`,
+ * `confidence = 1`, `tags`/`sources` = `[]`) and `.emit`s it into the owned
+ * `ingest` source. Re-`remember`ing an existing `id` is the MEME L1
+ * direct-replace lever; set `opts.validTo` to obsolete (MEME L3).
+ */
+type SimpleFactStoreRemember<T> = (id: FactId, payload: T, opts?: RememberOptions) => void;
+/**
+ * In-memory `simpleFactStore` graph (no `storage`) augmented with
+ * {@link SimpleFactStoreRemember}.
+ */
+interface SimpleFactStoreGraph<T> extends ReactiveFactStoreGraph<T> {
+    remember: SimpleFactStoreRemember<T>;
+}
+/**
+ * Durable (`storage`-backed) `simpleFactStore` graph — the **type-honest**
+ * persistent surface. EC-LOW-1 (`/qa` 2026-05-17): the `storage` overload
+ * returns this so `position` / `replayedCount` / `flush` / `tier` are typed
+ * without a hand-cast (the durable path is the headline 80%-case).
+ */
+type PersistentSimpleFactStoreGraph<T> = PersistentReactiveFactStoreGraph<T> & {
+    remember: SimpleFactStoreRemember<T>;
+};
+/**
+ * Build a fact store with sensible defaults and a one-call `remember`.
+ *
+ * @example
+ * ```ts
+ * import { simpleFactStore } from "@graphrefly/graphrefly/utils/memory";
+ * import { memoryBackend } from "@graphrefly/graphrefly/extra";
+ *
+ * const mem = simpleFactStore<string>(); // in-memory, decay ON
+ * mem.remember("user:lang", "TypeScript", { tags: ["pref"] });
+ * mem.answer.subscribe((a) => console.log(a)); // reactive read
+ *
+ * // Durable: the `storage` overload returns the typed persistent surface
+ * // (no hand-cast needed for `position` / `flush`).
+ * const durable = simpleFactStore<string>({ storage: memoryBackend() });
+ * durable.remember("k", "v");
+ * await durable.flush();
+ * ```
+ *
+ * @category memory
+ */
+declare function simpleFactStore<T>(opts: SimpleFactStoreOptions<T> & {
+    storage: StorageBackend;
+}): PersistentSimpleFactStoreGraph<T>;
+declare function simpleFactStore<T>(opts?: SimpleFactStoreOptions<T>): SimpleFactStoreGraph<T>;
+
 /**
  * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under
  * `archive/docs/SESSION-public-face-blocks-review.md` (Wave A, locked 2026-04-25).
@@ -1295,4 +1474,4 @@ type KnowledgeGraph<TEntity, TRelation extends string = string> = Graph & {
  */
 declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string, opts?: KnowledgeGraphOptions): KnowledgeGraph<TEntity, TRelation>;
 
-export { type AdmissionFilter, type AdmissionLlmJudgeOptions, type BitemporalQueryOptions, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type ConsolidationRemConfig, type ConsolidationRemOptions, type DecayExponentialOptions, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type InfluenceAnalysis, type InfluenceAnalysisOptions, type InfluenceRow, type InvalidationTraceEntry, type InvalidationTracerOptions, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type PersistentReactiveFactStoreConfig, type PersistentReactiveFactStoreGraph, type RankedCollectionEntry, type ReactiveFactStoreConfig, type ReactiveFactStoreGraph, type ReviewRequest, type ScoringByOutcomeOptions, type ScoringPolicy, type ShardByTenantConfig, type ShardByTenantOptions, type ShardKey, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, admissionLlmJudge, bitemporalQuery, collection, consolidationRem, cosineSimilarity, decayExponential, influenceAnalysis, invalidationTracer, knowledgeGraph, persistentReactiveFactStore, reactiveFactStore, scoringByOutcome, shardByTenant, vectorIndex };
+export { type AdmissionFilter, type AdmissionLlmJudgeOptions, type BitemporalQueryOptions, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type ConsolidationRemConfig, type ConsolidationRemOptions, DEFAULT_DECAY_HALF_LIFE_NS, DEFAULT_DECAY_PERIOD_MS, type DecayExponentialOptions, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type InfluenceAnalysis, type InfluenceAnalysisOptions, type InfluenceRow, type InvalidationTraceEntry, type InvalidationTracerOptions, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type PersistentReactiveFactStoreConfig, type PersistentReactiveFactStoreGraph, type RankedCollectionEntry, type ReactiveFactStoreConfig, ReactiveFactStoreGraph, type RememberOptions, type ReviewRequest, type ScoringByOutcomeOptions, type ScoringPolicy, type ShardByTenantConfig, type ShardByTenantOptions, type ShardKey, type SimpleFactStoreGraph, type SimpleFactStoreOptions, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, admissionLlmJudge, bitemporalQuery, collection, consolidationRem, cosineSimilarity, decayExponential, influenceAnalysis, invalidationTracer, knowledgeGraph, persistentReactiveFactStore, reactiveFactStore, scoringByOutcome, shardByTenant, simpleFactStore, vectorIndex };

package/dist/utils/memory/index.d.ts

@@ -173,6 +173,16 @@ interface FactStoreAuditRecord extends BaseAuditRecord {
     readonly action: "ingest" | "invalidate" | "outcome" | "consolidate" | "decay" | "overflow";
     readonly id?: FactId;
     readonly reason?: CascadeReason;
+    /**
+     * Number of facts whose state actually changed in a batch action
+     * (post-filter — excludes no-op / non-finite / resurrection-guard
+     * skips; equals the length of the emitted `decay_processor` value
+     * array). Populated for `"decay"` (a per-tick batch over many facts
+     * with no single `id` — the bare `{action,t_ns,seq}` record was opaque
+     * to audit-log forensics). Absent for single-fact actions (`id`
+     * carries those).
+     */
+    readonly count?: number;
 }
 interface ReactiveFactStoreConfig<T> {
     readonly extractDependencies: (f: MemoryFragment<T>) => readonly FactId[];
@@ -306,29 +316,6 @@ interface ReactiveFactStoreConfig<T> {
      */
     readonly recordIngest?: boolean;
 }
-interface ReactiveFactStoreGraph<T> extends Graph {
-    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
-    readonly shards: readonly Node<FactStore<T>>[];
-    /** Unified read view across all shards (derived). */
-    readonly factStore: Node<FactStore<T>>;
-    readonly dependentsIndex: Node<DependentsIndex>;
-    readonly answer: Node<MemoryAnswer<T> | null>;
-    readonly cascade: Node<readonly CascadeEvent[]>;
-    readonly cascadeOverflow: Node<CascadeOverflow | null>;
-    readonly review: Node<ReviewRequest | null>;
-    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
-    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
-    /**
-     * Payload-carrying, replayable log of every committed fragment. Present iff
-     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
-     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
-     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
-     * replayable projection source (see `recordIngest` docs for the recipe).
-     */
-    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
-    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
-    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
-}
 /**
  * Build a static-topology reactive fact store (DS-14.7 architecture C).
  *
@@ -362,6 +349,38 @@ interface ReactiveFactStoreGraph<T> extends Graph {
  *
  * @category memory
  */
+declare class ReactiveFactStoreGraph<T> extends Graph {
+    /** Per-shard `state<FactStore<T>>` nodes (length = shard count). */
+    readonly shards: readonly Node<FactStore<T>>[];
+    /** Unified read view across all shards (derived). */
+    readonly factStore: Node<FactStore<T>>;
+    readonly dependentsIndex: Node<DependentsIndex>;
+    readonly answer: Node<MemoryAnswer<T> | null>;
+    readonly cascade: Node<readonly CascadeEvent[]>;
+    readonly cascadeOverflow: Node<CascadeOverflow | null>;
+    readonly review: Node<ReviewRequest | null>;
+    readonly consolidated: Node<readonly MemoryFragment<T>[]>;
+    readonly events: ReactiveLogBundle<FactStoreAuditRecord>;
+    /**
+     * Payload-carrying, replayable log of every committed fragment. Present iff
+     * {@link ReactiveFactStoreConfig.recordIngest} is `true`. Unlike
+     * {@link ReactiveFactStoreGraph.events} (action-only audit), each entry is
+     * the full {@link MemoryFragment} — `attachStorage` it for a durable,
+     * replayable projection source (see `recordIngest` docs for the recipe).
+     */
+    readonly ingestLog?: ReactiveLogBundle<MemoryFragment<T>>;
+    constructor(config: ReactiveFactStoreConfig<T>);
+    /** Reactive read: a single fact by id (SENTINEL until the fact exists). */
+    itemNode(id: FactId): Node<MemoryFragment<T> | undefined>;
+}
+/**
+ * Build a static-topology reactive fact store (DS-14.7 architecture C).
+ *
+ * Thin factory over {@link ReactiveFactStoreGraph} — see that class for the
+ * full topology / locked-decision docs and the `instanceof`-narrowable type.
+ *
+ * @category memory
+ */
 declare function reactiveFactStore<T>(config: ReactiveFactStoreConfig<T>): ReactiveFactStoreGraph<T>;
 
 /**
@@ -954,6 +973,166 @@ interface ShardByTenantConfig<T> {
  */
 declare function shardByTenant<T>(tenantOf: (f: MemoryFragment<T>) => string, opts?: ShardByTenantOptions): ShardByTenantConfig<T>;
 
+/**
+ * `simpleFactStore()` — the 80%-case ergonomic wrapper over
+ * {@link reactiveFactStore} / {@link persistentReactiveFactStore}
+ * (DS-14.7 follow-up #2; design LOCKED 2026-05-17 `/dev-dispatch` Q-walk,
+ * Q1–Q6 + sub-decisions resolved).
+ *
+ * Closes the gap where a consumer wanting durable agent memory had to
+ * hand-compose: an `ingest` source + `extractDependencies` + (optionally) a
+ * `StorageBackend` + decay/consolidation recipes + the
+ * `BigInt(monotonicNs())` fragment boilerplate. `simpleFactStore` owns all
+ * of that and exposes a single ergonomic `remember(id, payload, opts?)`.
+ *
+ * **Q-walk locks (canonical: `docs/optimizations.md` DS-14.7 follow-up #2):**
+ * - **Q1** — `extractDependencies` defaults to `() => []` (flat store;
+ *   cascade inert by default — dependency-tracking is opt-in).
+ * - **Q2** — single factory, **optional `storage`**: present → wraps
+ *   {@link persistentReactiveFactStore} (durable, event-sourced); absent →
+ *   in-memory {@link reactiveFactStore}.
+ * - **Q3** — the wrapper **owns** the internal `ingest` source and exposes
+ *   {@link SimpleFactStoreGraph.remember}. `remember` `.emit`s into the
+ *   owned leaf source — this is the *sanctioned* external push that the
+ *   `reactiveFactStore` ingest contract documents (same shape as the
+ *   `decay`/replay recipes' `.emit`-into-source), **not** a spec-§5.9
+ *   imperative trigger: it feeds DATA into a source node, it does not
+ *   bypass topology for control flow. Reactive reads (`answer` / `review` /
+ *   `events`) stay the canonical observation surface.
+ * - **Q4** — auto-wire **default recipes** with internal `fromTimer`
+ *   cadences (batteries-included; user-blessed 2026-05-17). `decay` is
+ *   generically meaningful (confidence forgetting needs no domain
+ *   knowledge) → **ON by default** with conservative defaults
+ *   ({@link DEFAULT_DECAY_HALF_LIFE_NS} / {@link DEFAULT_DECAY_PERIOD_MS}),
+ *   tunable or `false` to disable. `consolidate` is **domain-bound** —
+ *   {@link consolidationRem} *requires* a `summarize` (there is no generic
+ *   default; an arbitrary `T` cannot be summarized blindly), so it is wired
+ *   **iff** the caller supplies `opts.consolidate`. This consolidation
+ *   asymmetry is dictated by the recipe's own required contract, not an
+ *   autonomous downgrade of the Q4 lock.
+ * - **Q5** — minimal input: `remember(id, payload, { tags? })` auto-fills
+ *   `t_ns = BigInt(monotonicNs())` (per the {@link MemoryFragment.t_ns}
+ *   contract + the clock-return-type rule — `monotonicNs()` is `number`,
+ *   the `BigInt(...)` wrap is load-bearing) and `confidence = 1`.
+ * - **Q6** — **wraps** the existing factories (not a parallel impl).
+ *
+ * Presentation-only (`@graphrefly/graphrefly`, `utils/memory` barrel),
+ * universal tier (`fromTimer` only, no `node:*`/DOM — the optional
+ * `StorageBackend` impl's tier is the *caller's* concern, forwarded
+ * verbatim, exactly as {@link persistentReactiveFactStore} does).
+ *
+ * @module
+ */
+
+/**
+ * Default exponential-decay half-life: **7 days** in nanoseconds. Confidence
+ * halves once per week of fact age — gentle forgetting suitable for the
+ * 80%-case agent memory. Override via `opts.decay.halfLifeNs`.
+ */
+declare const DEFAULT_DECAY_HALF_LIFE_NS = 604800000000000n;
+/**
+ * Default decay tick cadence: **1 hour** (ms). How often the forgetting pass
+ * runs. Override via `opts.decay.periodMs`.
+ */
+declare const DEFAULT_DECAY_PERIOD_MS = 3600000;
+/** Per-fact override fields accepted by {@link SimpleFactStoreGraph.remember}. */
+interface RememberOptions {
+    /** Tags. Default `[]`. */
+    readonly tags?: readonly string[];
+    /** Dependency edges (fact IDs this fact derives from). Default `[]`. */
+    readonly sources?: readonly FactId[];
+    /** Confidence 0..1. Default `1`. */
+    readonly confidence?: number;
+    /** Valid-time end — set to obsolete a fact (MEME L3 lever). */
+    readonly validTo?: bigint;
+    /** Valid-time start — `undefined` = unbounded past. */
+    readonly validFrom?: bigint;
+    /** Free-form provenance string. */
+    readonly provenance?: string;
+}
+interface SimpleFactStoreOptions<T> {
+    /**
+     * Durable backing. Present → delegates to
+     * {@link persistentReactiveFactStore} (event-sourced, replay-on-start,
+     * substrate-owned cursor). Absent → in-memory {@link reactiveFactStore}.
+     * The backend's runtime tier (node / browser) is the caller's concern —
+     * forwarded verbatim.
+     */
+    readonly storage?: StorageBackend;
+    /**
+     * Cascade dependency extractor. **Default `() => []`** — flat store, no
+     * cascade. Supply to opt into MEME L2 cascade invalidation.
+     */
+    readonly extractDependencies?: (f: MemoryFragment<T>) => readonly FactId[];
+    /**
+     * Exponential-decay forgetting. **Default: ON** with
+     * {@link DEFAULT_DECAY_HALF_LIFE_NS} / {@link DEFAULT_DECAY_PERIOD_MS}.
+     * Pass a partial to tune; pass `false` to disable. Wires an internal
+     * `fromTimer` (the user-blessed batteries-included cadence).
+     */
+    readonly decay?: false | Partial<DecayExponentialOptions>;
+    /**
+     * REM-replay consolidation. **Domain-bound** — requires a `summarize`
+     * (no generic default exists). Supply the full
+     * {@link ConsolidationRemOptions} to enable; omit to disable. Wires an
+     * internal `fromTimer` at `consolidate.periodMs`.
+     */
+    readonly consolidate?: ConsolidationRemOptions<T>;
+    /** Persistent-only: durable bucket name. Default `fact_store_ingest`. */
+    readonly persistName?: string;
+    /** Persistent-only: durable codec. Default `bigintJsonCodecFor`. */
+    readonly codec?: Codec<readonly MemoryFragment<T>[]>;
+}
+/**
+ * The ergonomic write added to every `simpleFactStore` graph. Normalizes to a
+ * {@link MemoryFragment} (auto `t_ns = BigInt(monotonicNs())`,
+ * `confidence = 1`, `tags`/`sources` = `[]`) and `.emit`s it into the owned
+ * `ingest` source. Re-`remember`ing an existing `id` is the MEME L1
+ * direct-replace lever; set `opts.validTo` to obsolete (MEME L3).
+ */
+type SimpleFactStoreRemember<T> = (id: FactId, payload: T, opts?: RememberOptions) => void;
+/**
+ * In-memory `simpleFactStore` graph (no `storage`) augmented with
+ * {@link SimpleFactStoreRemember}.
+ */
+interface SimpleFactStoreGraph<T> extends ReactiveFactStoreGraph<T> {
+    remember: SimpleFactStoreRemember<T>;
+}
+/**
+ * Durable (`storage`-backed) `simpleFactStore` graph — the **type-honest**
+ * persistent surface. EC-LOW-1 (`/qa` 2026-05-17): the `storage` overload
+ * returns this so `position` / `replayedCount` / `flush` / `tier` are typed
+ * without a hand-cast (the durable path is the headline 80%-case).
+ */
+type PersistentSimpleFactStoreGraph<T> = PersistentReactiveFactStoreGraph<T> & {
+    remember: SimpleFactStoreRemember<T>;
+};
+/**
+ * Build a fact store with sensible defaults and a one-call `remember`.
+ *
+ * @example
+ * ```ts
+ * import { simpleFactStore } from "@graphrefly/graphrefly/utils/memory";
+ * import { memoryBackend } from "@graphrefly/graphrefly/extra";
+ *
+ * const mem = simpleFactStore<string>(); // in-memory, decay ON
+ * mem.remember("user:lang", "TypeScript", { tags: ["pref"] });
+ * mem.answer.subscribe((a) => console.log(a)); // reactive read
+ *
+ * // Durable: the `storage` overload returns the typed persistent surface
+ * // (no hand-cast needed for `position` / `flush`).
+ * const durable = simpleFactStore<string>({ storage: memoryBackend() });
+ * durable.remember("k", "v");
+ * await durable.flush();
+ * ```
+ *
+ * @category memory
+ */
+declare function simpleFactStore<T>(opts: SimpleFactStoreOptions<T> & {
+    storage: StorageBackend;
+}): PersistentSimpleFactStoreGraph<T>;
+declare function simpleFactStore<T>(opts?: SimpleFactStoreOptions<T>): SimpleFactStoreGraph<T>;
+
 /**
  * Memory patterns (roadmap §4.3) — public-face Phase-4 primitives audited under
  * `archive/docs/SESSION-public-face-blocks-review.md` (Wave A, locked 2026-04-25).
@@ -1295,4 +1474,4 @@ type KnowledgeGraph<TEntity, TRelation extends string = string> = Graph & {
  */
 declare function knowledgeGraph<TEntity, TRelation extends string = string>(name: string, opts?: KnowledgeGraphOptions): KnowledgeGraph<TEntity, TRelation>;
 
-export { type AdmissionFilter, type AdmissionLlmJudgeOptions, type BitemporalQueryOptions, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type ConsolidationRemConfig, type ConsolidationRemOptions, type DecayExponentialOptions, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type InfluenceAnalysis, type InfluenceAnalysisOptions, type InfluenceRow, type InvalidationTraceEntry, type InvalidationTracerOptions, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type PersistentReactiveFactStoreConfig, type PersistentReactiveFactStoreGraph, type RankedCollectionEntry, type ReactiveFactStoreConfig, type ReactiveFactStoreGraph, type ReviewRequest, type ScoringByOutcomeOptions, type ScoringPolicy, type ShardByTenantConfig, type ShardByTenantOptions, type ShardKey, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, admissionLlmJudge, bitemporalQuery, collection, consolidationRem, cosineSimilarity, decayExponential, influenceAnalysis, invalidationTracer, knowledgeGraph, persistentReactiveFactStore, reactiveFactStore, scoringByOutcome, shardByTenant, vectorIndex };
+export { type AdmissionFilter, type AdmissionLlmJudgeOptions, type BitemporalQueryOptions, type CascadeEvent, type CascadeOverflow, type CascadeReason, type CollectionAuditRecord, type CollectionEntry, type CollectionGraph, type CollectionOptions, type CollectionScoreFn, type ConsolidationRemConfig, type ConsolidationRemOptions, DEFAULT_DECAY_HALF_LIFE_NS, DEFAULT_DECAY_PERIOD_MS, type DecayExponentialOptions, type DecayPolicy, type DependentsIndex, type FactId, type FactStore, type FactStoreAuditRecord, type HnswAdapter, type InfluenceAnalysis, type InfluenceAnalysisOptions, type InfluenceRow, type InvalidationTraceEntry, type InvalidationTracerOptions, type KnowledgeEdge, type KnowledgeGraph, type KnowledgeGraphAuditRecord, type KnowledgeGraphOptions, type MemoryAnswer, type MemoryFragment, type MemoryQuery, NodeOrValue, type OutcomeSignal, type PersistentReactiveFactStoreConfig, type PersistentReactiveFactStoreGraph, type RankedCollectionEntry, type ReactiveFactStoreConfig, ReactiveFactStoreGraph, type RememberOptions, type ReviewRequest, type ScoringByOutcomeOptions, type ScoringPolicy, type ShardByTenantConfig, type ShardByTenantOptions, type ShardKey, type SimpleFactStoreGraph, type SimpleFactStoreOptions, type StoreReadHandle, type VectorBackend, type VectorIndexAuditRecord, type VectorIndexGraph, type VectorIndexOptions, type VectorRecord, type VectorSearchResult, admissionLlmJudge, bitemporalQuery, collection, consolidationRem, cosineSimilarity, decayExponential, influenceAnalysis, invalidationTracer, knowledgeGraph, persistentReactiveFactStore, reactiveFactStore, scoringByOutcome, shardByTenant, simpleFactStore, vectorIndex };

package/dist/utils/memory/index.js

@@ -1,4 +1,7 @@
 import {
+  DEFAULT_DECAY_HALF_LIFE_NS,
+  DEFAULT_DECAY_PERIOD_MS,
+  ReactiveFactStoreGraph,
   admissionLlmJudge,
   bitemporalQuery,
   collection,
@@ -12,13 +15,17 @@ import {
   reactiveFactStore,
   scoringByOutcome,
   shardByTenant,
+  simpleFactStore,
   vectorIndex
-} from "../../chunk-7AVQIGF6.js";
+} from "../../chunk-K4ZYJ4EM.js";
 import "../../chunk-QMBYUVRL.js";
 import "../../chunk-FMPF42Q4.js";
-import "../../chunk-BXGZFGZ4.js";
+import "../../chunk-C5QD5DQX.js";
 import "../../chunk-AZDQPQ3V.js";
 export {
+  DEFAULT_DECAY_HALF_LIFE_NS,
+  DEFAULT_DECAY_PERIOD_MS,
+  ReactiveFactStoreGraph,
   admissionLlmJudge,
   bitemporalQuery,
   collection,
@@ -32,6 +39,7 @@ export {
   reactiveFactStore,
   scoringByOutcome,
   shardByTenant,
+  simpleFactStore,
   vectorIndex
 };
 //# sourceMappingURL=index.js.map