@stigmer/runner 3.12.7 → 3.12.9

package/src/shared/__tests__/memory-attachment.test.ts

@@ -0,0 +1,167 @@
+/**
+ * The memory capture attachment (DD-005 D1): the recall-snapshot gate
+ * (enabled bit, zero-facts included), both connection shapes with the
+ * capture-context carriers, the structural approval-freedom of
+ * synthesized attachments, and the cross-repo string pins (route +
+ * context keys, guarded here and in the mcp-server memory integration
+ * test — the TOOL_CALL_LIMIT precedent). The slug and roster are
+ * runner-internal and guarded here alone.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+import { RecalledMemoriesSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+
+import { mergeApprovalPolicies, type ActiveLeases } from "../approval-policy.js";
+import { needsBackfill } from "../connect-backfill.js";
+import {
+  MEMORY_AGENT_ID_ENV,
+  MEMORY_AGENT_ID_HEADER,
+  MEMORY_ATTACHMENT_SLUG,
+  MEMORY_EXECUTION_ID_ENV,
+  MEMORY_EXECUTION_ID_HEADER,
+  MEMORY_ORG_ENV,
+  MEMORY_ORG_HEADER,
+  MEMORY_ROUTE,
+  MEMORY_SESSION_ID_ENV,
+  MEMORY_SESSION_ID_HEADER,
+  memoryCaptureEnabled,
+  synthesizeMemoryAttachment,
+  type MemoryCaptureContext,
+} from "../memory-attachment.js";
+import type { ResolvedMcpServer } from "../mcp-resolver.js";
+
+const context: MemoryCaptureContext = {
+  org: "acme",
+  agentId: "agt_1",
+  sessionId: "ses_1",
+  agentExecutionId: "aex_1",
+};
+
+const cloudOptions = {
+  bridgeEndpoint: "https://mcp.stigmer.ai/",
+  credential: "sandbox-token",
+  backendEndpoint: "http://localhost:7234",
+};
+
+const ossOptions = {
+  bridgeEndpoint: null,
+  credential: null,
+  backendEndpoint: "http://localhost:7234",
+};
+
+const noLeases: ActiveLeases = {
+  global: false,
+  categories: new Set(),
+  servers: new Set(),
+};
+
+describe("memoryCaptureEnabled (the DD-005 D1 injection signal)", () => {
+  it("is the snapshot's enabled bit — absent and disabled read false", () => {
+    expect(memoryCaptureEnabled(undefined)).toBe(false);
+    expect(memoryCaptureEnabled(create(RecalledMemoriesSchema, { enabled: false }))).toBe(false);
+    expect(memoryCaptureEnabled(create(RecalledMemoriesSchema, { enabled: true }))).toBe(true);
+  });
+
+  it("enabled with ZERO facts still offers the tool — memory on, nothing stored yet", () => {
+    const snapshot = create(RecalledMemoriesSchema, { enabled: true, facts: [] });
+    expect(memoryCaptureEnabled(snapshot)).toBe(true);
+    expect(synthesizeMemoryAttachment(snapshot, context, cloudOptions)).toBeDefined();
+  });
+});
+
+describe("synthesizeMemoryAttachment", () => {
+  const enabled = create(RecalledMemoriesSchema, { enabled: true });
+
+  it("returns undefined when the snapshot is absent or disabled — honest absence", () => {
+    expect(synthesizeMemoryAttachment(undefined, context, cloudOptions)).toBeUndefined();
+    expect(
+      synthesizeMemoryAttachment(
+        create(RecalledMemoriesSchema, { enabled: false }),
+        context,
+        cloudOptions,
+      ),
+    ).toBeUndefined();
+  });
+
+  it("builds the HTTP shape against the bridge /memory route with credential + context headers", () => {
+    const attachment = synthesizeMemoryAttachment(enabled, context, cloudOptions);
+    expect(attachment).toMatchObject({
+      slug: MEMORY_ATTACHMENT_SLUG,
+      connectionType: "http",
+      url: "https://mcp.stigmer.ai/memory",
+      headers: {
+        Authorization: "Bearer sandbox-token",
+        [MEMORY_ORG_HEADER]: "acme",
+        [MEMORY_AGENT_ID_HEADER]: "agt_1",
+        [MEMORY_SESSION_ID_HEADER]: "ses_1",
+        [MEMORY_EXECUTION_ID_HEADER]: "aex_1",
+      },
+    });
+  });
+
+  it("builds the OSS stdio shape: the CLI-embedded bridge with the memory roster + context env", () => {
+    const attachment = synthesizeMemoryAttachment(enabled, context, ossOptions);
+    expect(attachment).toMatchObject({
+      connectionType: "stdio",
+      command: "stigmer",
+      args: ["mcp-server"],
+      env: {
+        STIGMER_MCP_ROSTER: "memory",
+        STIGMER_SERVER_ADDRESS: "localhost:7234",
+        [MEMORY_ORG_ENV]: "acme",
+        [MEMORY_AGENT_ID_ENV]: "agt_1",
+        [MEMORY_SESSION_ID_ENV]: "ses_1",
+        [MEMORY_EXECUTION_ID_ENV]: "aex_1",
+      },
+    });
+  });
+
+  it("omits empty context fields from the carrier — best-effort attribution, never blank entries", () => {
+    const partial: MemoryCaptureContext = {
+      org: "acme",
+      agentId: "",
+      sessionId: "ses_1",
+      agentExecutionId: "",
+    };
+
+    const http = synthesizeMemoryAttachment(enabled, partial, cloudOptions);
+    expect(Object.keys(http?.headers ?? {}).sort()).toEqual([
+      "Authorization",
+      MEMORY_ORG_HEADER,
+      MEMORY_SESSION_ID_HEADER,
+    ].sort());
+
+    const stdio = synthesizeMemoryAttachment(enabled, partial, ossOptions);
+    expect(stdio?.env).not.toHaveProperty(MEMORY_AGENT_ID_ENV);
+    expect(stdio?.env).not.toHaveProperty(MEMORY_EXECUTION_ID_ENV);
+  });
+
+  it("pins the cross-repo strings the mcp-server side guards too", () => {
+    expect(MEMORY_ATTACHMENT_SLUG).toBe("stigmer-memory");
+    expect(MEMORY_ROUTE).toBe("/memory");
+    expect(MEMORY_ORG_HEADER).toBe("x-stigmer-memory-org");
+    expect(MEMORY_AGENT_ID_HEADER).toBe("x-stigmer-memory-agent-id");
+    expect(MEMORY_SESSION_ID_HEADER).toBe("x-stigmer-memory-session-id");
+    expect(MEMORY_EXECUTION_ID_HEADER).toBe("x-stigmer-memory-execution-id");
+    expect(MEMORY_ORG_ENV).toBe("STIGMER_MEMORY_ORG");
+    expect(MEMORY_AGENT_ID_ENV).toBe("STIGMER_MEMORY_AGENT_ID");
+    expect(MEMORY_SESSION_ID_ENV).toBe("STIGMER_MEMORY_SESSION_ID");
+    expect(MEMORY_EXECUTION_ID_ENV).toBe("STIGMER_MEMORY_EXECUTION_ID");
+  });
+
+  it("is approval-free by construction: zero entries in the merged approval map", () => {
+    // Consent is the confirm RPC, not tool approval (DD-005 D3): the
+    // tool only creates a proposal, so gating it would stack a second
+    // consent gate in front of the real one.
+    const attachment = synthesizeMemoryAttachment(enabled, context, cloudOptions)!;
+    const merged = mergeApprovalPolicies([attachment as ResolvedMcpServer], noLeases);
+    expect(merged.size).toBe(0);
+  });
+
+  it("is structurally immune to the connect backfill (destructiveHint tightener)", () => {
+    const attachment = synthesizeMemoryAttachment(enabled, context, cloudOptions)!;
+    expect(attachment.discoveredCapabilitiesEmpty).toBe(false);
+    expect(needsBackfill(attachment)).toBe(false);
+  });
+});

package/src/shared/__tests__/memory-retrieval.test.ts

@@ -0,0 +1,310 @@
+/**
+ * Unit tests for the memory-retrieval module (stigmer/stigmer#293 Phase 3a,
+ * DD-008). What is pinned here, path by path:
+ *
+ *  - The activation threshold: selection runs ONLY above RETRIEVAL_K
+ *    candidates; at or below it there is NO embeddings call (most users
+ *    never touch the embeddings API — the DD-008 D3 activation contract).
+ *  - Top-k correctness and the presentation contract: selection is by
+ *    relevance, presentation is snapshot order, ties break toward the
+ *    lower snapshot index (deterministic across invocations).
+ *  - The failure posture: every degraded path — no embedder, embed error,
+ *    malformed response — injects wholesale with an honest
+ *    selection_active=false report, never a throw into prompt build.
+ *  - The written-once replay: a prior report (either polarity) replays
+ *    without an embeddings call, so a re-invocation can never inject a
+ *    different subset than the first invocation did.
+ *  - The report contract: a report exists exactly when facts are injected;
+ *    no injection, no report (absent report = wholesale by construction).
+ */
+
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { RecalledMemoriesSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import { RecalledMemoriesReportSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+
+import {
+  selectRecalledFacts,
+  RETRIEVAL_K,
+  EMBEDDING_MODEL,
+  QUERY_MAX_CHARS,
+  type EmbedFn,
+} from "../memory-retrieval.js";
+
+const QUERY = "How should I deploy the payments service?";
+
+/** Snapshot of `count` facts: mem_0..mem_{count-1}, "fact 0".."fact N". */
+function snapshot(count: number) {
+  return create(RecalledMemoriesSchema, {
+    enabled: true,
+    facts: Array.from({ length: count }, (_, i) => ({
+      memoryId: `mem_${i}`,
+      content: `fact ${i}`,
+    })),
+  });
+}
+
+/**
+ * A deterministic embedder over 2D unit vectors: the query embeds to
+ * [1, 0]; fact i embeds to an angle that grows with i, so relevance order
+ * is exactly snapshot order (fact 0 most similar) unless a test overrides
+ * per-input vectors.
+ */
+function angularEmbedder(overrides?: Map<string, number[]>): EmbedFn & {
+  calls: string[][];
+} {
+  const calls: string[][] = [];
+  const fn: EmbedFn = async (inputs) => {
+    calls.push([...inputs]);
+    return inputs.map((input, position) => {
+      const override = overrides?.get(input);
+      if (override) return override;
+      if (position === 0) return [1, 0];
+      const angle = (position / (inputs.length + 1)) * (Math.PI / 2);
+      return [Math.cos(angle), Math.sin(angle)];
+    });
+  };
+  return Object.assign(fn, { calls });
+}
+
+function baseOptions(embed: EmbedFn) {
+  return {
+    proxyEndpoint: null,
+    stigmerToken: null,
+    executionId: "exec_test",
+    embed,
+  };
+}
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("selectRecalledFacts — no injection, no report", () => {
+  it("answers nothing for an absent snapshot (pre-Phase-2 executions)", async () => {
+    const embed = angularEmbedder();
+    const result = await selectRecalledFacts(undefined, QUERY, baseOptions(embed));
+    expect(result.content).toBeUndefined();
+    expect(result.report).toBeUndefined();
+    expect(embed.calls).toHaveLength(0);
+  });
+
+  it("answers nothing when recall is disabled or enabled-with-zero-facts", async () => {
+    const embed = angularEmbedder();
+    const disabled = create(RecalledMemoriesSchema, {
+      enabled: false,
+      facts: [{ memoryId: "mem_0", content: "fact 0" }],
+    });
+    expect(
+      (await selectRecalledFacts(disabled, QUERY, baseOptions(embed))).report,
+    ).toBeUndefined();
+    const empty = create(RecalledMemoriesSchema, { enabled: true });
+    expect(
+      (await selectRecalledFacts(empty, QUERY, baseOptions(embed))).report,
+    ).toBeUndefined();
+    expect(embed.calls).toHaveLength(0);
+  });
+});
+
+describe("selectRecalledFacts — activation threshold (DD-008 D3)", () => {
+  it("injects wholesale with NO embeddings call at exactly k candidates", async () => {
+    const embed = angularEmbedder();
+    const result = await selectRecalledFacts(
+      snapshot(RETRIEVAL_K),
+      QUERY,
+      baseOptions(embed),
+    );
+
+    expect(embed.calls).toHaveLength(0);
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K);
+    expect(result.report?.selectionActive).toBe(false);
+    expect(result.report?.injectedMemoryIds).toEqual([]);
+    expect(result.report?.embeddingModel).toBe("");
+  });
+
+  it("activates selection at k+1: one batched call, k facts injected", async () => {
+    const embed = angularEmbedder();
+    const result = await selectRecalledFacts(
+      snapshot(RETRIEVAL_K + 1),
+      QUERY,
+      baseOptions(embed),
+    );
+
+    expect(embed.calls).toHaveLength(1);
+    expect(embed.calls[0]).toHaveLength(RETRIEVAL_K + 2); // query + all candidates
+    expect(embed.calls[0][0]).toBe(QUERY);
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K);
+    expect(result.report?.selectionActive).toBe(true);
+    expect(result.report?.injectedMemoryIds).toHaveLength(RETRIEVAL_K);
+    expect(result.report?.embeddingModel).toBe(EMBEDDING_MODEL);
+    // The angular embedder makes the LAST fact least relevant.
+    expect(result.report?.injectedMemoryIds).not.toContain(`mem_${RETRIEVAL_K}`);
+  });
+
+  it("counts only renderable candidates toward the threshold (blank facts dropped, the read-boundary semantics)", async () => {
+    const embed = angularEmbedder();
+    const recalled = create(RecalledMemoriesSchema, {
+      enabled: true,
+      facts: [
+        ...Array.from({ length: RETRIEVAL_K }, (_, i) => ({
+          memoryId: `mem_${i}`,
+          content: `fact ${i}`,
+        })),
+        { memoryId: "mem_blank", content: "   " },
+      ],
+    });
+
+    const result = await selectRecalledFacts(recalled, QUERY, baseOptions(embed));
+
+    expect(embed.calls).toHaveLength(0); // 20 renderable ≤ k → wholesale
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K);
+    expect(result.report?.selectionActive).toBe(false);
+  });
+});
+
+describe("selectRecalledFacts — ranking and presentation", () => {
+  it("selects by relevance but presents in snapshot order, ids parallel to facts", async () => {
+    // Invert relevance: the LAST fact is the most similar, fact 0 the least.
+    const count = RETRIEVAL_K + 5;
+    const overrides = new Map<string, number[]>();
+    for (let i = 0; i < count; i++) {
+      const angle = ((count - i) / (count + 1)) * (Math.PI / 2);
+      overrides.set(`fact ${i}`, [Math.cos(angle), Math.sin(angle)]);
+    }
+    const embed = angularEmbedder(overrides);
+
+    const result = await selectRecalledFacts(
+      snapshot(count),
+      QUERY,
+      baseOptions(embed),
+    );
+
+    // The 5 least relevant under inversion are the FIRST five snapshot facts.
+    const expectedIndices = Array.from({ length: RETRIEVAL_K }, (_, i) => i + 5);
+    expect(result.content?.facts).toEqual(expectedIndices.map((i) => `fact ${i}`));
+    expect(result.report?.injectedMemoryIds).toEqual(
+      expectedIndices.map((i) => `mem_${i}`),
+    );
+  });
+
+  it("breaks ties toward the lower snapshot index — equal scores never reorder across invocations", async () => {
+    // Every input embeds identically: all scores tie.
+    const count = RETRIEVAL_K + 3;
+    const overrides = new Map<string, number[]>([[QUERY, [1, 0]]]);
+    for (let i = 0; i < count; i++) {
+      overrides.set(`fact ${i}`, [1, 0]);
+    }
+    const embed = angularEmbedder(overrides);
+
+    const first = await selectRecalledFacts(snapshot(count), QUERY, baseOptions(embed));
+    const second = await selectRecalledFacts(snapshot(count), QUERY, baseOptions(embed));
+
+    const expected = Array.from({ length: RETRIEVAL_K }, (_, i) => `mem_${i}`);
+    expect(first.report?.injectedMemoryIds).toEqual(expected);
+    expect(second.report?.injectedMemoryIds).toEqual(expected);
+  });
+
+  it("truncates the query at QUERY_MAX_CHARS — a giant paste must not 400 the whole batch", async () => {
+    const embed = angularEmbedder();
+    const giant = "x".repeat(QUERY_MAX_CHARS + 500);
+
+    await selectRecalledFacts(snapshot(RETRIEVAL_K + 1), giant, baseOptions(embed));
+
+    expect(embed.calls[0][0]).toHaveLength(QUERY_MAX_CHARS);
+  });
+});
+
+describe("selectRecalledFacts — failure posture (never worse than Phase 2)", () => {
+  it("degrades to wholesale with an honest report when the embedder throws", async () => {
+    const embed: EmbedFn = async () => {
+      throw new Error("connect ETIMEDOUT");
+    };
+    const result = await selectRecalledFacts(
+      snapshot(RETRIEVAL_K + 1),
+      QUERY,
+      baseOptions(embed),
+    );
+
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K + 1);
+    expect(result.report?.selectionActive).toBe(false);
+    expect(result.report?.injectedMemoryIds).toEqual([]);
+  });
+
+  it("degrades to wholesale when the embedder answers the wrong vector count", async () => {
+    const embed: EmbedFn = async () => [[1, 0]];
+    const result = await selectRecalledFacts(
+      snapshot(RETRIEVAL_K + 1),
+      QUERY,
+      baseOptions(embed),
+    );
+
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K + 1);
+    expect(result.report?.selectionActive).toBe(false);
+  });
+
+  it("injects wholesale when no embedder resolves (no proxy, no OpenAI key — the Anthropic-only OSS posture)", async () => {
+    vi.stubEnv("OPENAI_API_KEY", "");
+
+    const result = await selectRecalledFacts(snapshot(RETRIEVAL_K + 1), QUERY, {
+      proxyEndpoint: null,
+      stigmerToken: null,
+      executionId: "exec_test",
+      // No embed injected: the module resolves — and finds — nothing.
+    });
+
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K + 1);
+    expect(result.report?.selectionActive).toBe(false);
+  });
+});
+
+describe("selectRecalledFacts — written-once replay across re-invocations", () => {
+  it("replays a selection-active prior report without an embeddings call", async () => {
+    const embed = angularEmbedder();
+    const prior = create(RecalledMemoriesReportSchema, {
+      selectionActive: true,
+      injectedMemoryIds: ["mem_1", "mem_3"],
+      embeddingModel: EMBEDDING_MODEL,
+    });
+
+    const result = await selectRecalledFacts(snapshot(RETRIEVAL_K + 1), QUERY, {
+      ...baseOptions(embed),
+      priorReport: prior,
+    });
+
+    expect(embed.calls).toHaveLength(0);
+    expect(result.content?.facts).toEqual(["fact 1", "fact 3"]);
+    expect(result.report).toBe(prior);
+  });
+
+  it("replays a wholesale prior report as wholesale — a recorded embed failure is never retried into a different prompt", async () => {
+    const embed = angularEmbedder();
+    const prior = create(RecalledMemoriesReportSchema, { selectionActive: false });
+
+    const result = await selectRecalledFacts(snapshot(RETRIEVAL_K + 1), QUERY, {
+      ...baseOptions(embed),
+      priorReport: prior,
+    });
+
+    expect(embed.calls).toHaveLength(0);
+    expect(result.content?.facts).toHaveLength(RETRIEVAL_K + 1);
+    expect(result.report?.selectionActive).toBe(false);
+  });
+
+  it("re-selects when a recorded id does not resolve against the snapshot (structurally impossible, defended anyway)", async () => {
+    const embed = angularEmbedder();
+    const prior = create(RecalledMemoriesReportSchema, {
+      selectionActive: true,
+      injectedMemoryIds: ["mem_1", "mem_never_existed"],
+      embeddingModel: EMBEDDING_MODEL,
+    });
+
+    const result = await selectRecalledFacts(snapshot(RETRIEVAL_K + 1), QUERY, {
+      ...baseOptions(embed),
+      priorReport: prior,
+    });
+
+    expect(embed.calls).toHaveLength(1);
+    expect(result.report?.selectionActive).toBe(true);
+    expect(result.report?.injectedMemoryIds).toHaveLength(RETRIEVAL_K);
+  });
+});

