@framers/agentos 0.1.112 → 0.1.114

package/dist/memory/observation/MemoryObserver.js

@@ -1,10 +1,18 @@
 /**
- * @fileoverview Memory Observer — personality-biased background note extraction.
+ * @fileoverview Memory Observer — personality-biased background note extraction
+ * with LLM-based compression and reflection tiers.
  *
  * Monitors accumulated conversation tokens via ObservationBuffer.
  * When the threshold is reached, extracts concise observation notes
  * via a persona-configured LLM (defaults to cheap model).
  *
+ * Three-tier agentic memory pipeline (Mastra-style):
+ *   1. Raw notes — extracted per-turn when token threshold is reached.
+ *   2. Compressed observations — produced by ObservationCompressor when
+ *      accumulated notes exceed the compression threshold (default: 50 notes).
+ *   3. Reflections — produced by ObservationReflector when compressed
+ *      observations exceed the reflection token threshold (default: 40,000 tokens).
+ *
  * Personality bias:
  * - High emotionality → notes emotional shifts
  * - High conscientiousness → notes commitments/deadlines
@@ -15,6 +23,9 @@
  * @module agentos/memory/observation/MemoryObserver
  */
 import { ObservationBuffer } from './ObservationBuffer.js';
+import { ObservationCompressor } from './ObservationCompressor.js';
+import { ObservationReflector } from './ObservationReflector.js';
+import { relativeTimeLabel } from './temporal.js';
 // ---------------------------------------------------------------------------
 // Personality-aware system prompt builder
 // ---------------------------------------------------------------------------
