@framers/agentos 0.1.126 → 0.1.127

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

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Reconsolidation — emotional drift on memory retrieval.
+ *
+ * Cognitive science foundations:
+ * - **Reconsolidation** (Nader, Schafe & Le Doux, 2000): Retrieved memories
+ *   re-enter a labile state and are restabilized with influence from the
+ *   current emotional context. Each retrieval is a potential modification event.
+ * - **Reconsolidation review** (Nader, 2003): Comprehensive review establishing
+ *   reconsolidation as a general memory phenomenon beyond fear conditioning.
+ *
+ * @module agentos/memory/mechanisms/retrieval/Reconsolidation
+ */
+import type { MemoryTrace } from '../../core/types.js';
+import type { PADState } from '../../core/config.js';
+import type { ResolvedReconsolidationConfig } from '../types.js';
+/**
+ * Apply reconsolidation drift to a trace's emotional context.
+ *
+ * Blends the trace's PAD values toward the current mood by `driftRate`.
+ * Respects importance immunity and cumulative drift caps.
+ * Records a DriftEvent in trace metadata for auditability.
+ *
+ * @param trace       The memory trace being accessed (mutated in place).
+ * @param currentMood Current GMI mood at retrieval time.
+ * @param config      Resolved reconsolidation config.
+ */
+export declare function applyReconsolidation(trace: MemoryTrace, currentMood: PADState, config: ResolvedReconsolidationConfig): void;
+//# sourceMappingURL=Reconsolidation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Reconsolidation.d.ts","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/Reconsolidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,EAAE,6BAA6B,EAAqB,MAAM,aAAa,CAAC;AAuBpF;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,WAAW,EAClB,WAAW,EAAE,QAAQ,EACrB,MAAM,EAAE,6BAA6B,GACpC,IAAI,CAsDN"}

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

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Reconsolidation — emotional drift on memory retrieval.
+ *
+ * Cognitive science foundations:
+ * - **Reconsolidation** (Nader, Schafe & Le Doux, 2000): Retrieved memories
+ *   re-enter a labile state and are restabilized with influence from the
+ *   current emotional context. Each retrieval is a potential modification event.
+ * - **Reconsolidation review** (Nader, 2003): Comprehensive review establishing
+ *   reconsolidation as a general memory phenomenon beyond fear conditioning.
+ *
+ * @module agentos/memory/mechanisms/retrieval/Reconsolidation
+ */
+// ---------------------------------------------------------------------------
+// Metadata helpers
+// ---------------------------------------------------------------------------
+/**
+ * Read mechanism metadata from trace.structuredData, initializing if absent.
+ * Metadata is stored under `structuredData.mechanismMetadata` to avoid
+ * polluting the core MemoryTrace interface.
+ */
+function getMeta(trace) {
+    if (!trace.structuredData)
+        trace.structuredData = {};
+    if (!trace.structuredData.mechanismMetadata) {
+        trace.structuredData.mechanismMetadata = {};
+    }
+    return trace.structuredData.mechanismMetadata;
+}
+// ---------------------------------------------------------------------------
+// Reconsolidation
+// ---------------------------------------------------------------------------
+/**
+ * Apply reconsolidation drift to a trace's emotional context.
+ *
+ * Blends the trace's PAD values toward the current mood by `driftRate`.
+ * Respects importance immunity and cumulative drift caps.
+ * Records a DriftEvent in trace metadata for auditability.
+ *
+ * @param trace       The memory trace being accessed (mutated in place).
+ * @param currentMood Current GMI mood at retrieval time.
+ * @param config      Resolved reconsolidation config.
+ */
+export function applyReconsolidation(trace, currentMood, config) {
+    if (!config.enabled)
+        return;
+    // Importance immunity — use encodingStrength as importance proxy
+    if (trace.encodingStrength >= config.immuneAboveImportance)
+        return;
+    const meta = getMeta(trace);
+    const cumulative = meta.cumulativeDrift ?? 0;
+    if (cumulative >= config.maxDriftPerTrace)
+        return;
+    const remaining = config.maxDriftPerTrace - cumulative;
+    const rate = config.driftRate;
+    // Snapshot before drift
+    const before = {
+        valence: trace.emotionalContext.valence,
+        arousal: trace.emotionalContext.arousal,
+        dominance: trace.emotionalContext.dominance,
+    };
+    // Compute raw deltas (linear interpolation toward current mood)
+    let dV = rate * (currentMood.valence - trace.emotionalContext.valence);
+    let dA = rate * (currentMood.arousal - trace.emotionalContext.arousal);
+    let dD = rate * (currentMood.dominance - trace.emotionalContext.dominance);
+    // Clamp total delta magnitude to remaining drift budget
+    const totalDelta = Math.abs(dV) + Math.abs(dA) + Math.abs(dD);
+    if (totalDelta > remaining && totalDelta > 0) {
+        const scale = remaining / totalDelta;
+        dV *= scale;
+        dA *= scale;
+        dD *= scale;
+    }
+    // Apply drift
+    trace.emotionalContext.valence += dV;
+    trace.emotionalContext.arousal += dA;
+    trace.emotionalContext.dominance += dD;
+    trace.emotionalContext.intensity =
+        Math.abs(trace.emotionalContext.valence) * Math.max(0, trace.emotionalContext.arousal);
+    // Update cumulative drift and audit trail
+    const actualDelta = Math.abs(dV) + Math.abs(dA) + Math.abs(dD);
+    meta.cumulativeDrift = cumulative + actualDelta;
+    if (!meta.driftHistory)
+        meta.driftHistory = [];
+    meta.driftHistory.push({
+        timestamp: Date.now(),
+        beforePAD: before,
+        afterPAD: {
+            valence: trace.emotionalContext.valence,
+            arousal: trace.emotionalContext.arousal,
+            dominance: trace.emotionalContext.dominance,
+        },
+    });
+}
+//# sourceMappingURL=Reconsolidation.js.map

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

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

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

