@framers/agentos 0.1.126 → 0.1.127

package/dist/memory/mechanisms/consolidation/SourceConfidenceDecay.js

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview Source Confidence Decay — source-type stability multipliers.
+ *
+ * Cognitive science foundations:
+ * - **Source monitoring framework** (Johnson, Hashtroudi & Lindsay, 1993):
+ *   Attributing a memory to its source is a judgment process. Internally
+ *   generated memories (agent inferences, reflections) are inherently less
+ *   reliable than externally observed facts.
+ * - **Updated review** (Mitchell & Johnson, 2009): Source monitoring errors
+ *   increase when source characteristics are similar — agent-generated
+ *   content is particularly prone to source confusion.
+ *
+ * @module agentos/memory/mechanisms/consolidation/SourceConfidenceDecay
+ */
+/** Importance floor: high-importance traces get a minimum multiplier. */
+const HIGH_IMPORTANCE_THRESHOLD = 0.8;
+const HIGH_IMPORTANCE_FLOOR_MULTIPLIER = 0.90;
+// ---------------------------------------------------------------------------
+// Metadata helpers
+// ---------------------------------------------------------------------------
+function getMeta(trace) {
+    if (!trace.structuredData)
+        trace.structuredData = {};
+    if (!trace.structuredData.mechanismMetadata) {
+        trace.structuredData.mechanismMetadata = {};
+    }
+    return trace.structuredData.mechanismMetadata;
+}
+// ---------------------------------------------------------------------------
+// Source Confidence Decay
+// ---------------------------------------------------------------------------
+/**
+ * Apply source-type stability multipliers to traces during consolidation.
+ *
+ * Each trace's stability is multiplied by a factor determined by its source
+ * type. User statements and tool results (externally verified) get 1.0x.
+ * Agent inferences and reflections (internally generated, prone to
+ * confabulation) decay faster at 0.80x and 0.75x respectively.
+ *
+ * @param traces All active traces (mutated in place).
+ * @param config Resolved source confidence decay config.
+ * @returns Number of traces that had source decay applied.
+ */
+export function applySourceConfidenceDecay(traces, config) {
+    if (!config.enabled)
+        return 0;
+    const now = Date.now();
+    let count = 0;
+    for (const trace of traces) {
+        if (!trace.isActive)
+            continue;
+        const meta = getMeta(trace);
+        // Skip if already decayed in this consolidation window (within 1 hour)
+        if (meta.lastSourceDecayAt && (now - meta.lastSourceDecayAt) < 3600000)
+            continue;
+        const sourceType = trace.provenance.sourceType;
+        let multiplier = config.decayMultipliers[sourceType] ?? 1.0;
+        // Importance floor: high-importance traces get minimum multiplier
+        if (trace.encodingStrength >= HIGH_IMPORTANCE_THRESHOLD) {
+            multiplier = Math.max(multiplier, HIGH_IMPORTANCE_FLOOR_MULTIPLIER);
+        }
+        // Only apply if multiplier actually reduces stability
+        if (multiplier < 1.0) {
+            trace.stability *= multiplier;
+            meta.lastSourceDecayAt = now;
+            count++;
+        }
+    }
+    return count;
+}
+//# sourceMappingURL=SourceConfidenceDecay.js.map

