@kindgi/agents 0.1.4 → 0.1.5

package/src/handlers/replay.ts

@@ -9,6 +9,12 @@
  *   - `live`: the tool runs. Only a tool declared read-only (see
  *     `isReadOnlyTool`) with no approval to wait for can; a `live`
  *     decision for any other is refused here, whatever the binding says;
+ *   - `recomputed`: the tool runs, as for `live`, because the replayed
+ *     version pins other settings than the past run's, and the tool
+ *     reads from nowhere (no `reads`, `network` or `sensitive-data-egress`
+ *     effect): its result is computed again from the same arguments, so
+ *     the replay hasn't diverged from the past run. A tool that does read
+ *     from somewhere runs as `live`;
  *   - `recorded`: the past run's result for the same call is used;
  *   - `refused`: the tool doesn't run, and the model gets the given result.
  *
@@ -24,7 +30,7 @@ import type { JournalEntry, ValueRecordedPayload } from '@kindgi/runtime';
 import type { Tool } from '@kindgi/tools';
 import type { RunId, TenantId } from '@kindgi/types';
 
-import type { RetrievedFact } from '../types.js';
+import type { RecalledMemory, RetrievedFact } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
@@ -53,7 +59,19 @@ export interface ReplayToolInput extends ReplayTurnRef {
 }
 
 export type ReplayToolDecision =
-  | { readonly kind: 'live' }
+  | {
+      readonly kind: 'live';
+      /**
+       * The env values the past run's call of this tool was sent, for a
+       * read-only tool run live: the replay sends them, so the tool reads
+       * the config the past run saw rather than today's. Names it doesn't
+       * hold (a tool version that declares more) resolve as usual.
+       * Absent: the past run recorded none (from before env was recorded,
+       * or a tool it didn't call), and the call resolves today's values.
+       */
+      readonly env?: Readonly<Record<string, string>>;
+    }
+  | { readonly kind: 'recomputed' }
   | { readonly kind: 'recorded'; readonly result: unknown }
   | { readonly kind: 'refused'; readonly result: unknown; readonly reason: string };
 
@@ -75,12 +93,35 @@ export interface ReplayBinding {
    * retrieve live. Absent: retrieve live.
    */
   retrievals?(input: ReplayTurnRef): Promise<readonly RetrievedFact[] | undefined>;
+  /**
+   * What the turn's recall of earlier conversations returns when its
+   * retrievals are the past run's: the messages the past run recalled.
+   * Absent (or `undefined`): none, as a run from before recall had.
+   */
+  recalled?(input: ReplayTurnRef): Promise<readonly RecalledMemory[] | undefined>;
   /**
    * The past run's decision at the session approval gate, when the replay
    * reaches that gate: the replay follows it. `undefined` (or absent): the
    * gate is skipped, and the result says so.
    */
   sessionApproval?(input: ReplayTurnRef): Promise<ReplayApproval | undefined>;
+  /**
+   * Block content the replay runs instead of the agent version's pinned
+   * content (a comparison's `overrides`: an improvement pass's search):
+   * settings values and prompt templates, by block id. The same for every
+   * turn of a replay, on resume too. `undefined` (or absent): the pinned
+   * content.
+   */
+  overrides?(input: {
+    readonly tenantId: TenantId;
+    readonly replay: RunReplayRef;
+  }): Promise<ReplayOverrides | undefined>;
+}
+
+/** Block content a replay runs instead of the pinned content, by block id. */
+export interface ReplayOverrides {
+  readonly settings?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+  readonly prompts?: Readonly<Record<string, { readonly template: string }>>;
 }
 
 /** One tool call of a replay turn, and what happened to it. */
@@ -91,6 +132,12 @@ export interface ReplayToolTrace {
   readonly toolVersion: string;
   readonly arguments: unknown;
   readonly source: 'live' | 'recorded' | 'refused';
+  /**
+   * With `live`: it ran again from the same arguments under other
+   * settings and reads from nowhere, so its result isn't new data (the
+   * replay hasn't diverged). Absent otherwise.
+   */
+  readonly recomputed?: true;
   /** Why it was refused. A refused call is what the turn would have done. */
   readonly reason?: string;
 }
@@ -119,6 +166,20 @@ const CHANGING_EFFECTS: ReadonlySet<string> = new Set([
   'external-side-effect',
 ]);
 
