@abot-ai/runtime 1.3.1 → 1.5.0

package/dist/src/runtime/long-term-memory/maturation/transition.js

@@ -0,0 +1,126 @@
+import { canAutomaticallyManageMemory } from "../automatic-management.js";
+import { normalizeMemoryText } from "../policies/normalization.js";
+import { assertObservationBatchReplayable, retainReplayableObservationReceipts } from "../observation-receipt-retention.js";
+import { isCandidateUnexpired, retainLearningCandidates, normalizeMaturationPolicy } from "./retention.js";
+import { assertCurrentLearningDecisionBindings } from "./current-bindings.js";
+import { assertCompatibleLearningEmbeddings, currentLearningEmbeddingBinding } from "./embedding-binding.js";
+import { mergeLearningSources } from "./sources.js";
+import { normalizeLearningDecisions } from "./decisions.js";
+import { consumeScheduledReviewTriggers } from "./scheduled-review.js";
+import { assertLearningReceiptCapacity } from "./receipt-capacity.js";
+import { canPromoteLearningCandidate, hasFreshCandidateReinforcement } from "./candidate-promotion.js";
+import { advanceLearningReinforcements, bindLearningMemorySource } from "./evidence.js";
+import { canCommitLearningReplacement, prepareLearningMemoryUpdate, updateMemoryReviewDeadline } from "./memory-update.js";
+export function commitLearningDecisions(options) {
+    const { current, now } = options;
+    const input = { ...options.input, policy: normalizeMaturationPolicy(current.maturationPolicy ?? options.input.policy), decisions: normalizeLearningDecisions(options.input.decisions) };
+    assertObservationBatchReplayable(input, now);
+    const previous = current.learningReceipts?.find((receipt) => receipt.batchId === input.batchId);
+    if (previous)
+        return { state: current, receipt: previous };
+    assertCurrentLearningDecisionBindings(current, input, now);
+    assertCompatibleLearningEmbeddings(options.embeddings.values(), currentLearningEmbeddingBinding(current, now));
+    const records = new Map(current.records.map((record) => [record.id, record]));
+    const vectors = new Map(current.vectors.map((vector) => [vector.memoryId, vector]));
+    const candidates = new Map((current.learningCandidates ?? []).filter((record) => isCandidateUnexpired(record, now)).map((record) => [record.id, record]));
+    const recordIds = new Set();
+    const candidateIds = new Set();
+    for (const decision of input.decisions) {
+        if (decision.action === "remove") {
+            removeTarget(decision, candidates, records, vectors);
+            continue;
+        }
+        const update = prepareLearningMemoryUpdate(decision, records, candidates);
+        const { id, previous: target } = update;
+        const source = bindLearningMemorySource(input, decision);
+        if (update.unchanged) {
+            records.set(id, updateMemoryReviewDeadline(update.unchanged, decision.reconsiderAt, candidates, now));
+            recordIds.add(id);
+            continue;
+        }
+        assertNoExactDuplicate(decision.content, id, candidates, records, [...decision.mergedCandidateIds, ...(update.replacement ? [update.replacement.id] : [])]);
+        const mergedSources = decision.mergedCandidateIds.flatMap((merged) => candidates.get(merged).sources);
+        for (const merged of decision.mergedCandidateIds)
+            candidates.delete(merged);
+        if (records.has(id))
+            throw new Error("learning_candidate_identity_conflict");
+        const existingVector = decision.targetKind === "memory" && records.get(decision.targetId)?.content === decision.content
+            ? vectors.get(decision.targetId) : undefined;
+        const vector = resolveCandidateVector(id, decision.content, target, options.embeddings, existingVector);
+        const reinforced = hasFreshCandidateReinforcement({ previous: target, decision, input, source, mergedSources });
+        const lastReinforcedAt = resolveReinforcementTime(target, reinforced, now);
+        const candidate = {
+            id, revision: (target?.revision ?? 0) + 1, content: decision.content, tags: decision.tags,
+            score: decision.score, reason: decision.reason, certainty: decision.certainty,
+            sources: source ? mergeLearningSources([...(target?.sources ?? []), ...mergedSources, source]) : target?.sources ?? [],
+            reinforcements: advanceLearningReinforcements(target?.reinforcements, source, reinforced, now),
+            ...(update.replacement ? { replacement: update.replacement } : {}),
+            createdAt: target?.createdAt ?? new Date(now).toISOString(), updatedAt: new Date(now).toISOString(),
+            lastReinforcedAt, expiresAt: new Date(Date.parse(lastReinforcedAt) + input.policy.retentionDays * 86_400_000).toISOString(),
+            reconsiderAt: decision.reconsiderAt, embedding: vector,
+        };
+        if (!canPromoteLearningCandidate(target, decision, input, reinforced, candidate.reinforcements) || !canCommitLearningReplacement(candidate, records)) {
+            candidates.set(id, candidate);
+            candidateIds.add(id);
+            continue;
+        }
+        const memoryId = candidate.replacement?.id ?? id;
+        const replaced = records.get(memoryId);
+        records.set(memoryId, { id: memoryId, content: candidate.content, tags: candidate.tags, provenance: source,
+            automaticManagement: "allowed", observationSources: candidate.sources.filter((entry) => entry.kind === "passive_observation"), reconsiderAt: candidate.reconsiderAt,
+            createdAt: replaced?.createdAt ?? new Date(now).toISOString(), updatedAt: nextVersionTime(replaced?.updatedAt ?? candidate.createdAt, now) });
+        vectors.set(memoryId, { ...vector, memoryId });
+        candidates.delete(id);
+        recordIds.add(memoryId);
+    }
+    consumeScheduledReviewTriggers(input, candidates, records, now);
+    const retained = retainLearningCandidates([...candidates.values()], input.policy, now);
+    const retainedIds = new Set(retained.map(({ id }) => id));
+    const receipt = Object.freeze({
+        batchId: input.batchId, recordIds: [...recordIds], candidateIds: [...candidateIds].filter((id) => retainedIds.has(id)),
+        removedCandidateCount: candidates.size - retained.length,
+        createdAt: new Date(now).toISOString(), expiresAt: input.batchExpiresAt,
+    });
+    assertLearningReceiptCapacity(current.learningReceipts ?? [], receipt, now);
+    return {
+        state: { records: [...records.values()], vectors: [...vectors.values()], learningCandidates: retained,
+            maturationPolicy: input.policy,
+            observationReceipts: retainReplayableObservationReceipts(current.observationReceipts ?? [], now),
+            learningReceipts: [...(current.learningReceipts ?? []).filter((entry) => Date.parse(entry.expiresAt) > now), receipt] },
+        receipt,
+    };
+}
+function removeTarget(decision, candidates, records, vectors) {
+    const id = decision.targetId;
+    if (decision.targetKind === "candidate") {
+        candidates.delete(id);
+        return;
+    }
+    const record = records.get(id);
+    if (!record || !canAutomaticallyManageMemory(record))
+        throw new Error("learning_memory_protected");
+    records.delete(id);
+    vectors.delete(id);
+}
+function assertNoExactDuplicate(content, targetId, candidates, records, mergedIds) {
+    const key = normalizeMemoryText(content);
+    const duplicate = [...candidates.values(), ...records.values()].some((record) => record.id !== targetId && !mergedIds.includes(record.id) && normalizeMemoryText(record.content) === key);
+    if (duplicate)
+        throw new Error("learning_duplicate_requires_bound_update");
+}
+function resolveCandidateVector(id, content, target, embeddings, existing) {
+    if (target?.content === content)
+        return target.embedding;
+    const vector = embeddings.get(content) ?? existing;
+    if (!vector)
+        throw new Error("learning_candidate_embedding_missing");
+    return { ...vector, memoryId: id };
+}
+function resolveReinforcementTime(target, reinforced, now) {
+    if (target && !reinforced)
+        return target.lastReinforcedAt;
+    return new Date(now).toISOString();
+}
+function nextVersionTime(previous, now) {
+    return new Date(Math.max(now, Date.parse(previous) + 1)).toISOString();
+}