package/dist/memory/mechanisms/consolidation/SourceConfidenceDecay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SourceConfidenceDecay.js","sourceRoot":"","sources":["../../../../src/memory/mechanisms/consolidation/SourceConfidenceDecay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,yEAAyE;AACzE,MAAM,yBAAyB,GAAG,GAAG,CAAC;AACtC,MAAM,gCAAgC,GAAG,IAAI,CAAC;AAE9C,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,SAAS,OAAO,CAAC,KAAkB;IACjC,IAAI,CAAC,KAAK,CAAC,cAAc;QAAE,KAAK,CAAC,cAAc,GAAG,EAAE,CAAC;IACrD,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,iBAAiB,EAAE,CAAC;QAC5C,KAAK,CAAC,cAAc,CAAC,iBAAiB,GAAG,EAAE,CAAC;IAC9C,CAAC;IACD,OAAO,KAAK,CAAC,cAAc,CAAC,iBAAsC,CAAC;AACrE,CAAC;AAED,8EAA8E;AAC9E,0BAA0B;AAC1B,8EAA8E;AAE9E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAqB,EACrB,MAA2C;IAE3C,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,CAAC,CAAC;IAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,CAAC,KAAK,CAAC,QAAQ;YAAE,SAAS;QAE9B,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;QAE5B,uEAAuE;QACvE,IAAI,IAAI,CAAC,iBAAiB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,OAAS;YAAE,SAAS;QAEnF,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC,UAAU,CAAC;QAC/C,IAAI,UAAU,GAAG,MAAM,CAAC,gBAAgB,CAAC,UAAU,CAAC,IAAI,GAAG,CAAC;QAE5D,kEAAkE;QAClE,IAAI,KAAK,CAAC,gBAAgB,IAAI,yBAAyB,EAAE,CAAC;YACxD,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,gCAAgC,CAAC,CAAC;QACtE,CAAC;QAED,sDAAsD;QACtD,IAAI,UAAU,GAAG,GAAG,EAAE,CAAC;YACrB,KAAK,CAAC,SAAS,IAAI,UAAU,CAAC;YAC9B,IAAI,CAAC,iBAAiB,GAAG,GAAG,CAAC;YAC7B,KAAK,EAAE,CAAC;QACV,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/memory/mechanisms/consolidation/TemporalGist.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Temporal Gist Extraction — verbatim-to-gist compression.
+ *
+ * Cognitive science foundations:
+ * - **Fuzzy-trace theory** (Reyna & Brainerd, 1995): Memory encodes two
+ *   parallel representations — verbatim (exact detail) and gist (semantic
+ *   meaning). Over time, verbatim traces decay faster while gist endures.
+ * - **False memory implications** (Brainerd & Reyna, 2002): Gist extraction
+ *   can produce meaning-consistent but factually imprecise memories.
+ *
+ * @module agentos/memory/mechanisms/consolidation/TemporalGist
+ */
+import type { MemoryTrace } from '../../core/types.js';
+import type { ResolvedTemporalGistConfig } from '../types.js';
+/**
+ * Apply temporal gist extraction to qualifying traces.
+ *
+ * Old, low-retrieval episodic/semantic traces have their content compressed
+ * to core assertions while preserving emotional context and entities.
+ *
+ * @param traces All active traces (mutated in place for qualifying ones).
+ * @param config Resolved temporal gist config.
+ * @param llmFn  Optional LLM function for higher-quality gist extraction.
+ * @returns Number of traces gisted in this cycle.
+ */
+export declare function applyTemporalGist(traces: MemoryTrace[], config: ResolvedTemporalGistConfig, llmFn?: (prompt: string) => Promise<string>): Promise<number>;
+//# sourceMappingURL=TemporalGist.d.ts.map

package/dist/memory/mechanisms/consolidation/TemporalGist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemporalGist.d.ts","sourceRoot":"","sources":["../../../../src/memory/mechanisms/consolidation/TemporalGist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,0BAA0B,EAAqB,MAAM,aAAa,CAAC;AAsCjF;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,WAAW,EAAE,EACrB,MAAM,EAAE,0BAA0B,EAClC,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAC1C,OAAO,CAAC,MAAM,CAAC,CAmEjB"}

package/dist/memory/mechanisms/consolidation/TemporalGist.js

