@rine-kit/agent-memory 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChristmasFox / Arthur Xu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/context/budget.d.ts

@@ -0,0 +1,55 @@
+/** One earlier turn of the conversation, in the host's own words. */
+export interface ConversationTurn {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/** A rolling, low-trust excerpt of what is older than the live window (see checkpoint.ts). */
+export interface ConversationCheckpointView {
+    text: string;
+    generation: number;
+    coverageFrom: string;
+    coverageThrough: string;
+    coveredMessageCount: number;
+    sourceEventIds: string[];
+}
+export interface ConversationWindow {
+    turns: ConversationTurn[];
+    /** Host label of the current speaker; not used for budgeting. */
+    currentSpeakerLabel?: string;
+    currentQuoteContext: string | null;
+    rollingCheckpoint?: ConversationCheckpointView | null;
+}
+export interface ContextBudgetPolicy {
+    recentTurnsTokens: number;
+    quotedMessageTokens: number;
+    episodicSummaryTokens: number;
+    longTermRecallTokens: number;
+    estimatedProviderContextTokens: number;
+    systemAndToolSchemaReserveTokens: number;
+    toolResultReserveTokens: number;
+    finalAnswerReserveTokens: number;
+}
+export declare const DEFAULT_CONTEXT_BUDGET_POLICY: Readonly<ContextBudgetPolicy>;
+export interface BuiltWorkingContext {
+    turns: ConversationTurn[];
+    currentQuoteContext: string | null;
+    episodicSummaryContext: string | null;
+    episodicSummarySourceEventIds: string[];
+    longTermMemoryContext: string | null;
+    currentMessage: string;
+    estimateMethod: 'conservative_unicode_char_v1';
+    estimatedRecentTokens: number;
+    estimatedQuoteTokens: number;
+    estimatedEpisodicSummaryTokens: number;
+    estimatedLongTermMemoryTokens: number;
+    estimatedCurrentMessageTokens: number;
+    reservedProviderTokens: number;
+    estimatedTotalContextTokens: number;
+}
+/**
+ * Conservative planning estimate: ASCII code points cost one third of a token;
+ * every non-ASCII code point costs one. This is deliberately labeled as an
+ * estimate because the configured provider tokenizer is not available here.
+ */
+export declare function estimateContextTokens(text: string): number;
+export declare function buildWorkingContext(window: ConversationWindow, currentMessage: string, policy?: Readonly<ContextBudgetPolicy>, longTermMemoryContext?: string | null): BuiltWorkingContext;

package/dist/context/budget.js

@@ -0,0 +1,103 @@
+export const DEFAULT_CONTEXT_BUDGET_POLICY = Object.freeze({
+    recentTurnsTokens: 4_000,
+    quotedMessageTokens: 1_000,
+    episodicSummaryTokens: 1_000,
+    longTermRecallTokens: 1_000,
+    estimatedProviderContextTokens: 24_000,
+    systemAndToolSchemaReserveTokens: 4_000,
+    toolResultReserveTokens: 5_000,
+    finalAnswerReserveTokens: 2_000,
+});
+/**
+ * Conservative planning estimate: ASCII code points cost one third of a token;
+ * every non-ASCII code point costs one. This is deliberately labeled as an
+ * estimate because the configured provider tokenizer is not available here.
+ */
+export function estimateContextTokens(text) {
+    let units = 0;
+    for (const character of text)
+        units += character.codePointAt(0) <= 0x7f ? 1 / 3 : 1;
+    return Math.ceil(units);
+}
+function fitText(text, budget) {
+    if (estimateContextTokens(text) <= budget)
+        return text;
+    const marker = ' …[正文按上下文预算截断]';
+    const markerCost = estimateContextTokens(marker);
+    const suffix = budget >= markerCost ? marker : '';
+    const prefixBudget = suffix ? budget - markerCost : budget;
+    let prefix = '';
+    let usedUnits = 0;
+    for (const character of text) {
+        const cost = character.codePointAt(0) <= 0x7f ? 1 / 3 : 1;
+        if (Math.ceil(usedUnits + cost) > prefixBudget)
+            break;
+        prefix += character;
+        usedUnits += cost;
+    }
+    let fitted = `${prefix.trimEnd()}${suffix}`;
+    while (estimateContextTokens(fitted) > budget && prefix.length > 0) {
+        prefix = Array.from(prefix).slice(0, -1).join('');
+        fitted = `${prefix.trimEnd()}${suffix}`;
+    }
+    return fitted;
+}
+export function buildWorkingContext(window, currentMessage, policy = DEFAULT_CONTEXT_BUDGET_POLICY, longTermMemoryContext = null) {
+    for (const [name, limit] of Object.entries(policy)) {
+        if (!Number.isSafeInteger(limit) || limit < 0)
+            throw new Error(`agent_context_budget_${name}_invalid`);
+    }
+    const currentTokens = estimateContextTokens(currentMessage);
+    const quote = window.currentQuoteContext === null
+        ? null
+        : fitText(window.currentQuoteContext, policy.quotedMessageTokens);
+    const quoteTokens = quote === null ? 0 : estimateContextTokens(quote);
+    const memoryContext = longTermMemoryContext === null
+        ? null
+        : fitText(longTermMemoryContext, policy.longTermRecallTokens);
+    const memoryTokens = memoryContext === null ? 0 : estimateContextTokens(memoryContext);
+    const reservedProviderTokens = policy.systemAndToolSchemaReserveTokens +
+        policy.toolResultReserveTokens +
+        policy.finalAnswerReserveTokens +
+        policy.longTermRecallTokens;
+    const availableHistoryTokens = Math.max(0, policy.estimatedProviderContextTokens - reservedProviderTokens - currentTokens - quoteTokens);
+    const selected = [];
+    let recentTokens = 0;
+    for (let index = window.turns.length - 1; index >= 0; index -= 1) {
+        const turn = window.turns[index];
+        const cost = estimateContextTokens(turn.content);
+        if (cost > policy.recentTurnsTokens ||
+            recentTokens + cost > policy.recentTurnsTokens ||
+            recentTokens + cost > availableHistoryTokens)
+            continue;
+        selected.push(turn);
+        recentTokens += cost;
+    }
+    selected.reverse();
+    const checkpoint = window.rollingCheckpoint;
+    const checkpointHeader = checkpoint
+        ? `此前对话滚动摘录（低信任原文片段；覆盖 ${checkpoint.coverageFrom} 至 ${checkpoint.coverageThrough}；第 ${checkpoint.generation} 代；${checkpoint.coveredMessageCount} 条源消息；${checkpoint.sourceEventIds.length} 个来源事件）：\n`
+        : '';
+    const summaryBudget = Math.min(policy.episodicSummaryTokens, Math.max(0, availableHistoryTokens - recentTokens));
+    const episodicSummaryContext = checkpoint && checkpoint.text && summaryBudget > 0
+        ? fitText(checkpointHeader + checkpoint.text, summaryBudget)
+        : null;
+    const summaryTokens = episodicSummaryContext === null ? 0 : estimateContextTokens(episodicSummaryContext);
+    const estimatedTotalContextTokens = reservedProviderTokens + currentTokens + quoteTokens + recentTokens + summaryTokens;
+    return {
+        turns: selected,
+        currentQuoteContext: quote,
+        episodicSummaryContext,
+        episodicSummarySourceEventIds: checkpoint?.sourceEventIds ?? [],
+        longTermMemoryContext: memoryContext,
+        currentMessage,
+        estimateMethod: 'conservative_unicode_char_v1',
+        estimatedRecentTokens: recentTokens,
+        estimatedQuoteTokens: quoteTokens,
+        estimatedEpisodicSummaryTokens: summaryTokens,
+        estimatedLongTermMemoryTokens: memoryTokens,
+        estimatedCurrentMessageTokens: currentTokens,
+        reservedProviderTokens,
+        estimatedTotalContextTokens,
+    };
+}

package/dist/context/checkpoint.d.ts

@@ -0,0 +1,24 @@
+export interface CheckpointSourceRow {
+    sourceEventId: string;
+    speakerKind: 'human' | 'assistant' | string;
+    /** ISO time. */
+    createdAt: string;
+    content: string;
+}
+export interface ExtractiveCheckpoint {
+    text: string;
+    coverageFrom: string;
+    coverageThrough: string;
+    coveredMessageCount: number;
+    sourceEventIds: string[];
+    /** Hash of the covered rows; changes exactly when the checkpoint needs a new generation. */
+    sourceDigest: string;
+}
+export declare const MAX_CHECKPOINT_SOURCE_ROWS = 100;
+export declare const MAX_CHECKPOINT_TOKENS = 1000;
+/**
+ * Builds a small extractive checkpoint (no model involved) from the rows older than the live window,
+ * newest first as the host reads them. The 100-row page and the token cap keep the work bounded; the
+ * result is safe to rebuild at any time.
+ */
+export declare function buildExtractiveCheckpoint(rowsNewestFirst: readonly CheckpointSourceRow[]): ExtractiveCheckpoint | null;

package/dist/context/checkpoint.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { estimateContextTokens } from './budget.js';
+export const MAX_CHECKPOINT_SOURCE_ROWS = 100;
+export const MAX_CHECKPOINT_TOKENS = 1_000;
+const CHECKPOINT_SOURCE_LIMIT = 48;
+function contentWithBudget(value, budget) {
+    if (estimateContextTokens(value) <= budget)
+        return value;
+    const marker = ' …[对话摘录截断]';
+    const markerTokens = estimateContextTokens(marker);
+    const textBudget = Math.max(0, budget - markerTokens);
+    let text = '';
+    let tokens = 0;
+    for (const character of value) {
+        const cost = estimateContextTokens(character);
+        if (tokens + cost > textBudget)
+            break;
+        text += character;
+        tokens += cost;
+    }
+    return `${text.trimEnd()}${budget >= markerTokens ? marker : ''}`;
+}
+/**
+ * Builds a small extractive checkpoint (no model involved) from the rows older than the live window,
+ * newest first as the host reads them. The 100-row page and the token cap keep the work bounded; the
+ * result is safe to rebuild at any time.
+ */
+export function buildExtractiveCheckpoint(rowsNewestFirst) {
+    const rows = rowsNewestFirst.slice(0, MAX_CHECKPOINT_SOURCE_ROWS);
+    if (!rows.length)
+        return null;
+    const chronologicalRows = [...rows].reverse();
+    const digestMaterial = chronologicalRows.map((row) => [
+        row.sourceEventId,
+        row.speakerKind,
+        row.createdAt,
+        row.content,
+    ]);
+    const sourceDigest = createHash('sha256').update(JSON.stringify(digestMaterial)).digest('hex');
+    const selected = [];
+    let usedTokens = 0;
+    for (const row of rows) {
+        if (!row.sourceEventId || (row.speakerKind !== 'human' && row.speakerKind !== 'assistant'))
+            continue;
+        if (selected.length >= CHECKPOINT_SOURCE_LIMIT || usedTokens >= MAX_CHECKPOINT_TOKENS)
+            break;
+        const prefix = row.speakerKind === 'assistant' ? '助手说：' : '成员说：';
+        const remaining = MAX_CHECKPOINT_TOKENS - usedTokens - estimateContextTokens(prefix);
+        if (remaining <= 0)
+            break;
+        const line = `${prefix}${contentWithBudget(row.content, remaining)}`;
+        const cost = estimateContextTokens(line);
+        if (cost <= 0 || cost > remaining)
+            continue;
+        selected.push({ sourceEventId: row.sourceEventId, line });
+        usedTokens += cost;
+    }
+    selected.reverse();
+    return {
+        text: selected.map((item) => item.line).join('\n'),
+        coverageFrom: chronologicalRows[0].createdAt,
+        coverageThrough: chronologicalRows.at(-1).createdAt,
+        coveredMessageCount: chronologicalRows.length,
+        sourceEventIds: [...new Set(selected.map((item) => item.sourceEventId))],
+        sourceDigest,
+    };
+}

package/dist/contracts.d.ts

@@ -0,0 +1,160 @@
+export type MemorySourceKind = 'trusted_ingress' | 'user_confirmed' | 'system_verified' | 'unknown';
+export interface MemoryEntry {
+    key: string;
+    content: string;
+    revision: number;
+    updatedAt: string;
+    sourceEventId: string;
+    sourceKind: MemorySourceKind;
+    sourceReliability: number;
+    validUntil: string | null;
+    semanticSimilarity?: number;
+}
+export interface MemoryDraft {
+    key: string;
+    content: string;
+}
+export interface MemoryWriteMetadata {
+    sourceKind?: MemorySourceKind;
+    sourceReliability?: number;
+    validUntil?: string | null;
+}
+export interface MemoryWriteState extends MemoryEntry {
+    revoked: boolean;
+}
+export type MemorySearchMode = 'semantic' | 'lexical_only';
+export type MemorySearchReason = 'semantic_unconfigured' | 'vector_index_unavailable' | 'semantic_unavailable' | 'semantic_timeout' | 'embedding_budget_exhausted' | 'embedding_budget_unavailable' | null;
+export interface MemorySearchResult {
+    entries: MemoryEntry[];
+    mode: MemorySearchMode;
+    reason: MemorySearchReason;
+}
+export interface MemorySearchMetric {
+    durationMs: number;
+    mode: MemorySearchMode;
+    reason: MemorySearchReason;
+}
+export interface MemorySemanticSearchResult {
+    matches: MemoryEntry[];
+    reason: MemorySearchReason;
+}
+export type MemoryRetrievalMode = 'hybrid' | 'lexical_only' | 'disabled';
+export type MemoryRetrievalReason = MemorySearchReason | 'memory_scope_unavailable' | 'memory_store_unavailable' | 'memory_candidate_source_unavailable' | 'disabled_by_operator';
+export interface MemoryRetrievedCandidate {
+    canonicalKey: string;
+    key: string;
+    content: string;
+    revision: number;
+    updatedAt: string;
+    sourceEventId: string;
+    sourceKind: MemorySourceKind;
+    score: number;
+    sources: Array<'exact' | 'lexical' | 'semantic'>;
+    reasons: string[];
+}
+export interface MemoryRetrievalMetric {
+    mode: MemoryRetrievalMode;
+    reason: MemoryRetrievalReason;
+    durationMs: number;
+    candidateCount: number;
+    exactCount: number;
+    lexicalCount: number;
+    semanticCount: number;
+}
+export interface MemoryRecallResult {
+    mode: MemoryRetrievalMode;
+    reason: MemoryRetrievalReason;
+    candidates: MemoryRetrievedCandidate[];
+    context: string | null;
+}
+/** Content-free signal linking a trusted recalled entry to one request. */
+export interface MemoryUsageSignal {
+    key: string;
+    revision: number;
+    sourceEventId: string;
+    queryFingerprint: string;
+}
+export type MemoryUsageSignalKind = 'recalled' | 'used';
+export interface MemoryRecallPolicyOptions {
+    topK: number;
+    semanticSimilarityThreshold: number;
+    minimumScore: number;
+}
+export interface MemoryEvidence {
+    id: string;
+    observedAt: string;
+    source: 'conversation' | 'user_confirmed' | 'system_verified';
+}
+export interface MemoryObservation {
+    content: string;
+    observedAt: string;
+    evidence: readonly MemoryEvidence[];
+}
+export interface MemoryRecallRequest {
+    query: string;
+    limit?: number;
+}
+export interface ExplicitMemoryWrite extends MemoryDraft {
+    operation: 'remember' | 'correct';
+    expectedRevision?: number;
+    validUntil?: string | null;
+}
+export interface MemoryForgetRequest {
+    key: string;
+    expectedRevision?: number;
+}
+export type MemoryWriteResult = {
+    status: 'created' | 'revised' | 'forgotten' | 'already_present' | 'not_found';
+};
+export type DreamingStage = 'light' | 'rem' | 'deep';
+export type MemoryCandidateSubject = 'self' | 'third_party' | 'unknown';
+export type MemoryCandidateKind = 'stable_preference' | 'verifiable_fact' | 'episodic_checkpoint';
+export type MemoryCandidateValidity = 'stable' | '7_days' | '30_days' | '90_days' | 'unknown';
+export interface MemoryCandidateDraft extends MemoryDraft {
+    confidence: 'high' | 'medium';
+    subject: MemoryCandidateSubject;
+    kind: MemoryCandidateKind;
+    evidence: string;
+    validity: MemoryCandidateValidity;
+}
+export interface MemoryPlanningRequest {
+    stage: DreamingStage;
+    messages: readonly {
+        content: string;
+        createdAt: string;
+    }[];
+}
+export interface DreamingStageResult {
+    stage: DreamingStage;
+    status: 'completed' | 'skipped' | 'failed';
+    processed: number;
+}
+export interface DreamingReport {
+    startedAt: string;
+    completedAt: string | null;
+    stages: readonly DreamingStageResult[];
+}
+export interface MemoryHealth {
+    status: 'ready' | 'degraded';
+    lastDreamingAt: string | null;
+    reason: string | null;
+}
+export interface MemoryFeatureFlags {
+    read: boolean;
+    write: boolean;
+    autoLearn: boolean;
+}
+export declare const MEMORY_FEATURE_DEFAULTS: Readonly<MemoryFeatureFlags>;
+export interface MemoryEmbeddingContract {
+    providerId: string;
+    modelId: string;
+    dimensions: number;
+    normalization: 'l2_unit';
+    indexVersion: number;
+}
+export interface MemoryEmbeddingBatch {
+    contract: MemoryEmbeddingContract;
+    vectors: number[][];
+    contentHashes: string[];
+    inputTokens: number | null;
+}

package/dist/contracts.js

@@ -0,0 +1,5 @@
+export const MEMORY_FEATURE_DEFAULTS = {
+    read: true,
+    write: true,
+    autoLearn: true,
+};

package/dist/dreaming/candidates.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryCandidateDraft, MemoryCandidateKind } from '../contracts.js';
+export interface MemoryCandidateSource {
+    content: string;
+    sourceEventId: string;
+}
+export interface NormalizedMemoryCandidate {
+    key: string;
+    content: string;
+    kind: MemoryCandidateKind;
+    validUntil: string | null;
+    evidenceEventIds: string[];
+    idempotencyKey: string;
+}
+export interface NormalizeMemoryCandidatesOptions {
+    maxCandidates: number;
+    now: () => number;
+    canonicalizeKey: (key: string) => string;
+    isProhibited: (text: string) => boolean;
+    createIdempotencyKey: (input: {
+        key: string;
+        content: string;
+        evidenceEventIds: readonly string[];
+    }) => string;
+}
+/** Normalize bounded Light/REM drafts against their source evidence before persistence. */
+export declare function normalizeMemoryCandidates(drafts: readonly MemoryCandidateDraft[], sources: readonly MemoryCandidateSource[], options: NormalizeMemoryCandidatesOptions): NormalizedMemoryCandidate[];

