@framers/agentos 0.1.112 → 0.1.114

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

package/dist/memory/tools/MemoryAddTool.d.ts

@@ -90,9 +90,9 @@ export declare class MemoryAddTool implements ITool<MemoryAddInput, MemoryAddOut
      * EmbeddingEncoder will embed it asynchronously.
      *
      * @param args    - Memory add input (content, optional type/scope/tags).
-     * @param _context - Tool execution context (not used by this tool).
+     * @param context - Tool execution context used to resolve the scope ID.
      * @returns `{ traceId }` on success, or an error result.
      */
-    execute(args: MemoryAddInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemoryAddOutput>>;
+    execute(args: MemoryAddInput, context: ToolExecutionContext): Promise<ToolExecutionResult<MemoryAddOutput>>;
 }
 //# sourceMappingURL=MemoryAddTool.d.ts.map

package/dist/memory/tools/MemoryAddTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoryAddTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryAddTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAc3D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,KAAK,CAAC,cAAc,EAAE,eAAe,CAAC;IA2D9D,OAAO,CAAC,QAAQ,CAAC,KAAK;IA1DlC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,mBAAmB;IAE9B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,gBAAgB;IAEpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,6GACwF;IAE5G,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,QAAQ;IAE/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAwBpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CACX,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC;CA0CjD"}
+{"version":3,"file":"MemoryAddTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemoryAddTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAe3D;;;;;;;GAOG;AACH,MAAM,WAAW,cAAe,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;CACjB;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,KAAK,CAAC,cAAc,EAAE,eAAe,CAAC;IA2D9D,OAAO,CAAC,QAAQ,CAAC,KAAK;IA1DlC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,mBAAmB;IAE9B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,gBAAgB;IAE7B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,gBAAgB;IAEpC;;;OAGG;IACH,QAAQ,CAAC,WAAW,6GACwF;IAE5G,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B;;;OAGG;IACH,QAAQ,CAAC,cAAc,QAAQ;IAE/B;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAwBpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;OAeG;IACG,OAAO,CACX,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,eAAe,CAAC,CAAC;CAiDjD"}

package/dist/memory/tools/MemoryAddTool.js

@@ -11,6 +11,7 @@
  * @module memory/tools/MemoryAddTool
  */
 import { buildInitialTraceMetadata, sha256Hex } from '../store/tracePersistence.js';
+import { resolveMemoryToolScopeId } from './scopeContext.js';
 // ---------------------------------------------------------------------------
 // Counter for unique ID generation within the process lifetime
 // ---------------------------------------------------------------------------