@@ -0,0 +1,117 @@
+/**
+ * @fileoverview Temporal Gist Extraction — verbatim-to-gist compression.
+ *
+ * Cognitive science foundations:
+ * - **Fuzzy-trace theory** (Reyna & Brainerd, 1995): Memory encodes two
+ *   parallel representations — verbatim (exact detail) and gist (semantic
+ *   meaning). Over time, verbatim traces decay faster while gist endures.
+ * - **False memory implications** (Brainerd & Reyna, 2002): Gist extraction
+ *   can produce meaning-consistent but factually imprecise memories.
+ *
+ * @module agentos/memory/mechanisms/consolidation/TemporalGist
+ */
+import { sha256 } from '../../core/util/crossPlatformCrypto.js';
+const DAY_MS = 86400000;
+/** Maximum gists per consolidation cycle to prevent runaway compression. */
+const MAX_GISTS_PER_CYCLE = 20;
+/** Flashbulb-grade encoding strength threshold. */
+const FLASHBULB_STRENGTH = 0.9;
+// ---------------------------------------------------------------------------
+// Metadata helpers
+// ---------------------------------------------------------------------------
+function getMeta(trace) {
+    if (!trace.structuredData)
+        trace.structuredData = {};
+    if (!trace.structuredData.mechanismMetadata) {
+        trace.structuredData.mechanismMetadata = {};
+    }
+    return trace.structuredData.mechanismMetadata;
+}
+// ---------------------------------------------------------------------------
+// Gist extraction
+// ---------------------------------------------------------------------------
+/**
+ * Truncate content to first N words + emotion label.
+ * Used as fallback when no LLM is available.
+ */
+function truncateToGist(content, emotion, maxWords = 30) {
+    const words = content.split(/\s+/).slice(0, maxWords);
+    const truncated = words.join(' ');
+    const suffix = words.length < content.split(/\s+/).length ? '...' : '';
+    return `${truncated}${suffix} [${emotion}]`;
+}
+/**
+ * Apply temporal gist extraction to qualifying traces.
+ *
+ * Old, low-retrieval episodic/semantic traces have their content compressed
+ * to core assertions while preserving emotional context and entities.
+ *
+ * @param traces All active traces (mutated in place for qualifying ones).
+ * @param config Resolved temporal gist config.
+ * @param llmFn  Optional LLM function for higher-quality gist extraction.
+ * @returns Number of traces gisted in this cycle.
+ */
+export async function applyTemporalGist(traces, config, llmFn) {
+    if (!config.enabled)
+        return 0;
+    const now = Date.now();
+    const minAge = config.ageThresholdDays * DAY_MS;
+    let gistedCount = 0;
+    for (const trace of traces) {
+        if (gistedCount >= MAX_GISTS_PER_CYCLE)
+            break;
+        // Only gist episodic and semantic types
+        if (trace.type !== 'episodic' && trace.type !== 'semantic')
+            continue;
+        // Skip inactive traces
+        if (!trace.isActive)
+            continue;
+        // Skip traces that aren't old enough
+        if ((now - trace.createdAt) < minAge)
+            continue;
+        // Skip frequently-retrieved traces
+        if (trace.retrievalCount >= config.minRetrievalCount)
+            continue;
+        // Skip flashbulb-grade traces
+        if (trace.encodingStrength >= FLASHBULB_STRENGTH)
+            continue;
+        // Skip already-gisted traces
+        const meta = getMeta(trace);
+        if (meta.gisted)
+            continue;
+        // Store original content hash for audit
+        const originalHash = await sha256(trace.content);
+        // Extract gist
+        let gist;
+        if (llmFn) {
+            const entityHint = trace.entities.length > 0
+                ? `Entities: ${trace.entities.join(', ')}.`
+                : '';
+            const prompt = [
+                'Extract 2-3 core assertions from this memory. Keep it under 50 words.',
+                entityHint,
+                config.preserveEntities ? 'Preserve entity names.' : '',
+                `Memory: "${trace.content}"`,
+            ].filter(Boolean).join('\n');
+            try {
+                gist = await llmFn(prompt);
+            }
+            catch {
+                // Fallback to truncation on LLM failure
+                gist = truncateToGist(trace.content, trace.emotionalContext.gmiMood);
+            }
+        }
+        else {
+            gist = truncateToGist(trace.content, trace.emotionalContext.gmiMood);
+        }
+        // Apply gist
+        trace.content = gist;
+        trace.encodingStrength *= 0.8; // verbatim detail loss weakens the trace
+        // Record in metadata
+        meta.gisted = true;
+        meta.originalContentHash = originalHash;
+        gistedCount++;
+    }
+    return gistedCount;
+}
+//# sourceMappingURL=TemporalGist.js.map

package/dist/memory/mechanisms/consolidation/TemporalGist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TemporalGist.js","sourceRoot":"","sources":["../../../../src/memory/mechanisms/consolidation/TemporalGist.ts"],"names":[],"mappings":"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"}

package/dist/memory/mechanisms/defaults.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Default configuration constants and resolver for cognitive mechanisms.
+ *
+ * All mechanisms default to enabled with empirically-grounded constants.
+ * The `resolveConfig()` function deep-merges partial user overrides with defaults.
+ *
+ * @module agentos/memory/mechanisms/defaults
+ */
+import type { CognitiveMechanismsConfig, ResolvedMechanismsConfig } from './types.js';
+/** Full default config with all mechanisms enabled and sensible constants. */
+export declare const DEFAULT_MECHANISMS_CONFIG: ResolvedMechanismsConfig;
+/**
+ * Deep-merge partial user config with defaults.
+ *
+ * Each mechanism's partial fields are spread over the default,
+ * preserving any user overrides while filling in missing values.
+ */
+export declare function resolveConfig(partial: CognitiveMechanismsConfig): ResolvedMechanismsConfig;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/memory/mechanisms/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../../src/memory/mechanisms/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,8EAA8E;AAC9E,eAAO,MAAM,yBAAyB,EAAE,wBAsDvC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,yBAAyB,GAAG,wBAAwB,CAmB1F"}