package/dist/dreaming/candidates.js

@@ -0,0 +1,53 @@
+/** Normalize bounded Light/REM drafts against their source evidence before persistence. */
+export function normalizeMemoryCandidates(drafts, sources, options) {
+    const accepted = [];
+    const seenKeys = new Set();
+    for (const draft of drafts.slice(0, Math.max(0, options.maxCandidates))) {
+        if (draft.subject !== 'self' || draft.confidence !== 'high')
+            continue;
+        if (!validCandidateKindAndValidity(draft.kind, draft.validity))
+            continue;
+        const evidence = draft.evidence.trim().normalize('NFKC');
+        const content = draft.content.trim().normalize('NFKC');
+        if (!content || !evidence.includes(content) || options.isProhibited(`${evidence}\n${content}`))
+            continue;
+        const evidenceSources = sources.filter((source) => source.content.normalize('NFKC').includes(evidence));
+        if (!evidenceSources.length)
+            continue;
+        let key;
+        try {
+            key = options.canonicalizeKey(draft.key);
+        }
+        catch {
+            continue;
+        }
+        if (seenKeys.has(key))
+            continue;
+        const evidenceEventIds = [
+            ...new Set(evidenceSources.map((source) => source.sourceEventId)),
+        ].slice(0, 8);
+        seenKeys.add(key);
+        accepted.push({
+            key,
+            content,
+            kind: draft.kind,
+            validUntil: candidateExpiry(draft.kind, draft.validity, options.now()),
+            evidenceEventIds,
+            idempotencyKey: options.createIdempotencyKey({ key, content, evidenceEventIds }),
+        });
+    }
+    return accepted;
+}
+function validCandidateKindAndValidity(kind, validity) {
+    if (kind === 'stable_preference')
+        return validity === 'stable';
+    if (kind === 'verifiable_fact')
+        return validity === '7_days' || validity === '30_days' || validity === '90_days';
+    return validity === '7_days' || validity === '30_days';
+}
+function candidateExpiry(kind, validity, now) {
+    if (kind === 'stable_preference' && validity === 'stable')
+        return null;
+    const days = validity === '7_days' ? 7 : validity === '30_days' ? 30 : validity === '90_days' ? 90 : 0;
+    return days === 0 ? null : new Date(now + days * 86_400_000).toISOString();
+}

