Memory & recall

Vadyl agent memory is immutable with supersession. Facts are recorded as durable entities; new facts can supersede old ones without erasing them. The history of what the agent knew at any point in time is reconstructable and auditable. Hard delete is reserved for legal compliance — performed by an explicit retention sweeper, never by the agent itself.

Why immutable

An agent's reasoning trace is only meaningful if you can reproduce the inputs that drove it. If memory is overwritable in place, the reasoning trace becomes paper — "here's what I thought, but the facts I based it on are gone." Immutable memory with explicit supersession preserves the auditable record.

Memory namespaces

Memory is organized into typed namespaces, each with its own scope and retention policy:

// Per-user memory for a personalized agent
memory: agent.memory.scopedTo("ctx.userId", { tier: "long-term" }),

// Per-organization memory shared across agents
memory: agent.memory.scopedTo("ctx.orgId", { tier: "long-term", crossAgent: true }),

// Ephemeral working memory for a single run
memory: agent.memory.scopedTo("ctx.runId", { tier: "ephemeral" }),

Fact lifecycle

// Record a fact
await ctx.memory.record({
  kind:    "preference",
  subject: ctx.userId,
  body:    { theme: "dark", timezone: "America/New_York" },
});

// Supersede an existing fact
await ctx.memory.supersede({
  factId:  prevFactId,
  newBody: { theme: "system", timezone: "America/Los_Angeles" },
});

// Recall facts by predicate
const prefs = await ctx.memory.recall({
  kind:    "preference",
  subject: ctx.userId,
  asOf:    "now",       // or a specific timestamp for replay
});

Supersession, not deletion

Calling supersede sets the previous fact's ValidUntil timestamp and links SupersededByFactId to the new fact. The row stays queryable for audit; just stops appearing in current recall.

Calling invalidate sets ValidUntil to now without recording a successor — the fact stops applying but remains for audit.

Recall ranking

Recall combines:

• Vector similarity (when the agent's recall query is embedded against the corpus).
• Recency (newer facts rank higher).
• Source authority (higher-trust source ranks higher).
• Validity window (only facts valid at the recall timestamp).

Recall journal

Every recall produces a RecallJournal entry: which query, which facts came back, with what scores, at what time. Combined with the agent's plan / step trace, this lets you replay exactly what the agent saw before each decision.

Retention and compliance

Each namespace declares a retention policy. The retention sweeper respects:

• retentionDays — facts older than this and superseded are eligible for hard delete.
• legalDeleteAt — explicit legal-hold timestamp; bypasses retention.
• complianceClass — typed classification (PII, PHI, financial, etc.) with automatic policy mapping.

Hard deletes go through a workflow with audit trail. The agent never invokes hard delete directly — the canonical anti-pattern protection.