diff()

Signature

mem.diff(options: DiffOptions): Promise<DiffResult>

What It Does

diff() returns a structured changelog of memory mutations since a given timestamp. It queries the audit trail at the SQL level — zero LLM calls, typically completes in < 20ms.

Use it to:

Make your agent aware of preference changes between sessions
Build "what's new" summaries
Debug memory mutations

Basic Usage

const diff = await mem.diff({
  since: "2024-03-20T10:00:00Z",
});

console.log(diff.summary);     // "1 new, 1 replaced"
console.log(diff.changeCount); // 2

Options

Option	Type	Required	Default	Description
`since`	`string`	✅	—	ISO timestamp — return changes after this time
`namespace`	`string`	—	constructor default	Override namespace
`entity`	`string`	—	constructor default	Override entity
`limit`	`number`	—	`200`	Max events to return

Return Type

interface DiffResult {
  /** New memories created since the timestamp */
  created: {
    id: string;
    content: string;
    category: string | null;
    createdAt: string;
  }[];

  /** Memories that were updated (merged/refined) */
  updated: {
    id: string;
    content: string;
    previousContent: string;
    category: string | null;
    updatedAt: string;
  }[];

  /** Memories that were deleted */
  deleted: {
    id: string;
    content: string;
    deletedAt: string;
  }[];

  /** Preference changes — old memory contradicted by new one */
  replaced: {
    oldId: string;
    oldContent: string;
    newId: string;
    newContent: string;
    category: string | null;
    reason: string;
    replacedAt: string;
  }[];

  /** ISO timestamp of the query window start */
  since: string;
  /** Total number of changes */
  changeCount: number;
  /** Human-readable summary (e.g., "2 new, 1 replaced") */
  summary: string;
}

Examples

Make your agent aware of changes

const diff = await mem.diff({
  since: lastSessionTimestamp,
});

if (diff.changeCount > 0) {
  const lines = [
    ...diff.replaced.map(
      (r) => `Changed: "${r.oldContent}" → "${r.newContent}"`,
    ),
    ...diff.created.map((c) => `New: ${c.content}`),
    ...diff.updated.map(
      (u) => `Updated: "${u.previousContent}" → "${u.content}"`,
    ),
  ];

  systemPrompt += `\n\nRecent changes:\n${lines.join("\n")}`;
}

Track contradictions

The replaced array specifically captures preference changes — when the user contradicts a previous statement:

// If user first said "I love vanilla ice cream"
// then later said "I don't like vanilla anymore"

diff.replaced;
// [{
//   oldContent: "Loves vanilla ice cream",
//   newContent: "No longer likes vanilla ice cream",
//   reason: "contradiction",
// }]

Recent changes summary

const diff = await mem.diff({
  since: new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(), // last 24h
});

console.log(`Changes in last 24h: ${diff.summary}`);
// "Changes in last 24h: 3 new, 1 updated, 1 replaced"

How It Works

diff() queries the memory_events audit trail and collapses events per memory to compute the net diff:

Scenario	Result
Created in window and still alive	Shows in `created`
Existed before, deleted in window	Shows in `deleted`
Created then contradiction-deleted, paired with new ADD	Shows in `replaced`
Created then deleted (non-contradiction)	Net zero — not shown
Updated/merged	Shows old→new in `updated`

LLM Cost

Zero LLM calls. Diff is a pure SQL query on the existing audit trail data.

On this page