package/dist/dreaming/deep.d.ts

@@ -0,0 +1,27 @@
+import type { MemoryCandidateKind } from '../contracts.js';
+/** Evidence collected by the host adapter for one normalized candidate value. */
+export interface DeepPromotionEvidence {
+    candidateKind: MemoryCandidateKind;
+    sourceReliability: number;
+    supportingObservations: number;
+    distinctObservationDays: number;
+    recallCount: number;
+    distinctQueries: number;
+    usedCount: number;
+    ageDays: number;
+    conflictsWithCurrent: boolean;
+    competingValues: number;
+    prohibited: boolean;
+}
+export type DeepPromotionReason = 'promotion_evidence_sufficient' | 'invalid_evidence' | 'sensitive_or_prohibited' | 'source_unreliable' | 'single_observation' | 'insufficient_repetition_or_usage' | 'ambiguous_conflict' | 'stale_evidence' | 'score_below_threshold';
+export interface DeepPromotionDecision {
+    promote: boolean;
+    score: number;
+    threshold: number;
+    reason: DeepPromotionReason;
+}
+/**
+ * Deterministic Deep policy. High model confidence is intentionally absent:
+ * repeated, attributable evidence and useful recall are what can promote.
+ */
+export declare function evaluateDeepPromotion(evidence: DeepPromotionEvidence): DeepPromotionDecision;