@@ -0,0 +1,32 @@
+/**
+ * @fileoverview Retrieval-Induced Forgetting — competitor suppression.
+ *
+ * Cognitive science foundations:
+ * - **Retrieval-Induced Forgetting** (Anderson, Bjork & Bjork, 1994):
+ *   Retrieving one memory actively suppresses similar competitors via
+ *   inhibitory mechanisms — not just a failure to retrieve, but active
+ *   weakening of competing traces.
+ * - **Inhibition account** (Anderson & Spellman, 1995): The suppression
+ *   is inhibitory (trace-level), not associative (cue-level).
+ *
+ * @module agentos/memory/mechanisms/retrieval/RetrievalInducedForgetting
+ */
+import type { MemoryTrace, ScoredMemoryTrace } from '../../core/types.js';
+import type { ResolvedRIFConfig } from '../types.js';
+/**
+ * Apply retrieval-induced forgetting to competitor traces.
+ *
+ * Competitors are traces that were activated (passed to this function)
+ * but NOT in the final retrieved set. Their stability is reduced by
+ * `suppressionFactor`, modeling the inhibitory suppression of competing
+ * memory traces during retrieval practice.
+ *
+ * @param retrieved   Traces that were selected by the retrieval pipeline.
+ * @param competitors Traces activated but not selected (mutated in place).
+ * @param config      Resolved RIF config.
+ * @returns List of suppressed trace IDs.
+ */
+export declare function applyRetrievalInducedForgetting(retrieved: Array<MemoryTrace | ScoredMemoryTrace>, competitors: MemoryTrace[], config: ResolvedRIFConfig): {
+    suppressedIds: string[];
+};
+//# sourceMappingURL=RetrievalInducedForgetting.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RetrievalInducedForgetting.d.ts","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/RetrievalInducedForgetting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAgBrD;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,SAAS,EAAE,KAAK,CAAC,WAAW,GAAG,iBAAiB,CAAC,EACjD,WAAW,EAAE,WAAW,EAAE,EAC1B,MAAM,EAAE,iBAAiB,GACxB;IAAE,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAwB7B"}

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

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview Retrieval-Induced Forgetting — competitor suppression.
+ *
+ * Cognitive science foundations:
+ * - **Retrieval-Induced Forgetting** (Anderson, Bjork & Bjork, 1994):
+ *   Retrieving one memory actively suppresses similar competitors via
+ *   inhibitory mechanisms — not just a failure to retrieve, but active
+ *   weakening of competing traces.
+ * - **Inhibition account** (Anderson & Spellman, 1995): The suppression
+ *   is inhibitory (trace-level), not associative (cue-level).
+ *
+ * @module agentos/memory/mechanisms/retrieval/RetrievalInducedForgetting
+ */
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Traces with encoding strength above this are considered flashbulb-grade. */
+const FLASHBULB_STRENGTH_FLOOR = 0.9;
+/** Minimum strength to be eligible for suppression (don't kick dead traces). */
+const MIN_SUPPRESSION_STRENGTH = 0.1;
+// ---------------------------------------------------------------------------
+// Retrieval-Induced Forgetting
+// ---------------------------------------------------------------------------
+/**
+ * Apply retrieval-induced forgetting to competitor traces.
+ *
+ * Competitors are traces that were activated (passed to this function)
+ * but NOT in the final retrieved set. Their stability is reduced by
+ * `suppressionFactor`, modeling the inhibitory suppression of competing
+ * memory traces during retrieval practice.
+ *
+ * @param retrieved   Traces that were selected by the retrieval pipeline.
+ * @param competitors Traces activated but not selected (mutated in place).
+ * @param config      Resolved RIF config.
+ * @returns List of suppressed trace IDs.
+ */
+export function applyRetrievalInducedForgetting(retrieved, competitors, config) {
+    if (!config.enabled)
+        return { suppressedIds: [] };
+    const retrievedIds = new Set(retrieved.map((t) => t.id));
+    const suppressedIds = [];
+    let count = 0;
+    for (const comp of competitors) {
+        if (count >= config.maxSuppressionsPerQuery)
+            break;
+        if (retrievedIds.has(comp.id))
+            continue;
+        // Guard: never suppress flashbulb-grade traces
+        if (comp.encodingStrength >= FLASHBULB_STRENGTH_FLOOR)
+            continue;
+        // Guard: skip nearly-dead traces
+        if (comp.encodingStrength < MIN_SUPPRESSION_STRENGTH)
+            continue;
+        // Apply stability reduction
+        comp.stability *= (1 - config.suppressionFactor);
+        suppressedIds.push(comp.id);
+        count++;
+    }
+    return { suppressedIds };
+}
+//# sourceMappingURL=RetrievalInducedForgetting.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"RetrievalInducedForgetting.js","sourceRoot":"","sources":["../../../../src/memory/mechanisms/retrieval/RetrievalInducedForgetting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E,+EAA+E;AAC/E,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,gFAAgF;AAChF,MAAM,wBAAwB,GAAG,GAAG,CAAC;AAErC,8EAA8E;AAC9E,+BAA+B;AAC/B,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,+BAA+B,CAC7C,SAAiD,EACjD,WAA0B,EAC1B,MAAyB;IAEzB,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;IAElD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,IAAI,KAAK,GAAG,CAAC,CAAC;IAEd,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,IAAI,KAAK,IAAI,MAAM,CAAC,uBAAuB;YAAE,MAAM;QACnD,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAAE,SAAS;QAExC,+CAA+C;QAC/C,IAAI,IAAI,CAAC,gBAAgB,IAAI,wBAAwB;YAAE,SAAS;QAEhE,iCAAiC;QACjC,IAAI,IAAI,CAAC,gBAAgB,GAAG,wBAAwB;YAAE,SAAS;QAE/D,4BAA4B;QAC5B,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,iBAAiB,CAAC,CAAC;QACjD,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC5B,KAAK,EAAE,CAAC;IACV,CAAC;IAED,OAAO,EAAE,aAAa,EAAE,CAAC;AAC3B,CAAC"}

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