@@ -103,17 +104,21 @@ export class MemoryAddTool {
      * EmbeddingEncoder will embed it asynchronously.
      *
      * @param args    - Memory add input (content, optional type/scope/tags).
-     * @param _context - Tool execution context (not used by this tool).
+     * @param context - Tool execution context used to resolve the scope ID.
      * @returns `{ traceId }` on success, or an error result.
      */
-    async execute(args, _context) {
+    async execute(args, context) {
         try {
             const now = Date.now();
             const traceId = `mt_${now}_${_idCounter++}`;
             const type = args.type ?? 'episodic';
             const scope = args.scope ?? 'user';
+            const scopeId = resolveMemoryToolScopeId(scope, context);
             const tags = JSON.stringify(args.tags ?? []);
-            const metadata = JSON.stringify(buildInitialTraceMetadata({}, { contentHash: sha256Hex(args.content) }));
+            const metadata = JSON.stringify(buildInitialTraceMetadata({}, {
+                contentHash: sha256Hex(args.content),
+                ...(scopeId ? { scopeId } : {}),
+            }));
             this.brain.db.transaction(() => {
                 this.brain.db
                     .prepare(`INSERT INTO memory_traces

package/dist/memory/tools/MemoryAddTool.js.map

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

package/dist/memory/tools/MemorySearchTool.d.ts

@@ -108,10 +108,10 @@ export declare class MemorySearchTool implements ITool<MemorySearchInput, Memory
      * Tags are stored as JSON arrays; they are parsed and returned as string[].
      * Malformed tag JSON returns an empty array rather than throwing.
      *
-     * @param args     - Search input (query, optional type/scope/limit).
-     * @param _context - Tool execution context (not used by this tool).
+     * @param args    - Search input (query, optional type/scope/limit).
+     * @param context - Tool execution context used to resolve scoped searches.
      * @returns `{ results }` array on success, or an error result.
      */
-    execute(args: MemorySearchInput, _context: ToolExecutionContext): Promise<ToolExecutionResult<MemorySearchOutput>>;
+    execute(args: MemorySearchInput, context: ToolExecutionContext): Promise<ToolExecutionResult<MemorySearchOutput>>;
 }
 //# sourceMappingURL=MemorySearchTool.d.ts.map

package/dist/memory/tools/MemorySearchTool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemorySearchTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemorySearchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAqB3D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,YAAW,KAAK,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAsDvE,OAAO,CAAC,QAAQ,CAAC,KAAK;IArDlC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,sBAAsB;IAEjC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,mBAAmB;IAEvC,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,SAGuF;IAE3G,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,SAAS;IAEhC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CA0BpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAqFpD"}
+{"version":3,"file":"MemorySearchTool.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/MemorySearchTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EACV,KAAK,EACL,mBAAmB,EACnB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAsB3D;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAkB,SAAQ,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAMD;;;;;;;;;;;;GAYG;AACH,qBAAa,gBAAiB,YAAW,KAAK,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;IAsDvE,OAAO,CAAC,QAAQ,CAAC,KAAK;IArDlC,uCAAuC;IACvC,QAAQ,CAAC,EAAE,sBAAsB;IAEjC,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,mBAAmB;IAEhC,mCAAmC;IACnC,QAAQ,CAAC,WAAW,mBAAmB;IAEvC,8BAA8B;IAC9B,QAAQ,CAAC,WAAW,SAGuF;IAE3G,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,YAAY;IAE7B,gEAAgE;IAChE,QAAQ,CAAC,cAAc,SAAS;IAEhC,uEAAuE;IACvE,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CA0BpC;IAEF;;OAEG;gBAC0B,KAAK,EAAE,WAAW;IAM/C;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CACX,IAAI,EAAE,iBAAiB,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,kBAAkB,CAAC,CAAC;CAoFpD"}

package/dist/memory/tools/MemorySearchTool.js

@@ -13,6 +13,7 @@
  * @module memory/tools/MemorySearchTool
  */
 import { buildNaturalLanguageFtsQuery } from '../store/tracePersistence.js';
+import { resolveMemoryToolScopeId } from './scopeContext.js';
 // ---------------------------------------------------------------------------
 // MemorySearchTool
 // ---------------------------------------------------------------------------
@@ -100,11 +101,11 @@ export class MemorySearchTool {
      * Tags are stored as JSON arrays; they are parsed and returned as string[].
      * Malformed tag JSON returns an empty array rather than throwing.
      *
-     * @param args     - Search input (query, optional type/scope/limit).
-     * @param _context - Tool execution context (not used by this tool).
+     * @param args    - Search input (query, optional type/scope/limit).
+     * @param context - Tool execution context used to resolve scoped searches.
      * @returns `{ results }` array on success, or an error result.
      */
-    async execute(args, _context) {
+    async execute(args, context) {
         try {
             const rawQuery = args.query.trim();
             if (!rawQuery) {
@@ -121,6 +122,11 @@ export class MemorySearchTool {
             if (args.scope !== undefined) {
                 extraClauses.push('mt.scope = ?');
                 extraParams.push(args.scope);
+                const scopeId = resolveMemoryToolScopeId(args.scope, context);
+                if (scopeId) {
+                    extraClauses.push(`json_extract(mt.metadata, '$.scopeId') = ?`);
+                    extraParams.push(scopeId);
+                }
             }
             const extraWhere = extraClauses.length > 0 ? `AND ${extraClauses.join(' AND ')}` : '';
             const sql = `
@@ -135,9 +141,7 @@ export class MemorySearchTool {
       `;
             const runSearch = (query) => {
                 const params = [query, ...extraParams, limit];
-                return this.brain.db
-                    .prepare(sql)
-                    .all(...params);
+                return this.brain.db.prepare(sql).all(...params);
             };
             let rows;
             try {
@@ -145,9 +149,7 @@ export class MemorySearchTool {
             }
             catch (error) {
                 const fallbackQuery = buildNaturalLanguageFtsQuery(rawQuery);
-                if (error?.code !== 'SQLITE_ERROR' ||
-                    !fallbackQuery ||
-                    fallbackQuery === rawQuery) {
+                if (error?.code !== 'SQLITE_ERROR' || !fallbackQuery || fallbackQuery === rawQuery) {
                     throw error;
                 }
                 rows = runSearch(fallbackQuery);

package/dist/memory/tools/MemorySearchTool.js.map

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

package/dist/memory/tools/scopeContext.d.ts

@@ -0,0 +1,11 @@
+import type { ToolExecutionContext } from '../../core/tools/ITool.js';
+/**
+ * Resolve the effective scope identity for a memory tool call from the active
+ * execution context.
+ *
+ * `user` and `persona` scopes are always resolvable in normal AgentOS tool
+ * execution because `userContext.userId` and `personaId` are required.
+ * `thread` and `organization` additionally rely on optional `sessionData`.
+ */
+export declare function resolveMemoryToolScopeId(scope: string | undefined, context: ToolExecutionContext): string | undefined;
+//# sourceMappingURL=scopeContext.d.ts.map

package/dist/memory/tools/scopeContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeContext.d.ts","sourceRoot":"","sources":["../../../src/memory/tools/scopeContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAetE;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,OAAO,EAAE,oBAAoB,GAC5B,MAAM,GAAG,SAAS,CA8BpB"}

package/dist/memory/tools/scopeContext.js

@@ -0,0 +1,46 @@
+function nonEmptyString(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed || undefined;
+}
+function buildPersonaScopeId(userId, personaId) {
+    return `${userId}::${personaId}`;
+}
+/**
+ * Resolve the effective scope identity for a memory tool call from the active
+ * execution context.
+ *
+ * `user` and `persona` scopes are always resolvable in normal AgentOS tool
+ * execution because `userContext.userId` and `personaId` are required.
+ * `thread` and `organization` additionally rely on optional `sessionData`.
+ */
+export function resolveMemoryToolScopeId(scope, context) {
+    const resolvedScope = nonEmptyString(scope);
+    if (!resolvedScope) {
+        return undefined;
+    }
+    const userId = nonEmptyString(context.userContext?.userId);
+    const personaId = nonEmptyString(context.personaId);
+    const conversationId = nonEmptyString(context.sessionData?.conversationId) ??
+        nonEmptyString(context.sessionData?.sessionId);
+    const organizationId = nonEmptyString(context.sessionData?.organizationId) ??
+        nonEmptyString(context.userContext?.organizationId);
+    switch (resolvedScope) {
+        case 'user':
+            return userId;
+        case 'persona':
+            if (!userId || !personaId) {
+                return undefined;
+            }
+            return buildPersonaScopeId(userId, personaId);
+        case 'thread':
+            return conversationId;
+        case 'organization':
+            return organizationId;
+        default:
+            return undefined;
+    }
+}
+//# sourceMappingURL=scopeContext.js.map

package/dist/memory/tools/scopeContext.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scopeContext.js","sourceRoot":"","sources":["../../../src/memory/tools/scopeContext.ts"],"names":[],"mappings":"AAEA,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,IAAI,SAAS,CAAC;AAC9B,CAAC;AAED,SAAS,mBAAmB,CAAC,MAAc,EAAE,SAAiB;IAC5D,OAAO,GAAG,MAAM,KAAK,SAAS,EAAE,CAAC;AACnC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAyB,EACzB,OAA6B;IAE7B,MAAM,aAAa,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,MAAM,GAAG,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3D,MAAM,SAAS,GAAG,cAAc,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACpD,MAAM,cAAc,GAClB,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC;QACnD,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,cAAc,GAClB,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC;QACnD,cAAc,CAAC,OAAO,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;IAEtD,QAAQ,aAAa,EAAE,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,MAAM,CAAC;QAChB,KAAK,SAAS;YACZ,IAAI,CAAC,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC1B,OAAO,SAAS,CAAC;YACnB,CAAC;YACD,OAAO,mBAAmB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAChD,KAAK,QAAQ;YACX,OAAO,cAAc,CAAC;QACxB,KAAK,cAAc;YACjB,OAAO,cAAc,CAAC;QACxB;YACE,OAAO,SAAS,CAAC;IACrB,CAAC;AACH,CAAC"}