package/dist/memory/mechanisms/defaults.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Default configuration constants and resolver for cognitive mechanisms.
+ *
+ * All mechanisms default to enabled with empirically-grounded constants.
+ * The `resolveConfig()` function deep-merges partial user overrides with defaults.
+ *
+ * @module agentos/memory/mechanisms/defaults
+ */
+/** Full default config with all mechanisms enabled and sensible constants. */
+export const DEFAULT_MECHANISMS_CONFIG = {
+    reconsolidation: {
+        enabled: true,
+        driftRate: 0.05,
+        maxDriftPerTrace: 0.4,
+        immuneAboveImportance: 9,
+    },
+    retrievalInducedForgetting: {
+        enabled: true,
+        similarityThreshold: 0.7,
+        suppressionFactor: 0.12,
+        maxSuppressionsPerQuery: 5,
+    },
+    involuntaryRecall: {
+        enabled: true,
+        probability: 0.08,
+        minAgeDays: 14,
+        minStrength: 0.15,
+    },
+    metacognitiveFOK: {
+        enabled: true,
+        partialActivationThreshold: 0.3,
+        surfaceTipOfTongue: true,
+    },
+    temporalGist: {
+        enabled: true,
+        ageThresholdDays: 60,
+        minRetrievalCount: 2,
+        preserveEntities: true,
+        preserveEmotionalContext: true,
+    },
+    schemaEncoding: {
+        enabled: true,
+        clusterSimilarityThreshold: 0.75,
+        noveltyBoost: 1.3,
+        congruencyDiscount: 0.85,
+    },
+    sourceConfidenceDecay: {
+        enabled: true,
+        decayMultipliers: {
+            user_statement: 1.0,
+            tool_result: 1.0,
+            observation: 0.95,
+            external: 0.90,
+            agent_inference: 0.80,
+            reflection: 0.75,
+        },
+    },
+    emotionRegulation: {
+        enabled: true,
+        reappraisalRate: 0.15,
+        suppressionThreshold: 0.8,
+        maxRegulationPerCycle: 10,
+    },
+};
+/**
+ * Deep-merge partial user config with defaults.
+ *
+ * Each mechanism's partial fields are spread over the default,
+ * preserving any user overrides while filling in missing values.
+ */
+export function resolveConfig(partial) {
+    const d = DEFAULT_MECHANISMS_CONFIG;
+    return {
+        reconsolidation: { ...d.reconsolidation, ...partial.reconsolidation },
+        retrievalInducedForgetting: { ...d.retrievalInducedForgetting, ...partial.retrievalInducedForgetting },
+        involuntaryRecall: { ...d.involuntaryRecall, ...partial.involuntaryRecall },
+        metacognitiveFOK: { ...d.metacognitiveFOK, ...partial.metacognitiveFOK },
+        temporalGist: { ...d.temporalGist, ...partial.temporalGist },
+        schemaEncoding: { ...d.schemaEncoding, ...partial.schemaEncoding },
+        sourceConfidenceDecay: {
+            ...d.sourceConfidenceDecay,
+            ...partial.sourceConfidenceDecay,
+            decayMultipliers: {
+                ...d.sourceConfidenceDecay.decayMultipliers,
+                ...partial.sourceConfidenceDecay?.decayMultipliers,
+            },
+        },
+        emotionRegulation: { ...d.emotionRegulation, ...partial.emotionRegulation },
+    };
+}
+//# sourceMappingURL=defaults.js.map