package/dist/src/runtime/long-term-memory/maturation/write-targets.d.ts

@@ -0,0 +1,4 @@
+import type { LongTermMemoryRepositorySnapshot } from "../contracts.js";
+import type { LearningMemoryDecision } from "./contracts.js";
+/** Candidate promotion and an explicit memory decision must not write the same record. */
+export declare function assertDistinctLearningMemoryWriteTargets(current: LongTermMemoryRepositorySnapshot, decisions: readonly LearningMemoryDecision[]): void;

package/dist/src/runtime/long-term-memory/maturation/write-targets.js

@@ -0,0 +1,22 @@
+/** Candidate promotion and an explicit memory decision must not write the same record. */
+export function assertDistinctLearningMemoryWriteTargets(current, decisions) {
+    const candidates = new Map((current.learningCandidates ?? []).map((candidate) => [candidate.id, candidate]));
+    const memoryTargets = new Set();
+    for (const decision of decisions) {
+        const id = resolveLearningMemoryWriteTarget(decision, candidates);
+        if (!id)
+            continue;
+        if (memoryTargets.has(id))
+            throw new Error("learning_decision_target_repeated");
+        memoryTargets.add(id);
+    }
+}
+function resolveLearningMemoryWriteTarget(decision, candidates) {
+    if (decision.action === "create")
+        return undefined;
+    if (decision.targetKind === "memory")
+        return decision.targetId;
+    if (decision.action === "remove")
+        return undefined;
+    return candidates.get(decision.targetId)?.replacement?.id;
+}

