@animus-labs/cortex 0.2.0

package/dist/compaction/observational/observer.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Observer module for the observational memory system.
+ *
+ * Handles extracting observations from raw conversation messages via a
+ * background LLM call. The observer watches the conversation and produces
+ * structured, timestamped observations that become the agent's sole
+ * memory of past interactions.
+ *
+ * References:
+ *   - observational-memory-architecture.md (Observer System section)
+ *   - compaction-strategy.md
+ */
+import type { CompleteFn } from '../compaction.js';
+import type { AgentMessage } from '../../context-manager.js';
+import type { ObserverOutput } from './types.js';
+/**
+ * Converts an array of AgentMessages into a formatted string for the
+ * observer LLM.
+ *
+ * Each message is formatted with role and positional timestamp. Messages
+ * with content arrays (tool calls/results) receive structured formatting
+ * so the observer can extract meaningful takeaways.
+ *
+ * Messages with timestamps are formatted with their actual date and time.
+ * Messages without timestamps fall back to sequential labels.
+ * Messages are grouped by date when timestamps are available.
+ */
+export declare function formatMessagesForObserver(messages: AgentMessage[]): string;
+/**
+ * Parse the raw LLM output from the observer.
+ *
+ * Extracts content from `<observations>`, `<current-task>`, and
+ * `<suggested-response>` XML blocks. Uses simple string matching
+ * (not a DOM parser) and is lenient with malformed output.
+ *
+ * If no `<observations>` tag is found, the entire output is used as
+ * observations (graceful fallback).
+ */
+export declare function parseObserverOutput(raw: string): ObserverOutput;
+/**
+ * Build the full observer system prompt.
+ *
+ * Starts with `OBSERVER_SYSTEM_PROMPT` from constants and optionally
+ * appends consumer-provided custom instructions.
+ *
+ * @param previousObservations - Previous observations for context (unused in system prompt, kept for signature consistency)
+ * @param previousObserverTokens - Token budget for previous observations (unused in system prompt)
+ * @param customInstruction - Optional consumer-provided instruction to append
+ * @returns The complete system prompt string
+ */
+export declare function buildObserverPrompt(previousObservations: string | null, previousObserverTokens: number, customInstruction?: string): string;
+/**
+ * Build the message array to send to the observer LLM.
+ *
+ * Constructs a sequence of user messages:
+ * 1. (Optional) Previous observations for deduplication context
+ * 2. The formatted message history
+ * 3. A task instruction to extract observations
+ *
+ * @param messages - The conversation messages to observe
+ * @param previousObservations - Previous observations to prevent duplication
+ * @param previousObserverTokens - Token budget for the previous observations context
+ * @returns Array of message objects for the LLM call
+ */
+export declare function buildObserverMessages(messages: AgentMessage[], previousObservations: string | null, previousObserverTokens: number): unknown[];
+/**
+ * Check if the output contains degenerate repetition.
+ *
+ * Detects a line appearing 5+ times consecutively, which is a known
+ * failure mode of LLMs under certain conditions (e.g., high temperature,
+ * long context, repetitive input patterns).
+ *
+ * @param text - The text to check for repetition
+ * @returns true if degenerate repetition is detected
+ */
+export declare function detectDegenerateRepetition(text: string): boolean;
+/**
+ * Run the observer LLM call to extract observations from messages.
+ *
+ * Orchestrates the full observer pipeline:
+ * 1. Builds the system prompt (with optional custom instructions)
+ * 2. Builds the message array (with previous observations context)
+ * 3. Calls the LLM via `complete`
+ * 4. Parses the structured output
+ * 5. Detects and retries on degenerate repetition (once)
+ *
+ * @param complete - The LLM completion function
+ * @param messages - The conversation messages to observe
+ * @param previousObservations - Previous observations for deduplication
+ * @param config - Observer configuration
+ * @returns Parsed observer output with observations, current task, and suggested response
+ */
+export declare function runObserver(complete: CompleteFn, messages: AgentMessage[], previousObservations: string | null, config: {
+    previousObserverTokens: number;
+    observerInstruction?: string;
+}): Promise<ObserverOutput>;
+//# sourceMappingURL=observer.d.ts.map