package/dist/memory/mechanisms/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../../src/memory/mechanisms/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,yBAAyB,GAA6B;IACjE,eAAe,EAAE;QACf,OAAO,EAAE,IAAI;QACb,SAAS,EAAE,IAAI;QACf,gBAAgB,EAAE,GAAG;QACrB,qBAAqB,EAAE,CAAC;KACzB;IACD,0BAA0B,EAAE;QAC1B,OAAO,EAAE,IAAI;QACb,mBAAmB,EAAE,GAAG;QACxB,iBAAiB,EAAE,IAAI;QACvB,uBAAuB,EAAE,CAAC;KAC3B;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,IAAI;QACb,WAAW,EAAE,IAAI;QACjB,UAAU,EAAE,EAAE;QACd,WAAW,EAAE,IAAI;KAClB;IACD,gBAAgB,EAAE;QAChB,OAAO,EAAE,IAAI;QACb,0BAA0B,EAAE,GAAG;QAC/B,kBAAkB,EAAE,IAAI;KACzB;IACD,YAAY,EAAE;QACZ,OAAO,EAAE,IAAI;QACb,gBAAgB,EAAE,EAAE;QACpB,iBAAiB,EAAE,CAAC;QACpB,gBAAgB,EAAE,IAAI;QACtB,wBAAwB,EAAE,IAAI;KAC/B;IACD,cAAc,EAAE;QACd,OAAO,EAAE,IAAI;QACb,0BAA0B,EAAE,IAAI;QAChC,YAAY,EAAE,GAAG;QACjB,kBAAkB,EAAE,IAAI;KACzB;IACD,qBAAqB,EAAE;QACrB,OAAO,EAAE,IAAI;QACb,gBAAgB,EAAE;YAChB,cAAc,EAAE,GAAG;YACnB,WAAW,EAAE,GAAG;YAChB,WAAW,EAAE,IAAI;YACjB,QAAQ,EAAE,IAAI;YACd,eAAe,EAAE,IAAI;YACrB,UAAU,EAAE,IAAI;SACmB;KACtC;IACD,iBAAiB,EAAE;QACjB,OAAO,EAAE,IAAI;QACb,eAAe,EAAE,IAAI;QACrB,oBAAoB,EAAE,GAAG;QACzB,qBAAqB,EAAE,EAAE;KAC1B;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,OAAkC;IAC9D,MAAM,CAAC,GAAG,yBAAyB,CAAC;IACpC,OAAO;QACL,eAAe,EAAE,EAAE,GAAG,CAAC,CAAC,eAAe,EAAE,GAAG,OAAO,CAAC,eAAe,EAAE;QACrE,0BAA0B,EAAE,EAAE,GAAG,CAAC,CAAC,0BAA0B,EAAE,GAAG,OAAO,CAAC,0BAA0B,EAAE;QACtG,iBAAiB,EAAE,EAAE,GAAG,CAAC,CAAC,iBAAiB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE;QAC3E,gBAAgB,EAAE,EAAE,GAAG,CAAC,CAAC,gBAAgB,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE;QACxE,YAAY,EAAE,EAAE,GAAG,CAAC,CAAC,YAAY,EAAE,GAAG,OAAO,CAAC,YAAY,EAAE;QAC5D,cAAc,EAAE,EAAE,GAAG,CAAC,CAAC,cAAc,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE;QAClE,qBAAqB,EAAE;YACrB,GAAG,CAAC,CAAC,qBAAqB;YAC1B,GAAG,OAAO,CAAC,qBAAqB;YAChC,gBAAgB,EAAE;gBAChB,GAAG,CAAC,CAAC,qBAAqB,CAAC,gBAAgB;gBAC3C,GAAG,OAAO,CAAC,qBAAqB,EAAE,gBAAgB;aACnD;SACF;QACD,iBAAiB,EAAE,EAAE,GAAG,CAAC,CAAC,iBAAiB,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE;KAC5E,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,17 @@
+/**
+ * Barrel exports for cognitive mechanisms module.
+ * @module agentos/memory/mechanisms
+ */
+export type { CognitiveMechanismsConfig, ResolvedMechanismsConfig, MetacognitiveSignal, MechanismMetadata, DriftEvent, ReconsolidationConfig, RetrievalInducedForgettingConfig, InvoluntaryRecallConfig, MetacognitiveFOKConfig, TemporalGistConfig, SchemaEncodingConfig, SourceConfidenceDecayConfig, EmotionRegulationConfig, ResolvedReconsolidationConfig, ResolvedRIFConfig, ResolvedInvoluntaryRecallConfig, ResolvedMetacognitiveFOKConfig, ResolvedTemporalGistConfig, ResolvedSchemaEncodingConfig, ResolvedSourceConfidenceDecayConfig, ResolvedEmotionRegulationConfig, } from './types.js';
+export { DEFAULT_MECHANISMS_CONFIG, resolveConfig } from './defaults.js';
+export { CognitiveMechanismsEngine } from './CognitiveMechanismsEngine.js';
+export { applyReconsolidation } from './retrieval/Reconsolidation.js';
+export { applyRetrievalInducedForgetting } from './retrieval/RetrievalInducedForgetting.js';
+export { selectInvoluntaryMemory } from './retrieval/InvoluntaryRecall.js';
+export { detectFeelingOfKnowing } from './retrieval/MetacognitiveFOK.js';
+export { applyTemporalGist } from './consolidation/TemporalGist.js';
+export { applySchemaEncoding } from './consolidation/SchemaEncoding.js';
+export type { SchemaEncodingResult } from './consolidation/SchemaEncoding.js';
+export { applySourceConfidenceDecay } from './consolidation/SourceConfidenceDecay.js';
+export { applyEmotionRegulation } from './consolidation/EmotionRegulation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/memory/mechanisms/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/mechanisms/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,qBAAqB,EACrB,gCAAgC,EAChC,uBAAuB,EACvB,sBAAsB,EACtB,kBAAkB,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,uBAAuB,EACvB,6BAA6B,EAC7B,iBAAiB,EACjB,+BAA+B,EAC/B,8BAA8B,EAC9B,0BAA0B,EAC1B,4BAA4B,EAC5B,mCAAmC,EACnC,+BAA+B,GAChC,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAG3E,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,+BAA+B,EAAE,MAAM,2CAA2C,CAAC;AAC5F,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAGzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,YAAY,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/memory/mechanisms/index.js