package/dist/src/runtime/long-term-memory/observation-contracts.d.ts

@@ -0,0 +1,40 @@
+import type { MemoryCandidate } from "./contracts.js";
+export type ObservationMemoryProposal = MemoryCandidate & Readonly<{
+    observationIds: readonly string[];
+    reason: string;
+    certainty: "observed" | "inferred";
+}>;
+export type ObservationMemorySource = Readonly<{
+    kind: "passive_observation";
+    environmentId: string;
+    deviceId: string;
+    batchId: string;
+    observationIds: readonly string[];
+    observedAt: string;
+    reason: string;
+    certainty: "observed" | "inferred";
+}>;
+export type ObservationMemoryReceipt = Readonly<{
+    batchId: string;
+    recordIds: readonly string[];
+    candidateIds?: readonly string[];
+    createdAt: string;
+    expiresAt?: string;
+}>;
+export type SaveObservationMemoryInput = Readonly<{
+    batchId: string;
+    batchExpiresAt: string;
+    environmentId: string;
+    proposals: readonly ObservationMemoryProposal[];
+    observations: readonly Readonly<{
+        id: string;
+        deviceId: string;
+        timestamp: string;
+        revisitsObservationId?: string;
+        revisit?: Readonly<{
+            firstObservedAt: string;
+            contentUnchanged: true;
+        }>;
+    }>[];
+    abortSignal: AbortSignal;
+}>;

package/dist/src/runtime/long-term-memory/observation-contracts.js

@@ -0,0 +1 @@
+export {};

package/dist/src/runtime/long-term-memory/observation-persistence.d.ts

@@ -0,0 +1,10 @@
+import type { LongTermMemoryRepository } from "./contracts.js";
+import type { ObservationMemoryReceipt, SaveObservationMemoryInput } from "./observation-contracts.js";
+import type { LearningMemoryService } from "./maturation/contracts.js";
+/** Legacy proposals have no quality assessment and enter the shared candidate gate. */
+export declare function saveObservationMemoryBatch(params: {
+    repository: LongTermMemoryRepository;
+    learning: LearningMemoryService;
+    input: SaveObservationMemoryInput;
+    now?: () => Date;
+}): Promise<ObservationMemoryReceipt>;

package/dist/src/runtime/long-term-memory/observation-persistence.js