package/src/shared/memory-attachment.ts

@@ -0,0 +1,167 @@
+/**
+ * The runner-synthesized memory capture attachment (DD-005 D1).
+ *
+ * When the execution's recall snapshot says memory is on
+ * (`spec.recalled_memories.enabled` — the ONE server-owned field that
+ * serves both the recall and capture sides, stamped by the create
+ * pipeline's compose step), the runner synthesizes ONE MCP attachment
+ * serving the `remember` tool. No discovery RPC exists on this path:
+ * unlike the channel attachment's registry read, the enablement answer
+ * is already on the spec — a free, synchronous read (the
+ * conversation-attachment session-label precedent). The enabled bit with
+ * ZERO facts is a meaningful state: memory is on, nothing stored yet —
+ * the tool is offered so the first fact can be proposed.
+ *
+ * Two connection shapes, one roster (the channels pattern):
+ *   - Bridge endpoint configured (cloud): Streamable HTTP against the
+ *     bridge's /memory route with the execution's own session-scoped
+ *     credential as the Bearer token, plus the capture context as
+ *     per-request headers.
+ *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
+ *     stdio child with STIGMER_MCP_ROSTER=memory, plus the capture
+ *     context as STIGMER_MEMORY_* env.
+ *
+ * The capture context (org + agent/session/execution ids) is
+ * attribution, never authorization (the Stage 3 provenance decision,
+ * owner-ratified 2026-08-22): the cloud create handler accepts it only
+ * from a session-sandbox credential and overrides session/org with the
+ * token's own claims; the OSS server stores it under the local
+ * single-user trust model. The subject is never threaded — the server
+ * derives it from the credential (DD-005 D2).
+ *
+ * Approval-free by construction (the synthesized-attachment contract):
+ * the tool only ever creates a PROPOSAL the user must confirm through
+ * the control plane, so gating the propose call would stack a second
+ * consent gate in front of the real one (DD-005 D3: consent is the
+ * confirm RPC, not tool approval). Callers inject AFTER resolve +
+ * backfill.
+ *
+ * Failure posture: the attachment is synthesized from values already in
+ * hand, so the only failure mode is the create RPC refusing at call
+ * time — which the mcp-server's memory error mapper relays honestly.
+ * When the snapshot is absent or disabled: no tool, honest absence.
+ */
+
+import type { RecalledMemories } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
+import type { ResolvedMcpServer } from "./mcp-resolver.js";
+import { grpcTarget, type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
+
+/**
+ * The synthesized attachment's slug. Reserved: a user McpServer with
+ * this slug is shadowed by the synthesized attachment, with a warning.
+ * Runner-internal (the resolved-server name and shadow key — the
+ * mcp-server never sees it); pinned by this module's test. The ROUTE
+ * and the context keys below are cross-repo strings, pinned on both
+ * sides (the TOOL_CALL_LIMIT precedent).
+ */
+export const MEMORY_ATTACHMENT_SLUG = "stigmer-memory";
+
+/** The bridge route serving the memory-only roster (mcp-server twin: MEMORY_ROUTE). */
+export const MEMORY_ROUTE = "/memory";
+
+/**
+ * The capture-context carriers, mirrored byte-for-byte by the
+ * mcp-server's memory domain (domains/memory/context.ts): headers on
+ * the bridge's per-request path, env on the stdio child — the same
+ * per-request-then-startup split the credential itself uses.
+ */
+export const MEMORY_ORG_HEADER = "x-stigmer-memory-org";
+export const MEMORY_AGENT_ID_HEADER = "x-stigmer-memory-agent-id";
+export const MEMORY_SESSION_ID_HEADER = "x-stigmer-memory-session-id";
+export const MEMORY_EXECUTION_ID_HEADER = "x-stigmer-memory-execution-id";
+
+export const MEMORY_ORG_ENV = "STIGMER_MEMORY_ORG";
+export const MEMORY_AGENT_ID_ENV = "STIGMER_MEMORY_AGENT_ID";
+export const MEMORY_SESSION_ID_ENV = "STIGMER_MEMORY_SESSION_ID";
+export const MEMORY_EXECUTION_ID_ENV = "STIGMER_MEMORY_EXECUTION_ID";
+
+/**
+ * Where a proposed memory comes from — threaded to the mcp-server so
+ * the create request carries org addressing and provenance. Empty
+ * fields are omitted from the carrier (best-effort attribution; the
+ * server treats absent as empty).
+ */
+export interface MemoryCaptureContext {
+  readonly org: string;
+  readonly agentId: string;
+  readonly sessionId: string;
+  readonly agentExecutionId: string;
+}
+
+/**
+ * Reports whether the execution's recall snapshot offers the remember
+ * tool (DD-005 D1: the snapshot's enabled bit IS the runner's injection
+ * signal — one server-owned field, no parallel flag, no discovery
+ * round-trip). Exposed for the harnesses' MCP gates, which must open
+ * MCP resolution for a memory-only agent.
+ */
+export function memoryCaptureEnabled(recalled: RecalledMemories | undefined): boolean {
+  return recalled?.enabled === true;
+}
+
+/**
+ * Synthesize the memory capture attachment. Returns undefined when the
+ * recall snapshot is absent or disabled — the attachment exists exactly
+ * when the server-composed snapshot says memory is on.
+ */
+export function synthesizeMemoryAttachment(
+  recalled: RecalledMemories | undefined,
+  context: MemoryCaptureContext,
+  options: SynthesizedAttachmentOptions,
+): ResolvedMcpServer | undefined {
+  if (!memoryCaptureEnabled(recalled)) {
+    return undefined;
+  }
+
+  // Approval-free by construction + backfill-proof: see file header.
+  const base = {
+    slug: MEMORY_ATTACHMENT_SLUG,
+    toolApprovals: [],
+    pinnedToolApprovals: [],
+    toolApprovalOverrides: [],
+    discoveredCapabilitiesEmpty: false,
+  };
+
+  if (options.bridgeEndpoint !== null && options.bridgeEndpoint !== "") {
+    return {
+      ...base,
+      connectionType: "http",
+      url: options.bridgeEndpoint.replace(/\/+$/, "") + MEMORY_ROUTE,
+      headers: {
+        ...(options.credential !== null && options.credential !== ""
+          ? { Authorization: `Bearer ${options.credential}` }
+          : undefined),
+        ...nonEmptyEntries([
+          [MEMORY_ORG_HEADER, context.org],
+          [MEMORY_AGENT_ID_HEADER, context.agentId],
+          [MEMORY_SESSION_ID_HEADER, context.sessionId],
+          [MEMORY_EXECUTION_ID_HEADER, context.agentExecutionId],
+        ]),
+      },
+    };
+  }
+
+  return {
+    ...base,
+    connectionType: "stdio",
+    command: "stigmer",
+    args: ["mcp-server"],
+    env: {
+      STIGMER_MCP_ROSTER: "memory",
+      STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+      ...nonEmptyEntries([
+        [MEMORY_ORG_ENV, context.org],
+        [MEMORY_AGENT_ID_ENV, context.agentId],
+        [MEMORY_SESSION_ID_ENV, context.sessionId],
+        [MEMORY_EXECUTION_ID_ENV, context.agentExecutionId],
+      ]),
+    },
+  };
+}
+
+/** The non-empty context fields as carrier entries (absent means empty). */
+function nonEmptyEntries(
+  pairs: ReadonlyArray<readonly [string, string]>,
+): Record<string, string> {
+  return Object.fromEntries(pairs.filter(([, value]) => value !== ""));
+}