@framers/agentos 0.1.111 → 0.1.113

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"}

package/dist/memory/observation/ObservationReflector.js

@@ -0,0 +1,212 @@
+/**
+ * @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 { relativeTimeLabel } from './temporal.js';
+// ---------------------------------------------------------------------------
+// System prompt
+// ---------------------------------------------------------------------------
+function buildReflectorSystemPrompt() {
+    return `You are a memory reflector. Your task is to analyze compressed observation summaries and extract higher-level patterns and insights.
+
+Rules:
+1. Look for recurring themes, preferences, behavioral patterns, capabilities, relationships, and goals.
+2. Each reflection should be a high-level insight that transcends individual observations (1-3 sentences).
+3. Assign a pattern type: "preference" (likes/dislikes, style choices), "behavior" (recurring actions, habits), "capability" (skills, knowledge domains), "relationship" (interpersonal dynamics), or "goal" (objectives, intentions, aspirations).
+4. Assign a confidence score 0.0-1.0 (how confident are you in this pattern?).
+5. Include the IDs of the compressed observations that support each reflection.
+6. Aim for high-value insights that would be useful for future interactions.
+
+Output a JSON array of objects:
+{
+  "insight": "high-level insight text",
+  "patternType": "preference|behavior|capability|relationship|goal",
+  "confidence": 0.0-1.0,
+  "sourceIds": ["cobs_id_1", "cobs_id_2"]
+}
+
+Output ONLY a valid JSON array. No markdown, no explanation.`;
+}
+// ---------------------------------------------------------------------------
+// Counter for unique IDs
+// ---------------------------------------------------------------------------
+let reflectionIdCounter = 0;
+// ---------------------------------------------------------------------------
+// ObservationReflector
+// ---------------------------------------------------------------------------
+/**
+ * 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 class ObservationReflector {
+    /**
+     * @param llmInvoker - Function that calls an LLM with (system, user) prompts.
+     */
+    constructor(llmInvoker) {
+        this.llmInvoker = llmInvoker;
+    }
+    /**
+     * 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.
+     */
+    async reflect(observations) {
+        if (observations.length === 0)
+            return [];
+        const systemPrompt = buildReflectorSystemPrompt();
+        // Format compressed observations for the LLM.
+        const userPrompt = observations
+            .map((o) => `[${o.id}] (priority=${o.priority}, importance=${o.importance.toFixed(2)}, ref=${o.temporal.relativeLabel}) ${o.summary}`)
+            .join('\n');
+        try {
+            const response = await this.llmInvoker(systemPrompt, userPrompt);
+            return this.parseReflections(response, observations);
+        }
+        catch {
+            return [];
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Internal parsing
+    // -------------------------------------------------------------------------
+    /**
+     * Parse the LLM response into Reflection objects.
+     */
+    parseReflections(llmResponse, sourceObservations) {
+        const now = Date.now();
+        const obsMap = new Map(sourceObservations.map((o) => [o.id, o]));
+        const results = [];
+        // Try parsing as a JSON array first.
+        let parsed;
+        try {
+            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 {
+                    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.insight !== 'string' || !obj.insight)
+                continue;
+            const validPatternTypes = [
+                'preference', 'behavior', 'capability', 'relationship', 'goal',
+            ];
+            const patternType = validPatternTypes.includes(obj.patternType)
+                ? obj.patternType
+                : 'behavior';
+            const confidence = typeof obj.confidence === 'number'
+                ? Math.max(0, Math.min(1, obj.confidence))
+                : 0.5;
+            const sourceIds = Array.isArray(obj.sourceIds)
+                ? obj.sourceIds.filter((id) => typeof id === 'string')
+                : [];
+            // Compute temporal span from source compressed observations.
+            const sourceTimes = [];
+            for (const id of sourceIds) {
+                const obs = obsMap.get(id);
+                if (obs) {
+                    sourceTimes.push(obs.temporal.referencedAt);
+                    sourceTimes.push(obs.temporal.observedAt);
+                }
+            }
+            // Fallback: use all observations if no specific sources matched.
+            if (sourceTimes.length === 0) {
+                for (const obs of sourceObservations) {
+                    sourceTimes.push(obs.temporal.referencedAt);
+                    sourceTimes.push(obs.temporal.observedAt);
+                }
+            }
+            const spanStart = sourceTimes.length > 0 ? Math.min(...sourceTimes) : now;
+            const spanEnd = sourceTimes.length > 0 ? Math.max(...sourceTimes) : now;
+            // Build a human-friendly span label.
+            const spanLabel = this.buildSpanLabel(spanStart, spanEnd, now);
+            results.push({
+                id: `refl_${Date.now()}_${++reflectionIdCounter}`,
+                insight: obj.insight,
+                patternType,
+                confidence,
+                sourceIds,
+                temporal: {
+                    reflectedAt: now,
+                    spanStart,
+                    spanEnd,
+                    relativeLabel: spanLabel,
+                },
+            });
+        }
+        return results;
+    }
+    /**
+     * 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".
+     */
+    buildSpanLabel(start, end, now) {
+        const spanMs = end - start;
+        const ageMs = now - start;
+        const DAY = 24 * 60 * 60 * 1000;
+        const WEEK = 7 * DAY;
+        // If the span is very short (< 1 day), use the relative label for start.
+        if (spanMs < DAY) {
+            return relativeTimeLabel(start, now);
+        }
+        const ageDays = Math.floor(ageMs / DAY);
+        if (ageDays <= 1)
+            return 'over the past day';
+        if (ageDays <= 7)
+            return `over the past ${ageDays} days`;
+        if (ageDays <= 14)
+            return 'over the past week';
+        const ageWeeks = Math.floor(ageMs / WEEK);
+        if (ageWeeks <= 4)
+            return `over the past ${ageWeeks} weeks`;
+        const ageMonths = Math.floor(ageDays / 30);
+        if (ageMonths <= 1)
+            return 'over the past month';
+        if (ageMonths <= 12)
+            return `over the past ${ageMonths} months`;
+        return `over the past ${Math.floor(ageDays / 365)} years`;
+    }
+}
+//# sourceMappingURL=ObservationReflector.js.map

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

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

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

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview Temporal reasoning utilities for the observation system.
+ *
+ * Provides a three-date model (observedAt, referencedAt, relativeLabel) and a
+ * human-friendly `relativeTimeLabel()` function that converts Unix-ms timestamps
+ * into natural-language labels such as "just now", "earlier today", "last Tuesday",
+ * "3 days ago", "last week", etc.
+ *
+ * @module agentos/memory/observation/temporal
+ */
+/**
+ * Three-date temporal model attached to memory traces.
+ *
+ * - `referencedAt` — when the event the memory refers to actually occurred.
+ * - `relativeLabel` — human-friendly relative time description.
+ * - `span` — optional time range if the memory covers a period.
+ */
+export interface TemporalMetadata {
+    /** When the event this memory refers to actually happened (Unix ms). */
+    referencedAt?: number;
+    /** Human-friendly relative time label, e.g. "last Tuesday". */
+    relativeLabel?: string;
+    /** Time span if this covers a period: [startMs, endMs]. */
+    span?: [number, number];
+}
+/**
+ * Produce a human-friendly label describing how long ago `timestamp` was
+ * relative to `now` (defaults to `Date.now()`).
+ *
+ * Examples:
+ * - "just now"       (< 60 s)
+ * - "5 minutes ago"  (< 1 h)
+ * - "2 hours ago"    (< today boundary, but > 1 h)
+ * - "earlier today"  (same calendar day, > 1 h)
+ * - "yesterday"      (previous calendar day)
+ * - "last Tuesday"   (2-6 days ago, uses day name)
+ * - "3 days ago"     (2-6 days ago, alternative when day name would be confusing)
+ * - "last week"      (7-13 days)
+ * - "2 weeks ago"    (14-20 days)
+ * - "3 weeks ago"    (21-27 days)
+ * - "last month"     (28-59 days)
+ * - "2 months ago"   (60-89 days)
+ * - "N months ago"   (90-364 days)
+ * - "last year"      (365-729 days)
+ * - "N years ago"    (730+ days)
+ *
+ * Future timestamps return "in the future".
+ *
+ * @param timestamp - Unix ms timestamp to describe.
+ * @param now - Reference timestamp (defaults to Date.now()).
+ * @returns Human-friendly relative time string.
+ */
+export declare function relativeTimeLabel(timestamp: number, now?: number): string;
+//# sourceMappingURL=temporal.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"temporal.d.ts","sourceRoot":"","sources":["../../../src/memory/observation/temporal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2DAA2D;IAC3D,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzB;AAeD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CA8EzE"}

package/dist/memory/observation/temporal.js

@@ -0,0 +1,115 @@
+/**
+ * @fileoverview Temporal reasoning utilities for the observation system.
+ *
+ * Provides a three-date model (observedAt, referencedAt, relativeLabel) and a
+ * human-friendly `relativeTimeLabel()` function that converts Unix-ms timestamps
+ * into natural-language labels such as "just now", "earlier today", "last Tuesday",
+ * "3 days ago", "last week", etc.
+ *
+ * @module agentos/memory/observation/temporal
+ */
+// ---------------------------------------------------------------------------
+// Day-of-week names
+// ---------------------------------------------------------------------------
+const DAY_NAMES = [
+    'Sunday', 'Monday', 'Tuesday', 'Wednesday',
+    'Thursday', 'Friday', 'Saturday',
+];
+// ---------------------------------------------------------------------------
+// relativeTimeLabel
+// ---------------------------------------------------------------------------
+/**
+ * Produce a human-friendly label describing how long ago `timestamp` was
+ * relative to `now` (defaults to `Date.now()`).
+ *
+ * Examples:
+ * - "just now"       (< 60 s)
+ * - "5 minutes ago"  (< 1 h)
+ * - "2 hours ago"    (< today boundary, but > 1 h)
+ * - "earlier today"  (same calendar day, > 1 h)
+ * - "yesterday"      (previous calendar day)
+ * - "last Tuesday"   (2-6 days ago, uses day name)
+ * - "3 days ago"     (2-6 days ago, alternative when day name would be confusing)
+ * - "last week"      (7-13 days)
+ * - "2 weeks ago"    (14-20 days)
+ * - "3 weeks ago"    (21-27 days)
+ * - "last month"     (28-59 days)
+ * - "2 months ago"   (60-89 days)
+ * - "N months ago"   (90-364 days)
+ * - "last year"      (365-729 days)
+ * - "N years ago"    (730+ days)
+ *
+ * Future timestamps return "in the future".
+ *
+ * @param timestamp - Unix ms timestamp to describe.
+ * @param now - Reference timestamp (defaults to Date.now()).
+ * @returns Human-friendly relative time string.
+ */
+export function relativeTimeLabel(timestamp, now) {
+    const reference = now ?? Date.now();
+    const diffMs = reference - timestamp;
+    // Future timestamps
+    if (diffMs < 0)
+        return 'in the future';
+    const SECOND = 1000;
+    const MINUTE = 60 * SECOND;
+    const HOUR = 60 * MINUTE;
+    const DAY = 24 * HOUR;
+    // Just now (< 60 seconds)
+    if (diffMs < MINUTE)
+        return 'just now';
+    // Minutes ago (< 1 hour)
+    if (diffMs < HOUR) {
+        const mins = Math.floor(diffMs / MINUTE);
+        return mins === 1 ? '1 minute ago' : `${mins} minutes ago`;
+    }
+    // Check calendar-day boundaries for "earlier today" / "yesterday"
+    const nowDate = new Date(reference);
+    const tsDate = new Date(timestamp);
+    const isSameDay = nowDate.getFullYear() === tsDate.getFullYear() &&
+        nowDate.getMonth() === tsDate.getMonth() &&
+        nowDate.getDate() === tsDate.getDate();
+    if (isSameDay) {
+        const hours = Math.floor(diffMs / HOUR);
+        if (hours < 2)
+            return '1 hour ago';
+        return 'earlier today';
+    }
+    // Yesterday check (previous calendar day)
+    const yesterday = new Date(reference);
+    yesterday.setDate(yesterday.getDate() - 1);
+    const isYesterday = yesterday.getFullYear() === tsDate.getFullYear() &&
+        yesterday.getMonth() === tsDate.getMonth() &&
+        yesterday.getDate() === tsDate.getDate();
+    if (isYesterday)
+        return 'yesterday';
+    const diffDays = Math.floor(diffMs / DAY);
+    // 2-6 days ago — use day name ("last Tuesday")
+    if (diffDays >= 2 && diffDays <= 6) {
+        const dayName = DAY_NAMES[tsDate.getDay()];
+        return `last ${dayName}`;
+    }
+    // 7-13 days — "last week"
+    if (diffDays >= 7 && diffDays <= 13)
+        return 'last week';
+    // 14-27 days — "N weeks ago"
+    if (diffDays >= 14 && diffDays <= 27) {
+        const weeks = Math.floor(diffDays / 7);
+        return `${weeks} weeks ago`;
+    }
+    // 28-59 days — "last month"
+    if (diffDays >= 28 && diffDays <= 59)
+        return 'last month';
+    // 60-364 days — "N months ago"
+    if (diffDays >= 60 && diffDays <= 364) {
+        const months = Math.floor(diffDays / 30);
+        return months === 1 ? '1 month ago' : `${months} months ago`;
+    }
+    // 365-729 days — "last year"
+    if (diffDays >= 365 && diffDays <= 729)
+        return 'last year';
+    // 730+ days — "N years ago"
+    const years = Math.floor(diffDays / 365);
+    return `${years} years ago`;
+}
+//# sourceMappingURL=temporal.js.map

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

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