+/** Effects that read from somewhere: a re-run of such a tool can see other data. */
+const READING_EFFECTS: ReadonlySet<string> = new Set(['reads', 'network', 'sensitive-data-egress']);
+
+/** A read-only tool that reads from nowhere either: its result follows from its arguments (and settings). */
+export function isComputeOnlyTool(tool: {
+  readonly mutating?: boolean;
+  readonly effects?: readonly { readonly kind: string }[] | readonly string[];
+}): boolean {
+  return (
+    isReadOnlyTool(tool) &&
+    !(tool.effects ?? []).some((e) => READING_EFFECTS.has(typeof e === 'string' ? e : e.kind))
+  );
+}
+
 /** A tool that declares it changes nothing: `mutating: false`, and no changing effect. */
 export function isReadOnlyTool(tool: {
   readonly mutating?: boolean;
@@ -139,9 +200,10 @@ function refusedResult(reason: string): Readonly<Record<string, unknown>> {
   return { status: 'not-executed', reason };
 }
 
-/** The journaled decision of one call: its trace entry, and the result the model got. */
+/** The journaled decision of one call: its trace entry, the result the model got, and a live call's env. */
 interface RecordedDecision extends ReplayToolTrace {
   readonly result?: unknown;
+  readonly env?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -202,21 +264,31 @@ export async function decideReplayTool(
       if (decision.kind === 'refused') {
         return { ...base, source: 'refused', reason: decision.reason, result: decision.result };
       }
-      // `live` runs only a read-only tool, and never waits for an approval.
+      // `live` and `recomputed` run only a read-only tool, and never wait
+      // for an approval; a tool that reads from somewhere is `live`.
       if (!isReadOnlyTool(call.tool)) return refuse(CHANGES_REASON);
       if (call.gated) return refuse(GATED_REASON);
-      return { ...base, source: 'live' };
+      const recomputed = decision.kind === 'recomputed' && isComputeOnlyTool(call.tool);
+      return {
+        ...base,
+        source: 'live',
+        ...(recomputed && { recomputed: true as const }),
+        ...(decision.kind === 'live' && decision.env !== undefined && { env: decision.env }),
+      };
     },
   );
   addReplayTrace(ctx, traceOf(decided));
-  if (decided.source === 'live') return { kind: 'live' };
+  if (decided.source === 'live') {
+    if (decided.recomputed === true) return { kind: 'recomputed' };
+    return { kind: 'live', ...(decided.env !== undefined && { env: decided.env }) };
+  }
   if (decided.source === 'recorded') return { kind: 'recorded', result: decided.result };
   return { kind: 'refused', result: decided.result, reason: decided.reason ?? CHANGES_REASON };
 }
 
-/** A journaled decision's trace entry (without the result). */
+/** A journaled decision's trace entry (without the result or the env values). */
 function traceOf(decided: RecordedDecision): ReplayToolTrace {
-  const { result: _result, ...trace } = decided;
+  const { result: _result, env: _env, ...trace } = decided;
   return trace;
 }
 

package/src/handlers/resolve-blocks.ts

@@ -13,6 +13,7 @@ import {
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import type { ReplayOverrides } from './replay.js';
 
 /** The block versions a turn runs, by kind then id, as `setup` journals them. */
 export interface PinnedBlockVersions {
@@ -90,7 +91,14 @@ export async function resolveTurnBlocks(
     versions[ref.kind][ref.id] = version;
     loaded.set(ref, block);
   }
-  return turnBlocks(refs, loaded, versions);
+  return turnBlocks(refs, loaded, versions, await replayOverrides(ctx));
+}
+
+/** A replay's block content in place of the pinned content (a comparison's overrides), if any. */
+async function replayOverrides(ctx: TurnContext): Promise<ReplayOverrides | undefined> {
+  const replay = ctx.input.replay;
+  if (replay === undefined || ctx.bindings.replay?.overrides === undefined) return undefined;
+  return ctx.bindings.replay.overrides({ tenantId: ctx.input.tenantId, replay });
 }
 
 function blockRefs(ctx: TurnContext): Ref[] {
@@ -139,6 +147,7 @@ function turnBlocks(
   refs: readonly Ref[],
   loaded: ReadonlyMap<Ref, BlockDefinition>,
   versions: PinnedBlockVersions,
+  overrides?: ReplayOverrides,
 ): TurnBlocks {
   const settings: Record<string, Readonly<Record<string, unknown>>> = {};
   let prompt: TurnBlocks['prompt'];
@@ -146,18 +155,23 @@ function turnBlocks(
   for (const ref of refs) {
     const block = loaded.get(ref) as BlockDefinition;
     if (block.kind === 'prompt') {
-      prompt = { id: block.id, version: block.version, content: block.content };
-    } else if (ref.role === 'model-settings') {
-      const issues = settingsSchemaIssues(block.content.values, MODEL_SETTINGS_SCHEMA);
+      const template = overrides?.prompts?.[block.id]?.template;
+      const content = template === undefined ? block.content : { ...block.content, template };
+      prompt = { id: block.id, version: block.version, content };
+      continue;
+    }
+    const values = overrides?.settings?.[block.id] ?? block.content.values;
+    if (ref.role === 'model-settings') {
+      const issues = settingsSchemaIssues(values, MODEL_SETTINGS_SCHEMA);
       if (issues.length > 0) {
         fail(
           ref,
-          `${describe(ref)} version ${block.version} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`,
+          `${describe(ref)} version ${block.version}${overrides?.settings?.[block.id] !== undefined ? " (with the replay's values)" : ''} isn't model settings: ${issues.map((i) => `${i.path} ${i.message}`).join('; ')}`,
         );
       }
-      modelSettings = block.content.values as ModelSettings;
+      modelSettings = values as ModelSettings;
     } else {
-      settings[block.id] = block.content.values;
+      settings[block.id] = values;
     }
   }
   return {

package/src/handlers/result-shape.ts

@@ -5,7 +5,12 @@ import type { EvaluationResult } from '@kindgi/guardrails';
 import type { Provenance } from '@kindgi/provenance';
 import type { RunId } from '@kindgi/types';
 
-import type { ConversationId, ConversationMessage, RetrievedFact } from '../types.js';
+import type {
+  ConversationId,
+  ConversationMessage,
+  RecalledMemory,
+  RetrievedFact,
+} from '../types.js';
 
 import type { ReplayTurnReport } from './replay.js';
 
@@ -31,11 +36,18 @@ export interface AgentTurnUsage {
  */
 export interface AgentTurnWarning {
   /**
-   * `fallback-provider`: a fallback provider answered. Any other code is a
-   * provider's own warning about its answers (`ModelCallResult.warnings`),
-   * such as dev-echo's `dev-echo-not-a-model`.
+   * `fallback-provider`: a fallback provider answered.
+   * `memory-needs-participant`: the agent keeps memory per end user
+   * (`same-user`), but the run named none (`participantId`), so it read and
+   * kept none.
+   * Any other code is a provider's own warning about its answers
+   * (`ModelCallResult.warnings`), such as dev-echo's `dev-echo-not-a-model`.
    */
-  readonly code: 'fallback-provider' | 'dev-echo-not-a-model' | (string & {});
+  readonly code:
+    | 'fallback-provider'
+    | 'memory-needs-participant'
+    | 'dev-echo-not-a-model'
+    | (string & {});
   readonly message: string;
 }
 
@@ -47,6 +59,8 @@ export interface AgentTurnResult {
   readonly appended: readonly ConversationMessage[];
   readonly response: ConversationMessage;
   readonly retrieved: readonly RetrievedFact[];
+  /** Messages of earlier conversations the turn recalled (intents over conversations). */
+  readonly recalled?: readonly RecalledMemory[];
   readonly violations: readonly EvaluationResult[];
   readonly usage: AgentTurnUsage;
   readonly provider: { readonly id: string; readonly model: string };

package/src/handlers/run-retrievals.ts

@@ -3,19 +3,21 @@
 
 import type { NodeContext, NodeHandler } from '@kindgi/handler';
 
-import { runRetrievals } from '../retrieval.js';
+import { runUserId } from '../remember.js';
+import { type RetrievalPass, retrieveForTurn } from '../retrieval.js';
 import { emitTurnEvent } from '../streaming.js';
-import type { RetrievedFact } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { historyStart } from './history.js';
 import { addRetrievalNodes } from './turn-provenance.js';
 
 /**
  * Execute the agent's declared retrieval intents. Populates
  * `ctx.retrieved` for downstream prompt building + emits
  * `retrieval.completed`. Adds provenance nodes + edges when a builder
- * is wired.
+ * is wired. The journal keeps the facts (with each one's rank in each
+ * search) and the intents that ran degraded.
  */
 export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
   return async (_input, kctx) => {
@@ -26,8 +28,11 @@ export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
         cause: null,
       });
     }
-    const facts = (await recordedRetrievals(ctx, kctx)) ?? (await retrieveLive(ctx));
+    const recorded = await recordedRetrievals(ctx, kctx);
+    const pass = recorded ?? (await retrieveLive(ctx));
+    const facts = pass.facts;
     ctx.retrieved = facts;
+    ctx.recalled = pass.recalled;
 
     await emitTurnEvent(ctx.bindings.onEvent, {
       kind: 'retrieval.completed',
@@ -36,32 +41,52 @@ export function buildRunRetrievalsHandler(ctx: TurnContext): NodeHandler {
     });
 
     if (ctx.provenance !== undefined && ctx.userMessage !== undefined) {
-      addRetrievalNodes(ctx.provenance, facts, ctx.userMessage);
+      addRetrievalNodes(
+        ctx.provenance,
+        ctx.input.agent.retrieval,
+        facts,
+        ctx.userMessage,
+        pass.recalled,
+      );
     }
 
-    // The facts go in the journal: a resumed turn restores them from it
-    // (`rehydrateTurnContext`) rather than retrieving again.
-    return { count: facts.length, retrieved: facts };
+    // The facts and recalled messages go in the journal: a resumed turn
+    // restores them from it (`rehydrateTurnContext`) rather than retrieving again.
+    return {
+      count: facts.length,
+      retrieved: facts,
+      ...(pass.recalled.length > 0 && { recalled: pass.recalled }),
+      ...(pass.degraded.length > 0 && { degraded: pass.degraded }),
+    };
   };
 }
 
-/** A replay's retrievals: what the past run retrieved, when the replay binding has it. */
+/**
+ * A replay's retrievals: what the past run retrieved and recalled, when
+ * the replay binding has them.
+ */
 async function recordedRetrievals(
   ctx: TurnContext,
   kctx: NodeContext,
-): Promise<readonly RetrievedFact[] | undefined> {
+): Promise<RetrievalPass | undefined> {
   const replay = ctx.input.replay;
-  if (replay === undefined || ctx.bindings.replay?.retrievals === undefined) return undefined;
-  return ctx.bindings.replay.retrievals({
-    tenantId: ctx.input.tenantId,
-    runId: kctx.runId,
-    replay,
-  });
+  const binding = ctx.bindings.replay;
+  if (replay === undefined || binding?.retrievals === undefined) return undefined;
+  const ref = { tenantId: ctx.input.tenantId, runId: kctx.runId, replay };
+  const facts = await binding.retrievals(ref);
+  if (facts === undefined) return undefined;
+  const recalled = (await binding.recalled?.(ref)) ?? [];
+  return { facts, recalled, degraded: [] };
 }
 
-async function retrieveLive(ctx: TurnContext): Promise<readonly RetrievedFact[]> {
-  if (ctx.conversation === undefined) return [];
-  const retrieved = await runRetrievals(
+async function retrieveLive(ctx: TurnContext): Promise<RetrievalPass> {
+  if (ctx.conversation === undefined) return { facts: [], recalled: [], degraded: [] };
+  const userId = runUserId(ctx.input.principal);
+  const recallsOlder = ctx.input.agent.retrieval.some(
+    (i) => i.source === 'conversations' && i.scope === 'same-conversation',
+  );
+  const historyFrom = recallsOlder ? await historyStart(ctx) : undefined;
+  const retrieved = await retrieveForTurn(
     ctx.input.agent,
     ctx.conversation,
     ctx.input.conversationId,
@@ -75,6 +100,14 @@ async function retrieveLive(ctx: TurnContext): Promise<readonly RetrievedFact[]>
         embeddingModel: ctx.bindings.embeddingModel,
       }),
     },
+    {
+      projectId: ctx.input.projectId,
+      ...(ctx.input.orgId !== undefined && { orgId: ctx.input.orgId }),
+      ...(ctx.input.participantId !== undefined && { participantId: ctx.input.participantId }),
+      ...(userId !== undefined && { userId }),
+      ...(ctx.input.segments !== undefined && { segments: ctx.input.segments }),
+      ...(historyFrom !== undefined && { historyFrom }),
+    },
   );
   if (retrieved.kind === 'err') throwAgentTurnFailure(retrieved.error);
   return retrieved.value;

package/src/handlers/turn-environment.ts

@@ -21,6 +21,7 @@ import { mergeTenantPolicies } from '../tenant-policy.js';
 import type { Conversation } from '../types.js';
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { withRememberTool } from './remember-tool.js';
 import { type PinnedBlockVersions, resolveTurnBlocks } from './resolve-blocks.js';
 import { resolveTurnTools } from './resolve-tools.js';
 import { type ToolErrorPolicy, effectiveToolErrorPolicy } from './tool-errors.js';
@@ -102,7 +103,7 @@ export async function resolveTurnEnvironment(
   // This turn's tools come from the tenant's own registry — never a
   // registry shared across concurrent turns of other tenants.
   const tenantTools = await ctx.bindings.toolRegistry.forTenant(ctx.input.tenantId);
-  ctx.tools = resolveTurnTools(tenantTools, ctx.input.agent, pinnedTools);
+  ctx.tools = withRememberTool(ctx, resolveTurnTools(tenantTools, ctx.input.agent, pinnedTools));
   // The data blocks, at the versions pinned (the turn's own on resume).
   const blocks = await resolveTurnBlocks(ctx, pinnedBlocks);
   if (blocks !== undefined) ctx.blocks = blocks;

package/src/handlers/turn-provenance.ts

@@ -12,9 +12,16 @@
 import type { ProvenanceBuilder } from '@kindgi/provenance';
 import type { Timestamp } from '@kindgi/types';
 
-import type { ConversationMessage, RetrievedFact } from '../types.js';
+import { REMEMBER_TOOL_ID } from '../remember.js';
+import type {
+  ConversationMessage,
+  RecalledMemory,
+  RetrievalIntent,
+  RetrievedFact,
+} from '../types.js';
 import type { TurnContext } from './context.js';
 import type { GateDecision } from './gate-decision.js';
+import type { RememberToolOutput } from './remember-tool.js';
 
 /** The turn's user message. */
 export function addInputNode(provenance: ProvenanceBuilder, message: ConversationMessage): void {
@@ -26,12 +33,43 @@ export function addInputNode(provenance: ProvenanceBuilder, message: Conversatio
   });
 }
 
-/** The facts the turn retrieved for its user message. */
+/**
+ * The turn's memory searches and the facts they found for its user
+ * message. Each retrieval intent is one `memory-read` node, `operation:
+ * search_memory` (the OpenTelemetry GenAI name), `caused-by` the input,
+ * with what it searched and the ids it found; each fact is a `retrieval`
+ * node `retrieved-from` its search and `influenced-by` the input.
+ */
 export function addRetrievalNodes(
   provenance: ProvenanceBuilder,
+  intents: readonly RetrievalIntent[],
   retrieved: readonly RetrievedFact[],
   input: ConversationMessage,
+  recalled: readonly RecalledMemory[] = [],
 ): void {
+  const searchIds = intents.map((intent, i) => {
+    const id = `memory-read:search:${input.sequence}:${i}`;
+    const found = retrieved.filter((r) => sameIntent(r.intent, intent));
+    const quoted = recalled.filter((r) => sameIntent(r.intent, intent));
+    provenance.addNode({
+      id,
+      kind: 'memory-read',
+      timestamp: input.createdAt,
+      attributes: {
+        operation: 'search_memory',
+        intent: i,
+        source: intent.source ?? 'facts',
+        ...(intent.types !== undefined && { types: [...intent.types] }),
+        scope: intent.scope,
+        mode: intent.mode ?? 'list',
+        ...(intent.source === 'conversations'
+          ? { messages: quoted.map((r) => recallRef(r)) }
+          : { factIds: found.map((r) => r.fact.id as unknown as string) }),
+      },
+    });
+    provenance.addEdge({ from: id, to: `input:${input.sequence}`, kind: 'caused-by' });
+    return id;
+  });
   for (const r of retrieved) {
     provenance.addNode({
       id: `retrieval:${r.fact.id}`,
@@ -43,14 +81,64 @@ export function addRetrievalNodes(
         factType: r.fact.type,
         intentScope: r.intent.scope,
         ...(r.score !== undefined && { score: r.score }),
+        ...(r.ranks !== undefined && { ranks: { ...r.ranks } }),
       },
     });
+    const search = searchIds[intents.findIndex((intent) => sameIntent(r.intent, intent))];
+    if (search !== undefined) {
+      provenance.addEdge({ from: `retrieval:${r.fact.id}`, to: search, kind: 'retrieved-from' });
+    }
     provenance.addEdge({
       from: `retrieval:${r.fact.id}`,
       to: `input:${input.sequence}`,
       kind: 'influenced-by',
     });
   }
+  addRecalledNodes(provenance, intents, searchIds, recalled, input);
+}
+
+/** A recalled message: its conversation and place in it. */
+function recallRef(r: RecalledMemory): string {
+  return `${r.message.conversationId}#${r.message.sequence}`;
+}
+
+/**
+ * The recalled messages: a `retrieval` node each (source conversations),
+ * `retrieved-from` its search and `influenced-by` the input.
+ */
+function addRecalledNodes(
+  provenance: ProvenanceBuilder,
+  intents: readonly RetrievalIntent[],
+  searchIds: readonly string[],
+  recalled: readonly RecalledMemory[],
+  input: ConversationMessage,
+): void {
+  for (const r of recalled) {
+    const id = `retrieval:recall:${recallRef(r)}`;
+    provenance.addNode({
+      id,
+      kind: 'retrieval',
+      timestamp: input.createdAt,
+      attributes: {
+        source: 'conversations',
+        conversationId: r.message.conversationId,
+        sequence: r.message.sequence,
+        role: r.message.role,
+        intentScope: r.intent.scope,
+        ...(r.anotherPerson === true && { anotherPerson: true }),
+        ...(r.score !== undefined && { score: r.score }),
+        ...(r.ranks !== undefined && { ranks: { ...r.ranks } }),
+      },
+    });
+    const search = searchIds[intents.findIndex((intent) => sameIntent(r.intent, intent))];
+    if (search !== undefined) provenance.addEdge({ from: id, to: search, kind: 'retrieved-from' });
+    provenance.addEdge({ from: id, to: `input:${input.sequence}`, kind: 'influenced-by' });
+  }
+}
+
+/** The same intent, whether live or read back from the journal. */
+function sameIntent(a: RetrievalIntent, b: RetrievalIntent): boolean {
+  return a === b || JSON.stringify(a) === JSON.stringify(b);
 }
 
 /** One model call: its identity; its usage is the cost ledger's, by `callId`. */
@@ -128,6 +216,45 @@ export function addToolNodes(
   provenance.addEdge({ from: resultNodeId, to: callNodeId, kind: 'produced' });
 }
 
+/**
+ * What a `remember` call wrote, from its stored result (so a resumed turn
+ * adds the same node): a `memory-write` node, `operation: create_memory`
+ * or `update_memory`, the fact's id and version, its actor the agent,
+ * `produced` by the call.
+ */
+export function addMemoryWriteNode(
+  provenance: ProvenanceBuilder,
+  result: ConversationMessage,
+  agent: { readonly id: string; readonly version: string },
+): void {
+  const call = result.toolCall;
+  if (call === undefined || call.toolId !== REMEMBER_TOOL_ID) return;
+  const written = rememberedOf(result.content);
+  if (written === undefined) return;
+  const id = `memory-write:${written.factId}@${written.version}`;
+  provenance.addNode({
+    id,
+    kind: 'memory-write',
+    timestamp: result.createdAt,
+    actor: `agent:${agent.id}@${agent.version}`,
+    attributes: {
+      operation: written.outcome === 'superseded' ? 'update_memory' : 'create_memory',
+      factId: written.factId,
+      version: written.version,
+      ...(written.status === 'pending-review' && { review: 'pending' }),
+    },
+  });
+  provenance.addEdge({ from: id, to: `tool-call:${call.invocationId}`, kind: 'produced' });
+}
+
+function rememberedOf(content: ConversationMessage['content']): RememberToolOutput | undefined {
+  if (typeof content !== 'object' || content === null) return undefined;
+  const out = content as Partial<RememberToolOutput>;
+  if (out.status !== 'remembered' && out.status !== 'pending-review') return undefined;
+  if (typeof out.factId !== 'string' || typeof out.version !== 'number') return undefined;
+  return out as RememberToolOutput;
+}
+
 /**
  * The tool calls of one model step: a node pair for each result the step
  * stored, and their invocation ids added to the turn's tool results.
@@ -142,6 +269,10 @@ export function addStepToolNodes(
     const { invocationId, toolId } = result.toolCall;
     if (ctx.provenance !== undefined) {
       addToolNodes(ctx.provenance, step, result, versionOf(ctx, toolId));
+      addMemoryWriteNode(ctx.provenance, result, {
+        id: ctx.input.agent.id as unknown as string,
+        version: ctx.input.agent.version as unknown as string,
+      });
       const approval = ctx.toolApprovals?.get(invocationId);
       if (approval !== undefined) {
         addToolApprovalNodes(