@@ -0,0 +1,19 @@
+/**
+ * Barrel exports for cognitive mechanisms module.
+ * @module agentos/memory/mechanisms
+ */
+// --- Defaults ---
+export { DEFAULT_MECHANISMS_CONFIG, resolveConfig } from './defaults.js';
+// --- Engine ---
+export { CognitiveMechanismsEngine } from './CognitiveMechanismsEngine.js';
+// --- Retrieval mechanisms ---
+export { applyReconsolidation } from './retrieval/Reconsolidation.js';
+export { applyRetrievalInducedForgetting } from './retrieval/RetrievalInducedForgetting.js';
+export { selectInvoluntaryMemory } from './retrieval/InvoluntaryRecall.js';
+export { detectFeelingOfKnowing } from './retrieval/MetacognitiveFOK.js';
+// --- Consolidation mechanisms ---
+export { applyTemporalGist } from './consolidation/TemporalGist.js';
+export { applySchemaEncoding } from './consolidation/SchemaEncoding.js';
+export { applySourceConfidenceDecay } from './consolidation/SourceConfidenceDecay.js';
+export { applyEmotionRegulation } from './consolidation/EmotionRegulation.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/mechanisms/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/mechanisms/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA2BH,mBAAmB;AACnB,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEzE,iBAAiB;AACjB,OAAO,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAE3E,+BAA+B;AAC/B,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,+BAA+B,EAAE,MAAM,2CAA2C,CAAC;AAC5F,OAAO,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AAEzE,mCAAmC;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAExE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC"}

package/dist/memory/mechanisms/retrieval/InvoluntaryRecall.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @fileoverview Involuntary Recall — random old memory surfacing.
+ *
+ * Cognitive science foundations:
+ * - **Involuntary autobiographical memory** (Berntsen, 2009): Memories
+ *   frequently surface without deliberate retrieval effort, triggered by
+ *   contextual cues. These involuntary memories tend to be more
+ *   emotionally intense and specific than voluntary retrievals.
+ * - **Diary study** (Berntsen & Hall, 2004): Involuntary memories are
+ *   predominantly episodic, emotionally charged, and cue-driven.
+ *
+ * @module agentos/memory/mechanisms/retrieval/InvoluntaryRecall
+ */
+import type { MemoryTrace } from '../../core/types.js';
+import type { ResolvedInvoluntaryRecallConfig } from '../types.js';
+/**
+ * Probabilistically select an involuntary memory from the trace pool.
+ *
+ * Selection is weighted by emotional intensity (`|valence| * arousal`) —
+ * emotionally vivid memories surface involuntarily more often, matching
+ * empirical findings (Berntsen, 2009).
+ *
+ * @param allTraces         Full pool of available memory traces.
+ * @param alreadyRetrievedIds IDs already in the retrieved set (excluded).
+ * @param config            Resolved involuntary recall config.
+ * @returns The selected trace, or null if probability check fails or no candidates qualify.
+ */
+export declare function selectInvoluntaryMemory(allTraces: MemoryTrace[], alreadyRetrievedIds: Set<string>, config: ResolvedInvoluntaryRecallConfig): MemoryTrace | null;
+//# sourceMappingURL=InvoluntaryRecall.d.ts.map

package/dist/memory/mechanisms/retrieval/InvoluntaryRecall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvoluntaryRecall.d.ts","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/InvoluntaryRecall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,aAAa,CAAC;AAInE;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,WAAW,EAAE,EACxB,mBAAmB,EAAE,GAAG,CAAC,MAAM,CAAC,EAChC,MAAM,EAAE,+BAA+B,GACtC,WAAW,GAAG,IAAI,CAkCpB"}