package/dist/compaction/observational/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/compaction/observational/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAQjD;;;;;;;;;;;GAWG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,MAAM,CAkD1E;AA4JD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAoB/D;AAwDD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,oBAAoB,EAAE,MAAM,GAAG,IAAI,EACnC,sBAAsB,EAAE,MAAM,EAC9B,iBAAiB,CAAC,EAAE,MAAM,GACzB,MAAM,CAQR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,YAAY,EAAE,EACxB,oBAAoB,EAAE,MAAM,GAAG,IAAI,EACnC,sBAAsB,EAAE,MAAM,GAC7B,OAAO,EAAE,CAsBX;AA+BD;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAwBhE;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,YAAY,EAAE,EACxB,oBAAoB,EAAE,MAAM,GAAG,IAAI,EACnC,MAAM,EAAE;IACN,sBAAsB,EAAE,MAAM,CAAC;IAC/B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,GACA,OAAO,CAAC,cAAc,CAAC,CAuBzB"}

package/dist/compaction/observational/observer.js

@@ -0,0 +1,424 @@
+/**
+ * Observer module for the observational memory system.
+ *
+ * Handles extracting observations from raw conversation messages via a
+ * background LLM call. The observer watches the conversation and produces
+ * structured, timestamped observations that become the agent's sole
+ * memory of past interactions.
+ *
+ * References:
+ *   - observational-memory-architecture.md (Observer System section)
+ *   - compaction-strategy.md
+ */
+import { OBSERVER_SYSTEM_PROMPT } from './constants.js';
+import { estimateTokens } from '../../token-estimator.js';
+// ---------------------------------------------------------------------------
+// Message Formatting
+// ---------------------------------------------------------------------------
+/**
+ * Converts an array of AgentMessages into a formatted string for the
+ * observer LLM.
+ *
+ * Each message is formatted with role and positional timestamp. Messages
+ * with content arrays (tool calls/results) receive structured formatting
+ * so the observer can extract meaningful takeaways.
+ *
+ * Messages with timestamps are formatted with their actual date and time.
+ * Messages without timestamps fall back to sequential labels.
+ * Messages are grouped by date when timestamps are available.
+ */
+export function formatMessagesForObserver(messages) {
+    if (messages.length === 0)
+        return '';
+    const lines = [];
+    let currentDateHeader = null;
+    for (let i = 0; i < messages.length; i++) {
+        const msg = messages[i];
+        const roleLabel = msg.role;
+        // Build the timestamp label from message metadata
+        let label;
+        if (msg.timestamp !== 0) {
+            const date = new Date(msg.timestamp);
+            const dateHeader = formatDateHeader(date);
+            // Insert a date header when the date changes
+            if (dateHeader !== currentDateHeader) {
+                if (currentDateHeader !== null) {
+                    lines.push(''); // blank line between date groups
+                }
+                lines.push(`Date: ${dateHeader}`);
+                currentDateHeader = dateHeader;
+            }
+            label = formatTime(date);
+        }
+        else {
+            // No timestamp available; use a sequential fallback
+            if (currentDateHeader === null) {
+                lines.push('Date: (not specified)');
+                currentDateHeader = '(not specified)';
+            }
+            label = `Message ${i + 1}`;
+        }
+        if (typeof msg.content === 'string') {
+            lines.push(`**${roleLabel} (${label})**: ${msg.content}`);
+        }
+        else if (Array.isArray(msg.content)) {
+            const parts = formatContentParts(msg.content);
+            if (parts) {
+                lines.push(`**${roleLabel} (${label})**:\n${parts}`);
+            }
+            else {
+                lines.push(`**${roleLabel} (${label})**: [empty]`);
+            }
+        }
+        else {
+            lines.push(`**${roleLabel} (${label})**: [empty]`);
+        }
+    }
+    return lines.join('\n\n');
+}
+/**
+ * Format a date for the observer date header.
+ * Example: "April 11, 2026"
+ */
+function formatDateHeader(date) {
+    return date.toLocaleDateString('en-US', {
+        month: 'long',
+        day: 'numeric',
+        year: 'numeric',
+    });
+}
+/**
+ * Format a time for a message label.
+ * Example: "2:30 PM"
+ */
+function formatTime(date) {
+    return date.toLocaleTimeString('en-US', {
+        hour: 'numeric',
+        minute: '2-digit',
+        hour12: true,
+    });
+}
+/**
+ * Format an array of content parts from a structured message.
+ *
+ * Handles text, tool_use, and tool_result part types. Other part types
+ * are rendered with their type label.
+ */
+function formatContentParts(parts) {
+    const formatted = [];
+    for (const part of parts) {
+        switch (part.type) {
+            case 'text': {
+                if (typeof part.text === 'string' && part.text.length > 0) {
+                    formatted.push(part.text);
+                }
+                break;
+            }
+            case 'tool_use': {
+                const toolName = typeof part['name'] === 'string' ? part['name'] : 'unknown';
+                const argsSummary = summarizeToolArgs(part['input']);
+                formatted.push(`[Tool Call: ${toolName}] ${argsSummary}`);
+                break;
+            }
+            case 'tool_result': {
+                const toolUseId = typeof part['tool_use_id'] === 'string'
+                    ? part['tool_use_id']
+                    : undefined;
+                // Resolve tool name: check for a name field on the part, fall back to tool_use_id reference
+                const resultToolName = typeof part['name'] === 'string'
+                    ? part['name']
+                    : undefined;
+                const header = resultToolName
+                    ? `[Tool Result: ${resultToolName}]`
+                    : toolUseId
+                        ? `[Tool Result (ref: ${toolUseId})]`
+                        : '[Tool Result]';
+                const content = extractToolResultContent(part);
+                if (content) {
+                    formatted.push(`${header}\n${content}`);
+                }
+                else {
+                    formatted.push(header);
+                }
+                break;
+            }
+            default: {
+                // Unknown part type: include type label and any text
+                if (typeof part.text === 'string' && part.text.length > 0) {
+                    formatted.push(`[${part.type}]: ${part.text}`);
+                }
+                break;
+            }
+        }
+    }
+    return formatted.join('\n');
+}
+/**
+ * Summarize tool call arguments into a brief string.
+ *
+ * Produces a compact summary of the key arguments without reproducing
+ * large values verbatim.
+ */
+function summarizeToolArgs(input) {
+    if (input === null || input === undefined)
+        return '';
+    if (typeof input === 'string')
+        return `{${truncateValue(input, 100)}}`;
+    if (typeof input === 'object' && !Array.isArray(input)) {
+        const obj = input;
+        const entries = Object.entries(obj);
+        if (entries.length === 0)
+            return '{}';
+        const parts = entries.slice(0, 5).map(([key, value]) => {
+            return `${key}: ${truncateValue(String(value), 80)}`;
+        });
+        const suffix = entries.length > 5 ? `, ... (+${entries.length - 5} more)` : '';
+        return `{${parts.join(', ')}${suffix}}`;
+    }
+    return String(input);
+}
+/**
+ * Extract text content from a tool_result part.
+ */
+function extractToolResultContent(part) {
+    // Direct text field
+    if (typeof part.text === 'string' && part.text.length > 0) {
+        return part.text;
+    }
+    // Content may be nested in a 'content' field (some tool result formats)
+    const nested = part['content'];
+    if (typeof nested === 'string' && nested.length > 0) {
+        return nested;
+    }
+    if (Array.isArray(nested)) {
+        const textParts = nested
+            .filter((p) => typeof p === 'object' && p !== null && typeof p.text === 'string')
+            .map(p => p.text);
+        if (textParts.length > 0)
+            return textParts.join('\n');
+    }
+    return '';
+}
+/**
+ * Truncate a string value for argument summaries.
+ */
+function truncateValue(value, maxLen) {
+    if (value.length <= maxLen)
+        return value;
+    return value.slice(0, maxLen) + '...';
+}
+// ---------------------------------------------------------------------------
+// Output Parsing
+// ---------------------------------------------------------------------------
+/**
+ * Parse the raw LLM output from the observer.
+ *
+ * Extracts content from `<observations>`, `<current-task>`, and
+ * `<suggested-response>` XML blocks. Uses simple string matching
+ * (not a DOM parser) and is lenient with malformed output.
+ *
+ * If no `<observations>` tag is found, the entire output is used as
+ * observations (graceful fallback).
+ */
+export function parseObserverOutput(raw) {
+    const observations = extractTagContent(raw, 'observations') ?? raw.trim();
+    const rawTask = extractTagContent(raw, 'current-task');
+    const rawSuggested = extractTagContent(raw, 'suggested-response');
+    const result = {
+        observations: observations.trim(),
+    };
+    const trimmedTask = rawTask?.trim();
+    if (trimmedTask && hasMeaningfulContent(trimmedTask)) {
+        result.currentTask = trimmedTask;
+    }
+    const trimmedSuggested = rawSuggested?.trim();
+    if (trimmedSuggested && hasMeaningfulContent(trimmedSuggested)) {
+        result.suggestedResponse = trimmedSuggested;
+    }
+    return result;
+}
+/**
+ * Check whether extracted tag content is meaningful (not just placeholder
+ * labels echoed from the prompt template).
+ *
+ * The observer prompt shows a structure like "- Primary:" and "- Secondary:"
+ * as a template. Some model outputs echo the template without filling in
+ * real content. This check rejects such outputs so the caller can fall back
+ * to prior hints or mark the field as missing.
+ */
+function hasMeaningfulContent(value) {
+    const contentOnly = value
+        .split('\n')
+        .map(line => line
+        .replace(/^\s*[-*]\s*/, '')
+        .replace(/^Primary\s*:\s*/i, '')
+        .replace(/^Secondary\s*:\s*/i, '')
+        .trim())
+        .filter(line => line.length > 0)
+        .join(' ')
+        .trim();
+    return contentOnly.length >= 8;
+}
+/**
+ * Extract content between XML-style tags.
+ *
+ * Lenient: handles whitespace around tags, multiline content, and
+ * nested content. Returns null if the tag pair is not found.
+ */
+function extractTagContent(text, tagName) {
+    const openPattern = new RegExp(`<${tagName}>`, 'i');
+    const closePattern = new RegExp(`</${tagName}>`, 'i');
+    const openMatch = openPattern.exec(text);
+    if (!openMatch)
+        return null;
+    const startIndex = openMatch.index + openMatch[0].length;
+    const closeMatch = closePattern.exec(text.slice(startIndex));
+    if (!closeMatch) {
+        // Opening tag found but no closing tag: return everything after the opening tag
+        return text.slice(startIndex);
+    }
+    return text.slice(startIndex, startIndex + closeMatch.index);
+}
+// ---------------------------------------------------------------------------
+// Prompt Building
+// ---------------------------------------------------------------------------
+/**
+ * Build the full observer system prompt.
+ *
+ * Starts with `OBSERVER_SYSTEM_PROMPT` from constants and optionally
+ * appends consumer-provided custom instructions.
+ *
+ * @param previousObservations - Previous observations for context (unused in system prompt, kept for signature consistency)
+ * @param previousObserverTokens - Token budget for previous observations (unused in system prompt)
+ * @param customInstruction - Optional consumer-provided instruction to append
+ * @returns The complete system prompt string
+ */
+export function buildObserverPrompt(previousObservations, previousObserverTokens, customInstruction) {
+    let prompt = OBSERVER_SYSTEM_PROMPT;
+    if (customInstruction) {
+        prompt += `\n\n## Additional Instructions\n\n${customInstruction}`;
+    }
+    return prompt;
+}
+/**
+ * Build the message array to send to the observer LLM.
+ *
+ * Constructs a sequence of user messages:
+ * 1. (Optional) Previous observations for deduplication context
+ * 2. The formatted message history
+ * 3. A task instruction to extract observations
+ *
+ * @param messages - The conversation messages to observe
+ * @param previousObservations - Previous observations to prevent duplication
+ * @param previousObserverTokens - Token budget for the previous observations context
+ * @returns Array of message objects for the LLM call
+ */
+export function buildObserverMessages(messages, previousObservations, previousObserverTokens) {
+    const result = [];
+    // 1. Previous observations context (if available)
+    if (previousObservations && previousObservations.trim().length > 0) {
+        const preamble = 'These are the observations that have already been captured. Do not repeat them. Only add NEW observations from the messages below.\n\n';
+        const truncated = tailTruncateToTokenBudget(previousObservations, previousObserverTokens);
+        result.push({ role: 'user', content: preamble + truncated });
+    }
+    // 2. Formatted message history (timestamps from message metadata)
+    const formatted = formatMessagesForObserver(messages);
+    result.push({ role: 'user', content: formatted });
+    // 3. Task instruction
+    result.push({
+        role: 'user',
+        content: 'Extract observations from the message history above. Follow the output format exactly.',
+    });
+    return result;
+}
+/**
+ * Tail-truncate a string to fit within a token budget.
+ *
+ * Keeps the end of the string (most recent observations) and trims
+ * from the beginning if the string exceeds the budget.
+ */
+function tailTruncateToTokenBudget(text, tokenBudget) {
+    const currentTokens = estimateTokens(text);
+    if (currentTokens <= tokenBudget)
+        return text;
+    // Estimate chars to keep (tokens * 4 chars/token approximation)
+    const charsToKeep = tokenBudget * 4;
+    if (charsToKeep >= text.length)
+        return text;
+    const truncated = text.slice(text.length - charsToKeep);
+    // Try to start at a line boundary for cleaner output
+    const firstNewline = truncated.indexOf('\n');
+    if (firstNewline > 0 && firstNewline < truncated.length * 0.2) {
+        return '[...truncated...]\n' + truncated.slice(firstNewline + 1);
+    }
+    return '[...truncated...]\n' + truncated;
+}
+// ---------------------------------------------------------------------------
+// Degenerate Repetition Detection
+// ---------------------------------------------------------------------------
+/**
+ * Check if the output contains degenerate repetition.
+ *
+ * Detects a line appearing 5+ times consecutively, which is a known
+ * failure mode of LLMs under certain conditions (e.g., high temperature,
+ * long context, repetitive input patterns).
+ *
+ * @param text - The text to check for repetition
+ * @returns true if degenerate repetition is detected
+ */
+export function detectDegenerateRepetition(text) {
+    const lines = text.split('\n');
+    if (lines.length < 5)
+        return false;
+    let consecutiveCount = 1;
+    let previousLine = lines[0];
+    for (let i = 1; i < lines.length; i++) {
+        const currentLine = lines[i];
+        // Skip empty lines for comparison
+        if (currentLine.trim() === '' && previousLine.trim() === '') {
+            continue;
+        }
+        if (currentLine === previousLine && currentLine.trim().length > 0) {
+            consecutiveCount++;
+            if (consecutiveCount >= 5)
+                return true;
+        }
+        else {
+            consecutiveCount = 1;
+            previousLine = currentLine;
+        }
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// Runner
+// ---------------------------------------------------------------------------
+/**
+ * Run the observer LLM call to extract observations from messages.
+ *
+ * Orchestrates the full observer pipeline:
+ * 1. Builds the system prompt (with optional custom instructions)
+ * 2. Builds the message array (with previous observations context)
+ * 3. Calls the LLM via `complete`
+ * 4. Parses the structured output
+ * 5. Detects and retries on degenerate repetition (once)
+ *
+ * @param complete - The LLM completion function
+ * @param messages - The conversation messages to observe
+ * @param previousObservations - Previous observations for deduplication
+ * @param config - Observer configuration
+ * @returns Parsed observer output with observations, current task, and suggested response
+ */
+export async function runObserver(complete, messages, previousObservations, config) {
+    const systemPrompt = buildObserverPrompt(previousObservations, config.previousObserverTokens, config.observerInstruction);
+    const observerMessages = buildObserverMessages(messages, previousObservations, config.previousObserverTokens);
+    const raw = await complete({ systemPrompt, messages: observerMessages });
+    const output = parseObserverOutput(raw);
+    // Detect degenerate repetition and retry once
+    if (detectDegenerateRepetition(output.observations)) {
+        const retryRaw = await complete({ systemPrompt, messages: observerMessages });
+        return parseObserverOutput(retryRaw);
+    }
+    return output;
+}
+//# sourceMappingURL=observer.js.map

package/dist/compaction/observational/observer.js.map

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

package/dist/compaction/observational/recall-tool.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Recall tool: search through past conversation history.
+ *
+ * The consumer provides a search function via RecallConfig. This module
+ * wraps it into a CortexTool that the agent can invoke to retrieve
+ * specific details from persisted messages. Observations include
+ * timestamps, enabling temporal anchoring for precise recall queries.
+ *
+ * Reference: docs/cortex/observational-memory-architecture.md (Recall Tool)
+ */
+import type { CortexTool } from '../../tool-contract.js';
+import type { RecallConfig } from './types.js';
+/**
+ * Create a CortexTool that wraps the consumer's recall search function.
+ *
+ * The returned tool lets the agent search through persisted conversation
+ * history using a free-text query and optional time range derived from
+ * observation timestamps.
+ */
+export declare function createRecallTool(recallConfig: RecallConfig): CortexTool<{
+    query: string;
+    timeRange?: {
+        start?: string;
+        end?: string;
+    };
+}, string>;
+//# sourceMappingURL=recall-tool.d.ts.map

package/dist/compaction/observational/recall-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recall-tool.d.ts","sourceRoot":"","sources":["../../../src/compaction/observational/recall-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,YAAY,CAAC;AA0E7D;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,YAAY,EAAE,YAAY,GAAG,UAAU,CAAC;IACvE,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9C,EAAE,MAAM,CAAC,CAgCT"}

package/dist/compaction/observational/recall-tool.js

@@ -0,0 +1,93 @@
+/**
+ * Recall tool: search through past conversation history.
+ *
+ * The consumer provides a search function via RecallConfig. This module
+ * wraps it into a CortexTool that the agent can invoke to retrieve
+ * specific details from persisted messages. Observations include
+ * timestamps, enabling temporal anchoring for precise recall queries.
+ *
+ * Reference: docs/cortex/observational-memory-architecture.md (Recall Tool)
+ */
+import { Type } from 'typebox';
+// ---------------------------------------------------------------------------
+// Schema
+// ---------------------------------------------------------------------------
+const RecallParams = Type.Object({
+    query: Type.String({
+        description: 'What to search for in past conversation history',
+    }),
+    timeRange: Type.Optional(Type.Object({
+        start: Type.Optional(Type.String({ description: 'ISO date string for range start' })),
+        end: Type.Optional(Type.String({ description: 'ISO date string for range end' })),
+    }, {
+        description: 'Optional time range to narrow results. Use timestamps from your observations.',
+    })),
+});
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Maximum number of results to include in the formatted output. */
+const MAX_RESULTS = 10;
+/** Maximum character length per individual result content. */
+const MAX_RESULT_CHARS = 2_000;
+// ---------------------------------------------------------------------------
+// Formatting
+// ---------------------------------------------------------------------------
+function formatResult(result) {
+    const role = result.role ?? result.type;
+    const timestamp = result.timestamp.toISOString();
+    const content = result.content.length > MAX_RESULT_CHARS
+        ? result.content.slice(0, MAX_RESULT_CHARS) + '... (truncated)'
+        : result.content;
+    return `[${role}] (${timestamp}): ${content}`;
+}
+function formatResults(results) {
+    if (results.length === 0) {
+        return 'No results found for your query.';
+    }
+    const limited = results.slice(0, MAX_RESULTS);
+    const lines = limited.map(formatResult);
+    if (results.length > MAX_RESULTS) {
+        lines.push(`\n(${results.length - MAX_RESULTS} additional results omitted)`);
+    }
+    return lines.join('\n\n');
+}
+// ---------------------------------------------------------------------------
+// Tool factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a CortexTool that wraps the consumer's recall search function.
+ *
+ * The returned tool lets the agent search through persisted conversation
+ * history using a free-text query and optional time range derived from
+ * observation timestamps.
+ */
+export function createRecallTool(recallConfig) {
+    return {
+        name: 'recall',
+        description: 'Search through past conversation history for specific details. ' +
+            'Use when your observations mention something but lack the detail needed, ' +
+            'or when you need exact content (code, errors, quotes, URLs). ' +
+            'Include a timeRange from your observation timestamps for precision.',
+        parameters: RecallParams,
+        async execute(params) {
+            const { query, timeRange } = params;
+            // Build the time range object without assigning undefined to optional
+            // properties (exactOptionalPropertyTypes is enabled).
+            let options;
+            if (timeRange) {
+                const range = {};
+                if (timeRange.start) {
+                    range.start = new Date(timeRange.start);
+                }
+                if (timeRange.end) {
+                    range.end = new Date(timeRange.end);
+                }
+                options = { timeRange: range };
+            }
+            const results = await recallConfig.search(query, options);
+            return formatResults(results);
+        },
+    };
+}
+//# sourceMappingURL=recall-tool.js.map