@kindgi/agents 0.1.4 → 0.1.5-rc.0

package/src/define.ts

@@ -9,18 +9,22 @@ import {
   loadZodConverterSync,
   toJSONSchemaSync,
 } from '@kindgi/schema';
-import { pickVersion } from '@kindgi/tools';
+import { BUILT_IN_TOOL_PREFIX, pickVersion } from '@kindgi/tools';
 import type { Result, Semver } from '@kindgi/types';
 
 import type { InvalidAgentError } from './errors.js';
+import { MAX_REMEMBER_DAYS, REMEMBER_TOOL_ID } from './remember.js';
 import type {
   Agent,
   AgentId,
+  AgentMemoryPolicy,
   AgentOutputSpec,
   BlockRef,
   ConversationPolicy,
   PromptParameter,
   PromptRef,
+  RememberPolicy,
+  RememberScope,
   RetrievalIntent,
   ToolRef,
   TurnBudget,
@@ -54,6 +58,7 @@ export function defineAgent(spec: DefineAgentSpec): Result<Agent, InvalidAgentEr
     ...validateBlockRefs(spec),
     ...validateArrays(spec),
     ...validateRetrieval(spec),
+    ...validateMemoryPolicy(spec),
     ...validatePromptParameters(spec.parameters),
     ...validateBudget(spec.budget),
     ...validateConversationPolicy(spec.conversationPolicy),
@@ -171,6 +176,12 @@ export interface DefineAgentSpec {
    * conversation history + user message.
    */
   readonly retrieval: readonly RetrievalIntent[];
+  /**
+   * How the agent uses what it retrieves: `instructionTypes` lists fact
+   * types whose verified facts are policies (in the system message).
+   * Absent: every retrieved fact is data.
+   */
+  readonly memory?: AgentMemoryPolicy;
   /**
    * Guardrail IDs that guard this agent's turns. Each id must
    * resolve among the guardrails bound for the run, or the turn fails
@@ -364,6 +375,11 @@ function validateToolRef(ref: unknown, i: number): Issue[] {
   const obj = ref as Record<string, unknown>;
   if (typeof obj.id !== 'string' || obj.id.trim().length === 0) {
     out.push({ path: `/tools/${i}/id`, message: 'tool id must be a non-empty string' });
+  } else if (obj.id.startsWith(BUILT_IN_TOOL_PREFIX)) {
+    out.push({
+      path: `/tools/${i}/id`,
+      message: `"${obj.id}" is a tool built into Kindgi (the "${BUILT_IN_TOOL_PREFIX}" prefix): an agent gets it from its declaration (memory.remember for ${REMEMBER_TOOL_ID}), not from tools`,
+    });
   }
   if (typeof obj.version !== 'string' || obj.version.trim().length === 0) {
     out.push({
@@ -386,28 +402,137 @@ function validateRetrieval(spec: DefineAgentSpec): Issue[] {
 
 function validateIntent(intent: RetrievalIntent, i: number): Issue[] {
   const out: Issue[] = [];
-  if (!Array.isArray(intent.types) || intent.types.length === 0) {
+  const source = intent.source ?? 'facts';
+  if (source !== 'facts' && source !== 'conversations') {
+    out.push({
+      path: `/retrieval/${i}/source`,
+      message: 'source must be facts or conversations (or absent: facts)',
+    });
+    return out;
+  }
+  if (source === 'facts' && (!Array.isArray(intent.types) || intent.types.length === 0)) {
     out.push({
       path: `/retrieval/${i}/types`,
-      message: 'each retrieval intent must declare at least one type',
+      message: 'each retrieval intent over facts must declare at least one type',
     });
   }
-  if (
-    intent.scope !== 'same-conversation' &&
-    intent.scope !== 'same-project' &&
-    intent.scope !== 'tenant'
-  ) {
+  if (source === 'conversations' && intent.types !== undefined) {
+    out.push({
+      path: `/retrieval/${i}/types`,
+      message: 'an intent over conversations has no types: it recalls messages',
+    });
+  }
+  if (intent.roles !== undefined) {
+    const roles = intent.roles as readonly unknown[];
+    if (source !== 'conversations') {
+      out.push({
+        path: `/retrieval/${i}/roles`,
+        message: 'roles are for an intent over conversations',
+      });
+    } else if (
+      !Array.isArray(roles) ||
+      roles.length === 0 ||
+      roles.some((r) => r !== 'user' && r !== 'agent')
+    ) {
+      out.push({
+        path: `/retrieval/${i}/roles`,
+        message: "roles must list 'user', 'agent' or both (absent: 'user', the people's own words)",
+      });
+    }
+  }
+  const scopes = source === 'facts' ? RETRIEVAL_SCOPES : RECALL_SCOPES;
+  if (!scopes.includes(intent.scope)) {
     out.push({
       path: `/retrieval/${i}/scope`,
-      message: 'scope must be same-conversation, same-project, or tenant',
+      message: `scope for ${source} must be one of ${scopes.join(', ')}`,
     });
   }
   if (intent.limit !== undefined && (!Number.isInteger(intent.limit) || intent.limit <= 0)) {
     out.push({ path: `/retrieval/${i}/limit`, message: 'limit must be a positive integer' });
   }
+  if (intent.mode !== undefined && !RETRIEVAL_MODES.includes(intent.mode)) {
+    out.push({
+      path: `/retrieval/${i}/mode`,
+      message: `mode must be one of ${RETRIEVAL_MODES.join(', ')} (or absent: the newest facts)`,
+    });
+  }
+  return out;
+}
+
+const RETRIEVAL_SCOPES: readonly RetrievalIntent['scope'][] = [
+  'same-conversation',
+  'same-user',
+  'same-project',
+  'tenant',
+];
+const RECALL_SCOPES: readonly RetrievalIntent['scope'][] = [
+  'same-user',
+  'same-conversation',
+  'same-segment',
+  'same-project',
+];
+const RETRIEVAL_MODES: readonly NonNullable<RetrievalIntent['mode']>[] = [
+  'keyword',
+  'semantic',
+  'both',
+];
+
+const REMEMBER_SCOPES: readonly RememberScope[] = [
+  'same-user',
+  'same-conversation',
+  'same-project',
+  'tenant',
+];
+
+function validateMemoryPolicy(spec: DefineAgentSpec): Issue[] {
+  const memory = spec.memory;
+  if (memory === undefined) return [];
+  if (memory === null || typeof memory !== 'object' || Array.isArray(memory)) {
+    return [{ path: '/memory', message: 'memory must be an object' }];
+  }
+  const out: Issue[] = [];
+  const types = memory.instructionTypes;
+  if (types !== undefined && !isTypeList(types)) {
+    out.push({
+      path: '/memory/instructionTypes',
+      message: 'instructionTypes must be a list of fact type names',
+    });
+  }
+  if (memory.remember !== undefined) out.push(...validateRemember(memory.remember));
+  return out;
+}
+
+function validateRemember(remember: RememberPolicy): Issue[] {
+  if (remember === null || typeof remember !== 'object' || Array.isArray(remember)) {
+    return [{ path: '/memory/remember', message: 'remember must be an object' }];
+  }
+  const out: Issue[] = [];
+  if (!isTypeList(remember.types) || remember.types.length === 0) {
+    out.push({
+      path: '/memory/remember/types',
+      message: 'remember.types must list at least one fact type name',
+    });
+  }
+  if (!REMEMBER_SCOPES.includes(remember.scope)) {
+    out.push({
+      path: '/memory/remember/scope',
+      message: `remember.scope must be one of: ${REMEMBER_SCOPES.join(', ')}`,
+    });
+  }
+  const days = remember.keepDays;
+  if (days !== undefined && (!Number.isInteger(days) || days < 1 || days > MAX_REMEMBER_DAYS)) {
+    out.push({
+      path: '/memory/remember/keepDays',
+      message: `remember.keepDays must be a whole number of days from 1 to ${MAX_REMEMBER_DAYS}`,
+    });
+  }
   return out;
 }
 
+function isTypeList(types: unknown): types is readonly string[] {
+  return Array.isArray(types) && types.every((t) => typeof t === 'string' && t.trim().length > 0);
+}
+
 const VALID_PARAM_TYPES = new Set(['string', 'number', 'boolean', 'date']);
 const AUTO_INJECTED_NAMES = new Set(['today', 'now', 'agent', 'conversation', 'settings']);
 
@@ -649,6 +774,16 @@ function buildAgent(spec: DefineAgentSpec, output: AgentOutputSpec | undefined):
     capabilities: spec.capabilities.map((c) => ({ ...c })),
     tools: [...spec.tools],
     retrieval: spec.retrieval.map((r) => ({ ...r })),
+    ...(spec.memory !== undefined && {
+      memory: {
+        ...(spec.memory.instructionTypes !== undefined && {
+          instructionTypes: [...spec.memory.instructionTypes],
+        }),
+        ...(spec.memory.remember !== undefined && {
+          remember: { ...spec.memory.remember, types: [...spec.memory.remember.types] },
+        }),
+      },
+    }),
     guardrails: [...spec.guardrails],
     ...(spec.parameters !== undefined && {
       parameters: spec.parameters.map((p) => ({ ...p })),

package/src/drafted-template.ts

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { Liquid } from 'liquidjs';
+
+import type { BlockIssue, PromptBlockContent } from './blocks.js';
+
+/**
+ * What a drafted prompt template (an improvement pass's candidate) is
+ * checked against: the template it would replace, and what the agent
+ * version already has.
+ */
+export interface DraftedTemplateContext {
+  /** The prompt block content the version pins: the template, and its parameters. */
+  readonly current: PromptBlockContent;
+  /** The settings blocks the version pins: `settings["<id>"]` may read these. */
+  readonly settingsBlocks: readonly string[];
+  /** The ids the agent already uses (its own, its tools', its blocks'): a template may name these. */
+  readonly knownIds: readonly string[];
+}
+
+/** The most a drafted template may be: twice the current one, at least 2,000 characters. */
+export const DRAFTED_TEMPLATE_MAX = 20_000;
+
+/** Variables any template may read: the turn's clock and identity. */
+const HARMLESS_VARS: ReadonlySet<string> = new Set(['today', 'now', 'agent', 'conversation']);
+
+/** A dotted id (`acme.export`): two or more segments, the first at least two characters. */
+const DOTTED_ID = /\b[a-z][a-z0-9_-]+(?:\.[a-z0-9_-]+)+\b/gi;
+
+const liquid = new Liquid();
+
+function rootsOf(template: string): Array<readonly (string | number)[]> {
+  return liquid.globalVariableSegmentsSync(template).map((s) => s as readonly (string | number)[]);
+}
+
+/**
+ * Whether a drafted template may replace the current one, as data: the
+ * problems, none when it may. Drafted templates come from a model fed
+ * judges' reasons and case data, so a template is held to what the agent
+ * already has, whatever the model was told:
+ *
+ *   - it parses as Liquid;
+ *   - the variables it reads are the declared parameters, the variables
+ *     the current template reads, the turn's clock and identity, and
+ *     `settings["<id>"]` of a settings block the version pins;
+ *   - the dotted ids it names (`acme.export`, say) are the agent's own,
+ *     its tools' and blocks', or ones the current template names: no new
+ *     tool, agent or data reference;
+ *   - it isn't empty or the current template, and at most twice as long
+ *     as it (at least 2,000 characters; never over `DRAFTED_TEMPLATE_MAX`).
+ */
+export function checkDraftedTemplate(
+  candidate: string,
+  context: DraftedTemplateContext,
+): BlockIssue[] {
+  const current = context.current.template;
+  const issues: BlockIssue[] = [];
+  if (candidate.trim() === '') return [{ path: '/template', message: 'the template is empty' }];
+  if (candidate === current) {
+    return [{ path: '/template', message: 'the template is the current one' }];
+  }
+  const max = Math.min(DRAFTED_TEMPLATE_MAX, Math.max(2 * current.length, 2000));
+  if (candidate.length > max) {
+    issues.push({
+      path: '/template',
+      message: `the template is ${candidate.length} characters; at most ${max} (twice the current one)`,
+    });
+  }
+
+  let read: Array<readonly (string | number)[]>;
+  try {
+    read = rootsOf(candidate);
+  } catch (cause) {
+    issues.push({
+      path: '/template',
+      message: `the template isn't valid Liquid: ${cause instanceof Error ? cause.message : String(cause)}`,
+    });
+    return issues;
+  }
+  const parameters = new Set((context.current.parameters ?? []).map((p) => p.name));
+  let currentRoots: Set<string>;
+  try {
+    currentRoots = new Set(rootsOf(current).map((s) => String(s[0])));
+  } catch {
+    currentRoots = new Set();
+  }
+  const settingsBlocks = new Set(context.settingsBlocks);
+  const named = new Set<string>();
+  for (const segments of read) {
+    const root = String(segments[0]);
+    if (root === 'settings') {
+      const block = segments[1];
+      if (block === undefined || !settingsBlocks.has(String(block))) {
+        named.add(`settings${block === undefined ? '' : `["${String(block)}"]`}`);
+      }
+      continue;
+    }
+    if (parameters.has(root) || currentRoots.has(root) || HARMLESS_VARS.has(root)) continue;
+    named.add(root);
+  }
+  for (const variable of named) {
+    issues.push({
+      path: '/template',
+      message: `it reads "${variable}", which the agent doesn't have (a declared parameter, a variable the current template reads, or a settings block the version pins)`,
+    });
+  }
+
+  const known = new Set([...context.knownIds, ...(current.match(DOTTED_ID) ?? [])]);
+  const newIds = new Set((candidate.match(DOTTED_ID) ?? []).filter((id) => !known.has(id)));
+  for (const id of newIds) {
+    issues.push({
+      path: '/template',
+      message: `it names "${id}", which the agent doesn't use (its tools, blocks, or what the current template names)`,
+    });
+  }
+  return issues;
+}

package/src/guardrails-gate.ts

@@ -9,7 +9,9 @@ import {
   type EvaluationOutcome,
   type EvaluationResult,
   type Guardrail,
+  type GuardrailSeverity,
   type ModelCallRecord,
+  type OnViolation,
   type RunTrace,
   type ToolCallRecord,
   type ToolResultRecord,
@@ -201,7 +203,20 @@ export async function evaluateGate(
   abortSignal?: AbortSignal,
   usage?: UsageSink,
 ): Promise<readonly EvaluationOutcome[]> {
-  if (guardrails.length === 0 || bindings.checks === undefined) return [];
+  if (guardrails.length === 0) return [];
+  // No check registry at all: every guardrail is one whose check can't run, never one that
+  // passed, so a `halt` guardrail fails the turn here too (it fails closed).
+  if (bindings.checks === undefined) {
+    return guardrails.map((g) => ({
+      kind: 'err' as const,
+      error: {
+        code: 'unknown-check' as const,
+        message: `guardrail "${g.id}": no check registry is bound, so its check "${g.check}" can't run`,
+        guardrailId: g.id,
+        checkId: g.check,
+      },
+    }));
+  }
   const evalBindings: EvaluationBindings = {
     ...(bindings.providerRegistry !== undefined && { providerRegistry: bindings.providerRegistry }),
     ...(bindings.compliance !== undefined && { compliance: bindings.compliance }),
@@ -212,6 +227,20 @@ export async function evaluateGate(
   return await evaluateAll(guardrails, bindings.checks, trace, evalBindings);
 }
 
+/**
+ * A guardrail whose check couldn't run (no such check, a bad configuration, a judge that couldn't
+ * be routed), with what the guardrail would have done. Never counted as a violation.
+ */
+export interface GuardrailEvaluationError {
+  readonly guardrailId: string;
+  readonly message: string;
+  /** The engine's error code: `unknown-check`, `invalid-check-config`, `judge-routing-failed`, … */
+  readonly code: string;
+  /** The guardrail's `on-violation` action and severity; absent when the guardrail is unknown. */
+  readonly action?: OnViolation;
+  readonly severity?: GuardrailSeverity;
+}
+
 /**
  * Sort evaluation outcomes by the failed guardrail's action. `halt` is
  * blocking — the turn fails with `guardrail-violation`. `log-only` and
@@ -220,38 +249,58 @@ export async function evaluateGate(
  * `other`. Warnings and `other` are attached to the successful turn
  * result under `result.violations`; the turn does not carry out those
  * actions. Evaluation errors (a check that could not run) are collected
- * in `errors`.
+ * in `errors`; those of a `halt` guardrail are also in `blockingErrors`,
+ * which fail the turn as a violation would (a guardrail that can't check
+ * fails closed). `guardrails` is the list the outcomes came from, one
+ * outcome per guardrail in order (`evaluateGate`), which says each error's
+ * action; without it, an error's guardrail is looked up by id.
  */
-export function categorizeOutcomes(outcomes: readonly EvaluationOutcome[]): {
+export function categorizeOutcomes(
+  outcomes: readonly EvaluationOutcome[],
+  guardrails: readonly Guardrail[] = [],
+): {
   readonly blocking: readonly EvaluationResult[];
   readonly warnings: readonly EvaluationResult[];
   readonly other: readonly EvaluationResult[];
-  readonly errors: readonly { readonly guardrailId: string; readonly message: string }[];
+  readonly errors: readonly GuardrailEvaluationError[];
+  readonly blockingErrors: readonly GuardrailEvaluationError[];
 } {
   const blocking: EvaluationResult[] = [];
   const warnings: EvaluationResult[] = [];
   const other: EvaluationResult[] = [];
-  const errors: { guardrailId: string; message: string }[] = [];
-  for (const outcome of outcomes) {
+  const errors: GuardrailEvaluationError[] = [];
+  const blockingErrors: GuardrailEvaluationError[] = [];
+  const byId = new Map(guardrails.map((g) => [g.id as string, g]));
+  const inOrder = guardrails.length === outcomes.length;
+  outcomes.forEach((outcome, i) => {
     if (outcome.kind === 'err') {
-      errors.push({
-        guardrailId:
-          'guardrailId' in outcome.error && typeof outcome.error.guardrailId === 'string'
-            ? outcome.error.guardrailId
-            : '<unknown>',
+      const named =
+        'guardrailId' in outcome.error && typeof outcome.error.guardrailId === 'string'
+          ? outcome.error.guardrailId
+          : undefined;
+      const guardrail = inOrder ? guardrails[i] : named !== undefined ? byId.get(named) : undefined;
+      const error: GuardrailEvaluationError = {
+        guardrailId: guardrail?.id ?? named ?? '<unknown>',
         message: outcome.error.message,
-      });
-      continue;
+        code: outcome.error.code,
+        ...(guardrail !== undefined && {
+          action: guardrail.action['on-violation'],
+          severity: guardrail.severity ?? 'error',
+        }),
+      };
+      errors.push(error);
+      if (error.action === 'halt') blockingErrors.push(error);
+      return;
     }
-    if (outcome.kind === 'skip') continue;
+    if (outcome.kind === 'skip') return;
     const evalResult = outcome.value;
-    if (evalResult.result.passed) continue;
+    if (evalResult.result.passed) return;
     if (evalResult.action === 'halt') blocking.push(evalResult);
     else if (evalResult.action === 'log-only' || evalResult.action === 'noop') {
       warnings.push(evalResult);
     } else other.push(evalResult);
-  }
-  return { blocking, warnings, other, errors };
+  });
+  return { blocking, warnings, other, errors, blockingErrors };
 }
 
 /**
@@ -261,21 +310,33 @@ export function categorizeOutcomes(outcomes: readonly EvaluationOutcome[]): {
  *   Turn blocked by guardrail 'no-pii': Response contains an email address
  *   Turn blocked by 2 guardrails: 'no-pii' (Response contains …); 'max-length'
  */
-export function describeBlockingViolations(blocking: readonly EvaluationResult[]): string {
+export function describeBlockingViolations(
+  blocking: readonly EvaluationResult[],
+  blockingErrors: readonly GuardrailEvaluationError[] = [],
+): string {
   const reasonOf = (v: EvaluationResult): string | undefined => {
     const reason = v.result.reason?.trim();
     return reason === undefined || reason === '' ? undefined : reason;
   };
+  const couldNotRun = (e: GuardrailEvaluationError) =>
+    `'${e.guardrailId}' couldn't run its check (${e.code}: ${e.message})`;
   const [only] = blocking;
-  if (blocking.length === 1 && only !== undefined) {
+  const [onlyError] = blockingErrors;
+  if (blocking.length === 1 && only !== undefined && blockingErrors.length === 0) {
     const reason = reasonOf(only);
     return `Turn blocked by guardrail '${only.guardrailId}'${reason !== undefined ? `: ${reason}` : ''}`;
   }
-  const named = blocking.map((v) => {
-    const reason = reasonOf(v);
-    return `'${v.guardrailId}'${reason !== undefined ? ` (${reason})` : ''}`;
-  });
-  return `Turn blocked by ${blocking.length} guardrails: ${named.join('; ')}`;
+  if (blocking.length === 0 && blockingErrors.length === 1 && onlyError !== undefined) {
+    return `Turn blocked: guardrail ${couldNotRun(onlyError)}`;
+  }
+  const named = [
+    ...blocking.map((v) => {
+      const reason = reasonOf(v);
+      return `'${v.guardrailId}'${reason !== undefined ? ` (${reason})` : ''}`;
+    }),
+    ...blockingErrors.map(couldNotRun),
+  ];
+  return `Turn blocked by ${named.length} guardrails: ${named.join('; ')}`;
 }
 
 /**
@@ -324,8 +385,11 @@ export interface GuardrailViolationError {
   readonly code: 'guardrail-violation';
   readonly message: string;
   readonly violations: readonly EvaluationResult[];
-  /** Errors from checks that couldn't even evaluate (missing check, bad config). */
-  readonly evaluationErrors: readonly { readonly guardrailId: string; readonly message: string }[];
+  /**
+   * Guardrails whose check couldn't even evaluate (missing check, bad config). A `halt`
+   * guardrail's error blocks the turn on its own, so `violations` can be empty.
+   */
+  readonly evaluationErrors: readonly GuardrailEvaluationError[];
 }
 
 /**

package/src/handlers/build-initial-messages.ts

@@ -4,21 +4,33 @@
 import type { ModelMessage, ModelToolCall } from '@kindgi/capabilities';
 import type { NodeHandler } from '@kindgi/handler';
 
-import { formatRetrievedForPrompt } from '../retrieval.js';
+import {
+  MEMORY_DATA_RULE,
+  formatPoliciesForPrompt,
+  formatRetrievedForPrompt,
+  isPolicyFact,
+} from '../retrieval.js';
 import type { ConversationMessage } from '../types.js';
 
 import type { TurnContext } from './context.js';
 import { throwAgentTurnFailure } from './errors.js';
+import { readHistory } from './history.js';
 
 /**
  * Compose the initial `modelMessages` array the loop's first iteration
  * feeds to the model:
  *
- *   [ system: rendered prompt,
- *     system: retrieved context (if any),
+ *   [ system: rendered prompt
+ *             (+ the memory rule, + "Policies (verified)", when there are),
  *     ...history,
+ *     user: <memory> data block (if anything was retrieved),
  *     user: current message ]
  *
+ * Retrieved facts are data: a labelled block in a user-role message, read
+ * as information about the world, never as instructions. Only a verified
+ * fact of a type the agent lists in `memory.instructionTypes` is an
+ * instruction, in the system message.
+ *
  * Output shape: `{ nextMessages: ModelMessage[] }` — matches the loop
  * iteration output's `nextMessages` field so the loop body can treat
  * iteration 0's input identically to subsequent iterations'.
@@ -37,24 +49,14 @@ export function buildBuildInitialMessagesHandler(ctx: TurnContext): NodeHandler
     // the closure by render-prompt through the local field `renderedPrompt`).
     void input;
 
-    const historyLimit = ctx.input.agent.conversationPolicy?.historyLimit;
-    const messages = await ctx.bindings.conversationBinding.readMessages({
-      tenantId: ctx.input.tenantId,
-      conversationId: ctx.input.conversationId,
-    });
-    if (messages.kind === 'err') throwAgentTurnFailure(messages.error);
-    // The user message just appended is included in the history read;
-    // drop it because the composer adds it explicitly as the last
-    // element.
-    const historyRaw = messages.value.filter((m) => m.sequence !== ctx.userMessage?.sequence);
-    const history =
-      historyLimit === undefined
-        ? historyRaw
-        : historyRaw.slice(Math.max(0, historyRaw.length - historyLimit));
+    const history = await readHistory(ctx);
 
-    const contextBlock = formatRetrievedForPrompt(ctx.retrieved);
-    const contextMessage: ModelMessage | undefined =
-      contextBlock.length > 0 ? { role: 'system', content: contextBlock } : undefined;
+    const agent = ctx.input.agent;
+    const policies = ctx.retrieved.filter((r) => isPolicyFact(agent, r));
+    const data = ctx.retrieved.filter((r) => !isPolicyFact(agent, r));
+    const memoryBlock = formatRetrievedForPrompt(data, ctx.recalled ?? []);
+    const memoryMessage: ModelMessage | undefined =
+      memoryBlock.length > 0 ? { role: 'user', content: memoryBlock } : undefined;
 
     const rendered = ctx.renderedPrompt;
     if (rendered === undefined) {
@@ -65,10 +67,15 @@ export function buildBuildInitialMessagesHandler(ctx: TurnContext): NodeHandler
       });
     }
 
+    const system = [
+      rendered,
+      ...(memoryMessage !== undefined ? [MEMORY_DATA_RULE] : []),
+      ...(policies.length > 0 ? [formatPoliciesForPrompt(policies)] : []),
+    ].join('\n\n');
     const modelMessages: ModelMessage[] = [
-      { role: 'system', content: rendered },
-      ...(contextMessage !== undefined ? [contextMessage] : []),
+      { role: 'system', content: system },
       ...history.map(conversationToModelMessage),
+      ...(memoryMessage !== undefined ? [memoryMessage] : []),
       { role: 'user', content: ctx.input.userMessage },
     ];
 

package/src/handlers/compose-result.ts

@@ -72,6 +72,7 @@ export function buildComposeResultHandler(ctx: TurnContext): NodeHandler {
       appended: ctx.appended,
       response: ctx.finalMessage,
       retrieved: ctx.retrieved ?? [],
+      ...(ctx.recalled !== undefined && ctx.recalled.length > 0 && { recalled: ctx.recalled }),
       violations: ctx.nonBlockingViolations ?? [],
       usage,
       provider,
@@ -90,6 +91,7 @@ export function buildComposeResultHandler(ctx: TurnContext): NodeHandler {
       turnNumber: ctx.conversation.turnCount + 1,
       response: ctx.finalMessage,
       retrieved: ctx.retrieved ?? [],
+      ...(ctx.recalled !== undefined && ctx.recalled.length > 0 && { recalled: ctx.recalled }),
       durationMs,
       totalCostUsd: ctx.usage.totalCostUsd,
     });

package/src/handlers/context.ts

@@ -16,7 +16,13 @@ import type { EvaluationResult } from '@kindgi/guardrails';
 
 import type { EffectiveHitlPolicy } from '../hitl-policy.js';
 import type { ProvenanceBindings } from '../provenance-emit.js';
-import type { Agent, Conversation, ConversationMessage, RetrievedFact } from '../types.js';
+import type {
+  Agent,
+  Conversation,
+  ConversationMessage,
+  RecalledMemory,
+  RetrievedFact,
+} from '../types.js';
 
 import type { HitlBindings, InvokeAgentBindings, InvokeAgentInput } from './public-types.js';
 import type { TurnBlocks } from './resolve-blocks.js';
@@ -103,6 +109,11 @@ export interface TurnContext {
    * Populated by `run-retrievals` — facts pulled by declared intents.
    */
   retrieved?: readonly RetrievedFact[];
+  /**
+   * Populated by `run-retrievals` — messages of earlier conversations
+   * recalled by intents over conversations.
+   */
+  recalled?: readonly RecalledMemory[];
   /**
    * Populated by `persist-final-message` — the terminal assistant
    * message. `compose-result` reads it back for the returned