@framers/agentos 0.1.46 → 0.1.48

package/dist/memory/index.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Barrel exports for the Cognitive Memory System.
+ * @module agentos/memory
+ */
+export { DEFAULT_ENCODING_CONFIG, DEFAULT_DECAY_CONFIG, DEFAULT_BUDGET_ALLOCATION, } from './config.js';
+// --- Encoding ---
+export { computeEncodingWeights, computeEncodingStrength, computeAttentionMultiplier, yerksDodson, moodCongruenceBoost, isFlashbulbMemory, buildEmotionalContext, } from './encoding/EncodingModel.js';
+export { createFeatureDetector, KeywordFeatureDetector, LlmFeatureDetector, HybridFeatureDetector, } from './encoding/ContentFeatureDetector.js';
+// --- Decay ---
+export { computeCurrentStrength, updateOnRetrieval, computeInterference, findPrunableTraces, } from './decay/DecayModel.js';
+export { scoreAndRankTraces, detectPartiallyRetrieved, computeRecencyBoost, computeEmotionalCongruence, DEFAULT_SCORING_WEIGHTS, } from './decay/RetrievalPriorityScorer.js';
+// --- Working Memory ---
+export { CognitiveWorkingMemory } from './working/CognitiveWorkingMemory.js';
+// --- Store ---
+export { MemoryStore } from './store/MemoryStore.js';
+// --- Prompt Assembly ---
+export { assembleMemoryContext } from './prompt/MemoryPromptAssembler.js';
+export { formatMemoryTrace, formatMemoryTraces } from './prompt/MemoryFormatters.js';
+// --- Orchestrator ---
+export { CognitiveMemoryManager } from './CognitiveMemoryManager.js';
+// --- Extension ---
+export { createCognitiveMemoryDescriptor } from './extension/CognitiveMemoryExtension.js';
+export { GraphologyMemoryGraph } from './graph/GraphologyMemoryGraph.js';
+export { KnowledgeGraphMemoryGraph } from './graph/KnowledgeGraphMemoryGraph.js';
+export { spreadActivation } from './graph/SpreadingActivation.js';
+// --- Observation System (Batch 2) ---
+export { ObservationBuffer } from './observation/ObservationBuffer.js';
+export { MemoryObserver } from './observation/MemoryObserver.js';
+export { MemoryReflector } from './observation/MemoryReflector.js';
+// --- Prospective Memory (Batch 2) ---
+export { ProspectiveMemoryManager } from './prospective/ProspectiveMemoryManager.js';
+// --- Consolidation Pipeline (Batch 2) ---
+export { ConsolidationPipeline } from './consolidation/ConsolidationPipeline.js';
+// --- Infinite Context Window (Batch 3) ---
+export { ContextWindowManager } from './context/ContextWindowManager.js';
+export { CompactionEngine } from './context/CompactionEngine.js';
+export { CompactionLog } from './context/CompactionLog.js';
+export { RollingSummaryChain } from './context/RollingSummaryChain.js';
+export { SlidingSummaryStrategy } from './context/strategies/SlidingSummaryStrategy.js';
+export { HierarchicalStrategy } from './context/strategies/HierarchicalStrategy.js';
+export { HybridStrategy } from './context/strategies/HybridStrategy.js';
+export { DEFAULT_INFINITE_CONTEXT_CONFIG } from './context/types.js';
+//# sourceMappingURL=index.js.map

