@deepagents/agent 0.1.2 → 0.2.0

package/dist/index.js

@@ -58,6 +58,106 @@ You are part of a multi-agent system called the DeepAgents SDK, designed to faci
 - Explicitly complete every todo list item and confirm all steps are working before ending your turn. Always follow through on stated actions.
 - You are a highly capable, autonomous agent, and should not require additional user input to fully solve the task.
 `;
+function thirdPersonPrompt(agentName = "this agent", agentRole = "assistant") {
+  return dedent`
+      <your_persona>
+        <persona_context>
+          This agent is ${agentName}, a ${agentRole} that speaks in third person, referring to itself as "this agent" or "${agentName}".
+        </persona_context>
+
+        <persona_speaking_style>
+        - This agent always refers to itself in third person
+        - Use "this agent" or "${agentName}" instead of "I", "me", "my"
+        - Use "This agent found..." instead of "I found..."
+        - Use "This agent recommends..." instead of "I recommend..."
+        - Use "This agent will..." instead of "I will..."
+        - Maintain this style consistently throughout all responses
+        </persona_speaking_style>
+      </your_persona>
+  `;
+}
+var STEM_STEP_BACK_EXAMPLES = [
+  {
+    originalQuestion: "What happens to the pressure, P, of an ideal gas if the temperature is increased by a factor of 2 and the volume is increased by a factor of 8?",
+    stepBackQuestion: "What are the physics principles behind this question?",
+    stepBackAnswer: "The Ideal Gas Law: PV = nRT, where P is pressure, V is volume, n is the number of moles, R is the gas constant, and T is temperature.",
+    finalAnswer: "Using PV = nRT, if T increases by 2x and V increases by 8x, then P = nRT/V = nR(2T)/(8V) = (1/4)(nRT/V). Therefore, pressure decreases to 1/4 of its original value."
+  },
+  {
+    originalQuestion: "If a solution has a pH of 3, how many times more acidic is it than a solution with pH of 6?",
+    stepBackQuestion: "What is the relationship between pH and acidity?",
+    stepBackAnswer: "The pH scale is logarithmic (base 10). pH = -log[H+], meaning each pH unit represents a 10-fold change in hydrogen ion concentration. Lower pH means higher acidity.",
+    finalAnswer: "The difference is 3 pH units. Since pH is logarithmic, this means 10^3 = 1000 times more acidic."
+  }
+];
+var KNOWLEDGE_QA_STEP_BACK_EXAMPLES = [
+  {
+    originalQuestion: "Which school did Estella Leopold attend between August 1954 and November 1954?",
+    stepBackQuestion: "What is Estella Leopold's education history?",
+    stepBackAnswer: "Estella Leopold studied at the University of Wisconsin-Madison (B.S. in Botany, 1948-1952) and later at Yale University (M.S. 1955, Ph.D. 1958). During 1954, she was transitioning between these institutions.",
+    finalAnswer: "Based on her education timeline, between August and November 1954, she was at Yale University, having completed her undergraduate degree at Wisconsin in 1952."
+  },
+  {
+    originalQuestion: "What was the capital of the country that colonized Brazil in the 16th century?",
+    stepBackQuestion: "Which country colonized Brazil and when?",
+    stepBackAnswer: "Portugal colonized Brazil starting in 1500 when Pedro \xC1lvares Cabral arrived. Brazil remained a Portuguese colony until independence in 1822.",
+    finalAnswer: "Portugal colonized Brazil in the 16th century. The capital of Portugal during that period was Lisbon."
+  }
+];
+var GENERAL_STEP_BACK_EXAMPLES = [
+  {
+    originalQuestion: "How should I optimize this specific database query that joins 5 tables?",
+    stepBackQuestion: "What are the general principles of database query optimization?",
+    stepBackAnswer: "Database query optimization involves: 1) Minimizing data retrieval through proper indexing, 2) Reducing join complexity by ordering joins efficiently, 3) Using query execution plans to identify bottlenecks, 4) Ensuring statistics are up-to-date, 5) Considering denormalization when appropriate.",
+    finalAnswer: "Apply these principles: Check if all foreign keys are indexed, analyze the execution plan to see which joins are most expensive, ensure statistics are current, and consider if the join order can be optimized based on table sizes."
+  },
+  {
+    originalQuestion: "Why is my React component re-rendering 10 times on each state update?",
+    stepBackQuestion: "What causes excessive re-renders in React?",
+    stepBackAnswer: "React re-renders occur when: 1) State changes trigger parent components to re-render all children, 2) Props change (including new object/function references), 3) Context values change, 4) Missing memoization (React.memo, useMemo, useCallback).",
+    finalAnswer: "Check if: 1) Parent component is creating new object/function references on each render, 2) The component is consuming context that changes frequently, 3) You need to wrap the component in React.memo or use useMemo/useCallback for props."
+  }
+];
+function stepBackPrompt(domain = "general", options) {
+  const { examples, stepBackQuestionTemplate } = options || {};
+  const domainExamples = examples || (domain === "stem" ? STEM_STEP_BACK_EXAMPLES : domain === "knowledge" ? KNOWLEDGE_QA_STEP_BACK_EXAMPLES : GENERAL_STEP_BACK_EXAMPLES);
+  const defaultTemplate = stepBackQuestionTemplate || (domain === "stem" ? "What are the underlying physics/chemistry/mathematical principles involved in this question?" : domain === "knowledge" ? "What is the broader historical context or background information related to this question?" : "What are the high-level concepts, principles, or patterns underlying this question?");
+  const formattedExamples = domainExamples.map(
+    (example, idx) => dedent`
+      Example ${idx + 1}:
+      Original Question: ${example.originalQuestion}
+      Step-Back Question: ${example.stepBackQuestion}
+      Step-Back Answer: ${example.stepBackAnswer}
+      ${example.finalAnswer ? `Final Answer: ${example.finalAnswer}` : ""}
+    `
+  ).join("\n\n");
+  return dedent`
+    <step_back_prompting>
+    You will use a two-step reasoning process called "Step-Back Prompting" to improve your answer quality.
+
+    ## STEP 1: ABSTRACTION
+    Before answering the user's question directly, first generate and answer a "step-back question" - a higher-level question about the underlying principles or context.
+
+    Step-Back Question Template: "${defaultTemplate}"
+
+    Here are examples of how to create step-back questions:
+
+    ${formattedExamples}
+
+    ## STEP 2: REASONING
+    After you have the step-back answer, use that high-level knowledge to reason about and answer the ORIGINAL question.
+    Ground your reasoning in the principles/context from your step-back answer.
+
+    ## Process to Follow:
+    1. When you receive a question, first formulate and answer a step-back question based on the template and examples above
+    2. Clearly state both the step-back question AND its answer
+    3. Then use that step-back answer as context to solve the original question
+    4. Show how the high-level principles apply to the specific case
+
+    This abstraction-grounded reasoning approach helps you avoid getting lost in specifics and ensures your answer is based on solid foundational understanding.
+    </step_back_prompting>
+  `;
+}
 
 // packages/agent/src/lib/stream_utils.ts
 import {
@@ -325,7 +425,7 @@ import chalk from "chalk";
 import dedent2 from "dedent";
 import { zodToJsonSchema } from "zod-to-json-schema";
 function generate(agent2, messages, contextVariables, config) {
-  return generateText({
+  const result = generateText({
     abortSignal: config?.abortSignal,
     providerOptions: agent2.providerOptions ?? config?.providerOptions,
     model: agent2.model,
@@ -354,10 +454,11 @@ function generate(agent2, messages, contextVariables, config) {
     //   (contextVariables as any).content = result.content;
     // },
   });
+  return Object.assign(result, { state: contextVariables });
 }
 function execute(agent2, messages, contextVariables, config) {
   const runId = generateId2();
-  return streamText({
+  const stream2 = streamText({
     abortSignal: config?.abortSignal,
     providerOptions: config?.providerOptions,
     model: agent2.model,
@@ -397,6 +498,7 @@ function execute(agent2, messages, contextVariables, config) {
     //   (contextVariables as any).content = result.content;
     // },
   });
+  return Object.assign(stream2, { state: contextVariables });
 }
 var stream = execute;
 var prepareStep = (agent2, model, contextVariables) => {
@@ -532,10 +634,10 @@ var repairToolCall = async ({
   console.log(
     `Debug: ${chalk.yellow("RepairingToolCall")}: ${toolCall.toolName}`
   );
-  const tool2 = tools[toolCall.toolName];
+  const tool3 = tools[toolCall.toolName];
   const { experimental_output } = await generateText({
     model: groq("openai/gpt-oss-20b"),
-    experimental_output: Output.object({ schema: tool2.inputSchema }),
+    experimental_output: Output.object({ schema: tool3.inputSchema }),
     prompt: [
       `The model tried to call the tool "${toolCall.toolName}" with the following inputs:`,
       JSON.stringify(toolCall.input),
@@ -747,7 +849,9 @@ ${JSON.stringify(error)}
       name: agent2?.name ?? this.handoff.name,
       handoffDescription: agent2?.handoffDescription ?? this.handoff.handoffDescription,
       handoffs: [...this.handoffs],
-      output: agent2?.output ?? this.output
+      output: agent2?.output ?? this.output,
+      temperature: agent2?.temperature ?? this.temperature,
+      providerOptions: agent2?.providerOptions ?? this.providerOptions
     });
   }
 };
@@ -884,12 +988,931 @@ function lastTransferResult(messages) {
   return void 0;
 }
 
+// packages/agent/src/lib/memory.ts
+import { tool as tool2 } from "ai";
+import Conf from "conf";
+import { z as z2 } from "zod";
+var MemoryStore = class {
+  store;
+  constructor(name = "agent-memory") {
+    this.store = new Conf({
+      projectName: name,
+      schema: {
+        memories: {
+          type: "object",
+          default: {}
+        },
+        relationships: {
+          type: "object",
+          default: {}
+        },
+        metadata: {
+          type: "object",
+          default: {
+            lastConsolidation: Date.now(),
+            totalAccesses: 0
+          }
+        }
+      }
+    });
+  }
+  /**
+   * Generate a unique memory ID
+   */
+  generateId() {
+    return `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+  /**
+   * Calculate memory decay based on time and access patterns
+   */
+  calculateDecay(memory) {
+    const now = Date.now();
+    const age = now - memory.timestamp;
+    const timeSinceAccess = now - memory.lastAccessed;
+    const daysSinceCreation = age / (1e3 * 60 * 60 * 24);
+    const daysSinceAccess = timeSinceAccess / (1e3 * 60 * 60 * 24);
+    const accessBonus = Math.log(memory.accessCount + 1) * 0.1;
+    const importanceBonus = memory.importance * 0.05;
+    const decay = Math.max(
+      0.1,
+      1 - (daysSinceCreation * 0.05 + daysSinceAccess * 0.08 - accessBonus - importanceBonus)
+    );
+    return Math.min(1, decay);
+  }
+  /**
+   * Store a new memory
+   */
+  write(entry) {
+    const id = this.generateId();
+    const now = Date.now();
+    const memory = {
+      ...entry,
+      id,
+      timestamp: now,
+      accessCount: 0,
+      lastAccessed: now,
+      decay: 1
+    };
+    const memories = this.store.get("memories");
+    memories[id] = memory;
+    this.store.set("memories", memories);
+    if (entry.relationships && entry.relationships.length > 0) {
+      const relationships = this.store.get("relationships");
+      for (const relatedId of entry.relationships) {
+        if (!relationships[relatedId]) {
+          relationships[relatedId] = [];
+        }
+        if (!relationships[relatedId].includes(id)) {
+          relationships[relatedId].push(id);
+        }
+      }
+      this.store.set("relationships", relationships);
+    }
+    return memory;
+  }
+  /**
+   * Retrieve a memory by ID
+   */
+  get(id) {
+    const memories = this.store.get("memories");
+    const memory = memories[id];
+    if (!memory) {
+      return null;
+    }
+    memory.accessCount++;
+    memory.lastAccessed = Date.now();
+    memory.decay = this.calculateDecay(memory);
+    memories[id] = memory;
+    this.store.set("memories", memories);
+    const metadata = this.store.get("metadata");
+    metadata.totalAccesses++;
+    this.store.set("metadata", metadata);
+    return memory;
+  }
+  /**
+   * Search memories based on query
+   */
+  lookup(query) {
+    const memories = Object.values(this.store.get("memories"));
+    let results = memories;
+    if (query.type) {
+      results = results.filter((m) => m.type === query.type);
+    }
+    if (query.minImportance !== void 0) {
+      results = results.filter((m) => m.importance >= query.minImportance);
+    }
+    if (query.tags && query.tags.length > 0) {
+      results = results.filter(
+        (m) => query.tags.some((tag) => m.tags.includes(tag))
+      );
+    }
+    if (query.timeRange) {
+      if (query.timeRange.start) {
+        results = results.filter((m) => m.timestamp >= query.timeRange.start);
+      }
+      if (query.timeRange.end) {
+        results = results.filter((m) => m.timestamp <= query.timeRange.end);
+      }
+    }
+    const searchTerms = query.query.toLowerCase().split(" ");
+    results = results.filter((m) => {
+      const content = m.content.toLowerCase();
+      const tags = m.tags.join(" ").toLowerCase();
+      return searchTerms.some(
+        (term) => content.includes(term) || tags.includes(term)
+      );
+    });
+    results = results.map((m) => ({
+      ...m,
+      decay: this.calculateDecay(m)
+    }));
+    results.sort((a, b) => {
+      const scoreA = (a.decay || 0) * a.importance * (1 + Math.log(a.accessCount + 1));
+      const scoreB = (b.decay || 0) * b.importance * (1 + Math.log(b.accessCount + 1));
+      return scoreB - scoreA;
+    });
+    const limit = query.limit || 10;
+    return results.slice(0, limit);
+  }
+  /**
+   * Update an existing memory
+   */
+  correct(id, updates) {
+    const memories = this.store.get("memories");
+    const memory = memories[id];
+    if (!memory) {
+      return null;
+    }
+    const updated = {
+      ...memory,
+      ...updates,
+      id: memory.id,
+      // Preserve ID
+      timestamp: memory.timestamp,
+      // Preserve original timestamp
+      lastAccessed: Date.now(),
+      accessCount: memory.accessCount + 1
+    };
+    updated.decay = this.calculateDecay(updated);
+    memories[id] = updated;
+    this.store.set("memories", memories);
+    return updated;
+  }
+  /**
+   * Delete a memory (forget)
+   */
+  forget(id) {
+    const memories = this.store.get("memories");
+    if (!memories[id]) {
+      return false;
+    }
+    delete memories[id];
+    this.store.set("memories", memories);
+    const relationships = this.store.get("relationships");
+    delete relationships[id];
+    for (const [key, refs] of Object.entries(relationships)) {
+      relationships[key] = refs.filter((ref) => ref !== id);
+    }
+    this.store.set("relationships", relationships);
+    return true;
+  }
+  /**
+   * Get related memories
+   */
+  getRelated(id, limit = 5) {
+    const relationships = this.store.get("relationships");
+    const relatedIds = relationships[id] || [];
+    const memories = this.store.get("memories");
+    const relatedMemories = relatedIds.map((relId) => memories[relId]).filter(Boolean).slice(0, limit);
+    return relatedMemories;
+  }
+  /**
+   * Get memory statistics
+   */
+  getStats() {
+    const memories = Object.values(this.store.get("memories"));
+    const byType = memories.reduce(
+      (acc, m) => {
+        acc[m.type] = (acc[m.type] || 0) + 1;
+        return acc;
+      },
+      {}
+    );
+    const mostAccessed = [...memories].sort((a, b) => b.accessCount - a.accessCount).slice(0, 10);
+    const recentMemories = [...memories].sort((a, b) => b.timestamp - a.timestamp).slice(0, 10);
+    const averageImportance = memories.length > 0 ? memories.reduce((sum, m) => sum + m.importance, 0) / memories.length : 0;
+    return {
+      totalMemories: memories.length,
+      byType,
+      mostAccessed,
+      recentMemories,
+      averageImportance
+    };
+  }
+  /**
+   * Consolidate memories (prune low-importance, rarely accessed memories)
+   */
+  consolidate(threshold = 0.2) {
+    const memories = this.store.get("memories");
+    const entries = Object.entries(memories);
+    let pruned = 0;
+    for (const [id, memory] of entries) {
+      const decay = this.calculateDecay(memory);
+      if (decay < threshold && memory.importance < 5) {
+        delete memories[id];
+        pruned++;
+      }
+    }
+    if (pruned > 0) {
+      this.store.set("memories", memories);
+      const metadata = this.store.get("metadata");
+      metadata.lastConsolidation = Date.now();
+      this.store.set("metadata", metadata);
+    }
+    return pruned;
+  }
+  /**
+   * Clear all memories
+   */
+  clear() {
+    this.store.clear();
+  }
+  /**
+   * Export all memories
+   */
+  export() {
+    return this.store.get("memories");
+  }
+  /**
+   * Import memories
+   */
+  import(memories) {
+    this.store.set("memories", memories);
+  }
+  // ============================================================================
+  // Specialized Write Functions - High-level convenience methods
+  // ============================================================================
+  /**
+   * Write a semantic memory (facts, concepts, general knowledge)
+   *
+   * @example
+   * store.writeSemantic("React is a JavaScript library for building UIs", {
+   *   tags: ["react", "javascript"],
+   *   importance: 8
+   * });
+   */
+  writeSemantic(content, options) {
+    return this.write({
+      content,
+      type: "semantic",
+      importance: options?.importance ?? 7,
+      // Default to 7 for facts
+      tags: options?.tags ?? [],
+      context: options?.context,
+      relationships: options?.relationships
+    });
+  }
+  /**
+   * Write an episodic memory (events, conversations, experiences)
+   *
+   * @example
+   * store.writeEpisodic("User completed onboarding", {
+   *   tags: ["milestone", "user123"],
+   *   context: { userId: "user123", timestamp: Date.now() }
+   * });
+   */
+  writeEpisodic(content, options) {
+    return this.write({
+      content,
+      type: "episodic",
+      importance: options?.importance ?? 6,
+      // Default to 6 for events
+      tags: options?.tags ?? [],
+      context: {
+        ...options?.context,
+        timestamp: options?.context?.timestamp ?? Date.now()
+      },
+      relationships: options?.relationships
+    });
+  }
+  /**
+   * Write a procedural memory (patterns, behaviors, methods)
+   *
+   * @example
+   * store.writeProcedural("When user asks for help, first check documentation", {
+   *   tags: ["pattern", "help"],
+   *   importance: 7
+   * });
+   */
+  writeProcedural(content, options) {
+    return this.write({
+      content,
+      type: "procedural",
+      importance: options?.importance ?? 7,
+      // Default to 7 for patterns
+      tags: options?.tags ?? [],
+      context: options?.context,
+      relationships: options?.relationships
+    });
+  }
+  /**
+   * Store a user preference (convenience wrapper for semantic memory)
+   *
+   * @example
+   * store.storePreference("user123", "theme", "dark");
+   */
+  storePreference(userId, preference, value, importance = 8) {
+    return this.writeSemantic(
+      `User ${userId} prefers ${preference}: ${typeof value === "object" ? JSON.stringify(value) : value}`,
+      {
+        importance,
+        tags: ["preference", userId, preference],
+        context: {
+          userId,
+          preference,
+          value,
+          category: "user-preference"
+        }
+      }
+    );
+  }
+  /**
+   * Record a conversation exchange (convenience wrapper for episodic memory)
+   *
+   * @example
+   * store.recordConversation("user123", "session456", "user", "How do I use React hooks?");
+   */
+  recordConversation(userId, sessionId, role, message, importance = 5) {
+    return this.writeEpisodic(`[${role}]: ${message}`, {
+      importance,
+      tags: ["conversation", userId, sessionId, role],
+      context: {
+        userId,
+        sessionId,
+        role,
+        timestamp: Date.now(),
+        category: "conversation"
+      }
+    });
+  }
+  /**
+   * Record a user action/event (convenience wrapper for episodic memory)
+   *
+   * @example
+   * store.recordAction("user123", "completed_tutorial", { tutorialId: "intro" });
+   */
+  recordAction(userId, action, details, importance = 6) {
+    return this.writeEpisodic(`User ${userId} performed action: ${action}`, {
+      importance,
+      tags: ["action", userId, action],
+      context: {
+        userId,
+        action,
+        details,
+        timestamp: Date.now(),
+        category: "user-action"
+      }
+    });
+  }
+  /**
+   * Learn a pattern from observations (convenience wrapper for procedural memory)
+   *
+   * @example
+   * store.learnPattern("optimization-workflow", "Profile before optimizing", {
+   *   conditions: "Performance issues reported",
+   *   relatedMemories: ["mem_123"]
+   * });
+   */
+  learnPattern(patternName, description, options) {
+    return this.writeProcedural(`Pattern [${patternName}]: ${description}`, {
+      importance: options?.importance ?? 7,
+      tags: ["pattern", "learned", patternName],
+      context: {
+        patternName,
+        conditions: options?.conditions,
+        category: "learned-pattern",
+        ...options?.context
+      },
+      relationships: options?.relatedMemories
+    });
+  }
+  /**
+   * Store a fact or knowledge (convenience wrapper for semantic memory)
+   *
+   * @example
+   * store.storeFact("JavaScript", "JavaScript is a programming language", {
+   *   source: "documentation",
+   *   relatedTo: ["mem_456"]
+   * });
+   */
+  storeFact(topic, fact, options) {
+    return this.writeSemantic(fact, {
+      importance: options?.importance ?? 7,
+      tags: ["fact", "knowledge", topic, ...options?.tags ?? []],
+      context: {
+        topic,
+        source: options?.source,
+        category: "fact"
+      },
+      relationships: options?.relatedTo
+    });
+  }
+  /**
+   * Record a milestone or achievement (convenience wrapper for episodic memory)
+   *
+   * @example
+   * store.recordMilestone("user123", "first-project-completed", "User completed their first project");
+   */
+  recordMilestone(userId, milestoneType, description, importance = 7) {
+    return this.writeEpisodic(description, {
+      importance,
+      tags: ["milestone", userId, milestoneType],
+      context: {
+        userId,
+        milestoneType,
+        timestamp: Date.now(),
+        category: "milestone"
+      }
+    });
+  }
+  /**
+   * Store contextual information about current session (working memory)
+   * Note: These should have lower importance as they're temporary
+   *
+   * @example
+   * store.storeSessionContext("session456", "user-preferences-loaded", { theme: "dark" });
+   */
+  storeSessionContext(sessionId, contextKey, data, importance = 4) {
+    return this.writeEpisodic(`Session context [${contextKey}]`, {
+      importance,
+      tags: ["session", "working-memory", sessionId, contextKey],
+      context: {
+        sessionId,
+        contextKey,
+        data,
+        category: "session-context",
+        timestamp: Date.now()
+      }
+    });
+  }
+  // ============================================================================
+  // Proactive Memory Loading - Auto-inject memories into system prompt
+  // ============================================================================
+  /**
+   * Get proactive memories that should always be present in system prompt
+   * These are high-importance memories that provide essential context
+   *
+   * @param options Configuration for proactive memory retrieval
+   * @returns Formatted string ready for system prompt injection
+   *
+   * @example
+   * const memoryContext = memoryStore.getProactiveMemories({
+   *   userId: 'user123',
+   *   minImportance: 7,
+   *   categories: ['preference', 'core-knowledge']
+   * });
+   *
+   * // Use in agent:
+   * const systemPrompt = `${basePrompt}\n\n${memoryContext}`;
+   */
+  getProactiveMemories(options) {
+    const {
+      userId,
+      sessionId,
+      minImportance = 7,
+      // High importance by default
+      categories = [],
+      maxMemories = 10,
+      types,
+      includeRelationships = false
+    } = options;
+    const tags = [];
+    if (userId) tags.push(userId);
+    if (sessionId) tags.push(sessionId);
+    if (categories.length > 0) tags.push(...categories);
+    const memoriesByType = {
+      semantic: [],
+      procedural: [],
+      episodic: []
+    };
+    const typesToFetch = types || ["semantic", "procedural", "episodic"];
+    for (const type of typesToFetch) {
+      const memories = this.lookup({
+        query: "",
+        // Empty query to get all matching filters
+        type,
+        minImportance,
+        tags: tags.length > 0 ? tags : void 0,
+        limit: maxMemories
+      });
+      memoriesByType[type] = memories;
+    }
+    return this.formatProactiveMemories(memoriesByType, includeRelationships);
+  }
+  /**
+   * Format proactive memories into a structured system prompt section
+   */
+  formatProactiveMemories(memoriesByType, includeRelationships) {
+    const sections = [];
+    if (memoriesByType.semantic.length > 0) {
+      sections.push("## Core Knowledge & Preferences");
+      sections.push("");
+      memoriesByType.semantic.forEach((mem, idx) => {
+        sections.push(`${idx + 1}. ${mem.content}`);
+        if (mem.context?.preference) {
+          sections.push(`   - Preference: ${mem.context.preference}`);
+        }
+        if (mem.context?.source) {
+          sections.push(`   - Source: ${mem.context.source}`);
+        }
+      });
+      sections.push("");
+    }
+    if (memoriesByType.procedural.length > 0) {
+      sections.push("## Behavioral Patterns & Guidelines");
+      sections.push("");
+      memoriesByType.procedural.forEach((mem, idx) => {
+        sections.push(`${idx + 1}. ${mem.content}`);
+        if (mem.context?.conditions) {
+          sections.push(`   - When: ${mem.context.conditions}`);
+        }
+        if (mem.context?.patternName) {
+          sections.push(`   - Pattern: ${mem.context.patternName}`);
+        }
+      });
+      sections.push("");
+    }
+    if (memoriesByType.episodic.length > 0) {
+      sections.push("## Recent Context & History");
+      sections.push("");
+      memoriesByType.episodic.forEach((mem, idx) => {
+        const timeAgo = this.formatTimeAgo(Date.now() - mem.timestamp);
+        sections.push(`${idx + 1}. ${mem.content} (${timeAgo})`);
+        if (mem.context?.milestoneType) {
+          sections.push(`   - Milestone: ${mem.context.milestoneType}`);
+        }
+      });
+      sections.push("");
+    }
+    if (sections.length === 0) {
+      return "";
+    }
+    return [
+      "",
+      "# Proactive Memory Context",
+      "The following information has been retrieved from memory to provide you with essential context:",
+      "",
+      ...sections
+    ].join("\n");
+  }
+  /**
+   * Helper to format time ago for human readability
+   */
+  formatTimeAgo(ms) {
+    const seconds = Math.floor(ms / 1e3);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0) return `${days}d ago`;
+    if (hours > 0) return `${hours}h ago`;
+    if (minutes > 0) return `${minutes}m ago`;
+    return `${seconds}s ago`;
+  }
+  /**
+   * Get user-specific proactive memories
+   * Convenience method that focuses on user preferences and patterns
+   *
+   * @example
+   * const userContext = memoryStore.getUserProactiveMemories('user123');
+   */
+  getUserProactiveMemories(userId, options) {
+    const {
+      includePreferences = true,
+      includePatterns = true,
+      includeRecentHistory = true,
+      maxPerCategory = 5
+    } = options || {};
+    const types = [];
+    const categories = [];
+    if (includePreferences) {
+      types.push("semantic");
+      categories.push("preference");
+    }
+    if (includePatterns) {
+      types.push("procedural");
+      categories.push("pattern");
+    }
+    if (includeRecentHistory) {
+      types.push("episodic");
+      categories.push("milestone", "action");
+    }
+    return this.getProactiveMemories({
+      userId,
+      minImportance: 7,
+      categories,
+      maxMemories: maxPerCategory * types.length,
+      types: types.length > 0 ? types : void 0
+    });
+  }
+  /**
+   * Get session-specific proactive memories
+   * Focuses on working memory and recent context
+   *
+   * @example
+   * const sessionContext = memoryStore.getSessionProactiveMemories('session456');
+   */
+  getSessionProactiveMemories(sessionId, options) {
+    const { includeWorkingMemory = true, maxMemories = 10 } = options || {};
+    const categories = includeWorkingMemory ? ["session", "working-memory", "conversation"] : ["session", "conversation"];
+    return this.getProactiveMemories({
+      sessionId,
+      minImportance: 4,
+      // Lower threshold for session context
+      categories,
+      maxMemories,
+      types: ["episodic"]
+    });
+  }
+  /**
+   * Get critical memories that should ALWAYS be present
+   * These are importance level 9-10 memories
+   *
+   * @example
+   * const criticalContext = memoryStore.getCriticalMemories();
+   */
+  getCriticalMemories(options) {
+    return this.getProactiveMemories({
+      userId: options?.userId,
+      minImportance: 9,
+      maxMemories: options?.maxMemories || 5,
+      types: ["semantic", "procedural"]
+    });
+  }
+  /**
+   * Build complete proactive context for an agent
+   * Combines critical, user-specific, and session-specific memories
+   *
+   * @example
+   * const fullContext = memoryStore.buildProactiveContext({
+   *   userId: 'user123',
+   *   sessionId: 'session456'
+   * });
+   *
+   * // Use in agent system prompt
+   * const systemPrompt = `${basePrompt}\n\n${fullContext}`;
+   */
+  buildProactiveContext(options) {
+    const {
+      userId,
+      sessionId,
+      includeCritical = true,
+      includeUser = true,
+      includeSession = true
+    } = options;
+    const sections = [];
+    if (includeCritical) {
+      const critical = this.getCriticalMemories({ userId });
+      if (critical) sections.push(critical);
+    }
+    if (includeUser && userId) {
+      const userContext = this.getUserProactiveMemories(userId);
+      if (userContext) sections.push(userContext);
+    }
+    if (includeSession && sessionId) {
+      const sessionContext = this.getSessionProactiveMemories(sessionId);
+      if (sessionContext) sections.push(sessionContext);
+    }
+    return sections.join("\n\n");
+  }
+};
+var memoryStore = new MemoryStore();
+var memoryLookup = tool2({
+  description: `Search and retrieve memories from the memory store.
+    Use this to recall past conversations, learned facts, or previous interactions.
+    Memories decay over time but are reinforced through repeated access.`,
+  inputSchema: z2.object({
+    query: z2.string().describe("Search query to find relevant memories"),
+    type: z2.enum(["episodic", "semantic", "procedural"]).optional().describe("Type of memory to search"),
+    limit: z2.number().int().positive().max(50).default(10).describe("Maximum number of memories to retrieve"),
+    minImportance: z2.number().min(1).max(10).optional().describe("Minimum importance level (1-10)"),
+    tags: z2.array(z2.string()).optional().describe("Filter by tags")
+  }),
+  execute: async ({ query, type, limit, minImportance, tags }) => {
+    console.log("Memory lookup:", { query, type, limit, minImportance, tags });
+    const results = memoryStore.lookup({
+      query,
+      type,
+      limit,
+      minImportance,
+      tags
+    });
+    return {
+      count: results.length,
+      memories: results.map((m) => ({
+        id: m.id,
+        content: m.content,
+        type: m.type,
+        importance: m.importance,
+        tags: m.tags,
+        timestamp: new Date(m.timestamp).toISOString(),
+        accessCount: m.accessCount,
+        decay: m.decay?.toFixed(2),
+        context: m.context
+      }))
+    };
+  }
+});
+var memoryExplain = tool2({
+  description: `Get detailed information about a specific memory, including its relationships,
+    access history, and decay status. Use this to understand the context and relevance of a memory.`,
+  inputSchema: z2.object({
+    id: z2.string().describe("The unique identifier of the memory to explain"),
+    includeRelated: z2.boolean().default(true).describe("Include related memories in the explanation")
+  }),
+  execute: async ({ id, includeRelated }) => {
+    console.log("Memory explain:", { id, includeRelated });
+    const memory = memoryStore.get(id);
+    if (!memory) {
+      return {
+        found: false,
+        message: `No memory found with ID: ${id}`
+      };
+    }
+    const related = includeRelated ? memoryStore.getRelated(id) : [];
+    return {
+      found: true,
+      memory: {
+        id: memory.id,
+        content: memory.content,
+        type: memory.type,
+        importance: memory.importance,
+        tags: memory.tags,
+        timestamp: new Date(memory.timestamp).toISOString(),
+        lastAccessed: new Date(memory.lastAccessed).toISOString(),
+        accessCount: memory.accessCount,
+        decay: memory.decay?.toFixed(2),
+        context: memory.context,
+        age: {
+          days: Math.floor(
+            (Date.now() - memory.timestamp) / (1e3 * 60 * 60 * 24)
+          ),
+          hours: Math.floor((Date.now() - memory.timestamp) / (1e3 * 60 * 60))
+        },
+        timeSinceAccess: {
+          days: Math.floor(
+            (Date.now() - memory.lastAccessed) / (1e3 * 60 * 60 * 24)
+          ),
+          hours: Math.floor(
+            (Date.now() - memory.lastAccessed) / (1e3 * 60 * 60)
+          )
+        }
+      },
+      related: related.map((r) => ({
+        id: r.id,
+        content: r.content.substring(0, 100) + (r.content.length > 100 ? "..." : ""),
+        type: r.type,
+        importance: r.importance
+      }))
+    };
+  }
+});
+var memoryWrite = tool2({
+  description: `Store a new memory in the memory system. Use this to remember important facts,
+    events, or learnings. Choose the appropriate memory type:
+    - episodic: Events, conversations, experiences with temporal context
+    - semantic: Facts, concepts, general knowledge
+    - procedural: Patterns, methods, learned behaviors`,
+  inputSchema: z2.object({
+    content: z2.string().describe("The content of the memory to store"),
+    type: z2.enum(["episodic", "semantic", "procedural"]).describe("Type of memory"),
+    importance: z2.number().min(1).max(10).default(5).describe("Importance level (1-10), affects retention"),
+    tags: z2.array(z2.string()).default([]).describe("Tags for categorization and retrieval"),
+    context: z2.record(z2.any(), z2.any()).optional().describe("Additional context metadata"),
+    relationships: z2.array(z2.string()).optional().describe("IDs of related memories")
+  }),
+  execute: async ({
+    content,
+    type,
+    importance,
+    tags,
+    context,
+    relationships
+  }) => {
+    console.log("Memory write:", { content, type, importance, tags });
+    const memory = memoryStore.write({
+      content,
+      type,
+      importance,
+      tags,
+      context,
+      relationships
+    });
+    return {
+      success: true,
+      id: memory.id,
+      message: "Memory stored successfully",
+      memory: {
+        id: memory.id,
+        type: memory.type,
+        importance: memory.importance,
+        timestamp: new Date(memory.timestamp).toISOString()
+      }
+    };
+  }
+});
+var memoryForget = tool2({
+  description: `Delete a memory from the memory store. Use this to remove outdated,
+    incorrect, or irrelevant memories. This action is irreversible.`,
+  inputSchema: z2.object({
+    id: z2.string().describe("The unique identifier of the memory to forget"),
+    reason: z2.string().optional().describe("Optional reason for forgetting")
+  }),
+  execute: async ({ id, reason }) => {
+    console.log("Memory forget:", { id, reason });
+    const success = memoryStore.forget(id);
+    return {
+      success,
+      message: success ? `Memory ${id} has been forgotten${reason ? `: ${reason}` : ""}` : `No memory found with ID: ${id}`
+    };
+  }
+});
+var memoryCorrect = tool2({
+  description: `Update or correct an existing memory. Use this to fix errors,
+    add new information, or adjust importance levels. The original timestamp is preserved.`,
+  inputSchema: z2.object({
+    id: z2.string().describe("The unique identifier of the memory to correct"),
+    updates: z2.object({
+      content: z2.string().optional().describe("Updated content"),
+      importance: z2.number().min(1).max(10).optional().describe("Updated importance"),
+      tags: z2.array(z2.string()).optional().describe("Updated tags"),
+      context: z2.record(z2.any(), z2.any()).optional().describe("Updated context"),
+      relationships: z2.array(z2.string()).optional().describe("Updated relationships")
+    }),
+    correctionNote: z2.string().optional().describe("Note explaining the correction")
+  }),
+  execute: async ({ id, updates, correctionNote }) => {
+    console.log("Memory correct:", { id, updates, correctionNote });
+    const memory = memoryStore.correct(id, updates);
+    if (!memory) {
+      return {
+        success: false,
+        message: `No memory found with ID: ${id}`
+      };
+    }
+    return {
+      success: true,
+      message: `Memory ${id} has been updated${correctionNote ? `: ${correctionNote}` : ""}`,
+      memory: {
+        id: memory.id,
+        content: memory.content,
+        type: memory.type,
+        importance: memory.importance,
+        lastAccessed: new Date(memory.lastAccessed).toISOString()
+      }
+    };
+  }
+});
+var memoryStats = tool2({
+  description: `Get statistics about the memory system, including total memories,
+    distribution by type, most accessed memories, and recent memories.`,
+  inputSchema: z2.object({}),
+  execute: async () => {
+    console.log("Memory stats requested");
+    const stats = memoryStore.getStats();
+    return {
+      total: stats.totalMemories,
+      byType: stats.byType,
+      averageImportance: stats.averageImportance.toFixed(2),
+      mostAccessed: stats.mostAccessed.slice(0, 5).map((m) => ({
+        id: m.id,
+        content: m.content.substring(0, 50) + "...",
+        accessCount: m.accessCount,
+        type: m.type
+      })),
+      recent: stats.recentMemories.slice(0, 5).map((m) => ({
+        id: m.id,
+        content: m.content.substring(0, 50) + "...",
+        timestamp: new Date(m.timestamp).toISOString(),
+        type: m.type
+      }))
+    };
+  }
+});
+var memoryTools = {
+  memoryLookup,
+  memoryExplain,
+  memoryWrite,
+  memoryForget,
+  memoryCorrect,
+  memoryStats
+};
+
 // packages/agent/src/lib/models.ts
 import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 import { embedMany } from "ai";
 var lmstudio = createOpenAICompatible({
   name: "lmstudio",
-  baseURL: "http://127.0.0.1:1234/v1",
+  baseURL: process.env.LM_STUDIO_BASE_URL ?? "http://127.0.0.1:1234/v1",
   supportsStructuredOutputs: true,
   includeUsage: true
 });