@@ -0,0 +1,78 @@
+import { bindObservationSource } from "./observation-source.js";
+import { prepareMemoryCandidates } from "./candidate-preparation.js";
+import { normalizeMemoryText } from "./policies/normalization.js";
+import { containsSensitiveMemoryData } from "./policies/sensitive-data.js";
+import { assertObservationBatchReplayable } from "./observation-receipt-retention.js";
+import { candidateKnowledge } from "./maturation/context.js";
+import { MAX_LEARNING_DECISIONS } from "./maturation/decisions.js";
+import { isCandidateUnexpired } from "./maturation/retention.js";
+/** Legacy proposals have no quality assessment and enter the shared candidate gate. */
+export async function saveObservationMemoryBatch(params) {
+    const { input, repository, learning } = params;
+    const now = (params.now ?? (() => new Date()))().getTime();
+    input.abortSignal.throwIfAborted();
+    assertObservationBatchReplayable(input, now);
+    const snapshot = await repository.read();
+    const previous = snapshot.observationReceipts?.find((entry) => entry.batchId === input.batchId)
+        ?? snapshot.learningReceipts?.find((entry) => entry.batchId === input.batchId);
+    if (previous)
+        return previous;
+    const { decisions, context } = adaptObservationProposals(input, snapshot, now);
+    return learning.apply({ ...input, decisions, context, policy: await learning.policy() });
+}
+function adaptObservationProposals(input, snapshot, now) {
+    const candidates = new Map((snapshot.learningCandidates ?? [])
+        .filter((entry) => isCandidateUnexpired(entry, now))
+        .map((entry) => [normalizeMemoryText(entry.content), entry]));
+    // Existing stored memories cannot be changed by an unassessed legacy proposal.
+    const seen = new Set(snapshot.records.map((entry) => normalizeMemoryText(entry.content)));
+    const decisions = [];
+    const entries = [];
+    for (const proposal of input.proposals) {
+        if (decisions.length >= MAX_LEARNING_DECISIONS)
+            break;
+        if (!canPersistObservationReason(proposal.reason))
+            continue;
+        const source = bindObservationSource(input, proposal);
+        const candidate = prepareMemoryCandidates([proposal]).candidates[0];
+        if (!candidate)
+            continue;
+        const key = normalizeMemoryText(candidate.content);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const existing = candidates.get(key);
+        if (existing)
+            entries.push(candidateKnowledge(existing));
+        decisions.push({
+            action: existing ? "update" : "create",
+            targetKind: "candidate", targetId: existing?.id ?? null,
+            targetVersion: existing ? String(existing.revision) : null,
+            content: existing?.content ?? candidate.content,
+            tags: existing?.tags ?? candidate.tags,
+            score: existing?.score ?? 0,
+            reason: existing?.reason ?? source.reason,
+            certainty: existing?.certainty ?? source.certainty,
+            observationIds: source.observationIds,
+            reinforced: false, mergedCandidateIds: [],
+            reconsiderAt: existing?.reconsiderAt ?? null,
+        });
+    }
+    return {
+        decisions,
+        context: {
+            kind: "learning_knowledge_reference_v1", authority: "passive_reference",
+            presenceEffect: "does_not_authorize_actions_or_add_user_intent",
+            repositoryRevision: snapshot.revision,
+            knowledgeRevision: snapshot.knowledgeRevision ?? snapshot.revision,
+            entries, omitted: 0, referenceTime: new Date(now).toISOString(),
+        },
+    };
+}
+function canPersistObservationReason(reason) {
+    if (!reason.trim())
+        return false;
+    if (reason.length > 1_000)
+        return false;
+    return !containsSensitiveMemoryData(reason);
+}

package/dist/src/runtime/long-term-memory/observation-receipt-retention.d.ts

@@ -0,0 +1,3 @@
+import type { ObservationMemoryReceipt, SaveObservationMemoryInput } from "./observation-contracts.js";
+export declare function assertObservationBatchReplayable(input: Pick<SaveObservationMemoryInput, "batchExpiresAt">, now: number): void;
+export declare function retainReplayableObservationReceipts(receipts: readonly ObservationMemoryReceipt[], now: number): readonly ObservationMemoryReceipt[];

package/dist/src/runtime/long-term-memory/observation-receipt-retention.js

@@ -0,0 +1,18 @@
+import { PASSIVE_OBSERVATION_RETENTION_MS } from "../../shared/passive-observation.js";
+export function assertObservationBatchReplayable(input, now) {
+    const expiresAt = Date.parse(input.batchExpiresAt);
+    if (!Number.isFinite(expiresAt))
+        throw new Error("invalid_learning_batch_expiry");
+    if (expiresAt <= now)
+        throw new Error("learning_batch_expired");
+}
+export function retainReplayableObservationReceipts(receipts, now) {
+    return receipts.filter((receipt) => {
+        // Older receipts predate explicit deadlines. Their commit time is later
+        // than evidence collection, so this fallback preserves every valid replay.
+        const expiresAt = receipt.expiresAt
+            ? Date.parse(receipt.expiresAt)
+            : Date.parse(receipt.createdAt) + PASSIVE_OBSERVATION_RETENTION_MS;
+        return expiresAt > now;
+    });
+}