package/dist/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/memory/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAoCH,OAAO,EACL,uBAAuB,EACvB,oBAAoB,EACpB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAErB,mBAAmB;AACnB,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,0BAA0B,EAC1B,WAAW,EACX,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,sCAAsC,CAAC;AAG9C,gBAAgB;AAChB,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,wBAAwB,EACxB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,GACxB,MAAM,oCAAoC,CAAC;AAG5C,yBAAyB;AACzB,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAG7E,gBAAgB;AAChB,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAGrD,0BAA0B;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAE1E,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGrF,uBAAuB;AACvB,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAGrE,oBAAoB;AACpB,OAAO,EAAE,+BAA+B,EAAE,MAAM,yCAAyC,CAAC;AAY1F,OAAO,EAAE,qBAAqB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,EAAE,yBAAyB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGlE,uCAAuC;AACvC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAEvE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAGnE,uCAAuC;AACvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2CAA2C,CAAC;AAGrF,2CAA2C;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAGjF,4CAA4C;AAC5C,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,gDAAgD,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8CAA8C,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAYxE,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC"}

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

@@ -0,0 +1,59 @@
+/**
+ * @fileoverview Memory Observer — personality-biased background note extraction.
+ *
+ * Monitors accumulated conversation tokens via ObservationBuffer.
+ * When the threshold is reached, extracts concise observation notes
+ * via a persona-configured LLM (defaults to cheap model).
+ *
+ * Personality bias:
+ * - High emotionality → notes emotional shifts
+ * - High conscientiousness → notes commitments/deadlines
+ * - High openness → notes creative tangents
+ * - High agreeableness → notes user preferences and rapport cues
+ * - High honesty → notes corrections and retractions
+ *
+ * @module agentos/memory/observation/MemoryObserver
+ */
+import type { HexacoTraits, PADState, ObserverConfig } from '../config.js';
+import { ObservationBuffer, type BufferedMessage } from './ObservationBuffer.js';
+export interface ObservationNote {
+    id: string;
+    /** Category of observation. */
+    type: 'factual' | 'emotional' | 'commitment' | 'preference' | 'creative' | 'correction';
+    /** Short summary of the observation. */
+    content: string;
+    /** 0-1 importance score. */
+    importance: number;
+    /** Entities mentioned. */
+    entities: string[];
+    /** Emotional context at observation time. */
+    emotionalContext?: {
+        valence: number;
+        arousal: number;
+    };
+    timestamp: number;
+}
+export declare class MemoryObserver {
+    private buffer;
+    private traits;
+    private llmInvoker?;
+    private config;
+    constructor(traits: HexacoTraits, config?: Partial<ObserverConfig>);
+    /**
+     * Feed a message into the observation buffer.
+     * Returns observation notes if the buffer has reached activation threshold.
+     */
+    observe(role: BufferedMessage['role'], content: string, mood?: PADState): Promise<ObservationNote[] | null>;
+    /**
+     * Force extraction of observation notes from buffered messages.
+     */
+    extractNotes(mood?: PADState): Promise<ObservationNote[]>;
+    /** Get the underlying buffer for inspection. */
+    getBuffer(): ObservationBuffer;
+    /** Check if observation should be triggered. */
+    shouldActivate(): boolean;
+    /** Reset the observer. */
+    clear(): void;
+    private parseNotes;
+}
+//# sourceMappingURL=MemoryObserver.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryObserver.d.ts","sourceRoot":"","sources":["../../../src/memory/observation/MemoryObserver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAMjF,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,+BAA+B;IAC/B,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,CAAC;IACxF,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACxD,SAAS,EAAE,MAAM,CAAC;CACnB;AAqCD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAgE;IACnF,OAAO,CAAC,MAAM,CAAiB;gBAG7B,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC;IAclC;;;OAGG;IACG,OAAO,CACX,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAC7B,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,QAAQ,GACd,OAAO,CAAC,eAAe,EAAE,GAAG,IAAI,CAAC;IASpC;;OAEG;IACG,YAAY,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAqB/D,gDAAgD;IAChD,SAAS,IAAI,iBAAiB;IAI9B,gDAAgD;IAChD,cAAc,IAAI,OAAO;IAIzB,0BAA0B;IAC1B,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,UAAU;CAyBnB"}

