@ixo/oracle-runtime-workers 0.23.0 → 0.25.0

package/src/memory/session-history-indexer.ts

@@ -16,7 +16,10 @@
  *  - Auth is the oracle's two-hop UCAN invocation minted from the user's
  *    delegation (`ixo:memory` / `memory/*`) — no delegation, no indexing.
  *  - Endpoint: `POST <MEMORY_ENGINE_URL>/messages` with `x-room-id`, as
- *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`.
+ *    `@ixo/common`'s `MemoryEngineService.processConversationHistory`, plus
+ *    `x-oracle-entity-did`: the engine keys the user's space by the oracle's
+ *    domain entity (`ORACLE_ENTITY_DID`). Without one nothing is indexed
+ *    (one warning per indexer) and the watermark stays put.
  *  - A per-session lock prevents overlapping runs; a failed upload is
  *    retried 3× with a 10 s pause (Node's numbers).
  *
@@ -24,6 +27,7 @@
  * preferred name is set; here the fallback is the literal "Me" straight away.
  */
 import type { Logger } from '../plugin-api/types';
+import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
 
 export interface HistoryMessage {
   /** LangChain message type: `human` | `ai` | `tool` | `system`. */
@@ -53,6 +57,12 @@ export interface SpeakerLabels {
 export interface SessionHistoryIndexerDeps {
   /** `MEMORY_ENGINE_URL`; undefined disables indexing (memory plugin absent). */
   memoryEngineUrl: string | undefined;
+  /**
+   * The configured `ORACLE_ENTITY_DID` (a well-formed domain entity DID),
+   * sent as `x-oracle-entity-did`. Never the `ORACLE_DID` fallback:
+   * undefined → every session is `skipped`.
+   */
+  entityDid: string | undefined;
   getSession(sessionId: string): Promise<IndexableSession | undefined>;
   /** The session transcript, summarisation bookkeeping already removed. */
   listMessages(sessionId: string): Promise<HistoryMessage[]>;
@@ -153,6 +163,9 @@ export class SessionHistoryIndexer {
 
   private readonly requestTimeoutMs: number;
 
+  /** The missing-entity warning has been logged (it is logged once). */
+  private warnedNoEntity = false;
+
   constructor(private readonly deps: SessionHistoryIndexerDeps) {
     this.fetchImpl = deps.fetchImpl ?? fetch.bind(globalThis);
     this.sleep =
@@ -187,6 +200,16 @@ export class SessionHistoryIndexer {
       );
       return 'skipped';
     }
+    const entityDid = this.deps.entityDid;
+    if (!entityDid) {
+      if (!this.warnedNoEntity) {
+        this.warnedNoEntity = true;
+        logger.warn(
+          `[history-indexer] ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>); the memory engine keys every space by it, so session history is not indexed`,
+        );
+      }
+      return 'skipped';
+    }
     if (this.inFlight.has(sessionId)) {
       logger.log(
         `[history-indexer] session ${sessionId} is already being indexed, skipping`,
@@ -197,7 +220,7 @@ export class SessionHistoryIndexer {
     try {
       for (let attempt = 1; attempt <= this.maxRetries; attempt += 1) {
         try {
-          const outcome = await this.processOnce(sessionId);
+          const outcome = await this.processOnce(sessionId, entityDid);
           if (outcome === 'processed') {
             logger.log(
               `[history-indexer] indexed session ${sessionId} into the memory engine`,
@@ -223,7 +246,10 @@ export class SessionHistoryIndexer {
     }
   }
 
-  private async processOnce(sessionId: string): Promise<IndexOutcome> {
+  private async processOnce(
+    sessionId: string,
+    entityDid: string,
+  ): Promise<IndexOutcome> {
     const { deps } = this;
     const { logger } = deps;
     const memoryEngineUrl = deps.memoryEngineUrl!.replace(/\/+$/, '');
@@ -306,6 +332,7 @@ export class SessionHistoryIndexer {
         headers: {
           Authorization: `Bearer ${invocation}`,
           'X-Auth-Type': 'ucan',
+          [MEMORY_ENTITY_HEADER]: entityDid,
           'x-room-id': roomId,
           'Content-Type': 'application/json',
         },

package/src/memory/user-context-fetcher.ts

@@ -9,7 +9,8 @@
  * memory-context block before the model's first call.
  *
  * Policy:
- *  - The result is a function of the room (and the oracle), not the session,
+ *  - The result is a function of the room (and the oracle's domain entity,
+ *    which keys every memory space on the engine), not the session,
  *    so the cache is keyed by room: a new session in the same room reuses it.
  *    Positive entries live `cacheTtlMs` (5 min) in an LRU of `maxCachedRooms`.
  *    A successful batch is cached even when every slot is empty — "no
@@ -25,7 +26,9 @@
  *    a memory write and after session history is indexed.
  *  - A missing signing key or a failed invocation mint is a skip, never a
  *    negative-cache entry: the user may delegate `ixo:memory` before the next
- *    turn.
+ *    turn. So is a missing domain entity (`ORACLE_ENTITY_DID`): the engine
+ *    refuses a request that names none, so none is sent; it is warned about
+ *    once per fetcher.
  *  - One gather per room at a time; a second caller joins it. The blocking
  *    `fetch` waits at most `blockingCapMs`; past the cap the gather keeps
  *    running and fills the cache for later turns (the caller keeps the
@@ -41,6 +44,7 @@
  */
 import type { MemoryContextSection } from '../core/prompt-composer';
 import type { Logger, UserContextData } from '../plugin-api/types';
+import { MEMORY_ENTITY_HEADER } from '../plugins/memory/memory-entity';
 import type {
   ComparisonOperator,
   EntityType,
@@ -99,15 +103,17 @@ const RECENT_WINDOW_DAYS = 90;
  * brittle), `node_labels` only where it discriminates, and the `recent`
  * slot bounded to the last 90 days explicitly (the server's
  * `recent_memory` strategy injects the same lower bound and keeps an
- * existing one).
+ * existing one). `oracle_dids` names the oracle's domain entity.
  */
 export function buildUserContextQueries(
-  oracleDid: string,
+  entityDid: string,
   now: Date,
 ): UserContextQuery[] {
   const recentSince = new Date(now.getTime());
   recentSince.setUTCDate(recentSince.getUTCDate() - RECENT_WINDOW_DAYS);
-  const oracle_dids = [oracleDid];
+  // The wire name predates entity keying; the engine reads its entries as
+  // domain entity DIDs (the knowledge spaces the queries also search).
+  const oracle_dids = [entityDid];
   return [
     {
       oracle_dids,
@@ -471,8 +477,13 @@ function perSlot<T>(
 export interface UserContextFetcherDeps {
   /** `MEMORY_ENGINE_URL`; undefined → every call is `skipped`, no request. */
   memoryEngineUrl: string | undefined;
-  /** `ORACLE_DID` — the knowledge space the queries search (`oracle_dids`). */
-  oracleDid: string;
+  /**
+   * The configured `ORACLE_ENTITY_DID` (a well-formed domain entity DID) —
+   * sent as `x-oracle-entity-did` and as the queries' `oracle_dids`. Never
+   * the `ORACLE_DID` fallback: undefined → every call is `skipped`
+   * (`no-entity`), no request, one warning per fetcher.
+   */
+  entityDid: string | undefined;
   /** The user's UCAN surface, bound to the user's DID by the caller. */
   ucan: {
     hasSigningKey(): boolean;
@@ -515,6 +526,7 @@ const DEFAULT_MAX_CACHED_ROOMS = 64;
 
 export type UserContextSkipReason =
   | 'no-engine-url'
+  | 'no-entity'
   | 'no-signing-key'
   | 'no-invocation'
   | 'recently-failed'
@@ -616,6 +628,9 @@ export class UserContextFetcher {
 
   private readonly maxCachedRooms: number;
 
+  /** The missing-entity warning has been logged (it is logged once). */
+  private warnedNoEntity = false;
+
   constructor(
     private readonly deps: UserContextFetcherDeps,
     options: UserContextFetcherOptions = {},
@@ -773,6 +788,16 @@ export class UserContextFetcher {
       );
       return { kind: 'skipped', reason: 'no-engine-url' };
     }
+    const entityDid = this.deps.entityDid;
+    if (!entityDid) {
+      if (!this.warnedNoEntity) {
+        this.warnedNoEntity = true;
+        logger.warn(
+          `[user-context] skipped: ORACLE_ENTITY_DID is not a domain entity DID (did:ixo:entity:<32 hex>); the memory engine keys every space by it, so no first-turn context is gathered`,
+        );
+      }
+      return { kind: 'skipped', reason: 'no-entity' };
+    }
     if (!roomId) {
       logger.warn(`[user-context] skipped: no oracle room for this turn`);
       return { kind: 'skipped', reason: 'no-room' };
@@ -807,7 +832,7 @@ export class UserContextFetcher {
 
     const entry: InFlightGather = {
       startedAt: this.now(),
-      promise: this.gather(engineUrl, roomId).then(
+      promise: this.gather(engineUrl, entityDid, roomId).then(
         (result) => this.settle(roomId, entry, result),
         (err: unknown) =>
           this.settle(roomId, entry, {
@@ -870,6 +895,7 @@ export class UserContextFetcher {
   /** Mint the invocation, run the batch, map the slots. Never rejects. */
   private async gather(
     engineUrl: string,
+    entityDid: string,
     roomId: string,
   ): Promise<GatherResult> {
     const { logger, ucan } = this.deps;
@@ -905,14 +931,12 @@ export class UserContextFetcher {
         headers: {
           Authorization: `Bearer ${invocation}`,
           'X-Auth-Type': 'ucan',
+          [MEMORY_ENTITY_HEADER]: entityDid,
           'x-room-id': roomId,
           'Content-Type': 'application/json',
         },
         body: JSON.stringify({
-          queries: buildUserContextQueries(
-            this.deps.oracleDid,
-            new Date(this.now()),
-          ),
+          queries: buildUserContextQueries(entityDid, new Date(this.now())),
         }),
         signal: AbortSignal.timeout(this.requestTimeoutMs),
       });

package/src/plugin-api/types.ts

@@ -762,7 +762,26 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       provider: string;
       bindingId: string;
       bindingRevision: number;
-    }): Promise<import('@ixo/action-protocol').HubActionOptionsV2>;
+    }): Promise<import('@ixo/action-protocol').HubActionOptionsV3>;
+    /**
+     * A bank send of a token from the owner's options list: `amount` is a
+     * decimal in the token's display units; the host converts it to base
+     * units from the listed decimals and builds the operation (no fee).
+     */
+    transfer(input: {
+      ownerDid: string;
+      sessionId: string;
+      runId: string;
+      requestId: string;
+      provider: string;
+      bindingId: string;
+      bindingRevision: number;
+      requestKey: string;
+      toAddress: string;
+      denom: string;
+      amount: string;
+      memo: string;
+    }): Promise<ActionReferenceV1>;
     request(input: {
       ownerDid: string;
       sessionId: string;
@@ -774,7 +793,11 @@ export interface RuntimeContext<TConfig = MergedConfig> {
       requestKey: string;
       operation: ActionOperationV1;
     }): Promise<ActionReferenceV1>;
-    status(ownerDid: string, actionId: string): Promise<ActionOutcomeV1 | null>;
+    /** The latest authenticated outcome and, for a transfer, its owner-facing line. */
+    status(
+      ownerDid: string,
+      actionId: string,
+    ): Promise<{ outcome: ActionOutcomeV1 | null; summary: string | null }>;
   };
 
   decisions: {

package/src/plugins/hub-actions/hub-actions.plugin.ts

@@ -24,9 +24,37 @@ const statusSchema = z.strictObject({
   actionId: z.string().regex(/^[A-Za-z0-9_-]{32}$/),
 });
 const discoverSchema = z.strictObject({});
+const transferSchema = z.strictObject({
+  toAddress: z
+    .string()
+    .min(1)
+    .max(100)
+    .describe('The recipient address the user gave, exactly.'),
+  denom: z
+    .string()
+    .min(1)
+    .max(128)
+    .describe(
+      'The token, copied exactly from a `denom` in hub_action_options `transfer.tokens` (never guessed).',
+    ),
+  amount: z
+    .string()
+    .regex(/^(0|[1-9][0-9]*)(\.[0-9]+)?$/)
+    .max(80)
+    .describe(
+      "A decimal amount in the token's listed units (its `decimals`); for an unverified token (decimals 0) a whole number of base units.",
+    ),
+  memo: z.string().max(256).optional(),
+});
 
 export type HubActionRequestResult =
-  | { status: 'prepared'; actionReference: ActionReferenceV1; summary: string }
+  | {
+      status: 'prepared';
+      actionReference: ActionReferenceV1;
+      summary: string;
+      /** How the review reaches the user; set on a chat surface only. */
+      note?: string;
+    }
   | {
       status: 'unavailable' | 'expired';
       reason: string;
@@ -34,6 +62,34 @@ export type HubActionRequestResult =
       priorActionId?: string;
     };
 
+/**
+ * What a prepared result tells the model on a chat surface. There the
+ * finished run's Reply Plan carries the review as its own `hub-action` part
+ * (a card with the title and a review button; its title linked to the review
+ * in a plain-text rendering), so text that repeats it reaches the user twice.
+ */
+export const HUB_ACTION_CARD_NOTE =
+  'The user is shown this action automatically as a card with its title and a Review action button that opens it in Auth Hub. Do not repeat the link or the title, and do not say that you have not executed or signed anything. Reply with one short line, or nothing.';
+
+/**
+ * A prepared result. Only a chat turn's reply is a Reply Plan, so only a
+ * chat surface gets the note: on the Portal stream no card is added and the
+ * model's own text is the whole reply.
+ */
+function preparedResult(
+  reference: ActionReferenceV1,
+  ctx: RuntimeContext,
+): HubActionRequestResult {
+  return {
+    status: 'prepared',
+    actionReference: reference,
+    summary: reference.title,
+    ...(ctx.session.surface?.kind === 'chat'
+      ? { note: HUB_ACTION_CARD_NOTE }
+      : {}),
+  };
+}
+
 /**
  * The idempotency key the Hub sees: a fixed-length digest of the run and
  * tool call (the Hub allows 120 characters; a run id alone is 72).
@@ -74,6 +130,15 @@ async function requestHubAction(
   let operation;
   try {
     operation = parseOperation(parsed.data.operation);
+    if (operation.kind === 'ixo.bank.send.v1')
+      // A transfer is built by the runtime from a listed token and a
+      // display amount (request_hub_transfer): the model never supplies
+      // base units, a denom it chose or a fee.
+      return {
+        status: 'unavailable',
+        reason:
+          'Use request_hub_transfer with a token from hub_action_options for a transfer.',
+      };
   } catch (error) {
     // The protocol's own words ("Invalid fromAddress"): the model can fix
     // the field instead of guessing.
@@ -96,28 +161,83 @@ async function requestHubAction(
       operation,
     });
   } catch (error) {
-    // A cap reached, a request that expired, a run no user message
-    // started: the runtime's own words, so the model can tell the user.
+    // A request that expired, a run no user message started, a Hub
+    // refusal: the runtime's own words, so the model can tell the user.
     // Anything else stays an error.
-    if (
-      error instanceof Error &&
-      error.name === 'HubActionRefused' &&
-      'kind' in error
-    )
-      return {
-        status: error.kind === 'expired' ? 'expired' : 'unavailable',
-        reason: error.message,
-        ...('priorActionId' in error && typeof error.priorActionId === 'string'
-          ? { priorActionId: error.priorActionId }
-          : {}),
-      };
+    const refused = refusalOf(error);
+    if (refused) return refused;
     throw error;
   }
-  return {
-    status: 'prepared',
-    actionReference: reference,
-    summary: reference.title,
-  };
+  return preparedResult(reference, ctx);
+}
+
+async function requestHubTransfer(
+  input: unknown,
+  ctx: RuntimeContext,
+): Promise<HubActionRequestResult> {
+  const parsed = transferSchema.safeParse(input);
+  if (!parsed.success)
+    return {
+      status: 'unavailable',
+      reason:
+        'A recipient, a listed token denom and a plain decimal amount are required.',
+    };
+  if (ctx.config.HUB_ACTIONS_ENABLED !== 'true' || !ctx.hubActions)
+    return {
+      status: 'unavailable',
+      reason: 'Hub actions are not enabled for this oracle.',
+    };
+  const channel = ctx.session.channel;
+  if (
+    ctx.session.client !== 'channel' ||
+    !channel ||
+    !ctx.session.runId ||
+    !ctx.toolCallId
+  )
+    return {
+      status: 'unavailable',
+      reason: 'A verified channel turn is required.',
+    };
+  try {
+    const reference = await ctx.hubActions.transfer({
+      ownerDid: ctx.user.did,
+      sessionId: ctx.session.id,
+      runId: ctx.session.runId,
+      requestId: ctx.session.requestId,
+      provider: channel.provider,
+      bindingId: channel.bindingId,
+      bindingRevision: channel.bindingRevision,
+      requestKey: await hubRequestKey(ctx.session.runId, ctx.toolCallId),
+      toAddress: parsed.data.toAddress,
+      denom: parsed.data.denom,
+      amount: parsed.data.amount,
+      memo: parsed.data.memo ?? '',
+    });
+    return preparedResult(reference, ctx);
+  } catch (error) {
+    // The owner object turns the protocol refusing the operation built
+    // from the model's fields into a refusal; anything else is an error.
+    const refused = refusalOf(error);
+    if (refused) return refused;
+    throw error;
+  }
+}
+
+/** A typed runtime refusal as a result the model can relay, else null. */
+function refusalOf(error: unknown): HubActionRequestResult | null {
+  if (
+    error instanceof Error &&
+    error.name === 'HubActionRefused' &&
+    'kind' in error
+  )
+    return {
+      status: error.kind === 'expired' ? 'expired' : 'unavailable',
+      reason: error.message,
+      ...('priorActionId' in error && typeof error.priorActionId === 'string'
+        ? { priorActionId: error.priorActionId }
+        : {}),
+    };
+  return null;
 }
 
 async function hubActionStatus(
@@ -131,10 +251,11 @@ async function hubActionStatus(
     ctx.config.HUB_ACTIONS_ENABLED !== 'true'
   )
     return { status: 'unavailable' };
-  return {
-    status: 'known',
-    outcome: await ctx.hubActions.status(ctx.user.did, parsed.data.actionId),
-  };
+  const { outcome, summary } = await ctx.hubActions.status(
+    ctx.user.did,
+    parsed.data.actionId,
+  );
+  return { status: 'known', outcome, ...(summary ? { summary } : {}) };
 }
 
 async function hubActionCapabilities(
@@ -218,7 +339,7 @@ export class HubActionsPlugin extends OraclePlugin {
       {
         name: 'hub_action_options',
         description:
-          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents and action resources. Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending.',
+          'Read this authenticated owner’s confirmed Gmail and Calendar connections, requestable documents, action resources and bank tokens (`transfer.tokens`: denom, symbol, decimals, verified, balance in base units). Use each returned service, identifier and label before preparing a related Hub review. A Gmail profile connection does not authorize sending. For a token that is not verified, name its full denom and say it is unverified; its amounts are base units.',
         schema: discoverSchema,
         effect: 'read',
         handler: hubActionOptions,
@@ -231,6 +352,14 @@ export class HubActionsPlugin extends OraclePlugin {
         effect: 'write',
         handler: requestHubAction,
       },
+      {
+        name: 'request_hub_transfer',
+        description:
+          'Prepare a bank transfer of one of the owner’s listed tokens for review in Auth Hub. Never signs or executes. Read hub_action_options first and copy the token `denom` exactly; give the amount as the user said it in that token’s units (no base-unit math, no fee: Auth Hub sets the fee). Name the full denom for anything but IXO, and say when a token is unverified.',
+        schema: transferSchema,
+        effect: 'write',
+        handler: requestHubTransfer,
+      },
       {
         name: 'hub_action_status',
         description:

package/src/plugins/memory/index.ts

@@ -12,6 +12,10 @@ export {
   type MemoryMcpFactory,
   type UpstreamMcpTool,
 } from './memory-tools';
+export {
+  MEMORY_ENTITY_HEADER,
+  ORACLE_ENTITY_DID_PATTERN,
+} from './memory-entity';
 export { buildMemoryHeaders } from './memory-ucan';
 export { MemoryPlugin, type MemoryPluginOptions } from './memory.plugin';
 export type * from './types';

package/src/plugins/memory/memory-entity.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+/**
+ * The Memory Engine keys every memory space by the oracle's domain entity
+ * (`did:ixo:entity:<32 hex>`): the user's personal space is
+ * `sha256(<userDid>-<entityDid>)` and the shared knowledge spaces are the
+ * entity's. Every engine request names the entity in this header; the engine
+ * refuses a request without it and checks (on chain) that the entity lists
+ * the oracle's agent account as a Matrix admin.
+ */
+export const MEMORY_ENTITY_HEADER = 'x-oracle-entity-did';
+
+/** The shape the Memory Engine accepts for {@link MEMORY_ENTITY_HEADER}. */
+export const ORACLE_ENTITY_DID_PATTERN = /^did:ixo:entity:[0-9a-f]{32}$/;
+
+const ENTITY_REQUIRED_MESSAGE =
+  "ORACLE_ENTITY_DID is required by the memory plugin: set it to the oracle's domain entity DID (did:ixo:entity: followed by 32 lower-case hex characters). The Memory Engine keys every memory space by that entity and refuses requests without it.";
+
+const ENTITY_SHAPE_MESSAGE =
+  "ORACLE_ENTITY_DID must be the oracle's domain entity DID (did:ixo:entity: followed by 32 lower-case hex characters); the Memory Engine refuses any other value.";
+
+/**
+ * `ORACLE_ENTITY_DID` as the memory plugin requires it. The core schema keeps
+ * the variable optional (rooms and feedback fall back to `ORACLE_DID`); the
+ * memory plugin redeclares it so an oracle with `MEMORY_MCP_URL` and no
+ * entity fails at boot. The engine never receives the `ORACLE_DID` fallback.
+ */
+export const oracleEntityDidSchema = z
+  .string({
+    error: (issue) =>
+      issue.input === undefined
+        ? ENTITY_REQUIRED_MESSAGE
+        : ENTITY_SHAPE_MESSAGE,
+  })
+  .regex(ORACLE_ENTITY_DID_PATTERN, ENTITY_SHAPE_MESSAGE);
+
+/**
+ * The configured `ORACLE_ENTITY_DID` when it is a well-formed domain entity
+ * DID, else `undefined`. For the engine paths outside the plugin (first-turn
+ * prefetch, session-history indexing, the memory debug route): they read the
+ * merged env directly and run wherever `MEMORY_ENGINE_URL` survives
+ * validation, which another plugin than this one may declare, so the
+ * plugin's schema does not cover them.
+ */
+export function memoryEntityDid(value: unknown): string | undefined {
+  return typeof value === 'string' && ORACLE_ENTITY_DID_PATTERN.test(value)
+    ? value
+    : undefined;
+}

package/src/plugins/memory/memory-tools.ts

@@ -28,8 +28,9 @@ export const MEMORY_CLEAR_MCP_NAME = 'memory-engine__clear';
  * destructive `clear` stays in the default set. `add_oracle_knowledge` is in
  * the set so the controllers and owners of any oracle can grow its shared
  * knowledge from chat without a per-oracle code change: the Memory Engine
- * itself checks on chain that the caller controls or owns an entity linked to
- * the oracle and refuses everyone else, so listing the tool for every user
+ * itself checks on chain that the caller is a member (controller, owner,
+ * Matrix admin or DAO member) of the oracle's domain entity and refuses
+ * everyone else, so listing the tool for every user
  * costs one tool description and grants nothing. Forks that want a different
  * surface (drop `clear`, add `delete_edge`) pass an explicit list via plugin
  * options.
@@ -370,7 +371,8 @@ function buildLazyUpstreamTools(
 
 /**
  * Default factory: authenticates with the per-request UCAN headers from
- * {@link buildMemoryHeaders}, then serves the upstream tool list.
+ * {@link buildMemoryHeaders} (which name the oracle's domain entity,
+ * `entityDid`), then serves the upstream tool list.
  *
  * The first request per isolate connects and lists tools exactly like the
  * old always-fetch path, then snapshots the definitions. Subsequent requests
@@ -384,9 +386,10 @@ function buildLazyUpstreamTools(
  */
 export function createDefaultMemoryMcpFactory(
   memoryMcpUrl: string,
+  entityDid: string,
 ): MemoryMcpFactory {
   return async (runCtx) => {
-    const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl);
+    const headers = await buildMemoryHeaders(runCtx, memoryMcpUrl, entityDid);
     if (!headers) return null;
 
     const cached = toolDefsCache.get(memoryMcpUrl);

package/src/plugins/memory/memory-ucan.ts

@@ -1,6 +1,7 @@
 import type { RuntimeContext } from '../../plugin-api/types';
 import { MEMORY_CAPABILITY } from '../delegated-capabilities';
 import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
+import { MEMORY_ENTITY_HEADER } from './memory-entity';
 
 /**
  * Build the headers needed to call the Memory Engine MCP server on behalf of
@@ -9,7 +10,13 @@ import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
  *   1. Resolve the memory service DID via `runCtx.ucan.resolveServiceDid`
  *      (delegates the did:web lookup + cache to the UCAN service).
  *   2. Mint an `ixo:memory` invocation using the user's signing key.
- *   3. Layer the resulting Bearer token plus the active `x-room-id`.
+ *   3. Layer the resulting Bearer token, the oracle's domain entity
+ *      (`x-oracle-entity-did`, which keys every memory space on the engine)
+ *      and the active `x-room-id`.
+ *
+ * `entityDid` is the configured `ORACLE_ENTITY_DID` (validated by the memory
+ * plugin's `configSchema`), passed in because `RuntimeContext` carries no
+ * oracle identity. It is never the core's `ORACLE_DID` fallback.
  *
  * UCAN-only — no Matrix-OpenID fallback. If resolution or minting fails for
  * any reason (no signing key, no cached delegation, did:web unresolved,
@@ -22,6 +29,7 @@ import { mintInvocationSafely, resolveServiceDidSafely } from '../ucan-failure';
 export async function buildMemoryHeaders(
   runCtx: RuntimeContext,
   memoryMcpUrl: string,
+  entityDid: string,
 ): Promise<Record<string, string> | null> {
   const memoryDid = await resolveServiceDidSafely(
     runCtx,
@@ -44,6 +52,7 @@ export async function buildMemoryHeaders(
     Authorization: `Bearer ${invocation}`,
     'X-Auth-Type': 'ucan',
     'User-Agent': 'LangChain-MCP-Client/1.0',
+    [MEMORY_ENTITY_HEADER]: entityDid,
   };
   if (runCtx.session.roomId) {
     headers['x-room-id'] = runCtx.session.roomId;