@@ -0,0 +1,210 @@
+/**
+ * @fileoverview Configuration and shared types for cognitive mechanisms.
+ *
+ * Each mechanism is individually toggleable and tunable. When the top-level
+ * `cognitiveMechanisms` field is `undefined` on `CognitiveMemoryConfig`,
+ * the engine is never instantiated and zero code paths execute.
+ *
+ * @module agentos/memory/mechanisms/types
+ */
+import type { PADState } from '../core/config.js';
+import type { MemorySourceType } from '../core/types.js';
+/** Reconsolidation config (Nader, Schafe & Le Doux, 2000). */
+export interface ReconsolidationConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Fraction of PAD delta applied per retrieval. @default 0.05 */
+    driftRate?: number;
+    /** Maximum cumulative drift allowed per trace. @default 0.4 */
+    maxDriftPerTrace?: number;
+    /** Traces with importance >= this value resist drift. @default 9 */
+    immuneAboveImportance?: number;
+}
+/** Retrieval-Induced Forgetting config (Anderson, Bjork & Bjork, 1994). */
+export interface RetrievalInducedForgettingConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Cosine similarity threshold to identify competitors. @default 0.7 */
+    similarityThreshold?: number;
+    /** Stability reduction factor for suppressed competitors. @default 0.12 */
+    suppressionFactor?: number;
+    /** Maximum competitors suppressed per query. @default 5 */
+    maxSuppressionsPerQuery?: number;
+}
+/** Involuntary Recall config (Berntsen, 2009). */
+export interface InvoluntaryRecallConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Probability of surfacing an involuntary memory per assembly. @default 0.08 */
+    probability?: number;
+    /** Minimum age in days for involuntary recall candidates. @default 14 */
+    minAgeDays?: number;
+    /** Minimum Ebbinghaus strength for candidates. @default 0.15 */
+    minStrength?: number;
+}
+/** Metacognitive Feeling-of-Knowing config (Nelson & Narens, 1990). */
+export interface MetacognitiveFOKConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Score threshold for partial activation zone. @default 0.3 */
+    partialActivationThreshold?: number;
+    /** Whether to surface TOT signals in assembled prompt. @default true */
+    surfaceTipOfTongue?: boolean;
+}
+/** Temporal Gist config (Reyna & Brainerd, 1995). */
+export interface TemporalGistConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Age in days before gist extraction applies. @default 60 */
+    ageThresholdDays?: number;
+    /** Traces retrieved more than this many times are not gisted. @default 2 */
+    minRetrievalCount?: number;
+    /** Keep entity names in gist output. @default true */
+    preserveEntities?: boolean;
+    /** Keep emotional context in gist output. @default true */
+    preserveEmotionalContext?: boolean;
+}
+/** Schema Encoding config (Bartlett, 1932; Tse et al., 2007). */
+export interface SchemaEncodingConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Cosine similarity to nearest cluster centroid for schema match. @default 0.75 */
+    clusterSimilarityThreshold?: number;
+    /** Encoding strength multiplier for schema-violating (novel) input. @default 1.3 */
+    noveltyBoost?: number;
+    /** Encoding strength multiplier for schema-congruent input. @default 0.85 */
+    congruencyDiscount?: number;
+}
+/** Source Confidence Decay config (Johnson, Hashtroudi & Lindsay, 1993). */
+export interface SourceConfidenceDecayConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Per-source-type stability multiplier applied each consolidation cycle. */
+    decayMultipliers?: Partial<Record<MemorySourceType, number>>;
+}
+/** Emotion Regulation config (Gross, 1998, 2015). */
+export interface EmotionRegulationConfig {
+    /** @default true */
+    enabled?: boolean;
+    /** Valence/arousal reduction rate per consolidation cycle. @default 0.15 */
+    reappraisalRate?: number;
+    /** Arousal above this triggers regulation. @default 0.8 */
+    suppressionThreshold?: number;
+    /** Maximum traces regulated per consolidation cycle. @default 10 */
+    maxRegulationPerCycle?: number;
+}
+/**
+ * Per-mechanism toggle config for cognitive mechanisms.
+ *
+ * When present (even as `{}`), all mechanisms default to enabled with
+ * sensible constants. When `undefined` on `CognitiveMemoryConfig`,
+ * the engine is never instantiated.
+ */
+export interface CognitiveMechanismsConfig {
+    reconsolidation?: Partial<ReconsolidationConfig>;
+    retrievalInducedForgetting?: Partial<RetrievalInducedForgettingConfig>;
+    involuntaryRecall?: Partial<InvoluntaryRecallConfig>;
+    metacognitiveFOK?: Partial<MetacognitiveFOKConfig>;
+    temporalGist?: Partial<TemporalGistConfig>;
+    schemaEncoding?: Partial<SchemaEncodingConfig>;
+    sourceConfidenceDecay?: Partial<SourceConfidenceDecayConfig>;
+    emotionRegulation?: Partial<EmotionRegulationConfig>;
+}
+/** Metacognitive signal produced by FOK detection. */
+export interface MetacognitiveSignal {
+    type: 'tip_of_tongue' | 'low_confidence' | 'high_confidence';
+    traceId: string;
+    /** Feeling-of-knowing score, 0 (no idea) to 1 (certain it exists). */
+    feelingOfKnowing: number;
+    /** Partial info: entities, emotion, approximate timeframe. */
+    partialInfo?: string;
+}
+/** A single reconsolidation drift event for audit trail. */
+export interface DriftEvent {
+    timestamp: number;
+    beforePAD: PADState;
+    afterPAD: PADState;
+}
+/** Optional metadata fields added to MemoryTrace.structuredData by mechanisms. */
+export interface MechanismMetadata {
+    /** Reconsolidation: cumulative absolute PAD drift. */
+    cumulativeDrift?: number;
+    /** Reconsolidation: audit trail of drift events. */
+    driftHistory?: DriftEvent[];
+    /** Temporal Gist: whether content has been compressed. */
+    gisted?: boolean;
+    /** Temporal Gist: SHA-256 of original content before gisting. */
+    originalContentHash?: string;
+    /** Schema Encoding: trace matched an existing schema cluster. */
+    schemaCongruent?: boolean;
+    /** Schema Encoding: trace violated all existing schemas (novel). */
+    schemaViolating?: boolean;
+    /** Schema Encoding: ID of the matched cluster. */
+    schemaClusterId?: string;
+    /** Source Confidence Decay: timestamp of last decay application. */
+    lastSourceDecayAt?: number;
+    /** Emotion Regulation: audit trail of reappraisal events. */
+    reappraisalHistory?: Array<{
+        reappraisedAt: number;
+        previousValence: number;
+        previousArousal: number;
+    }>;
+}
+export interface ResolvedReconsolidationConfig {
+    enabled: boolean;
+    driftRate: number;
+    maxDriftPerTrace: number;
+    immuneAboveImportance: number;
+}
+export interface ResolvedRIFConfig {
+    enabled: boolean;
+    similarityThreshold: number;
+    suppressionFactor: number;
+    maxSuppressionsPerQuery: number;
+}
+export interface ResolvedInvoluntaryRecallConfig {
+    enabled: boolean;
+    probability: number;
+    minAgeDays: number;
+    minStrength: number;
+}
+export interface ResolvedMetacognitiveFOKConfig {
+    enabled: boolean;
+    partialActivationThreshold: number;
+    surfaceTipOfTongue: boolean;
+}
+export interface ResolvedTemporalGistConfig {
+    enabled: boolean;
+    ageThresholdDays: number;
+    minRetrievalCount: number;
+    preserveEntities: boolean;
+    preserveEmotionalContext: boolean;
+}
+export interface ResolvedSchemaEncodingConfig {
+    enabled: boolean;
+    clusterSimilarityThreshold: number;
+    noveltyBoost: number;
+    congruencyDiscount: number;
+}
+export interface ResolvedSourceConfidenceDecayConfig {
+    enabled: boolean;
+    decayMultipliers: Record<MemorySourceType, number>;
+}
+export interface ResolvedEmotionRegulationConfig {
+    enabled: boolean;
+    reappraisalRate: number;
+    suppressionThreshold: number;
+    maxRegulationPerCycle: number;
+}
+/** Fully resolved config with all fields required. */
+export interface ResolvedMechanismsConfig {
+    reconsolidation: ResolvedReconsolidationConfig;
+    retrievalInducedForgetting: ResolvedRIFConfig;
+    involuntaryRecall: ResolvedInvoluntaryRecallConfig;
+    metacognitiveFOK: ResolvedMetacognitiveFOKConfig;
+    temporalGist: ResolvedTemporalGistConfig;
+    schemaEncoding: ResolvedSchemaEncodingConfig;
+    sourceConfidenceDecay: ResolvedSourceConfidenceDecayConfig;
+    emotionRegulation: ResolvedEmotionRegulationConfig;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/memory/mechanisms/types.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Configuration and shared types for cognitive mechanisms.
+ *
+ * Each mechanism is individually toggleable and tunable. When the top-level
+ * `cognitiveMechanisms` field is `undefined` on `CognitiveMemoryConfig`,
+ * the engine is never instantiated and zero code paths execute.
+ *
+ * @module agentos/memory/mechanisms/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/memory/mechanisms/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}