@animus-labs/cortex 0.2.0

package/src/compaction/observational/reflector.ts

@@ -0,0 +1,221 @@
+/**
+ * Reflector module for the observational memory system.
+ *
+ * The Reflector condenses observations when they grow too large. It runs
+ * on the utility model and uses progressive compression: starting with
+ * no compression guidance (level 0) and escalating through levels 1-4
+ * if the output exceeds the target token threshold.
+ *
+ * References:
+ *   - observational-memory-architecture.md (Reflector System section)
+ *   - compaction-strategy.md
+ */
+
+import type { CompleteFn } from '../compaction.js';
+import type { ReflectorOutput } from './types.js';
+import {
+  REFLECTOR_SYSTEM_PROMPT,
+  COMPRESSION_LEVEL_GUIDANCE,
+} from './constants.js';
+import { estimateTokens } from '../../token-estimator.js';
+
+// ---------------------------------------------------------------------------
+// Prompt Building
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full reflector system prompt.
+ *
+ * Starts with the base reflector prompt, then appends compression level
+ * guidance and optional consumer instructions.
+ *
+ * @param compressionLevel - Compression level (0-4). Level 0 adds no
+ *   compression guidance.
+ * @param customInstruction - Optional consumer-provided instruction to
+ *   append to the prompt.
+ * @returns The assembled system prompt string.
+ */
+export function buildReflectorPrompt(
+  compressionLevel: number,
+  customInstruction?: string,
+): string {
+  let prompt = REFLECTOR_SYSTEM_PROMPT;
+
+  const guidance = COMPRESSION_LEVEL_GUIDANCE[compressionLevel];
+  if (compressionLevel > 0 && guidance) {
+    prompt += `\n\n## Compression Target\n\n${guidance}`;
+  }
+
+  if (customInstruction) {
+    prompt += `\n\n## Additional Instructions\n\n${customInstruction}`;
+  }
+
+  return prompt;
+}
+
+// ---------------------------------------------------------------------------
+// Message Building
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the message array to send to the reflector LLM.
+ *
+ * Creates two user messages: one containing the observations to reflect on,
+ * and one with the output instruction.
+ *
+ * @param observations - The full observation text to consolidate.
+ * @returns An array of message objects for the LLM call.
+ */
+export function buildReflectorMessages(
+  observations: string,
+): unknown[] {
+  return [
+    {
+      role: 'user',
+      content:
+        'Here are all current observations to reflect on and consolidate:\n\n' +
+        observations,
+    },
+    {
+      role: 'user',
+      content:
+        'Produce your consolidated reflections. Follow the observation format exactly. Output ONLY the consolidated observations, nothing else.',
+    },
+  ];
+}
+
+// ---------------------------------------------------------------------------
+// Output Parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Parse the raw LLM output from the reflector.
+ *
+ * Extracts content from `<observations>` tags if present, strips any
+ * analysis/thinking tags, and trims whitespace.
+ *
+ * @param raw - The raw string output from the reflector LLM call.
+ * @returns The cleaned observation text.
+ */
+export function parseReflectorOutput(raw: string): string {
+  let output = raw;
+
+  // Strip analysis/thinking tags if present
+  output = output.replace(/<analysis>[\s\S]*?<\/analysis>/g, '');
+  output = output.replace(/<thinking>[\s\S]*?<\/thinking>/g, '');
+
+  // Extract content from <observations> tags if present
+  const match = /<observations>([\s\S]*?)<\/observations>/.exec(output);
+  if (match?.[1]) {
+    output = match[1];
+  }
+
+  return output.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Validation
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the reflector output is within the target token budget.
+ *
+ * @param output - The parsed reflector output text.
+ * @param targetTokens - The maximum allowed token count.
+ * @returns `true` if estimated tokens are at or below the target.
+ */
+export function validateCompression(
+  output: string,
+  targetTokens: number,
+): boolean {
+  return estimateTokens(output) <= targetTokens;
+}
+
+// ---------------------------------------------------------------------------
+// Threshold Computation
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the effective reflection threshold by clamping to both the
+ * primary model's context window and the utility model's context window.
+ *
+ * The threshold is the smaller of:
+ * - `reflectionThreshold` as a percentage of the primary context window
+ * - 50% of the utility model's context window (to ensure the reflector
+ *   input fits within the utility model)
+ *
+ * @param contextWindow - The primary model's context window size in tokens.
+ * @param reflectionThreshold - Fraction of the context window (e.g. 0.20).
+ * @param utilityModelContextWindow - The utility model's context window
+ *   size in tokens.
+ * @returns The effective reflection threshold in tokens.
+ */
+export function computeEffectiveReflectionThreshold(
+  contextWindow: number,
+  reflectionThreshold: number,
+  utilityModelContextWindow: number,
+): number {
+  return Math.min(
+    contextWindow * reflectionThreshold,
+    utilityModelContextWindow * 0.5,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Reflector Execution
+// ---------------------------------------------------------------------------
+
+const MAX_RETRIES = 4;
+const MAX_COMPRESSION_LEVEL = 4;
+
+/**
+ * Run the reflector with progressive compression retry.
+ *
+ * Starts at compression level 0 and escalates if the output exceeds the
+ * reflection threshold. Retries up to 3 times, incrementing the
+ * compression level each time (capped at level 4).
+ *
+ * Even if the final attempt does not validate, the best result is returned.
+ * The observation slot will be larger than ideal, but the next reflection
+ * cycle will try again.
+ *
+ * @param complete - The LLM completion function.
+ * @param observations - The full observation text to consolidate.
+ * @param config - Configuration with reflectionThreshold (in tokens) and
+ *   optional reflectorInstruction.
+ * @returns The reflector output with consolidated observations and the
+ *   compression level that was applied.
+ */
+export async function runReflector(
+  complete: CompleteFn,
+  observations: string,
+  config: {
+    reflectionThreshold: number;
+    reflectorInstruction?: string;
+  },
+): Promise<ReflectorOutput> {
+  let level = 0;
+  let retries = 0;
+  let parsedOutput = '';
+
+  while (true) {
+    const systemPrompt = buildReflectorPrompt(level, config.reflectorInstruction);
+    const messages = buildReflectorMessages(observations);
+    const raw = await complete({ systemPrompt, messages });
+
+    parsedOutput = parseReflectorOutput(raw);
+
+    if (validateCompression(parsedOutput, config.reflectionThreshold)) {
+      return { observations: parsedOutput, compressionLevel: level };
+    }
+
+    if (level >= MAX_COMPRESSION_LEVEL || retries >= MAX_RETRIES) {
+      break;
+    }
+
+    level++;
+    retries++;
+  }
+
+  return { observations: parsedOutput, compressionLevel: level };
+}

package/src/compaction/observational/types.ts

@@ -0,0 +1,343 @@
+/**
+ * Type definitions for the observational memory system.
+ *
+ * Observational memory is an alternative compaction strategy that replaces
+ * Layers 1 and 2 (microcompaction + conversation summarization) with a
+ * continuous, background-driven compression system. Two background LLM agents
+ * (Observer and Reflector) maintain a compressed event log of the conversation.
+ *
+ * References:
+ *   - observational-memory-architecture.md
+ *   - compaction-strategy.md
+ *   - context-manager.md
+ */
+
+import type { AgentMessage } from '../../context-manager.js';
+
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+
+/**
+ * Consumer-facing configuration for the observational memory system.
+ *
+ * All fields are optional with sensible defaults. The system adapts to any
+ * context window size from 32k to 1M+ through percentage-based thresholds.
+ */
+export interface ObservationalMemoryConfig {
+  /**
+   * Percentage of total context window utilization that triggers observation
+   * activation. When total context (system prompt + slots + observations +
+   * messages) exceeds this fraction of the context window, buffered
+   * observations activate and raw messages are trimmed.
+   * @default 0.9
+   */
+  activationThreshold: number;
+
+  /**
+   * Maximum token count per async buffer observation. Caps how many tokens
+   * of unobserved messages a single observer call will process. Prevents
+   * oversized observer calls on large context windows.
+   * The actual interval is computed dynamically (see Observer System section
+   * in architecture doc).
+   * Internally clamped to utilityModelContextWindow * 0.6 to ensure the
+   * observer input fits within the utility model's context window.
+   * @default 30_000
+   */
+  bufferTokenCap: number;
+
+  /**
+   * Minimum tokens of unobserved messages before a buffer observation runs.
+   * Prevents thrashing when the context window is nearly full or on very
+   * small windows.
+   * @default 5_000
+   */
+  bufferMinTokens: number;
+
+  /**
+   * Target number of buffer cycles between current utilization and the
+   * activation threshold. Higher values mean more frequent, smaller observer
+   * calls. Lower values mean fewer, larger observer calls.
+   * @default 4
+   */
+  bufferTargetCycles: number;
+
+  /**
+   * Fraction of the context window at which reflection triggers.
+   * When the observation slot exceeds this percentage of the context window,
+   * the Reflector condenses it. Scales naturally across all window sizes.
+   * Internally clamped to utilityModelContextWindow * 0.5 to ensure the
+   * reflector input fits within the utility model's context window.
+   * @default 0.20
+   */
+  reflectionThreshold: number;
+
+  /**
+   * Fraction of reflectionThreshold at which async reflection buffering
+   * begins. For example, 0.5 means start background reflection at 50% of
+   * the threshold.
+   * @default 0.5
+   */
+  reflectionBufferActivation: number;
+
+  /**
+   * Token budget for previous observations sent to the Observer as context.
+   * Provides continuity between observation cycles so the observer does not
+   * duplicate already-captured information.
+   * @default 2_000
+   */
+  previousObserverTokens: number;
+
+  /**
+   * Custom instructions appended to the Observer's system prompt.
+   * Use for domain-specific observation behavior. Cannot replace the core
+   * prompt, only extend it.
+   */
+  observerInstruction?: string;
+
+  /**
+   * Custom instructions appended to the Reflector's system prompt.
+   * Use for domain-specific reflection behavior. Cannot replace the core
+   * prompt, only extend it.
+   */
+  reflectorInstruction?: string;
+
+  /**
+   * Optional recall tool configuration. When provided, Cortex registers a
+   * recall tool that enables the agent to search through persisted
+   * conversation history. The consumer owns message persistence and search
+   * implementation.
+   */
+  recall?: RecallConfig;
+}
+
+/**
+ * Configuration for the optional recall tool.
+ *
+ * The consumer provides a search function that Cortex wraps into a tool
+ * registered on the agent. Observations include timestamps, enabling
+ * temporal anchoring for precise recall queries.
+ */
+export interface RecallConfig {
+  /**
+   * Search function provided by the consumer. Accepts a query string and
+   * optional time range for narrowing results.
+   *
+   * The consumer owns the search implementation (vector DB, full-text
+   * search, SQL, etc.). Cortex only wraps it into a tool.
+   */
+  search: (
+    query: string,
+    options?: { timeRange?: { start?: Date; end?: Date } },
+  ) => Promise<RecallResult[]>;
+}
+
+// ---------------------------------------------------------------------------
+// Session State
+// ---------------------------------------------------------------------------
+
+/**
+ * Serializable session state for the observational memory system.
+ *
+ * Saved via `agent.getObservationalMemoryState()` and restored via
+ * `agent.restoreObservationalMemoryState()`. The consumer decides where
+ * and when to persist this (same pattern as `getConversationHistory()`).
+ */
+export interface ObservationalMemoryState {
+  /** Current observation text (the content stored in the _observations slot). */
+  observations: string;
+
+  /** Continuation hints from the last observer run. */
+  continuationHint: ContinuationHint | null;
+
+  /** Current observation token estimate. */
+  observationTokenCount: number;
+
+  /** How many reflection cycles have occurred in this session. */
+  generationCount: number;
+
+  /** Buffered observation chunks not yet activated. */
+  bufferedChunks: ObservationChunk[];
+}
+
+// ---------------------------------------------------------------------------
+// Observation Chunks
+// ---------------------------------------------------------------------------
+
+/**
+ * A buffered observation chunk produced by an async observer call.
+ *
+ * Chunks accumulate between activation cycles. On activation, completed
+ * chunks are merged into the observation slot and their corresponding
+ * raw messages are removed from context.
+ */
+export interface ObservationChunk {
+  /** The observation text produced by the observer. */
+  observations: string;
+
+  /** Token count of messages that were observed in this chunk. */
+  messageTokensObserved: number;
+
+  /** When this chunk was created. */
+  createdAt: Date;
+
+  /** Current task extracted from this observation. Latest chunk wins on activation. */
+  currentTask?: string;
+
+  /** Suggested response extracted from this observation. Latest chunk wins on activation. */
+  suggestedResponse?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Events
+// ---------------------------------------------------------------------------
+
+/**
+ * Event payload fired when observation activates (messages are compressed
+ * and removed from context).
+ *
+ * Registered via `agent.onObservation()`. Multiple handlers are supported.
+ * Consumers can use this to persist compacted messages or coordinate their
+ * own compression systems.
+ */
+export interface ObservationEvent {
+  /** The raw messages that were compressed and removed from context. */
+  compactedMessages: AgentMessage[];
+
+  /** The observation text those messages were compressed into. */
+  observations: string;
+
+  /** Total context utilization (0-1) at the time of activation. */
+  contextUtilization: number;
+
+  /** Whether this was a sync (blocking) or async (buffered) observation. */
+  sync: boolean;
+
+  /** Timestamp of the observation. */
+  timestamp: Date;
+}
+
+/**
+ * Event payload fired after a reflection cycle completes (observations
+ * are condensed by the reflector).
+ *
+ * Registered via `agent.onReflection()`. Multiple handlers are supported.
+ * Consumers can use this to coordinate their own compaction timing with
+ * Cortex's reflection cycles.
+ */
+export interface ReflectionEvent {
+  /** Observations before reflection. */
+  previousObservations: string;
+
+  /** Observations after reflection (condensed). */
+  newObservations: string;
+
+  /** How many reflection generations have occurred in this session. */
+  generationCount: number;
+
+  /** Compression level used (0-4). */
+  compressionLevel: number;
+
+  /** Timestamp of the reflection. */
+  timestamp: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Recall
+// ---------------------------------------------------------------------------
+
+/**
+ * A single result returned from the consumer's recall search function.
+ *
+ * Contains the content of a past message or tool result along with
+ * temporal and classification metadata.
+ */
+export interface RecallResult {
+  /** The message or tool result content. */
+  content: string;
+
+  /** When the message occurred. */
+  timestamp: Date;
+
+  /** Type of content returned. */
+  type: 'message' | 'tool-result' | 'tool-call';
+
+  /** Message role, if applicable. */
+  role?: 'user' | 'assistant';
+}
+
+// ---------------------------------------------------------------------------
+// LLM Output Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Parsed output from the observer LLM call.
+ *
+ * The observer produces XML with three sections: observations, current-task,
+ * and suggested-response. This type represents the parsed result.
+ */
+export interface ObserverOutput {
+  /** Extracted observations in the structured bulleted format. */
+  observations: string;
+
+  /** The agent's current task, if identified by the observer. */
+  currentTask?: string;
+
+  /** A suggested response hint for the agent after observation activates. */
+  suggestedResponse?: string;
+}
+
+/**
+ * Parsed output from the reflector LLM call.
+ *
+ * The reflector produces consolidated observations and reports the
+ * compression level it applied.
+ */
+export interface ReflectorOutput {
+  /** Consolidated and reorganized observations. */
+  observations: string;
+
+  /** The compression level that was applied (0-4). */
+  compressionLevel: number;
+}
+
+// ---------------------------------------------------------------------------
+// Internal Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Continuation hint carried between observer runs and across sessions.
+ *
+ * Provides the agent with awareness of what it was working on and what
+ * it should say next, particularly valuable on session resumption.
+ */
+export interface ContinuationHint {
+  /** What the agent is currently working on. */
+  currentTask: string;
+
+  /** Hint for the agent's next message after observation activates. */
+  suggestedResponse: string;
+}
+
+/**
+ * Internal state for the buffering coordinator.
+ *
+ * Tracks the observation watermark, accumulated chunks, and in-flight
+ * async operations for both the observer and reflector.
+ */
+export interface BufferState {
+  /**
+   * Index into agent.state.messages marking where the last completed
+   * observation ended. Messages from this index onward are "unobserved."
+   */
+  watermark: number;
+
+  /** Completed observation chunks awaiting activation. */
+  chunks: ObservationChunk[];
+
+  /** Promise for the currently in-flight async observer call, or null. */
+  inFlightObserver: Promise<ObserverOutput | null> | null;
+
+  /** Promise for the currently in-flight async reflector call, or null. */
+  inFlightReflector: Promise<ReflectorOutput | null> | null;
+}