package/dist/memory/mechanisms/retrieval/InvoluntaryRecall.js

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Involuntary Recall — random old memory surfacing.
+ *
+ * Cognitive science foundations:
+ * - **Involuntary autobiographical memory** (Berntsen, 2009): Memories
+ *   frequently surface without deliberate retrieval effort, triggered by
+ *   contextual cues. These involuntary memories tend to be more
+ *   emotionally intense and specific than voluntary retrievals.
+ * - **Diary study** (Berntsen & Hall, 2004): Involuntary memories are
+ *   predominantly episodic, emotionally charged, and cue-driven.
+ *
+ * @module agentos/memory/mechanisms/retrieval/InvoluntaryRecall
+ */
+const DAY_MS = 86400000;
+/**
+ * Probabilistically select an involuntary memory from the trace pool.
+ *
+ * Selection is weighted by emotional intensity (`|valence| * arousal`) —
+ * emotionally vivid memories surface involuntarily more often, matching
+ * empirical findings (Berntsen, 2009).
+ *
+ * @param allTraces         Full pool of available memory traces.
+ * @param alreadyRetrievedIds IDs already in the retrieved set (excluded).
+ * @param config            Resolved involuntary recall config.
+ * @returns The selected trace, or null if probability check fails or no candidates qualify.
+ */
+export function selectInvoluntaryMemory(allTraces, alreadyRetrievedIds, config) {
+    if (!config.enabled)
+        return null;
+    // Probability gate
+    if (Math.random() >= config.probability)
+        return null;
+    const now = Date.now();
+    const minAge = config.minAgeDays * DAY_MS;
+    // Filter candidates: active, old enough, strong enough, not already retrieved
+    const candidates = allTraces.filter((t) => t.isActive &&
+        !alreadyRetrievedIds.has(t.id) &&
+        (now - t.createdAt) > minAge &&
+        t.encodingStrength >= config.minStrength);
+    if (candidates.length === 0)
+        return null;
+    // Weighted selection by emotional intensity
+    const weights = candidates.map((t) => {
+        const intensity = Math.abs(t.emotionalContext.valence) * Math.max(0, t.emotionalContext.arousal);
+        return Math.max(0.01, intensity); // floor to avoid zero-weight
+    });
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    let roll = Math.random() * totalWeight;
+    for (let i = 0; i < candidates.length; i++) {
+        roll -= weights[i];
+        if (roll <= 0)
+            return candidates[i];
+    }
+    return candidates[candidates.length - 1];
+}
+//# sourceMappingURL=InvoluntaryRecall.js.map

package/dist/memory/mechanisms/retrieval/InvoluntaryRecall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"InvoluntaryRecall.js","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/InvoluntaryRecall.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,MAAM,MAAM,GAAG,QAAU,CAAC;AAE1B;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAAwB,EACxB,mBAAgC,EAChC,MAAuC;IAEvC,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAEjC,mBAAmB;IACnB,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,MAAM,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAErD,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC;IAE1C,8EAA8E;IAC9E,MAAM,UAAU,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CACxC,CAAC,CAAC,QAAQ;QACV,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9B,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,GAAG,MAAM;QAC5B,CAAC,CAAC,gBAAgB,IAAI,MAAM,CAAC,WAAW,CACzC,CAAC;IAEF,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEzC,4CAA4C;IAC5C,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QACjG,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,6BAA6B;IACjE,CAAC,CAAC,CAAC;IAEH,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3D,IAAI,IAAI,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3C,IAAI,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,IAAI,IAAI,CAAC;YAAE,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,OAAO,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC3C,CAAC"}

package/dist/memory/mechanisms/retrieval/MetacognitiveFOK.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview Metacognitive Feeling-of-Knowing (FOK) detection.
+ *
+ * Cognitive science foundations:
+ * - **Metamemory framework** (Nelson & Narens, 1990): Two-level monitoring
+ *   system where a meta-level assesses object-level memory processes.
+ * - **FOK paradigm** (Hart, 1965): Introduced the recall-judgment-recognition
+ *   methodology for studying feeling-of-knowing states.
+ * - **Accessibility model** (Koriat, 1993): FOK judgments are based on the
+ *   amount and intensity of partial information that comes to mind, not
+ *   direct access to trace strength.
+ *
+ * @module agentos/memory/mechanisms/retrieval/MetacognitiveFOK
+ */
+import type { ScoredMemoryTrace } from '../../core/types.js';
+import type { ResolvedMetacognitiveFOKConfig, MetacognitiveSignal } from '../types.js';
+/**
+ * Detect tip-of-tongue and partial-recall states from scored candidates.
+ *
+ * Traces in the "partial activation zone" (above `partialActivationThreshold`
+ * but below `retrievalCutoff`) produce MetacognitiveSignals.
+ *
+ * FOK score is based on (following Koriat's accessibility model):
+ * - Gap between trace score and cutoff (smaller gap = higher FOK)
+ * - Entity overlap with query entities (classic TOT trigger)
+ * - Raw similarity score (accessibility heuristic)
+ *
+ * @param scoredCandidates All scored candidates from the retrieval pipeline.
+ * @param retrievalCutoff  Minimum score that qualified for retrieval.
+ * @param config           Resolved FOK config.
+ * @param queryEntities    Entities extracted from the query (for TOT detection).
+ */
+export declare function detectFeelingOfKnowing(scoredCandidates: ScoredMemoryTrace[], retrievalCutoff: number, config: ResolvedMetacognitiveFOKConfig, queryEntities?: string[]): MetacognitiveSignal[];
+//# sourceMappingURL=MetacognitiveFOK.d.ts.map

