Memory

Memory Lifecycle

Memories are the core learning mechanism. Each step an agent takes is recorded, graded, and stored for future retrieval.

Step-by-Step

initEpisode() — Creates a session context (or resumes an existing one) for the current run
recordStepStart() — Records each agent action with its environment state and internal reasoning
persistMemories() — Converts pending steps into MemoryEntry records and writes to storage
addGradesToMemories() — Applies grading results (correct/incorrect, corrections) to stored memories
retrieveMemories() — On subsequent reps, retrieves relevant memories for the agent's current state

MemoryEntry Schema

Each memory record is validated with Zod:

import { memoryEntrySchema } from "@trayn/memory";

// memoryEntrySchema validates:
interface MemoryEntry {
  id: number;
  stepId?: string;
  envPre: EnvironmentState;          // Page state before action
  internalState: string;             // Agent's reasoning context
  think?: string;                    // Agent's chain-of-thought
  internalStateEmbedding: number[];  // Vector embedding
  action: string;                    // e.g. "click('42')"
  actionElementText: string;         // Semantic description of target
  envPost: EnvironmentState;         // Page state after action
  outcome: "pending" | "success" | "failure";
  outcomeReason?: string;            // Grader's explanation
  correction?: string;               // What should have been done instead
  taskIncomplete?: string;           // Why the overall task failed
  createdAt: number;
  stepNum: number;
  rep: number;
}

Export Formats

Export memories in the format your pipeline needs:

import { exportMemories, loadAllMemoriesForSession } from "@trayn/memory";

const memories = await loadAllMemoriesForSession(sessionId);

// Structured JSON for programmatic use
const json = exportMemories(memories, "json");

// CSV for analysis and dashboards
const csv = exportMemories(memories, "csv");

// REPEAT/AVOID format for injecting into LLM context
const prompt = exportMemories(memories, "prompt");

Prompt Format

The prompt format produces the REPEAT/AVOID text that agents use for learning:

# Lessons From Previous Attempt
These are results from a PREVIOUS attempt at this task.
- REPEAT: actions that worked before — do them again now
- AVOID: mistakes from before — do NOT repeat them

1. REPEAT: [/tickets 85%] click: 'Priority dropdown'
   This worked: Correctly opened the priority selector
2. AVOID: [/tickets 72%] click: 'Delete button'
   This failed: Wrong action — task was to change priority
   Do this instead: Select "High" from the priority dropdown

How Memories Flow Between Reps

Rep 1 always runs without memory retrieval (baseline). Rep 2+ retrieves memories from all previous reps for the same session.