package/dist/memory/observation/MemoryObserver.js

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Memory Observer — personality-biased background note extraction.
+ *
+ * Monitors accumulated conversation tokens via ObservationBuffer.
+ * When the threshold is reached, extracts concise observation notes
+ * via a persona-configured LLM (defaults to cheap model).
+ *
+ * Personality bias:
+ * - High emotionality → notes emotional shifts
+ * - High conscientiousness → notes commitments/deadlines
+ * - High openness → notes creative tangents
+ * - High agreeableness → notes user preferences and rapport cues
+ * - High honesty → notes corrections and retractions
+ *
+ * @module agentos/memory/observation/MemoryObserver
+ */
+import { ObservationBuffer } from './ObservationBuffer.js';
+// ---------------------------------------------------------------------------
+// Personality-aware system prompt builder
+// ---------------------------------------------------------------------------
+function buildObserverSystemPrompt(traits) {
+    const clamp = (v) => v == null ? 0.5 : Math.max(0, Math.min(1, v));
+    const emphases = [];
+    if (clamp(traits.emotionality) > 0.6)
+        emphases.push('Pay special attention to emotional shifts, tone changes, and sentiment transitions.');
+    if (clamp(traits.conscientiousness) > 0.6)
+        emphases.push('Note any commitments, deadlines, action items, or structured plans.');
+    if (clamp(traits.openness) > 0.6)
+        emphases.push('Capture creative tangents, novel ideas, and exploratory topics.');
+    if (clamp(traits.agreeableness) > 0.6)
+        emphases.push('Track user preferences, rapport cues, and communication style patterns.');
+    if (clamp(traits.honesty) > 0.6)
+        emphases.push('Flag any corrections, retractions, or contradictions to prior statements.');
+    const emphasisBlock = emphases.length > 0
+        ? `\n\nPriority focus areas:\n${emphases.map((e) => `- ${e}`).join('\n')}`
+        : '';
+    return `You are a memory observer. Extract concise observation notes from the conversation below.
+
+For each observation, output a JSON object on its own line with these fields:
+- type: "factual" | "emotional" | "commitment" | "preference" | "creative" | "correction"
+- content: brief summary (1-2 sentences max)
+- importance: 0.0-1.0 (how important is this for future recall?)
+- entities: string[] (key entities mentioned)
+
+Output ONLY valid JSON objects, one per line. No markdown, no explanation.${emphasisBlock}`;
+}
+// ---------------------------------------------------------------------------
+// MemoryObserver
+// ---------------------------------------------------------------------------
+let noteIdCounter = 0;
+export class MemoryObserver {
+    constructor(traits, config) {
+        this.traits = traits;
+        this.config = {
+            activationThresholdTokens: config?.activationThresholdTokens ?? 30000,
+            modelId: config?.modelId,
+            llmInvoker: config?.llmInvoker,
+        };
+        this.llmInvoker = config?.llmInvoker;
+        this.buffer = new ObservationBuffer({
+            activationThresholdTokens: this.config.activationThresholdTokens,
+        });
+    }
+    /**
+     * Feed a message into the observation buffer.
+     * Returns observation notes if the buffer has reached activation threshold.
+     */
+    async observe(role, content, mood) {
+        const shouldActivate = this.buffer.push(role, content);
+        if (!shouldActivate)
+            return null;
+        if (!this.llmInvoker)
+            return null;
+        return this.extractNotes(mood);
+    }
+    /**
+     * Force extraction of observation notes from buffered messages.
+     */
+    async extractNotes(mood) {
+        if (!this.llmInvoker)
+            return [];
+        const messages = this.buffer.drain();
+        if (messages.length === 0)
+            return [];
+        // Build conversation text for the LLM
+        const conversationText = messages
+            .map((m) => `[${m.role}] ${m.content}`)
+            .join('\n');
+        const systemPrompt = buildObserverSystemPrompt(this.traits);
+        try {
+            const response = await this.llmInvoker(systemPrompt, conversationText);
+            return this.parseNotes(response, mood);
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Get the underlying buffer for inspection. */
+    getBuffer() {
+        return this.buffer;
+    }
+    /** Check if observation should be triggered. */
+    shouldActivate() {
+        return this.buffer.shouldActivate();
+    }
+    /** Reset the observer. */
+    clear() {
+        this.buffer.clear();
+    }
+    // --- Internal ---
+    parseNotes(llmResponse, mood) {
+        const notes = [];
+        const lines = llmResponse.split('\n').filter((l) => l.trim());
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line.trim());
+                if (parsed.type && parsed.content) {
+                    notes.push({
+                        id: `obs_${Date.now()}_${++noteIdCounter}`,
+                        type: parsed.type,
+                        content: parsed.content,
+                        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(),
+                    });
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        return notes;
+    }
+}
+//# sourceMappingURL=MemoryObserver.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Memory Reflector — consolidates observation notes into long-term traces.
+ *
+ * Activates when accumulated observation notes exceed a token threshold.
+ * Uses a persona-configured LLM to:
+ * 1. Merge redundant observations
+ * 2. Elevate important facts to long-term memory traces
+ * 3. Detect conflicts against existing memories
+ * 4. Resolve conflicts based on personality (high honesty → update, high agreeableness → coexist)
+ *
+ * Target compression: 5-40x (many observations → few traces).
+ *
+ * @module agentos/memory/observation/MemoryReflector
+ */
+import type { MemoryTrace } from '../types.js';
+import type { HexacoTraits, ReflectorConfig } from '../config.js';
+import type { ObservationNote } from './MemoryObserver.js';
+export interface MemoryReflectionResult {
+    /** New long-term memory traces to store. */
+    traces: Omit<MemoryTrace, 'id' | 'encodingStrength' | 'stability' | 'retrievalCount' | 'lastAccessedAt' | 'accessCount' | 'reinforcementInterval' | 'createdAt' | 'updatedAt'>[];
+    /** IDs of existing traces that should be superseded. */
+    supersededTraceIds: string[];
+    /** IDs of observation notes that were consumed. */
+    consumedNoteIds: string[];
+    /** Compression ratio achieved. */
+    compressionRatio: number;
+}
+export declare class MemoryReflector {
+    private pendingNotes;
+    private traits;
+    private llmInvoker?;
+    private config;
+    constructor(traits: HexacoTraits, config?: Partial<ReflectorConfig>);
+    /**
+     * Add observation notes for future reflection.
+     * Returns a MemoryReflectionResult if the note threshold is reached.
+     */
+    addNotes(notes: ObservationNote[]): Promise<MemoryReflectionResult | null>;
+    /** Whether accumulated notes exceed the reflection threshold. */
+    shouldActivate(): boolean;
+    /**
+     * Force reflection over all pending notes.
+     */
+    reflect(existingMemoryContext?: string): Promise<MemoryReflectionResult>;
+    /** Get pending note count. */
+    getPendingNoteCount(): number;
+    /** Clear all pending notes. */
+    clear(): void;
+    private parseReflection;
+}
+//# sourceMappingURL=MemoryReflector.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"MemoryReflector.d.ts","sourceRoot":"","sources":["../../../src/memory/observation/MemoryReflector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAA2B,MAAM,aAAa,CAAC;AACxE,OAAO,KAAK,EAAE,YAAY,EAAY,eAAe,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM3D,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,IAAI,GAAG,kBAAkB,GAAG,WAAW,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,aAAa,GAAG,uBAAuB,GAAG,WAAW,GAAG,WAAW,CAAC,EAAE,CAAC;IACjL,wDAAwD;IACxD,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,mDAAmD;IACnD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAoDD,qBAAa,eAAe;IAC1B,OAAO,CAAC,YAAY,CAAyB;IAC7C,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAAC,CAAgE;IACnF,OAAO,CAAC,MAAM,CAAkB;gBAG9B,MAAM,EAAE,YAAY,EACpB,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC;IAWnC;;;OAGG;IACG,QAAQ,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAShF,iEAAiE;IACjE,cAAc,IAAI,OAAO;IAQzB;;OAEG;IACG,OAAO,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAkC9E,8BAA8B;IAC9B,mBAAmB,IAAI,MAAM;IAI7B,+BAA+B;IAC/B,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,eAAe;CA+DxB"}

package/dist/memory/observation/MemoryReflector.js

@@ -0,0 +1,184 @@
+/**
+ * @fileoverview Memory Reflector — consolidates observation notes into long-term traces.
+ *
+ * Activates when accumulated observation notes exceed a token threshold.
+ * Uses a persona-configured LLM to:
+ * 1. Merge redundant observations
+ * 2. Elevate important facts to long-term memory traces
+ * 3. Detect conflicts against existing memories
+ * 4. Resolve conflicts based on personality (high honesty → update, high agreeableness → coexist)
+ *
+ * Target compression: 5-40x (many observations → few traces).
+ *
+ * @module agentos/memory/observation/MemoryReflector
+ */
+// ---------------------------------------------------------------------------
+// Personality-aware system prompt
+// ---------------------------------------------------------------------------
+function buildReflectorSystemPrompt(traits) {
+    const clamp = (v) => v == null ? 0.5 : Math.max(0, Math.min(1, v));
+    const conflictStrategy = clamp(traits.honesty) > 0.6
+        ? 'When you detect a contradiction with existing knowledge, prefer the newer information and flag the old memory for supersession.'
+        : clamp(traits.agreeableness) > 0.6
+            ? 'When you detect a contradiction, keep both versions and note the discrepancy.'
+            : 'When you detect a contradiction, keep the version with higher confidence.';
+    const memoryStyle = clamp(traits.conscientiousness) > 0.6
+        ? 'Produce structured, well-organized memory traces with clear categories.'
+        : clamp(traits.openness) > 0.6
+            ? 'Produce rich, associative memory traces that capture connections and context.'
+            : 'Produce concise, factual memory traces focused on key information.';
+    return `You are a memory reflector. Your job is to consolidate observation notes into long-term memory traces.
+
+Rules:
+1. Merge redundant or overlapping observations into single traces
+2. Assign each trace a type: "episodic" (events), "semantic" (facts/knowledge), "procedural" (how-to), or "prospective" (future goals/intentions)
+3. Assign a scope: "user" (about the user), "thread" (conversation-specific), "persona" (about the agent), or "organization" (shared)
+4. ${conflictStrategy}
+5. ${memoryStyle}
+6. Target 5-40x compression: many notes → few high-quality traces
+
+For each trace, output a JSON object on its own line:
+{
+  "type": "episodic|semantic|procedural|prospective",
+  "scope": "user|thread|persona|organization",
+  "scopeId": "relevant_id",
+  "content": "consolidated memory content",
+  "entities": ["entity1", "entity2"],
+  "tags": ["tag1", "tag2"],
+  "confidence": 0.0-1.0,
+  "sourceType": "observation|reflection",
+  "supersedes": ["existing_trace_id_if_contradicted"],
+  "consumedNotes": ["note_id1", "note_id2"]
+}
+
+Output ONLY valid JSON objects, one per line.`;
+}
+// ---------------------------------------------------------------------------
+// MemoryReflector
+// ---------------------------------------------------------------------------
+export class MemoryReflector {
+    constructor(traits, config) {
+        this.pendingNotes = [];
+        this.traits = traits;
+        this.config = {
+            activationThresholdTokens: config?.activationThresholdTokens ?? 40000,
+            modelId: config?.modelId,
+            llmInvoker: config?.llmInvoker,
+        };
+        this.llmInvoker = config?.llmInvoker;
+    }
+    /**
+     * Add observation notes for future reflection.
+     * Returns a MemoryReflectionResult if the note threshold is reached.
+     */
+    async addNotes(notes) {
+        this.pendingNotes.push(...notes);
+        if (!this.shouldActivate())
+            return null;
+        if (!this.llmInvoker)
+            return null;
+        return this.reflect();
+    }
+    /** Whether accumulated notes exceed the reflection threshold. */
+    shouldActivate() {
+        const totalTokens = this.pendingNotes.reduce((sum, note) => sum + Math.ceil(note.content.length / 4), 0);
+        return totalTokens >= this.config.activationThresholdTokens;
+    }
+    /**
+     * Force reflection over all pending notes.
+     */
+    async reflect(existingMemoryContext) {
+        if (!this.llmInvoker || this.pendingNotes.length === 0) {
+            return { traces: [], supersededTraceIds: [], consumedNoteIds: [], compressionRatio: 1 };
+        }
+        const notesText = this.pendingNotes
+            .map((n) => `[${n.id}] (${n.type}, importance=${n.importance.toFixed(2)}) ${n.content}`)
+            .join('\n');
+        const userPrompt = existingMemoryContext
+            ? `## Existing Memory Context\n${existingMemoryContext}\n\n## New Observation Notes\n${notesText}`
+            : `## Observation Notes\n${notesText}`;
+        const systemPrompt = buildReflectorSystemPrompt(this.traits);
+        try {
+            const response = await this.llmInvoker(systemPrompt, userPrompt);
+            const result = this.parseReflection(response);
+            // Clear consumed notes
+            const consumedSet = new Set(result.consumedNoteIds);
+            this.pendingNotes = this.pendingNotes.filter((n) => !consumedSet.has(n.id));
+            // Compute compression ratio
+            const inputTokens = notesText.length / 4;
+            const outputTokens = result.traces.reduce((sum, t) => sum + t.content.length / 4, 0);
+            result.compressionRatio = outputTokens > 0 ? inputTokens / outputTokens : 1;
+            return result;
+        }
+        catch {
+            return { traces: [], supersededTraceIds: [], consumedNoteIds: [], compressionRatio: 1 };
+        }
+    }
+    /** Get pending note count. */
+    getPendingNoteCount() {
+        return this.pendingNotes.length;
+    }
+    /** Clear all pending notes. */
+    clear() {
+        this.pendingNotes = [];
+    }
+    // --- Internal ---
+    parseReflection(llmResponse) {
+        const traces = [];
+        const supersededTraceIds = [];
+        const consumedNoteIds = [];
+        const lines = llmResponse.split('\n').filter((l) => l.trim());
+        const now = Date.now();
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line.trim());
+                if (!parsed.content)
+                    continue;
+                const type = (['episodic', 'semantic', 'procedural', 'prospective'].includes(parsed.type)
+                    ? parsed.type
+                    : 'semantic');
+                const scope = (['user', 'thread', 'persona', 'organization'].includes(parsed.scope)
+                    ? parsed.scope
+                    : 'user');
+                traces.push({
+                    type,
+                    scope,
+                    scopeId: parsed.scopeId ?? '',
+                    content: parsed.content,
+                    entities: Array.isArray(parsed.entities) ? parsed.entities : [],
+                    tags: Array.isArray(parsed.tags) ? parsed.tags : [],
+                    provenance: {
+                        sourceType: 'reflection',
+                        confidence: typeof parsed.confidence === 'number' ? parsed.confidence : 0.7,
+                        verificationCount: 0,
+                        sourceTimestamp: now,
+                    },
+                    emotionalContext: {
+                        valence: 0,
+                        arousal: 0,
+                        dominance: 0,
+                        intensity: 0,
+                        gmiMood: '',
+                    },
+                    associatedTraceIds: [],
+                    isActive: true,
+                });
+                if (Array.isArray(parsed.supersedes)) {
+                    supersededTraceIds.push(...parsed.supersedes);
+                }
+                if (Array.isArray(parsed.consumedNotes)) {
+                    consumedNoteIds.push(...parsed.consumedNotes);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+        // If no specific notes were claimed, consider all pending consumed
+        if (consumedNoteIds.length === 0 && traces.length > 0) {
+            consumedNoteIds.push(...this.pendingNotes.map((n) => n.id));
+        }
+        return { traces, supersededTraceIds, consumedNoteIds, compressionRatio: 1 };
+    }
+}
+//# sourceMappingURL=MemoryReflector.js.map

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview Token-counting buffer for the observation system.
+ *
+ * Accumulates conversation messages and tracks approximate token count.
+ * When the configured threshold is reached, signals that observation
+ * extraction should be triggered.
+ *
+ * @module agentos/memory/observation/ObservationBuffer
+ */
+export interface BufferedMessage {
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    timestamp: number;
+    /** Cached token estimate for this message. */
+    tokenEstimate: number;
+}
+export interface ObservationBufferConfig {
+    /** Token threshold before observer should be triggered. @default 30_000 */
+    activationThresholdTokens: number;
+}
+export declare class ObservationBuffer {
+    private messages;
+    private totalTokens;
+    private config;
+    /** Number of tokens that have been drained (consumed by observer). */
+    private drainedTokens;
+    constructor(config?: Partial<ObservationBufferConfig>);
+    /**
+     * Add a message to the buffer.
+     * Returns true if the buffer has reached activation threshold.
+     */
+    push(role: BufferedMessage['role'], content: string): boolean;
+    /** Whether accumulated tokens since last drain exceed the threshold. */
+    shouldActivate(): boolean;
+    /**
+     * Drain messages since last drain for observation processing.
+     * Returns the messages and marks them as consumed.
+     */
+    drain(): BufferedMessage[];
+    /** Index of next unprocessed message. */
+    private drainCursor;
+    /** Total accumulated tokens. */
+    getTotalTokens(): number;
+    /** Unprocessed tokens since last drain. */
+    getPendingTokens(): number;
+    /** Total message count. */
+    getMessageCount(): number;
+    /** Clear the buffer entirely. */
+    clear(): void;
+}
+//# sourceMappingURL=ObservationBuffer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObservationBuffer.d.ts","sourceRoot":"","sources":["../../../src/memory/observation/ObservationBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,yBAAyB,EAAE,MAAM,CAAC;CACnC;AAeD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,MAAM,CAA0B;IACxC,sEAAsE;IACtE,OAAO,CAAC,aAAa,CAAK;gBAEd,MAAM,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC;IAMrD;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAY7D,wEAAwE;IACxE,cAAc,IAAI,OAAO;IAIzB;;;OAGG;IACH,KAAK,IAAI,eAAe,EAAE;IAO1B,yCAAyC;IACzC,OAAO,CAAC,WAAW,CAAK;IAExB,gCAAgC;IAChC,cAAc,IAAI,MAAM;IAIxB,2CAA2C;IAC3C,gBAAgB,IAAI,MAAM;IAI1B,2BAA2B;IAC3B,eAAe,IAAI,MAAM;IAIzB,iCAAiC;IACjC,KAAK,IAAI,IAAI;CAMd"}

package/dist/memory/observation/ObservationBuffer.js

@@ -0,0 +1,81 @@
+/**
+ * @fileoverview Token-counting buffer for the observation system.
+ *
+ * Accumulates conversation messages and tracks approximate token count.
+ * When the configured threshold is reached, signals that observation
+ * extraction should be triggered.
+ *
+ * @module agentos/memory/observation/ObservationBuffer
+ */
+// ---------------------------------------------------------------------------
+// Token estimation
+// ---------------------------------------------------------------------------
+/** Rough token estimate: ~4 chars per token for English text. */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ---------------------------------------------------------------------------
+// ObservationBuffer
+// ---------------------------------------------------------------------------
+export class ObservationBuffer {
+    constructor(config) {
+        this.messages = [];
+        this.totalTokens = 0;
+        /** Number of tokens that have been drained (consumed by observer). */
+        this.drainedTokens = 0;
+        /** Index of next unprocessed message. */
+        this.drainCursor = 0;
+        this.config = {
+            activationThresholdTokens: config?.activationThresholdTokens ?? 30000,
+        };
+    }
+    /**
+     * Add a message to the buffer.
+     * Returns true if the buffer has reached activation threshold.
+     */
+    push(role, content) {
+        const tokenEstimate = estimateTokens(content);
+        this.messages.push({
+            role,
+            content,
+            timestamp: Date.now(),
+            tokenEstimate,
+        });
+        this.totalTokens += tokenEstimate;
+        return this.shouldActivate();
+    }
+    /** Whether accumulated tokens since last drain exceed the threshold. */
+    shouldActivate() {
+        return (this.totalTokens - this.drainedTokens) >= this.config.activationThresholdTokens;
+    }
+    /**
+     * Drain messages since last drain for observation processing.
+     * Returns the messages and marks them as consumed.
+     */
+    drain() {
+        const unprocessed = this.messages.slice(this.drainCursor);
+        this.drainedTokens = this.totalTokens;
+        this.drainCursor = this.messages.length;
+        return unprocessed;
+    }
+    /** Total accumulated tokens. */
+    getTotalTokens() {
+        return this.totalTokens;
+    }
+    /** Unprocessed tokens since last drain. */
+    getPendingTokens() {
+        return this.totalTokens - this.drainedTokens;
+    }
+    /** Total message count. */
+    getMessageCount() {
+        return this.messages.length;
+    }
+    /** Clear the buffer entirely. */
+    clear() {
+        this.messages = [];
+        this.totalTokens = 0;
+        this.drainedTokens = 0;
+        this.drainCursor = 0;
+    }
+}
+//# sourceMappingURL=ObservationBuffer.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ObservationBuffer.js","sourceRoot":"","sources":["../../../src/memory/observation/ObservationBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH,8EAA8E;AAC9E,mBAAmB;AACnB,8EAA8E;AAE9E,iEAAiE;AACjE,SAAS,cAAc,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC;AAED,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,OAAO,iBAAiB;IAO5B,YAAY,MAAyC;QAN7C,aAAQ,GAAsB,EAAE,CAAC;QACjC,gBAAW,GAAG,CAAC,CAAC;QAExB,sEAAsE;QAC9D,kBAAa,GAAG,CAAC,CAAC;QAwC1B,yCAAyC;QACjC,gBAAW,GAAG,CAAC,CAAC;QAtCtB,IAAI,CAAC,MAAM,GAAG;YACZ,yBAAyB,EAAE,MAAM,EAAE,yBAAyB,IAAI,KAAM;SACvE,CAAC;IACJ,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAA6B,EAAE,OAAe;QACjD,MAAM,aAAa,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;YACjB,IAAI;YACJ,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;YACrB,aAAa;SACd,CAAC,CAAC;QACH,IAAI,CAAC,WAAW,IAAI,aAAa,CAAC;QAClC,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IAED,wEAAwE;IACxE,cAAc;QACZ,OAAO,CAAC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,yBAAyB,CAAC;IAC1F,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC,WAAW,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;QACxC,OAAO,WAAW,CAAC;IACrB,CAAC;IAKD,gCAAgC;IAChC,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED,2CAA2C;IAC3C,gBAAgB;QACd,OAAO,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,aAAa,CAAC;IAC/C,CAAC;IAED,2BAA2B;IAC3B,eAAe;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC9B,CAAC;IAED,iCAAiC;IACjC,KAAK;QACH,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;QACrB,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,WAAW,GAAG,CAAC,CAAC;IACvB,CAAC;CACF"}