Memory API

The memory interface provides access to historical decisions and similarity search.

ctx.memory.similar()

Finds similar historical decisions.

ctx.memory.similar(params: {
  situation: string;
  context?: Record<string, any>;
  crossWorkflow?: string[];
}): Promise<MemoryInsight[]>

Parameters:

• situation (string) - Situation identifier
• context (Record<string, any>, optional) - Context for similarity matching
• crossWorkflow (string[], optional) - Workflow IDs to search across

Returns: Promise<MemoryInsight[]> - Array of similar decisions

Example:

const insights = await ctx.memory.similar({
  situation: "refund_decision",
  context: {
    amount: ctx.input.amount,
    userTier: ctx.input.userTier
  }
});

if (insights.length > 0) {
  const best = insights[0];
  console.log(best.decision.decision);
  console.log(best.decision.reason);
}

ctx.memory.query()

Queries stored decisions.

ctx.memory.query(params: {
  workflowId?: string;
  stepName?: string;
  decision?: string;
  limit?: number;
}): Promise<StoredDecision[]>

Parameters:

• workflowId (string, optional) - Filter by workflow ID
• stepName (string, optional) - Filter by step name
• decision (string, optional) - Filter by decision value
• limit (number, optional) - Maximum results (default: 10)

Returns: Promise<StoredDecision[]> - Array of stored decisions

Example:

// Query by workflow
const decisions = await ctx.memory.query({
  workflowId: "refund_v1",
  limit: 10
});

// Query by step
const stepDecisions = await ctx.memory.query({
  stepName: "evaluate_risk",
  limit: 20
});

// Query by decision
const approvals = await ctx.memory.query({
  decision: "approve",
  limit: 50
});

MemoryInsight

interface MemoryInsight {
  decision: {
    decision: string;
    reason: string;
    confidence?: number;
  };
  context: {
    input: any;
    state: any;
    metadata?: any;
  };
  outcome?: {
    success: boolean;
    data?: any;
  };
  similarity: number;        // 0-1 similarity score
  timestamp: string;
  workflowId: string;
  stepName: string;
}

StoredDecision

interface StoredDecision {
  decision: {
    decision: string;
    reason: string;
    confidence?: number;
  };
  context: {
    input: any;
    state: any;
    metadata?: any;
  };
  outcome?: {
    success: boolean;
    data?: any;
  };
  timestamp: string;
  workflowId: string;
  stepName: string;
  executionId: string;
}

Complete Example

.step("decide", async (ctx) => {
  // Find similar decisions
  const insights = await ctx.memory.similar({
    situation: "approval_decision",
    context: {
      amount: ctx.input.amount,
      userTier: ctx.input.userTier
    }
  });

  let decision = "approve";
  let reason = "Standard approval";
  let confidence = 0.8;

  // Use best insight
  if (insights.length > 0) {
    const best = insights[0];
    
    // Only use successful outcomes
    if (best.outcome?.success) {
      decision = best.decision.decision;
      reason = `Based on similar decision: ${best.decision.reason}`;
      confidence = Math.min(0.95, (best.decision.confidence || 0.8) + 0.1);
    }
  }

  // Query specific decisions
  const recentApprovals = await ctx.memory.query({
    decision: "approve",
    limit: 10
  });

  return {
    decision,
    reason,
    confidence,
    metadata: {
      similarDecisions: insights.length,
      recentApprovals: recentApprovals.length
    }
  };
}, true)

Best Practices

1. Use Specific Situations

// Good
await ctx.memory.similar({
  situation: "refund_decision_high_amount",
  context: { amount: ctx.input.amount }
});

// Avoid
await ctx.memory.similar({
  situation: "decision",
  context: {}
});

2. Include Relevant Context

await ctx.memory.similar({
  situation: "approval_decision",
  context: {
    amount: ctx.input.amount,
    userTier: ctx.input.userTier,
    urgency: ctx.input.urgency
  }
});

3. Filter by Outcomes

const insights = await ctx.memory.similar({...});
const successful = insights.filter(i => i.outcome?.success);

if (successful.length > 0) {
  // Use successful pattern
}

Next Steps

• Memory Integration - Learn memory patterns
• Workflow API - Workflow methods
• Examples - See memory in action