package/dist/src/runtime/long-term-memory/observation-source.d.ts

@@ -0,0 +1,3 @@
+import type { ObservationMemorySource, SaveObservationMemoryInput } from "./observation-contracts.js";
+/** Bind model-selected source IDs only to the submitted observation batch. */
+export declare function bindObservationSource(input: SaveObservationMemoryInput, proposal: SaveObservationMemoryInput["proposals"][number]): ObservationMemorySource;

package/dist/src/runtime/long-term-memory/observation-source.js

@@ -0,0 +1,24 @@
+/** Bind model-selected source IDs only to the submitted observation batch. */
+export function bindObservationSource(input, proposal) {
+    if (!proposal.observationIds.length || !proposal.reason.trim())
+        throw new Error("learning_proposal_source_required");
+    const sources = proposal.observationIds.map((id) => input.observations.find((observation) => observation.id === id));
+    if (sources.some((source) => !source))
+        throw new Error("learning_proposal_source_unknown");
+    const deviceId = sources[0].deviceId;
+    if (sources.some((source) => source.deviceId !== deviceId))
+        throw new Error("learning_proposal_device_mismatch");
+    return Object.freeze({
+        kind: "passive_observation",
+        environmentId: input.environmentId,
+        deviceId,
+        batchId: input.batchId,
+        observationIds: Object.freeze([...new Set(proposal.observationIds)]),
+        observedAt: sources
+            .map((source) => source.timestamp)
+            .sort()
+            .at(-1),
+        reason: proposal.reason.replace(/\s+/gu, " ").trim(),
+        certainty: proposal.certainty,
+    });
+}

package/dist/src/runtime/long-term-memory/observation-state.d.ts

@@ -0,0 +1,4 @@
+import type { ObservationMemoryReceipt, ObservationMemorySource } from "./observation-contracts.js";
+export declare function parseObservationSource(value: unknown): ObservationMemorySource;
+export declare function parseObservationReceipts(value: unknown): readonly ObservationMemoryReceipt[];
+export declare function parseObservationSources(value: unknown): readonly ObservationMemorySource[];

package/dist/src/runtime/long-term-memory/observation-state.js

@@ -0,0 +1,58 @@
+function readRecord(value) {
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return value;
+    throw new Error("long_term_memory_observation_corrupt");
+}
+function readText(value) {
+    if (typeof value === "string" && value.trim())
+        return value;
+    throw new Error("long_term_memory_observation_corrupt");
+}
+function readTexts(value) {
+    if (!Array.isArray(value))
+        throw new Error("long_term_memory_observation_corrupt");
+    return Object.freeze(value.map(readText));
+}
+function readTime(value) {
+    const text = readText(value);
+    if (!Number.isFinite(Date.parse(text)))
+        throw new Error("long_term_memory_observation_corrupt");
+    return text;
+}
+export function parseObservationSource(value) {
+    const source = readRecord(value);
+    if (source.kind !== "passive_observation")
+        throw new Error("long_term_memory_observation_corrupt");
+    if (source.certainty !== "observed" && source.certainty !== "inferred")
+        throw new Error("long_term_memory_observation_corrupt");
+    return Object.freeze({
+        kind: "passive_observation",
+        environmentId: readText(source.environmentId),
+        deviceId: readText(source.deviceId),
+        batchId: readText(source.batchId),
+        observationIds: readTexts(source.observationIds),
+        observedAt: readTime(source.observedAt),
+        reason: readText(source.reason),
+        certainty: source.certainty,
+    });
+}
+export function parseObservationReceipts(value) {
+    if (!Array.isArray(value))
+        throw new Error("long_term_memory_observation_corrupt");
+    return Object.freeze(value.map((entry) => {
+        const receipt = readRecord(entry);
+        return Object.freeze({
+            batchId: readText(receipt.batchId),
+            recordIds: readTexts(receipt.recordIds),
+            createdAt: readTime(receipt.createdAt),
+            ...(receipt.expiresAt === undefined
+                ? {}
+                : { expiresAt: readTime(receipt.expiresAt) }),
+        });
+    }));
+}
+export function parseObservationSources(value) {
+    if (!Array.isArray(value))
+        throw new Error("long_term_memory_observation_corrupt");
+    return Object.freeze(value.map(parseObservationSource));
+}