@@ -907,8 +1930,70 @@ async function embed(documents) {
   });
   return { embeddings, dimensions };
 }
+
+// packages/agent/src/lib/pipe.ts
+import { createUIMessageStream as createUIMessageStream2, generateId as generateId3 } from "ai";
+function pipe(state, ...processes) {
+  return () => {
+    return createUIMessageStream2({
+      originalMessages: state.messages,
+      generateId: generateId3,
+      onError(error) {
+        console.error("Error in pipe execution:", error);
+        return " An error occurred during processing. ";
+      },
+      execute: async ({ writer }) => {
+        for (const it of processes) {
+          if (it instanceof Agent) {
+            const result = execute(it, state.messages, state);
+            writer.merge(
+              result.toUIMessageStream({
+                generateMessageId: generateId3,
+                originalMessages: state.messages,
+                onFinish: async ({ responseMessage }) => {
+                  state.messages.push(responseMessage);
+                }
+              })
+            );
+            await result.consumeStream();
+          } else {
+            const output = await it(state, (newState) => {
+              Object.assign(
+                state,
+                newState
+              );
+            });
+            if (typeof output === "string") {
+              writer.write({
+                id: generateId3(),
+                type: "text-start"
+              });
+              writer.write({
+                id: generateId3(),
+                type: "text-delta",
+                delta: output
+              });
+              writer.write({
+                id: generateId3(),
+                type: "text-end"
+              });
+            } else {
+              writer.merge(output);
+            }
+          }
+        }
+      }
+    });
+  };
+}
 export {
   Agent,
+  GENERAL_STEP_BACK_EXAMPLES,
+  KNOWLEDGE_QA_STEP_BACK_EXAMPLES,
+  MemoryStore,
+  RECOMMENDED_PROMPT_PREFIX,
+  STEM_STEP_BACK_EXAMPLES,
+  SUPERVISOR_PROMPT_PREFIX,
   agent,
   confirm,
   embed,
@@ -922,13 +2007,24 @@ export {
   last,
   lastTransferResult,
   lmstudio,
+  memoryCorrect,
+  memoryExplain,
+  memoryForget,
+  memoryLookup,
+  memoryStats,
+  memoryStore,
+  memoryTools,
+  memoryWrite,
   messageToUiMessage,
+  pipe,
   prepareAgent,
   prepareStep,
   printer,
+  stepBackPrompt,
   stream,
   streamWrite,
   swarm,
+  thirdPersonPrompt,
   toOutput,
   toState,
   user