package/dist/dreaming/deep.js

@@ -0,0 +1,63 @@
+const SCORE_THRESHOLDS = {
+    stable_preference: 70,
+    verifiable_fact: 75,
+    episodic_checkpoint: 78,
+};
+/**
+ * Deterministic Deep policy. High model confidence is intentionally absent:
+ * repeated, attributable evidence and useful recall are what can promote.
+ */
+export function evaluateDeepPromotion(evidence) {
+    const threshold = SCORE_THRESHOLDS[evidence.candidateKind];
+    const integerFields = [
+        evidence.sourceReliability,
+        evidence.supportingObservations,
+        evidence.distinctObservationDays,
+        evidence.recallCount,
+        evidence.distinctQueries,
+        evidence.usedCount,
+        evidence.competingValues,
+    ];
+    if (!threshold ||
+        integerFields.some((value) => !Number.isSafeInteger(value) || value < 0) ||
+        evidence.sourceReliability > 100 ||
+        !Number.isFinite(evidence.ageDays) ||
+        evidence.ageDays < 0 ||
+        typeof evidence.conflictsWithCurrent !== 'boolean' ||
+        typeof evidence.prohibited !== 'boolean') {
+        return { promote: false, score: 0, threshold: threshold ?? 0, reason: 'invalid_evidence' };
+    }
+    const rawScore = evidence.sourceReliability * 0.55 +
+        Math.min(evidence.supportingObservations, 4) * 8 +
+        Math.min(evidence.distinctObservationDays, 4) * 6 +
+        Math.min(evidence.recallCount, 5) +
+        Math.min(evidence.distinctQueries, 5) * 2 +
+        Math.min(evidence.usedCount, 3) * 4 -
+        Math.max(0, evidence.ageDays - 2) * 2 -
+        (evidence.conflictsWithCurrent ? 5 : 0) -
+        Math.min(evidence.competingValues, 3) * 25;
+    const score = Math.max(0, Math.min(100, Math.round(rawScore)));
+    const decision = (reason) => ({
+        promote: false,
+        score,
+        threshold,
+        reason,
+    });
+    if (evidence.prohibited)
+        return decision('sensitive_or_prohibited');
+    if (evidence.sourceReliability < 80)
+        return decision('source_unreliable');
+    if (evidence.supportingObservations < 2)
+        return decision('single_observation');
+    if (evidence.ageDays > 30)
+        return decision('stale_evidence');
+    if (evidence.competingValues > 0)
+        return decision('ambiguous_conflict');
+    const repeatedAcrossDays = evidence.distinctObservationDays >= 2;
+    const recalledAndUseful = evidence.recallCount >= 2 && evidence.distinctQueries >= 2 && evidence.usedCount >= 1;
+    if (!repeatedAcrossDays && !recalledAndUseful)
+        return decision('insufficient_repetition_or_usage');
+    if (score < threshold)
+        return decision('score_below_threshold');
+    return { promote: true, score, threshold, reason: 'promotion_evidence_sufficient' };
+}

package/dist/dreaming/runner.d.ts

@@ -0,0 +1,16 @@
+import type { DreamingReport } from '../contracts.js';
+export type MemoryDreamingWorkStatus = 'processed' | 'skipped' | 'retry' | 'dead' | 'timed_out';
+export interface MemoryDreamingStageWorker {
+    processNext(stage: 'light' | 'rem', signal: AbortSignal): Promise<MemoryDreamingWorkStatus>;
+    processDeep(signal: AbortSignal): Promise<{
+        status: MemoryDreamingWorkStatus;
+        processed: number;
+    }>;
+}
+export interface MemoryDreamingRunOptions {
+    maxLightBatches?: number;
+    maxRemBatches?: number;
+    now?: () => Date;
+}
+/** Generic bounded Light -> REM -> Deep orchestration over host-owned workers. */
+export declare function runMemoryDreamingStages(worker: MemoryDreamingStageWorker, signal: AbortSignal, options?: MemoryDreamingRunOptions): Promise<DreamingReport>;