@@ -48,8 +59,17 @@ Output ONLY valid JSON objects, one per line. No markdown, no explanation.${emph
 // MemoryObserver
 // ---------------------------------------------------------------------------
 let noteIdCounter = 0;
+/** Default number of accumulated notes before compression triggers. */
+const DEFAULT_COMPRESSION_THRESHOLD = 50;
+/** Default token count of compressed observations before reflection triggers. */
+const DEFAULT_REFLECTION_THRESHOLD_TOKENS = 40000;
 export class MemoryObserver {
     constructor(traits, config) {
+        // --- Compression / reflection tier state ---
+        this.accumulatedNotes = [];
+        this.accumulatedCompressed = [];
+        this.compressor = null;
+        this.reflector = null;
         this.traits = traits;
         this.config = {
             activationThresholdTokens: config?.activationThresholdTokens ?? 30000,
@@ -60,6 +80,14 @@ export class MemoryObserver {
         this.buffer = new ObservationBuffer({
             activationThresholdTokens: this.config.activationThresholdTokens,
         });
+        // Default thresholds for compression and reflection tiers.
+        this.compressionThreshold = DEFAULT_COMPRESSION_THRESHOLD;
+        this.reflectionThresholdTokens = DEFAULT_REFLECTION_THRESHOLD_TOKENS;
+        // Initialize compressor and reflector if LLM invoker is provided.
+        if (this.llmInvoker) {
+            this.compressor = new ObservationCompressor(this.llmInvoker, this.traits);
+            this.reflector = new ObservationReflector(this.llmInvoker);
+        }
     }
     /**
      * Feed a message into the observation buffer.
@@ -89,12 +117,55 @@ export class MemoryObserver {
         const systemPrompt = buildObserverSystemPrompt(this.traits);
         try {
             const response = await this.llmInvoker(systemPrompt, conversationText);
-            return this.parseNotes(response, mood);
+            const notes = this.parseNotes(response, mood, messages);
+            // Accumulate notes for the compression tier.
+            this.accumulatedNotes.push(...notes);
+            return notes;
         }
         catch {
             return [];
         }
     }
+    /**
+     * Run compression if accumulated notes exceed the compression threshold.
+     *
+     * When the number of accumulated raw notes exceeds the configured threshold
+     * (default: 50), the ObservationCompressor is invoked to produce denser
+     * compressed observations. The raw notes are then cleared.
+     *
+     * @returns Compressed observations if threshold was met, null otherwise.
+     */
+    async compressIfNeeded() {
+        if (!this.compressor)
+            return null;
+        if (this.accumulatedNotes.length < this.compressionThreshold)
+            return null;
+        const compressed = await this.compressor.compress(this.accumulatedNotes);
+        // Clear consumed notes and accumulate compressed observations.
+        this.accumulatedNotes = [];
+        this.accumulatedCompressed.push(...compressed);
+        return compressed;
+    }
+    /**
+     * Run reflection if accumulated compressed observations exceed the token threshold.
+     *
+     * When the total estimated tokens of accumulated compressed observations
+     * exceeds the configured threshold (default: 40,000 tokens), the
+     * ObservationReflector is invoked to extract higher-level patterns.
+     *
+     * @returns Reflections if threshold was met, null otherwise.
+     */
+    async reflectIfNeeded() {
+        if (!this.reflector)
+            return null;
+        const totalTokens = this.accumulatedCompressed.reduce((sum, o) => sum + Math.ceil(o.summary.length / 4), 0);
+        if (totalTokens < this.reflectionThresholdTokens)
+            return null;
+        const reflections = await this.reflector.reflect(this.accumulatedCompressed);
+        // Clear consumed compressed observations.
+        this.accumulatedCompressed = [];
+        return reflections;
+    }
     /** Get the underlying buffer for inspection. */
     getBuffer() {
         return this.buffer;
@@ -103,18 +174,53 @@ export class MemoryObserver {
     shouldActivate() {
         return this.buffer.shouldActivate();
     }
+    /** Get the count of accumulated raw notes awaiting compression. */
+    getAccumulatedNoteCount() {
+        return this.accumulatedNotes.length;
+    }
+    /** Get the count of accumulated compressed observations awaiting reflection. */
+    getAccumulatedCompressedCount() {
+        return this.accumulatedCompressed.length;
+    }
+    /** Get the accumulated compressed observations (read-only snapshot). */
+    getAccumulatedCompressed() {
+        return this.accumulatedCompressed;
+    }
+    /** Set the compression threshold (number of notes before compression triggers). */
+    setCompressionThreshold(threshold) {
+        this.compressionThreshold = threshold;
+    }
+    /** Set the reflection token threshold (estimated tokens before reflection triggers). */
+    setReflectionThresholdTokens(threshold) {
+        this.reflectionThresholdTokens = threshold;
+    }
     /** Reset the observer. */
     clear() {
         this.buffer.clear();
+        this.accumulatedNotes = [];
+        this.accumulatedCompressed = [];
     }
     // --- Internal ---
-    parseNotes(llmResponse, mood) {
+    /**
+     * Parse LLM response into ObservationNote objects.
+     *
+     * Attaches three-date temporal metadata from conversation message timestamps
+     * when available, using the earliest message timestamp as `referencedAt`
+     * and the current time as `observedAt`.
+     */
+    parseNotes(llmResponse, mood, messages) {
         const notes = [];
         const lines = llmResponse.split('\n').filter((l) => l.trim());
+        // Determine the earliest message timestamp for the referencedAt field.
+        const earliestMessageTime = messages && messages.length > 0
+            ? Math.min(...messages.map((m) => m.timestamp))
+            : undefined;
         for (const line of lines) {
             try {
                 const parsed = JSON.parse(line.trim());
                 if (parsed.type && parsed.content) {
+                    const now = Date.now();
+                    const referencedAt = earliestMessageTime ?? now;
                     notes.push({
                         id: `obs_${Date.now()}_${++noteIdCounter}`,
                         type: parsed.type,
@@ -122,7 +228,12 @@ export class MemoryObserver {
                         importance: typeof parsed.importance === 'number' ? parsed.importance : 0.5,
                         entities: Array.isArray(parsed.entities) ? parsed.entities : [],
                         emotionalContext: mood ? { valence: mood.valence, arousal: mood.arousal } : undefined,
-                        timestamp: Date.now(),
+                        timestamp: now,
+                        temporal: {
+                            observedAt: now,
+                            referencedAt,
+                            relativeLabel: relativeTimeLabel(referencedAt, now),
+                        },
                     });
                 }
             }

package/dist/memory/observation/MemoryObserver.js.map

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

package/dist/memory/observation/ObservationCompressor.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview LLM-based observational memory compressor.
+ *
+ * Takes a batch of {@link ObservationNote} objects and compresses them into
+ * denser {@link CompressedObservation} summaries via an LLM call. This is the
+ * "Observer" agent in Mastra's agentic memory model — it groups related
+ * observations by topic/entity overlap, produces a 1-3 sentence summary per
+ * group, assigns a priority level, and attaches three-date temporal metadata.
+ *
+ * Typical compression: 3-10x (many individual notes become fewer dense
+ * summaries while preserving all critical facts).
+ *
+ * Personality bias: when HEXACO traits are provided, the system prompt
+ * is tuned to emphasise observation categories that align with the agent's
+ * personality (e.g. high conscientiousness → emphasise commitments).
+ *
+ * @module agentos/memory/observation/ObservationCompressor
+ */
+import type { HexacoTraits } from '../config.js';
+import type { ObservationNote } from './MemoryObserver.js';
+/** Priority level for a compressed observation. */
+export type CompressionPriority = 'critical' | 'important' | 'informational';
+/**
+ * A compressed observation produced by merging multiple raw
+ * {@link ObservationNote} objects into a single dense summary.
+ */
+export interface CompressedObservation {
+    /** Unique identifier for this compressed observation. */
+    id: string;
+    /** Dense summary of multiple observations (1-3 sentences). */
+    summary: string;
+    /** Triage priority. */
+    priority: CompressionPriority;
+    /** Three-date temporal metadata. */
+    temporal: {
+        /** When this compression was performed (Unix ms). */
+        observedAt: number;
+        /** Earliest event timestamp across all source observations (Unix ms). */
+        referencedAt: number;
+        /** Human-friendly relative time label for `referencedAt`. */
+        relativeLabel: string;
+    };
+    /** IDs of the source {@link ObservationNote} objects that were compressed. */
+    sourceIds: string[];
+    /** Union of key entities across all source observations. */
+    entities: string[];
+    /** Average importance score of the source observations (0-1). */
+    importance: number;
+}
+/**
+ * LLM-based compressor that takes a batch of {@link ObservationNote} objects
+ * and produces denser {@link CompressedObservation} summaries.
+ *
+ * Achieves 3-10x compression while preserving key facts, entities, and
+ * temporal context. Each compressed observation carries three-date temporal
+ * metadata: when the compression happened, the earliest referenced event,
+ * and a human-friendly relative time label.
+ */
+export declare class ObservationCompressor {
+    private llmInvoker;
+    private traits?;
+    /**
+     * @param llmInvoker - Function that calls an LLM with (system, user) prompts.
+     * @param traits - Optional HEXACO personality traits for bias-aware compression.
+     */
+    constructor(llmInvoker: (system: string, user: string) => Promise<string>, traits?: HexacoTraits | undefined);
+    /**
+     * Compress a batch of observation notes into denser summaries.
+     *
+     * The method:
+     * 1. Formats the notes as a numbered list for the LLM.
+     * 2. Sends the batch to the LLM with a compression prompt.
+     * 3. Parses the JSON array response into {@link CompressedObservation} objects.
+     * 4. Attaches three-date temporal metadata (observedAt, referencedAt, relativeLabel).
+     *
+     * @param notes - Batch of observation notes to compress.
+     * @returns Array of compressed observations. Returns empty array on LLM failure.
+     */
+    compress(notes: ObservationNote[]): Promise<CompressedObservation[]>;
+    /**
+     * Parse the LLM response into CompressedObservation objects.
+     *
+     * Tries to parse the response as a JSON array. Falls back to extracting
+     * individual JSON objects from lines if the array parse fails.
+     */
+    private parseCompressed;
+}
+//# sourceMappingURL=ObservationCompressor.d.ts.map

package/dist/memory/observation/ObservationCompressor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservationCompressor.d.ts","sourceRoot":"","sources":["../../../src/memory/observation/ObservationCompressor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAO3D,mDAAmD;AACnD,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,WAAW,GAAG,eAAe,CAAC;AAE7E;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,oCAAoC;IACpC,QAAQ,EAAE;QACR,qDAAqD;QACrD,UAAU,EAAE,MAAM,CAAC;QACnB,yEAAyE;QACzE,YAAY,EAAE,MAAM,CAAC;QACrB,6DAA6D;QAC7D,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;CACpB;AAwDD;;;;;;;;GAQG;AACH,qBAAa,qBAAqB;IAM9B,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,MAAM,CAAC;IANjB;;;OAGG;gBAEO,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,EAC7D,MAAM,CAAC,EAAE,YAAY,YAAA;IAG/B;;;;;;;;;;;OAWG;IACG,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;IAwB1E;;;;;OAKG;IACH,OAAO,CAAC,eAAe;CAuFxB"}

package/dist/memory/observation/ObservationCompressor.js

@@ -0,0 +1,207 @@
+/**
+ * @fileoverview LLM-based observational memory compressor.
+ *
+ * Takes a batch of {@link ObservationNote} objects and compresses them into
+ * denser {@link CompressedObservation} summaries via an LLM call. This is the
+ * "Observer" agent in Mastra's agentic memory model — it groups related
+ * observations by topic/entity overlap, produces a 1-3 sentence summary per
+ * group, assigns a priority level, and attaches three-date temporal metadata.
+ *
+ * Typical compression: 3-10x (many individual notes become fewer dense
+ * summaries while preserving all critical facts).
+ *
+ * Personality bias: when HEXACO traits are provided, the system prompt
+ * is tuned to emphasise observation categories that align with the agent's
+ * personality (e.g. high conscientiousness → emphasise commitments).
+ *
+ * @module agentos/memory/observation/ObservationCompressor
+ */
+import { relativeTimeLabel } from './temporal.js';
+// ---------------------------------------------------------------------------
+// System prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Build the LLM system prompt for observation compression.
+ * Personality traits modulate which observation categories receive emphasis.
+ */
+function buildCompressorSystemPrompt(traits) {
+    const emphases = [];
+    if (traits) {
+        const c = (v) => v == null ? 0.5 : Math.max(0, Math.min(1, v));
+        if (c(traits.emotionality) > 0.6)
+            emphases.push('Preserve emotional context and sentiment shifts.');
+        if (c(traits.conscientiousness) > 0.6)
+            emphases.push('Preserve commitments, deadlines, and action items.');
+        if (c(traits.openness) > 0.6)
+            emphases.push('Preserve creative ideas and exploratory tangents.');
+        if (c(traits.agreeableness) > 0.6)
+            emphases.push('Preserve rapport cues and user preferences.');
+        if (c(traits.honesty) > 0.6)
+            emphases.push('Preserve corrections, retractions, and factual updates.');
+    }
+    const emphasisBlock = emphases.length > 0
+        ? `\n\nPersonality emphasis:\n${emphases.map((e) => `- ${e}`).join('\n')}`
+        : '';
+    return `You are a memory compressor. Your task is to compress a batch of observation notes into denser summary groups.
+
+Rules:
+1. Group related observations by topic overlap or entity overlap.
+2. For each group, produce ONE dense summary of 1-3 sentences that captures all key facts.
+3. Assign a priority: "critical" (security, safety, urgent deadlines), "important" (user preferences, key decisions, commitments), or "informational" (context, background, trivia).
+4. Include the IDs of all source observations in each group.
+5. Merge entity lists from all grouped observations.
+6. Target 3-10x compression while preserving ALL critical facts.
+
+Output a JSON array of objects, each with:
+{
+  "summary": "dense summary text",
+  "priority": "critical|important|informational",
+  "sourceIds": ["obs_id_1", "obs_id_2"],
+  "entities": ["entity1", "entity2"]
+}
+
+Output ONLY a valid JSON array. No markdown, no explanation.${emphasisBlock}`;
+}
+// ---------------------------------------------------------------------------
+// Counter for unique IDs
+// ---------------------------------------------------------------------------
+let compressedIdCounter = 0;
+// ---------------------------------------------------------------------------
+// ObservationCompressor
+// ---------------------------------------------------------------------------
+/**
+ * LLM-based compressor that takes a batch of {@link ObservationNote} objects
+ * and produces denser {@link CompressedObservation} summaries.
+ *
+ * Achieves 3-10x compression while preserving key facts, entities, and
+ * temporal context. Each compressed observation carries three-date temporal
+ * metadata: when the compression happened, the earliest referenced event,
+ * and a human-friendly relative time label.
+ */
+export class ObservationCompressor {
+    /**
+     * @param llmInvoker - Function that calls an LLM with (system, user) prompts.
+     * @param traits - Optional HEXACO personality traits for bias-aware compression.
+     */
+    constructor(llmInvoker, traits) {
+        this.llmInvoker = llmInvoker;
+        this.traits = traits;
+    }
+    /**
+     * Compress a batch of observation notes into denser summaries.
+     *
+     * The method:
+     * 1. Formats the notes as a numbered list for the LLM.
+     * 2. Sends the batch to the LLM with a compression prompt.
+     * 3. Parses the JSON array response into {@link CompressedObservation} objects.
+     * 4. Attaches three-date temporal metadata (observedAt, referencedAt, relativeLabel).
+     *
+     * @param notes - Batch of observation notes to compress.
+     * @returns Array of compressed observations. Returns empty array on LLM failure.
+     */
+    async compress(notes) {
+        if (notes.length === 0)
+            return [];
+        const systemPrompt = buildCompressorSystemPrompt(this.traits);
+        // Format notes as a numbered list with IDs, types, importance, and content.
+        const userPrompt = notes
+            .map((n) => `[${n.id}] (${n.type}, importance=${n.importance.toFixed(2)}, entities=[${n.entities.join(', ')}]) ${n.content}`)
+            .join('\n');
+        try {
+            const response = await this.llmInvoker(systemPrompt, userPrompt);
+            return this.parseCompressed(response, notes);
+        }
+        catch {
+            return [];
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal parsing
+    // -------------------------------------------------------------------------
+    /**
+     * Parse the LLM response into CompressedObservation objects.
+     *
+     * Tries to parse the response as a JSON array. Falls back to extracting
+     * individual JSON objects from lines if the array parse fails.
+     */
+    parseCompressed(llmResponse, sourceNotes) {
+        const now = Date.now();
+        const noteMap = new Map(sourceNotes.map((n) => [n.id, n]));
+        const results = [];
+        // Try parsing as a JSON array first.
+        let parsed;
+        try {
+            // Strip markdown fences if present.
+            const cleaned = llmResponse
+                .replace(/^```json\s*/i, '')
+                .replace(/```\s*$/, '')
+                .trim();
+            parsed = JSON.parse(cleaned);
+            if (!Array.isArray(parsed)) {
+                parsed = [parsed];
+            }
+        }
+        catch {
+            // Fallback: try parsing line by line.
+            parsed = [];
+            for (const line of llmResponse.split('\n')) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed === '[' || trimmed === ']')
+                    continue;
+                try {
+                    // Strip trailing comma for JSON-lines style.
+                    const clean = trimmed.endsWith(',') ? trimmed.slice(0, -1) : trimmed;
+                    parsed.push(JSON.parse(clean));
+                }
+                catch {
+                    // Skip malformed lines.
+                }
+            }
+        }
+        for (const item of parsed) {
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const obj = item;
+            if (typeof obj.summary !== 'string' || !obj.summary)
+                continue;
+            const sourceIds = Array.isArray(obj.sourceIds)
+                ? obj.sourceIds.filter((id) => typeof id === 'string')
+                : [];
+            const entities = Array.isArray(obj.entities)
+                ? obj.entities.filter((e) => typeof e === 'string')
+                : [];
+            const priority = (['critical', 'important', 'informational'].includes(obj.priority)
+                ? obj.priority
+                : 'informational');
+            // Compute temporal metadata from source notes.
+            const sourceTimes = sourceIds
+                .map((id) => noteMap.get(id)?.timestamp)
+                .filter((t) => t != null);
+            const earliestRef = sourceTimes.length > 0
+                ? Math.min(...sourceTimes)
+                : now;
+            // Compute average importance from source notes.
+            const sourceImportances = sourceIds
+                .map((id) => noteMap.get(id)?.importance)
+                .filter((i) => i != null);
+            const avgImportance = sourceImportances.length > 0
+                ? sourceImportances.reduce((a, b) => a + b, 0) / sourceImportances.length
+                : 0.5;
+            results.push({
+                id: `cobs_${Date.now()}_${++compressedIdCounter}`,
+                summary: obj.summary,
+                priority,
+                temporal: {
+                    observedAt: now,
+                    referencedAt: earliestRef,
+                    relativeLabel: relativeTimeLabel(earliestRef, now),
+                },
+                sourceIds,
+                entities,
+                importance: avgImportance,
+            });
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=ObservationCompressor.js.map

package/dist/memory/observation/ObservationCompressor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservationCompressor.js","sourceRoot":"","sources":["../../../src/memory/observation/ObservationCompressor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAqClD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;GAGG;AACH,SAAS,2BAA2B,CAAC,MAAqB;IACxD,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,GAAG,CAAC,CAAqB,EAAU,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QAC3F,IAAI,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,GAAG;YAAE,QAAQ,CAAC,IAAI,CAAC,kDAAkD,CAAC,CAAC;QACpG,IAAI,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,GAAG,GAAG;YAAE,QAAQ,CAAC,IAAI,CAAC,oDAAoD,CAAC,CAAC;QAC3G,IAAI,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,GAAG;YAAE,QAAQ,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;QACjG,IAAI,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,GAAG;YAAE,QAAQ,CAAC,IAAI,CAAC,6CAA6C,CAAC,CAAC;QAChG,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,GAAG;YAAE,QAAQ,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IACxG,CAAC;IAED,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC;QACvC,CAAC,CAAC,8BAA8B,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAC1E,CAAC,CAAC,EAAE,CAAC;IAEP,OAAO;;;;;;;;;;;;;;;;;;8DAkBqD,aAAa,EAAE,CAAC;AAC9E,CAAC;AAED,8EAA8E;AAC9E,yBAAyB;AACzB,8EAA8E;AAE9E,IAAI,mBAAmB,GAAG,CAAC,CAAC;AAE5B,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,OAAO,qBAAqB;IAChC;;;OAGG;IACH,YACU,UAA6D,EAC7D,MAAqB;QADrB,eAAU,GAAV,UAAU,CAAmD;QAC7D,WAAM,GAAN,MAAM,CAAe;IAC5B,CAAC;IAEJ;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,QAAQ,CAAC,KAAwB;QACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,EAAE,CAAC;QAElC,MAAM,YAAY,GAAG,2BAA2B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAE9D,4EAA4E;QAC5E,MAAM,UAAU,GAAG,KAAK;aACrB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CACT,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,gBAAgB,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CACjH;aACA,IAAI,CAAC,IAAI,CAAC,CAAC;QAEd,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;YACjE,OAAO,IAAI,CAAC,eAAe,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,4EAA4E;IAC5E,mBAAmB;IACnB,4EAA4E;IAE5E;;;;;OAKG;IACK,eAAe,CACrB,WAAmB,EACnB,WAA8B;QAE9B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3D,MAAM,OAAO,GAA4B,EAAE,CAAC;QAE5C,qCAAqC;QACrC,IAAI,MAAiB,CAAC;QACtB,IAAI,CAAC;YACH,oCAAoC;YACpC,MAAM,OAAO,GAAG,WAAW;iBACxB,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC;iBAC3B,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;iBACtB,IAAI,EAAE,CAAC;YACV,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC;YACpB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,sCAAsC;YACtC,MAAM,GAAG,EAAE,CAAC;YACZ,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;gBAC5B,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,GAAG;oBAAE,SAAS;gBAC7D,IAAI,CAAC;oBACH,6CAA6C;oBAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC;oBACrE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;gBACjC,CAAC;gBAAC,MAAM,CAAC;oBACP,wBAAwB;gBAC1B,CAAC;YACH,CAAC;QACH,CAAC;QAED,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC1B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;gBAAE,SAAS;YACxD,MAAM,GAAG,GAAG,IAA+B,CAAC;YAE5C,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,OAAO;gBAAE,SAAS;YAE9D,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;gBAC5C,CAAC,CAAE,GAAG,CAAC,SAAsB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC;gBACpE,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;gBAC1C,CAAC,CAAE,GAAG,CAAC,QAAqB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC;gBACjE,CAAC,CAAC,EAAE,CAAC;YAEP,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,EAAE,WAAW,EAAE,eAAe,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAkB,CAAC;gBAC3F,CAAC,CAAC,GAAG,CAAC,QAAQ;gBACd,CAAC,CAAC,eAAe,CAAwB,CAAC;YAE5C,+CAA+C;YAC/C,MAAM,WAAW,GAAG,SAAS;iBAC1B,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC;iBACvC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;YACzC,MAAM,WAAW,GAAG,WAAW,CAAC,MAAM,GAAG,CAAC;gBACxC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC;gBAC1B,CAAC,CAAC,GAAG,CAAC;YAER,gDAAgD;YAChD,MAAM,iBAAiB,GAAG,SAAS;iBAChC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,UAAU,CAAC;iBACxC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;YACzC,MAAM,aAAa,GAAG,iBAAiB,CAAC,MAAM,GAAG,CAAC;gBAChD,CAAC,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,GAAG,iBAAiB,CAAC,MAAM;gBACzE,CAAC,CAAC,GAAG,CAAC;YAER,OAAO,CAAC,IAAI,CAAC;gBACX,EAAE,EAAE,QAAQ,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,mBAAmB,EAAE;gBACjD,OAAO,EAAE,GAAG,CAAC,OAAO;gBACpB,QAAQ;gBACR,QAAQ,EAAE;oBACR,UAAU,EAAE,GAAG;oBACf,YAAY,EAAE,WAAW;oBACzB,aAAa,EAAE,iBAAiB,CAAC,WAAW,EAAE,GAAG,CAAC;iBACnD;gBACD,SAAS;gBACT,QAAQ;gBACR,UAAU,EAAE,aAAa;aAC1B,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/memory/observation/ObservationReflector.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Higher-level reflector that condenses compressed observations
+ * into reflections — long-lived insights about user patterns, preferences,
+ * capabilities, relationships, and goals.
+ *
+ * This is the "Reflector" agent in Mastra's agentic memory model. It runs
+ * when compressed observations exceed a configurable token threshold
+ * (default: 40,000 tokens) and extracts higher-level patterns that transcend
+ * individual conversation turns.
+ *
+ * Each {@link Reflection} carries a pattern type classifier, confidence score,
+ * source provenance, and temporal span metadata.
+ *
+ * @module agentos/memory/observation/ObservationReflector
+ */
+import type { CompressedObservation } from './ObservationCompressor.js';
+/** The kind of pattern identified by the reflector. */
+export type ReflectionPatternType = 'preference' | 'behavior' | 'capability' | 'relationship' | 'goal';
+/**
+ * A high-level insight derived from multiple compressed observations.
+ * Reflections are the highest tier in the observation hierarchy:
+ *   raw notes → compressed observations → reflections.
+ */
+export interface Reflection {
+    /** Unique identifier for this reflection. */
+    id: string;
+    /** High-level insight text (1-3 sentences). */
+    insight: string;
+    /** Pattern type classifier. */
+    patternType: ReflectionPatternType;
+    /** Confidence in this reflection (0-1). */
+    confidence: number;
+    /** IDs of the source compressed observations. */
+    sourceIds: string[];
+    /** Temporal span covered by this reflection. */
+    temporal: {
+        /** When this reflection was produced (Unix ms). */
+        reflectedAt: number;
+        /** Earliest source timestamp in the compressed observations (Unix ms). */
+        spanStart: number;
+        /** Latest source timestamp in the compressed observations (Unix ms). */
+        spanEnd: number;
+        /** Human-friendly label for the temporal span. */
+        relativeLabel: string;
+    };
+}
+/**
+ * Condenses compressed observations into higher-level reflections.
+ *
+ * Runs when accumulated compressed observations exceed 40,000 tokens
+ * (configurable). Each reflection captures a long-lived pattern such as
+ * a user preference, behavioral habit, capability, relationship dynamic,
+ * or goal.
+ */
+export declare class ObservationReflector {
+    private llmInvoker;
+    /**
+     * @param llmInvoker - Function that calls an LLM with (system, user) prompts.
+     */
+    constructor(llmInvoker: (system: string, user: string) => Promise<string>);
+    /**
+     * Reflect on compressed observations to extract higher-level patterns.
+     *
+     * @param observations - Compressed observations to reflect on.
+     * @returns Array of reflections. Returns empty array on LLM failure.
+     */
+    reflect(observations: CompressedObservation[]): Promise<Reflection[]>;
+    /**
+     * Parse the LLM response into Reflection objects.
+     */
+    private parseReflections;
+    /**
+     * Build a human-friendly label describing a temporal span.
+     *
+     * @param start - Earliest timestamp in the span (Unix ms).
+     * @param end - Latest timestamp in the span (Unix ms).
+     * @param now - Current reference time (Unix ms).
+     * @returns Label such as "over the past week" or "over the past 3 days".
+     */
+    private buildSpanLabel;
+}
+//# sourceMappingURL=ObservationReflector.d.ts.map

package/dist/memory/observation/ObservationReflector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ObservationReflector.d.ts","sourceRoot":"","sources":["../../../src/memory/observation/ObservationReflector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAOxE,uDAAuD;AACvD,MAAM,MAAM,qBAAqB,GAC7B,YAAY,GACZ,UAAU,GACV,YAAY,GACZ,cAAc,GACd,MAAM,CAAC;AAEX;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,WAAW,EAAE,qBAAqB,CAAC;IACnC,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,iDAAiD;IACjD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE;QACR,mDAAmD;QACnD,WAAW,EAAE,MAAM,CAAC;QACpB,0EAA0E;QAC1E,SAAS,EAAE,MAAM,CAAC;QAClB,wEAAwE;QACxE,OAAO,EAAE,MAAM,CAAC;QAChB,kDAAkD;QAClD,aAAa,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAsCD;;;;;;;GAOG;AACH,qBAAa,oBAAoB;IAK7B,OAAO,CAAC,UAAU;IAJpB;;OAEG;gBAEO,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC;IAGvE;;;;;OAKG;IACG,OAAO,CAAC,YAAY,EAAE,qBAAqB,EAAE,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAwB3E;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAgGxB;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;CA2BvB"}