@oortmem/core 0.1.0 → 0.2.0

package/dist/adapters.d.ts

@@ -25,9 +25,21 @@ export interface GateDecision {
     salience: number;
     /** Probability per memory type; absent types are treated as 0. */
     types: Partial<Record<MemoryType, number>>;
+    /**
+     * Probability that the fact is likely to change within weeks (a status, a current version).
+     * Optional; a controller that sets it also records a `gate`/`volatile` decision, which is how
+     * the stored memory remembers it.
+     */
+    volatile?: number;
     decisions: Decision[];
 }
-export type ReconcileAction = 'NOOP' | 'REINFORCE' | 'ADD' | 'UPDATE' | 'SUPERSEDE';
+/**
+ * Stage C actions (CON-49). REFINE adds detail to the same fact and rewrites it in place.
+ * SUPERSEDE means the situation changed: the old fact was true until the new one starts.
+ * CORRECT means the old fact was wrong from the start: it is retracted in transaction time and
+ * the correction takes its place in valid time. UPDATE is the earlier name for REFINE.
+ */
+export type ReconcileAction = 'NOOP' | 'REINFORCE' | 'ADD' | 'REFINE' | 'SUPERSEDE' | 'CORRECT' | 'UPDATE';
 /** Stage C: what to do with the observation relative to one candidate. */
 export interface ReconcileDecision {
     /** The existing memory this decision concerns; `null` for a standalone ADD. */
@@ -75,6 +87,15 @@ export interface GuardedWriteResult {
  * silent no-op), so a caller learns nothing about records it cannot see.
  * Callers never post-filter.
  */
+/** Filters and shape for `MemoryStore.list`. */
+export interface ListOptions {
+    tier?: Tier;
+    validOnly?: boolean;
+    /** true: pinned memories only. */
+    pinned?: boolean;
+    /** false: skip reading embeddings (default true). */
+    embeddings?: boolean;
+}
 export interface MemoryStore {
     /**
      * Insert or replace the memory with `m.id`. When `m.tier` is not `cold`, any
@@ -121,12 +142,11 @@ export interface MemoryStore {
     /**
      * Listing within `grant.read`, newest `updatedAt` first. `validOnly`
      * defaults to true (only memories for which `isCurrent(m, now)` holds);
-     * `tier` restricts to one tier.
+     * `tier` restricts to one tier and `pinned: true` to pinned memories (both
+     * filtered in the store). `embeddings: false` leaves `embedding` unset, for
+     * callers that read only text and metadata.
      */
-    list(grant: Grant, opts?: {
-        tier?: Tier;
-        validOnly?: boolean;
-    }): Promise<Memory[]>;
+    list(grant: Grant, opts?: ListOptions): Promise<Memory[]>;
     /**
      * Marks each snapshot's record expired: sets `expiredAt = at`, and
      * `endReason = "expired"` where it is null. No other field is written.

package/dist/config.d.ts

@@ -41,6 +41,7 @@ export declare const OortConfig: z.ZodObject<{
         lexicalFirst: z.ZodDefault<z.ZodBoolean>;
         rerankBudgetMs: z.ZodDefault<z.ZodNumber>;
         queryCacheTtlSec: z.ZodDefault<z.ZodNumber>;
+        staleAfterDays: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     project: z.ZodDefault<z.ZodObject<{
         id: z.ZodOptional<z.ZodString>;

package/dist/config.js

@@ -64,6 +64,11 @@ const recall = z
     rerankBudgetMs: z.number().int().min(0).default(400),
     /** How long a query embedding is reused, in seconds. 0 turns the cache off. */
     queryCacheTtlSec: z.number().int().min(0).default(600),
+    /**
+     * Days after which a volatile memory (a status, a current version) that nobody confirmed is
+     * marked "may be outdated" when injected, and listed by `oort revalidate`. 0 turns it off.
+     */
+    staleAfterDays: z.number().int().min(0).default(30),
 })
     .default({
     lexicalK: 50,
@@ -78,6 +83,7 @@ const recall = z
     lexicalFirst: true,
     rerankBudgetMs: 400,
     queryCacheTtlSec: 600,
+    staleAfterDays: 30,
 });
 const project = z
     .strictObject({

package/dist/fusion.d.ts

@@ -1,6 +1,15 @@
 import { type ActivationParams } from './activation.js';
 import type { Hit } from './adapters.js';
 import { type Memory } from './model.js';
+import type { RecallMode } from './temporal.js';
+/** Which slice of time a recall reads (CON-34). */
+export interface TemporalView {
+    mode: RecallMode;
+    /** For `as-of`: the instant in valid time. */
+    asOf?: string;
+    /** For `known-at`: the instant in transaction time. */
+    knownAt?: string;
+}
 /**
  * Weight of the activation boost: fused = rrf * (1 + ACTIVATION_BOOST * sigmoid(A)). With one RRF
  * list (k=60) ranks 1 and r differ by (r-1)/61, so a band of B reorders about 61*B ranks (about 3).
@@ -14,6 +23,8 @@ export interface FuseParams {
     activation: ActivationParams;
     /** ISO timestamp: fuse over what was true then instead of what is true now. */
     asOf?: string;
+    /** The temporal view; wins over `asOf`. Defaults to current, or as-of `asOf`. */
+    view?: TemporalView;
 }
 /**
  * Reciprocal rank fusion: score(id) = Σ over lists of 1 / (k + rank), rank
@@ -22,10 +33,19 @@ export interface FuseParams {
 export declare function rrf(lists: Hit[][], k?: number): Map<string, number>;
 /**
  * Current now (`isCurrent(m, now)`), or, with `asOf`, valid in the world at
- * that instant. As-of ignores `expiredAt`: it asks what was true then, not
- * what the system currently believes.
+ * that instant. As-of ignores `expiredAt` (it asks what was true then, not
+ * what the system currently believes), but a corrected fact was never true.
  */
 export declare function isValid(m: Memory, now: Date, asOf: string | undefined): boolean;
+/**
+ * Validity is a hard filter, per view:
+ * - current: true now and still believed (`isCurrent`).
+ * - as-of T: true at T in valid time, whatever we learned since; corrected facts never are.
+ * - known-at X: what we believed at X: recorded by then, not yet retracted then, and true at X
+ *   as far as we knew (an end recorded after X was not known yet), corrected facts included.
+ * - history: every version of a fact, except corrected ones.
+ */
+export declare function isVisible(m: Memory, now: Date, v: TemporalView): boolean;
 /**
  * RRF over the first-stage lists, filtered by temporal validity and
  * scaled by a bounded activation boost. Ids absent from `memories` are

package/dist/fusion.js

@@ -36,13 +36,44 @@ export function rrf(lists, k = 60) {
 }
 /**
  * Current now (`isCurrent(m, now)`), or, with `asOf`, valid in the world at
- * that instant. As-of ignores `expiredAt`: it asks what was true then, not
- * what the system currently believes.
+ * that instant. As-of ignores `expiredAt` (it asks what was true then, not
+ * what the system currently believes), but a corrected fact was never true.
  */
 export function isValid(m, now, asOf) {
     if (asOf === undefined)
         return isCurrent(m, now);
-    return isCurrent({ ...m, expiredAt: null }, new Date(asOf));
+    return isVisible(m, now, { mode: 'as-of', asOf });
+}
+const t = (iso) => Date.parse(iso);
+/**
+ * Validity is a hard filter, per view:
+ * - current: true now and still believed (`isCurrent`).
+ * - as-of T: true at T in valid time, whatever we learned since; corrected facts never are.
+ * - known-at X: what we believed at X: recorded by then, not yet retracted then, and true at X
+ *   as far as we knew (an end recorded after X was not known yet), corrected facts included.
+ * - history: every version of a fact, except corrected ones.
+ */
+export function isVisible(m, now, v) {
+    switch (v.mode) {
+        case 'current':
+            return isCurrent(m, now);
+        case 'as-of':
+            return (m.endReason !== 'corrected' &&
+                isCurrent({ ...m, expiredAt: null }, v.asOf === undefined ? now : new Date(v.asOf)));
+        case 'known-at': {
+            const x = v.knownAt === undefined ? now.getTime() : t(v.knownAt);
+            const retractedLater = m.expiredAt !== null && t(m.expiredAt) > x;
+            // Only a supersession or correction sets an end later than the fact was written, so only
+            // then was the end unknown at X. An end the fact stated itself (or expiry) always counts.
+            const endLearnedLater = retractedLater && (m.endReason === 'superseded' || m.endReason === 'corrected');
+            return (t(m.createdAt) <= x &&
+                (m.expiredAt === null || retractedLater) &&
+                t(m.validFrom) <= x &&
+                (m.validTo === null || t(m.validTo) > x || endLearnedLater));
+        }
+        case 'history':
+            return m.endReason !== 'corrected' && t(m.validFrom) <= now.getTime();
+    }
 }
 /**
  * RRF over the first-stage lists, filtered by temporal validity and
@@ -51,9 +82,10 @@ export function isValid(m, now, asOf) {
  */
 export function fuse(hits, memories, now, p) {
     const out = [];
+    const view = p.view ?? (p.asOf === undefined ? { mode: 'current' } : { mode: 'as-of', asOf: p.asOf });
     for (const [id, base] of rrf(hits)) {
         const m = memories.get(id);
-        if (m === undefined || !isValid(m, now, p.asOf))
+        if (m === undefined || !isVisible(m, now, view))
             continue;
         const a = activation(m.accessLog, m.salience, now, p.activation);
         out.push({ id, score: base * activationBoost(a), rrf: base });

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "0.1.0";
+export declare const VERSION = "0.2.0";
 export * from './model.js';
 export * from './scope.js';
 export * from './config.js';
@@ -13,6 +13,8 @@ export * from './gate.js';
 export * from './recall.js';
 export * from './relevance.js';
 export * from './observe.js';
+export * from './temporal.js';
+export * from './volatile.js';
 export * from './scrub.js';
 export * from './cap.js';
 export * from './consolidate.js';

package/dist/index.js

@@ -1,4 +1,4 @@
-export const VERSION = '0.1.0';
+export const VERSION = '0.2.0';
 export * from './model.js';
 export * from './scope.js';
 export * from './config.js';
@@ -13,6 +13,8 @@ export * from './gate.js';
 export * from './recall.js';
 export * from './relevance.js';
 export * from './observe.js';
+export * from './temporal.js';
+export * from './volatile.js';
 export * from './scrub.js';
 export * from './cap.js';
 export * from './consolidate.js';

package/dist/memory-store.js

@@ -207,8 +207,14 @@ export function createMemoryStore(opts = {}) {
             return scoped(grant.read)
                 .filter((m) => !validOnly || isCurrent(m, now))
                 .filter((m) => listOpts.tier === undefined || m.tier === listOpts.tier)
+                .filter((m) => listOpts.pinned !== true || m.pinned)
                 .sort((x, y) => Date.parse(y.updatedAt) - Date.parse(x.updatedAt))
-                .map((m) => structuredClone(m));
+                .map((m) => {
+                if (listOpts.embeddings !== false)
+                    return structuredClone(m);
+                const { embedding: _e, ...rest } = m;
+                return structuredClone(rest);
+            });
         },
         expireMany,
         coldPut: (grant, m) => coldPutMany(grant, [m]),

package/dist/observe.d.ts

@@ -1,7 +1,7 @@
 import type { DecisionController, Embedder, MemoryStore, MemoryWriter, Observation } from './adapters.js';
 import type { ResolvedConfig } from './config.js';
 import type { Decision, Scope } from './model.js';
-export type MemoryOutcomeKind = 'skipped' | 'reinforced' | 'added' | 'updated' | 'superseded';
+export type MemoryOutcomeKind = 'skipped' | 'reinforced' | 'added' | 'updated' | 'superseded' | 'corrected';
 /** What happened to one memory the turn produced. */
 export interface MemoryOutcome {
     outcome: MemoryOutcomeKind;

package/dist/observe.js

@@ -2,7 +2,21 @@ import { randomUUID } from 'node:crypto';
 import { localGrant } from './grant.js';
 import { capObservation } from './cap.js';
 import { scrubObservation } from './scrub.js';
+import { checkWriterDate, factInterval, utcOffset } from './temporal.js';
 import { tokenizeLexical } from './tokenize.js';
+/** How the writer is asked to author each action; its interface predates REFINE and CORRECT. */
+const WRITER_ACTION = {
+    ADD: 'ADD',
+    REFINE: 'UPDATE',
+    SUPERSEDE: 'SUPERSEDE',
+    CORRECT: 'SUPERSEDE',
+};
+const OUTCOME = {
+    ADD: 'added',
+    REFINE: 'updated',
+    SUPERSEDE: 'superseded',
+    CORRECT: 'corrected',
+};
 function countOf(ms) {
     const counts = {};
     for (const m of ms)
@@ -49,6 +63,7 @@ async function confirm(store, grant, id, nowIso) {
     if (m !== null)
         await store.upsert(grant, { ...m, lastConfirmedAt: nowIso });
 }
+const DAY_MS = 86_400_000;
 const GATE_THRESHOLD = 0.5;
 const HOT_SALIENCE = 0.8;
 const CANDIDATES = 5;
@@ -89,6 +104,8 @@ function bestOf(rs) {
 async function apply(a) {
     const { obs, scope, grant, deps, now, candidates, decisions } = a;
     const { store } = deps;
+    // Decisions from here on are this memory's own (the turn's gate and reconcile come before).
+    const firstOwn = decisions.length;
     let best = bestOf(a.rs);
     if (best === undefined && a.noopMeansNew === true && a.rs.length > 0) {
         // Every candidate is unrelated. The writer already said this is a fact worth keeping,
@@ -111,7 +128,7 @@ async function apply(a) {
         await confirm(store, grant, target.id, now.toISOString());
         return { outcome: 'reinforced', memoryId: target.id };
     }
-    let action = best.action;
+    let action = best.action === 'UPDATE' ? 'REFINE' : best.action;
     let prior = action === 'ADD' ? undefined : candidates.find((c) => c.id === best.candidateId);
     if (prior !== undefined && (prior.scope.projectId ?? null) !== (scope.projectId ?? null)) {
         // Candidates include global memories. A project's observation must not end or
@@ -126,7 +143,7 @@ async function apply(a) {
         prior = undefined;
     }
     if (prior !== undefined && a.claimed?.has(prior.id) === true) {
-        // An earlier memory of this turn already ended this prior: this one stands on its own.
+        // An earlier memory of this turn already ended or rewrote this prior: this one stands on its own.
         decisions.push({
             stage: 'write',
             question: 'prior-claimed',
@@ -144,30 +161,78 @@ async function apply(a) {
         action = 'ADD';
     if (prior !== undefined)
         a.claimed?.add(prior.id);
-    const w = await a.author(action, prior);
+    // The turn's time and UTC offset: relative dates are read in the offset the turn was written
+    // in. A turn with no usable timestamp starts now: an empty or unparseable validFrom would make
+    // the memory never current (and consolidation would evict it).
+    const usable = !Number.isNaN(Date.parse(obs.at));
+    const turnAt = usable ? new Date(obs.at) : now;
+    const offset = usable ? (utcOffset(obs.at) ?? 0) : 0;
+    const w = dated(obs, await a.author(WRITER_ACTION[action], prior), turnAt, offset, decisions);
     const id = randomUUID();
     const iso = now.toISOString();
-    // Temporal order of the new fact against the one it replaces. `deep` means it is
-    // also older than the prior's own predecessor; chains are re-slotted at most one
-    // step back (deeper out-of-order chains are a Phase 2 concern).
-    // A turn with no usable timestamp starts now: an empty or unparseable validFrom
-    // would make the memory never current (and consolidation would evict it).
-    const validFrom = Number.isNaN(Date.parse(obs.at)) ? iso : obs.at;
-    const inOrder = prior === undefined || Date.parse(prior.validFrom) <= Date.parse(validFrom);
-    let pred = null;
-    if (prior !== undefined && !inOrder && prior.supersedes !== null) {
-        pred = await store.get(grant, prior.supersedes);
-    }
-    const deep = pred !== null && Date.parse(validFrom) < Date.parse(pred.validFrom);
-    if (prior !== undefined) {
+    const writeDecision = {
+        stage: 'write',
+        question: 'action',
+        answer: action,
+        probability: best.probability,
+    };
+    // The fact's own bounds ("until Friday", "starting next week"), resolved in code.
+    const bounds = factInterval(w.text, turnAt, offset);
+    if (bounds.validFrom !== undefined || bounds.validTo !== undefined) {
         decisions.push({
             stage: 'temporal',
-            question: 'order',
-            answer: inOrder ? 'in-order' : deep ? 'out-of-order-deep' : 'out-of-order',
+            question: 'interval',
+            answer: `${bounds.validFrom ?? 'turn'} .. ${bounds.validTo ?? 'open'}`,
             probability: 1,
         });
     }
-    const memory = {
+    // A start, moved back a day before an end it would pass: an end already in the past ("the
+    // freeze ran until yesterday") is kept, and the fact is stored already ended.
+    const startBefore = (from, to) => to !== null && Date.parse(to) <= Date.parse(from)
+        ? new Date(Date.parse(to) - DAY_MS).toISOString()
+        : from;
+    const validTo = bounds.validTo ?? null;
+    const validFrom = startBefore(bounds.validFrom ?? turnAt.toISOString(), validTo);
+    if (action === 'REFINE' && prior !== undefined) {
+        // Same fact, more detail: rewrite in place. The earlier wording stays in the decisions, and
+        // only this turn's own decisions are appended, so the list grows by a few per refine.
+        // A cold memory is promoted: the store drops its cold copy, so hydration can't undo this.
+        const to = bounds.validTo ?? prior.validTo;
+        await store.upsert(grant, {
+            ...prior,
+            type: w.type,
+            text: w.text,
+            stub: w.stub,
+            entities: w.entities,
+            embedding: a.embedding,
+            tier: prior.tier === 'cold' ? 'warm' : prior.tier,
+            salience: Math.max(prior.salience, a.salience),
+            validFrom: startBefore(bounds.validFrom ?? prior.validFrom, to),
+            validTo: to,
+            lastConfirmedAt: iso,
+            updatedAt: iso,
+            source: {
+                ...prior.source,
+                ...(obs.sessionId !== undefined && { sessionId: obs.sessionId }),
+                ...(obs.turnRef !== undefined && { turnRef: obs.turnRef }),
+                decisions: [
+                    ...prior.source.decisions,
+                    ...decisions.slice(0, firstOwn).filter(isVolatileDecision),
+                    ...best.decisions,
+                    ...decisions.slice(firstOwn),
+                    {
+                        stage: 'refine',
+                        question: 'previous-text',
+                        answer: prior.text,
+                        probability: best.probability,
+                    },
+                    writeDecision,
+                ],
+            },
+        });
+        return { outcome: 'updated', memoryId: prior.id };
+    }
+    const base = {
         id,
         scope,
         type: w.type,
@@ -179,7 +244,7 @@ async function apply(a) {
         tier: a.salience >= HOT_SALIENCE ? 'hot' : 'warm',
         accessLog: { count: 0, recent: [], compactedSum: 0, compactedAt: null },
         validFrom,
-        validTo: null,
+        validTo,
         expiredAt: null,
         endReason: null,
         lastConfirmedAt: null,
@@ -190,29 +255,69 @@ async function apply(a) {
             harness: deps.harness ?? 'unknown',
             ...(obs.sessionId !== undefined && { sessionId: obs.sessionId }),
             ...(obs.turnRef !== undefined && { turnRef: obs.turnRef }),
-            decisions: [
-                ...decisions,
-                { stage: 'write', question: 'action', answer: action, probability: best.probability },
-            ],
+            decisions: [],
         },
         createdAt: iso,
         updatedAt: iso,
     };
-    // A supersede, update or out-of-order insert changes several records; they land
+    const withDecisions = (m) => ({
+        ...m,
+        source: { ...m.source, decisions: [...decisions, writeDecision] },
+    });
+    if (action === 'CORRECT' && prior !== undefined) {
+        // The prior was never true: retract it in transaction time and put the correction in its
+        // place in valid time. Its valid interval is left alone, so as-of reads skip it by reason.
+        // The correction keeps bounds its own text states, else takes the prior's.
+        const to = bounds.validTo ?? prior.validTo;
+        const from = startBefore(bounds.validFrom ?? prior.validFrom, to);
+        await store.upsertMany(grant, [
+            withDecisions({ ...base, validFrom: from, validTo: to }),
+            {
+                ...prior,
+                expiredAt: iso,
+                endReason: 'corrected',
+                supersededBy: id,
+                updatedAt: iso,
+            },
+        ]);
+        return { outcome: 'corrected', memoryId: id };
+    }
+    // Temporal order of the new fact against the one it replaces. `deep` means it is
+    // also older than the prior's own predecessor; chains are re-slotted at most one
+    // step back (deeper out-of-order chains are a Phase 2 concern).
+    // Order is the turn's: a turn after the prior that says "since <earlier day>" is an update and
+    // becomes current; only a turn that itself arrives late slots in behind the prior.
+    const inOrder = prior === undefined || Date.parse(prior.validFrom) <= turnAt.getTime();
+    let pred = null;
+    if (prior !== undefined && !inOrder && prior.supersedes !== null) {
+        pred = await store.get(grant, prior.supersedes);
+    }
+    const deep = pred !== null && Date.parse(validFrom) < Date.parse(pred.validFrom);
+    if (prior !== undefined) {
+        decisions.push({
+            stage: 'temporal',
+            question: 'order',
+            answer: inOrder ? 'in-order' : deep ? 'out-of-order-deep' : 'out-of-order',
+            probability: 1,
+        });
+    }
+    const memory = withDecisions(base);
+    // A supersede or out-of-order insert changes several records; they land
     // together in one atomic write so a crash cannot leave a half-linked chain.
     if (prior === undefined) {
         await store.upsert(grant, memory);
     }
     else if (inOrder) {
-        // Close the prior where the new fact starts, not where we observed it. A fact
-        // starting in the future leaves the prior current until then (`expiredAt` stays
-        // null; consolidation expires it once `validTo` has passed).
+        // Close the prior where the new fact starts, not where we observed it (but never before
+        // the prior's own start). A fact starting in the future leaves the prior current until
+        // then (`expiredAt` stays null; consolidation expires it once `validTo` has passed).
+        const closeAt = Date.parse(validFrom) > Date.parse(prior.validFrom) ? validFrom : prior.validFrom;
         await store.upsertMany(grant, [
             memory,
             {
                 ...prior,
-                validTo: validFrom,
-                expiredAt: Date.parse(validFrom) <= now.getTime() ? iso : null,
+                validTo: closeAt,
+                expiredAt: Date.parse(closeAt) <= now.getTime() ? iso : null,
                 endReason: 'superseded',
                 supersededBy: id,
                 updatedAt: iso,
@@ -250,8 +355,34 @@ async function apply(a) {
             ...(pred === null ? [] : [{ ...pred, validTo: validFrom, supersededBy: id, updatedAt: iso }]),
         ]);
     }
-    const outcome = action === 'ADD' ? 'added' : action === 'UPDATE' ? 'updated' : 'superseded';
-    return { outcome, memoryId: id };
+    return { outcome: OUTCOME[action], memoryId: id };
+}
+/** The gate's volatile answer: recorded on the memory, it is what marks a fact as volatile. */
+const isVolatileDecision = (d) => d.stage === 'gate' && d.question === 'volatile';
+/**
+ * The writer's absolute date checked against the turn (CON-34): when the turn says "yesterday"
+ * and the fact carries one ISO day a day or two off, that day is chrono's reading, not the
+ * model's arithmetic. A stated or distant date is kept and the difference logged.
+ */
+function dated(obs, w, at, offset, decisions) {
+    const r = checkWriterDate(`${obs.userText}\n${obs.assistantText}`, w.text, at, offset);
+    if (r.mismatch !== undefined) {
+        decisions.push({
+            stage: 'temporal',
+            question: 'writer-date',
+            answer: `kept ${r.mismatch.written} (turn reads ${r.mismatch.resolved})`,
+            probability: 1,
+        });
+    }
+    if (r.fixed === undefined)
+        return w;
+    decisions.push({
+        stage: 'temporal',
+        question: 'writer-date',
+        answer: `${r.fixed.from} -> ${r.fixed.to}`,
+        probability: 1,
+    });
+    return { ...w, text: r.text, stub: w.stub.split(r.fixed.from).join(r.fixed.to) };
 }
 /** The same fact twice (whitespace and case aside) is written once. */
 function dedupe(ms) {
@@ -351,11 +482,14 @@ async function observeMany(obs, scope, grant, deps, g, now) {
         throw new Error('reconcileMany returned the wrong number of answers');
     const claimed = new Set();
     const memories = [];
-    const all = [...g.decisions];
+    // The gate's volatile answer is about the whole turn, not each fact of it: until there is a
+    // per-fact question, facts split from a turn carry none (so none is ever marked stale).
+    const turnDecisions = g.decisions.filter((d) => !isVolatileDecision(d));
+    const all = [...turnDecisions];
     for (const [i, f] of facts.entries()) {
         const rs = rss[i];
         const decisions = [
-            ...g.decisions,
+            ...turnDecisions,
             { stage: 'write', question: 'fact', answer: `${i + 1}/${facts.length}`, probability: 1 },
             ...rs.flatMap((r) => r.decisions),
         ];
@@ -374,7 +508,7 @@ async function observeMany(obs, scope, grant, deps, g, now) {
             claimed,
             noopMeansNew: true,
         }));
-        all.push(...decisions.slice(g.decisions.length));
+        all.push(...decisions.slice(turnDecisions.length));
     }
     const head = memories.find((m) => m.outcome !== 'skipped') ?? memories[0];
     return {

package/dist/recall.d.ts

@@ -1,12 +1,28 @@
 import type { Embedder, MemoryStore, Reranker, ScopeFilter } from './adapters.js';
 import type { ResolvedConfig } from './config.js';
-import type { Memory } from './model.js';
+import { type Memory } from './model.js';
+import { type RecallMode } from './temporal.js';
 export interface RecallQuery {
     text: string;
     scope: ScopeFilter;
     budgetChars?: number;
-    /** ISO timestamp: recall what was true then. */
+    /** ISO timestamp: recall what was true then (valid time). Implies `mode: 'as-of'`. */
     asOf?: string;
+    /** ISO timestamp: recall what was believed then (transaction time). Implies `mode: 'known-at'`. */
+    knownAt?: string;
+    /**
+     * Which slice of time to read (CON-34): `current` (the default), `as-of` (`asOf`), `history`
+     * (every version, along the supersede chain) or `known-at` (`knownAt`). Without a mode, `asOf`
+     * or `knownAt`, the mode is read from the query ("on 2 April", "how has … changed").
+     */
+    mode?: RecallMode;
+}
+/** The temporal view a recall used, and whether it was read from the query. */
+export interface RecallTemporal {
+    mode: RecallMode;
+    asOf?: string;
+    knownAt?: string;
+    inferred: boolean;
 }
 export interface RecalledMemory extends Memory {
     explanation: {
@@ -23,6 +39,10 @@ export interface RecalledMemory extends Memory {
         dense?: number;
         activation: number;
         hydrated: boolean;
+        /** History mode: found by walking the supersede chain, not by the search. */
+        chain?: true;
+        /** A volatile fact nobody confirmed within `recall.staleAfterDays`. */
+        stale?: true;
     };
 }
 export type Degradation = 'no-embedder' | 'no-reranker' | 'embed-failed' | 'rerank-failed'
@@ -33,7 +53,9 @@ export type Degradation = 'no-embedder' | 'no-reranker' | 'embed-failed' | 'rera
 /** The reranker did not answer within `recall.rerankBudgetMs`: the fused order stands. */
  | 'rerank-timeout'
 /** Reading or promoting a cold copy failed: those memories stay cold, unhydrated. */
- | 'hydrate-failed';
+ | 'hydrate-failed'
+/** Recording the access failed: the results stand, but their activation was not bumped. */
+ | 'access-failed';
 export interface RecallResult {
     memories: RecalledMemory[];
     /** Reserved for the hook layer (gate decision); `recall` never sets it. */
@@ -51,6 +73,8 @@ export interface RecallResult {
     rerankSkipped?: 'confident';
     /** The query was not embedded, because the lexical search already had a clear answer. */
     embedSkipped?: 'lexical-confident';
+    /** The temporal view this recall read. Always set by `recall`. */
+    temporal?: RecallTemporal;
     timings: Record<string, number>;
 }
 export interface RecallDeps {
@@ -61,10 +85,12 @@ export interface RecallDeps {
     now?: Date;
 }
 /**
- * Hybrid recall: lexical + dense first stage, cold hydration, activation-aware
- * fusion, optional rerank. Adapter failures degrade, never throw; so do store
- * failures in the dense search and in cold hydration (lexical-only, with the
- * reason in `degraded`). The lexical search is the floor: its failure rejects.
+ * Hybrid recall: lexical + dense first stage, activation-aware fusion, optional
+ * rerank, relevance gate, then (only for what is returned, within `budgetChars`
+ * when set) cold hydration and the access record. Adapter failures degrade,
+ * never throw; so do store failures in the dense search, in cold hydration and
+ * in the access record (with the reason in `degraded`). The lexical search is
+ * the floor: its failure rejects.
  */
 export declare function recall(q: RecallQuery, deps: RecallDeps): Promise<RecallResult>;
 /**
@@ -73,3 +99,11 @@ export declare function recall(q: RecallQuery, deps: RecallDeps): Promise<Recall
  * memory stored before a rule existed, written by another tool, or missed by a regression.
  */
 export declare function formatForInjection(r: RecallResult, budgetChars: number, now?: Date): string;
+/**
+ * The memories `formatForInjection` renders within `budgetChars`, in order (a prefix: whole
+ * lines only, stopping at the first that does not fit), with their lines.
+ */
+export declare function fitForInjection<M extends RecalledMemory>(memories: M[], budgetChars: number, now?: Date): {
+    kept: M[];
+    lines: string[];
+};