package/dist/memory/mechanisms/retrieval/MetacognitiveFOK.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetacognitiveFOK.d.ts","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/MetacognitiveFOK.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,8BAA8B,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAIvF;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,iBAAiB,EAAE,EACrC,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,8BAA8B,EACtC,aAAa,GAAE,MAAM,EAAO,GAC3B,mBAAmB,EAAE,CA+CvB"}

package/dist/memory/mechanisms/retrieval/MetacognitiveFOK.js

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Metacognitive Feeling-of-Knowing (FOK) detection.
+ *
+ * Cognitive science foundations:
+ * - **Metamemory framework** (Nelson & Narens, 1990): Two-level monitoring
+ *   system where a meta-level assesses object-level memory processes.
+ * - **FOK paradigm** (Hart, 1965): Introduced the recall-judgment-recognition
+ *   methodology for studying feeling-of-knowing states.
+ * - **Accessibility model** (Koriat, 1993): FOK judgments are based on the
+ *   amount and intensity of partial information that comes to mind, not
+ *   direct access to trace strength.
+ *
+ * @module agentos/memory/mechanisms/retrieval/MetacognitiveFOK
+ */
+const DAY_MS = 86400000;
+/**
+ * Detect tip-of-tongue and partial-recall states from scored candidates.
+ *
+ * Traces in the "partial activation zone" (above `partialActivationThreshold`
+ * but below `retrievalCutoff`) produce MetacognitiveSignals.
+ *
+ * FOK score is based on (following Koriat's accessibility model):
+ * - Gap between trace score and cutoff (smaller gap = higher FOK)
+ * - Entity overlap with query entities (classic TOT trigger)
+ * - Raw similarity score (accessibility heuristic)
+ *
+ * @param scoredCandidates All scored candidates from the retrieval pipeline.
+ * @param retrievalCutoff  Minimum score that qualified for retrieval.
+ * @param config           Resolved FOK config.
+ * @param queryEntities    Entities extracted from the query (for TOT detection).
+ */
+export function detectFeelingOfKnowing(scoredCandidates, retrievalCutoff, config, queryEntities = []) {
+    if (!config.enabled)
+        return [];
+    const signals = [];
+    const queryEntitySet = new Set(queryEntities.map((e) => e.toLowerCase()));
+    for (const trace of scoredCandidates) {
+        const score = trace.retrievalScore;
+        // Must be in partial activation zone: above threshold, below cutoff
+        if (score >= retrievalCutoff || score < config.partialActivationThreshold)
+            continue;
+        // Gap factor: how close to the cutoff (0 = far, 1 = almost retrieved)
+        const range = retrievalCutoff - config.partialActivationThreshold;
+        const gapFactor = range > 0 ? (score - config.partialActivationThreshold) / range : 0;
+        // Similarity factor (raw accessibility signal per Koriat, 1993)
+        const similarityFactor = trace.scoreBreakdown.similarityScore;
+        // Entity overlap bonus (classic TOT: recognize the entity, can't recall details)
+        let entityBonus = 0;
+        if (queryEntitySet.size > 0 && trace.entities.length > 0) {
+            const overlap = trace.entities.filter((e) => queryEntitySet.has(e.toLowerCase())).length;
+            entityBonus = overlap / Math.max(queryEntitySet.size, trace.entities.length);
+        }
+        // Composite FOK (weighted blend)
+        const fok = Math.min(1, gapFactor * 0.4 + similarityFactor * 0.3 + entityBonus * 0.3);
+        // Build partial info string for prompt injection
+        const parts = [];
+        if (trace.entities.length > 0)
+            parts.push(trace.entities.slice(0, 3).join(', '));
+        if (trace.emotionalContext.gmiMood && trace.emotionalContext.gmiMood !== 'NEUTRAL') {
+            parts.push(`mood: ${trace.emotionalContext.gmiMood}`);
+        }
+        const ageDays = Math.floor((Date.now() - trace.createdAt) / DAY_MS);
+        if (ageDays > 0)
+            parts.push(`~${ageDays} days ago`);
+        signals.push({
+            type: fok > 0.6 ? 'high_confidence' : 'tip_of_tongue',
+            traceId: trace.id,
+            feelingOfKnowing: fok,
+            partialInfo: parts.length > 0 ? parts.join(' | ') : undefined,
+        });
+    }
+    return signals;
+}
+//# sourceMappingURL=MetacognitiveFOK.js.map

package/dist/memory/mechanisms/retrieval/MetacognitiveFOK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetacognitiveFOK.js","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/MetacognitiveFOK.ts"],"names":[],"mappings":"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"}