package/dist/src/runtime/long-term-memory/projection.js

@@ -33,7 +33,23 @@ function serializeProjection(records) {
         kind: LONG_TERM_MEMORY_MESSAGE_KIND,
         authority: "passive_reference",
         purpose: "support_personalized_terminal_response_authoring",
-        memories: records.map(({ content, tags }) => ({ content, tags })),
+        memories: records.map((record) => ({
+            content: record.content,
+            tags: record.tags,
+            ...projectObservationContext(record),
+        })),
         presenceEffect: "reference_only_not_current_user_intent_assignment_action_authority_or_completion_evidence",
     });
 }
+function projectObservationContext(record) {
+    const source = record.observationSources?.at(-1) ?? record.provenance;
+    if (source.kind !== "passive_observation")
+        return {};
+    return {
+        source: {
+            kind: source.kind,
+            observedAt: source.observedAt,
+            certainty: source.certainty,
+        },
+    };
+}

package/dist/src/runtime/long-term-memory/repository-state.js

@@ -1,3 +1,6 @@
+import { parseObservationSource, parseObservationReceipts, parseObservationSources, } from "./observation-state.js";
+import { normalizeMaturationPolicy } from "./maturation/retention.js";
+import { parseLearningCandidates, parseLearningReceipts } from "./maturation/state.js";
 export function createEmptyMemorySnapshot() {
     return Object.freeze({
         schemaVersion: 1,
@@ -8,33 +11,60 @@ export function createEmptyMemorySnapshot() {
 }
 export function advanceMemorySnapshot(current, state) {
     return freezeMemorySnapshot({
-        schemaVersion: 1,
+        schemaVersion: resolveMemorySchemaVersion(current, state),
         revision: current.revision + 1,
+        knowledgeRevision: (current.knowledgeRevision ?? current.revision) + (hasMemoryKnowledgeChanged(current, state) ? 1 : 0),
         records: state.records,
         vectors: state.vectors,
+        ...preserveLearningState(current, state),
+        ...((state.observationReceipts ?? current.observationReceipts)
+            ? {
+                observationReceipts: state.observationReceipts ?? current.observationReceipts,
+            }
+            : {}),
     });
 }
 export function parseMemorySnapshot(value) {
     const root = readRecord(value, "long_term_memory_store_corrupt");
-    if (root.schemaVersion !== 1 || !isNonNegativeInteger(root.revision)) {
+    // Version 2 belonged to an unsupported QA prototype; never reinterpret it.
+    if (!isSupportedMemorySchema(root.schemaVersion) ||
+        !isNonNegativeInteger(root.revision)) {
         throw new Error("long_term_memory_store_schema_unsupported");
     }
     if (!Array.isArray(root.records) || !Array.isArray(root.vectors)) {
         throw new Error("long_term_memory_store_corrupt");
     }
     return freezeMemorySnapshot({
-        schemaVersion: 1,
+        schemaVersion: root.schemaVersion,
         revision: root.revision,
+        ...(root.knowledgeRevision === undefined ? {} : { knowledgeRevision: readKnowledgeRevision(root.knowledgeRevision) }),
+        ...(root.maturationPolicy === undefined ? {} : { maturationPolicy: parseMaturationPolicy(root.maturationPolicy) }),
         records: root.records.map(parseMemoryRecord),
         vectors: root.vectors.map(parseVectorEntry),
+        ...(root.learningCandidates === undefined ? {} : { learningCandidates: parseLearningCandidates(root.learningCandidates, root.schemaVersion) }),
+        ...(root.learningReceipts === undefined ? {} : { learningReceipts: parseLearningReceipts(root.learningReceipts) }),
+        ...(root.observationReceipts === undefined
+            ? {}
+            : {
+                observationReceipts: parseObservationReceipts(root.observationReceipts),
+            }),
     });
 }
 function freezeMemorySnapshot(snapshot) {
     return Object.freeze({
-        schemaVersion: 1,
+        schemaVersion: snapshot.schemaVersion,
         revision: snapshot.revision,
+        ...(snapshot.knowledgeRevision === undefined ? {} : { knowledgeRevision: snapshot.knowledgeRevision }),
+        ...(snapshot.maturationPolicy ? { maturationPolicy: normalizeMaturationPolicy(snapshot.maturationPolicy) } : {}),
         records: Object.freeze(snapshot.records.map(freezeRecord)),
         vectors: Object.freeze(snapshot.vectors.map(freezeVectorEntry)),
+        ...(snapshot.learningCandidates ? { learningCandidates: parseLearningCandidates(snapshot.learningCandidates, snapshot.schemaVersion) } : {}),
+        ...(snapshot.learningReceipts ? { learningReceipts: parseLearningReceipts(snapshot.learningReceipts) } : {}),
+        ...(snapshot.observationReceipts
+            ? {
+                observationReceipts: parseObservationReceipts(snapshot.observationReceipts),
+            }
+            : {}),
     });
 }
 export function parseMemoryRecord(value) {
@@ -47,10 +77,68 @@ export function parseMemoryRecord(value) {
         provenance: parseProvenance(record.provenance),
         createdAt: readTimestamp(record.createdAt),
         updatedAt: readTimestamp(record.updatedAt),
+        ...parseAutomaticManagement(record.automaticManagement),
+        ...(record.reconsiderAt === undefined ? {} : { reconsiderAt: record.reconsiderAt === null ? null : readTimestamp(record.reconsiderAt) }),
+        ...(record.observationSources === undefined
+            ? {}
+            : {
+                observationSources: parseObservationSources(record.observationSources),
+            }),
     });
 }
+function isSupportedMemorySchema(value) {
+    return value === 1 || value === 3 || value === 4 || value === 5;
+}
+function resolveMemorySchemaVersion(current, state) {
+    if (current.schemaVersion === 5 || state.maturationPolicy)
+        return 5;
+    if (state.learningCandidates?.some((record) => record.reinforcements || record.replacement || record.sources.some((source) => source.kind === "passive_response")))
+        return 5;
+    if (current.schemaVersion === 4 || state.learningCandidates || state.learningReceipts)
+        return 4;
+    if (state.records.some((record) => record.automaticManagement !== undefined || record.reconsiderAt !== undefined))
+        return 4;
+    if (hasObservationMemoryState(state) || current.schemaVersion === 3)
+        return 3;
+    return 1;
+}
+function preserveLearningState(current, state) {
+    const maturationPolicy = state.maturationPolicy ?? current.maturationPolicy;
+    const learningCandidates = state.learningCandidates ?? current.learningCandidates;
+    const learningReceipts = state.learningReceipts ?? current.learningReceipts;
+    return {
+        ...(maturationPolicy ? { maturationPolicy } : {}),
+        ...(learningCandidates ? { learningCandidates } : {}),
+        ...(learningReceipts ? { learningReceipts } : {}),
+    };
+}
+function parseAutomaticManagement(value) {
+    if (value === undefined)
+        return {};
+    if (value === "allowed" || value === "protected")
+        return { automaticManagement: value };
+    throw new Error("long_term_memory_protection_corrupt");
+}
+function hasMemoryKnowledgeChanged(current, state) {
+    if (current.records.length !== state.records.length)
+        return true;
+    if (state.records.some((record, index) => JSON.stringify(record) !== JSON.stringify(current.records[index])))
+        return true;
+    const candidates = state.learningCandidates ?? current.learningCandidates ?? [];
+    const previous = current.learningCandidates ?? [];
+    if (candidates.length !== previous.length)
+        return true;
+    return candidates.some((candidate, index) => candidate.id !== previous[index]?.id || candidate.revision !== previous[index]?.revision);
+}
+function readKnowledgeRevision(value) {
+    if (!isNonNegativeInteger(value))
+        throw new Error("long_term_memory_knowledge_revision_corrupt");
+    return value;
+}
 function parseProvenance(value) {
     const provenance = readRecord(value, "long_term_memory_provenance_corrupt");
+    if (provenance.kind === "passive_observation")
+        return parseObservationSource(provenance);
     if (provenance.kind === "passive_response") {
         return Object.freeze({
             kind: "passive_response",
@@ -129,3 +217,16 @@ function isNonNegativeInteger(value) {
 function isPositiveInteger(value) {
     return Number.isSafeInteger(value) && Number(value) > 0;
 }
+function hasObservationMemoryState(state) {
+    if (state.observationReceipts?.length)
+        return true;
+    return state.records.some((record) => record.provenance.kind === "passive_observation" ||
+        (record.observationSources?.length ?? 0) > 0);
+}
+function parseMaturationPolicy(value) {
+    const policy = readRecord(value, "learning_maturation_policy_invalid");
+    return normalizeMaturationPolicy({
+        promotionScore: policy.promotionScore, retentionDays: policy.retentionDays,
+        maxCandidates: policy.maxCandidates, maxBytes: policy.maxBytes,
+    });
+}

package/dist/src/runtime/long-term-memory/service.js

@@ -3,8 +3,17 @@ import { createLongTermMemorySaveQueue } from "./background-save-queue.js";
 import { emitLongTermMemoryEvent, LONG_TERM_MEMORY_EVENTS } from "./events.js";
 import { createLongTermMemoryManagement } from "./management/service.js";
 import { retrieveLongTermMemories } from "./retrieval.js";
+import { saveObservationMemoryBatch } from "./observation-persistence.js";
+import { createLearningMemoryService } from "./maturation/service.js";
+import { observeMemoryChanges } from "./change-notifications.js";
+import { createMemoryRetentionLifecycle } from "./maturation/retention-lifecycle.js";
 export function createLongTermMemoryService(options) {
+    const changes = observeMemoryChanges(options.repository);
+    options = { ...options, repository: changes.repository };
     const embeddings = resolveEmbeddingClient(options);
+    const retention = createMemoryRetentionLifecycle({ repository: options.repository,
+        subscribeCommits: changes.subscribeCommits, ...(options.now ? { now: options.now } : {}) });
+    const learning = embeddings ? createLearningMemoryService({ ...options, embeddings }) : undefined;
     const management = createLongTermMemoryManagement({
         repository: options.repository,
         enabled: options.enabled,
@@ -13,7 +22,7 @@ export function createLongTermMemoryService(options) {
         ...(options.createId ? { createId: options.createId } : {}),
     });
     const processCandidates = async (input) => {
-        if (!options.enabled || !embeddings) {
+        if (!options.enabled || !learning) {
             return Object.freeze({
                 available: false,
                 proposedCount: input.candidates.length,
@@ -25,11 +34,11 @@ export function createLongTermMemoryService(options) {
         }
         return processMemoryCandidates({
             repository: options.repository,
-            embeddings,
+            learning,
+            management,
             candidates: input.candidates,
             context: input.context,
             ...(options.now ? { now: options.now } : {}),
-            ...(options.createId ? { createId: options.createId } : {}),
         });
     };
     const backgroundSaves = createLongTermMemorySaveQueue({
@@ -39,7 +48,27 @@ export function createLongTermMemoryService(options) {
             : {}),
     });
     return Object.freeze({
+        retention,
+        subscribeChanges: changes.subscribe,
         enabled: options.enabled,
+        ...(learning ? { learning } : {}),
+        async observationBatchReceipt(batchId) {
+            const snapshot = await options.repository.read();
+            const learned = snapshot.learningReceipts?.find((receipt) => receipt.batchId === batchId);
+            if (learned)
+                return learned;
+            return snapshot.observationReceipts?.find((receipt) => receipt.batchId === batchId);
+        },
+        async saveObservationBatch(input) {
+            if (!options.enabled || !learning)
+                throw new Error("long_term_memory_disabled");
+            return saveObservationMemoryBatch({
+                repository: options.repository,
+                learning,
+                input,
+                ...(options.now ? { now: options.now } : {}),
+            });
+        },
         async retrieve(input) {
             if (!options.enabled || !embeddings) {
                 return Object.freeze({