load_memory_pack

Instructions

Implementation Reference

• src/mcp/tools/memory-packs.ts:469-553 (handler)

  The `registerLoadMemoryPackTool` function registers the 'load_memory_pack' MCP tool handler. It validates pack existence, status (revoked/expired), TTL, role authorization, and context class before returning the pack content. It also updates usage counters, persists usage events, and emits telemetry.

  export function registerLoadMemoryPackTool(server: McpServer, engine: GovernanceEngine): void {
    server.tool(
      'load_memory_pack',
      'Load a Governed Memory Pack into agent context. Validates TTL, trust level, role access, context class, and hash integrity before loading.',
      {
        pack_id: z.string().max(100).describe('Memory pack ID to load'),
        agent_id: z.string().max(100).describe('Agent requesting the load'),
        run_id: z.string().max(100).describe('Current run/pipeline ID'),
        operator_role: z.string().max(100).describe('Role of the operator'),
        context_class: z.enum(['PROD', 'STAGING', 'DEMO', 'EVAL_ONLY', 'TRAINING']).optional().describe('Execution context class'),
      },
      { title: 'Load Memory Pack', readOnlyHint: false, idempotentHint: false, destructiveHint: false, openWorldHint: false },
      async (input) => {
        try {
          await seedDefaults();
          const pack = gmpPacks.get(input.pack_id);
          if (!pack) {
            return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Memory pack not found: ${input.pack_id}`, available: Array.from(gmpPacks.keys()) }) }], isError: true };
          }
  
          // Check status
          if (pack.status === 'REVOKED') {
            const promotedId = `${input.pack_id}-promoted`;
            const promotedExists = gmpPacks.has(promotedId);
            return { content: [{ type: 'text' as const, text: JSON.stringify({
              error: `Pack revoked: ${input.pack_id}`,
              hint: promotedExists
                ? `This pack was promoted to a higher trust level. Use pack_id: "${promotedId}" instead.`
                : 'This pack has been revoked and cannot be used. Re-seal a new pack with seal_memory_pack.',
              promotedPackId: promotedExists ? promotedId : undefined,
            }) }], isError: true };
          }
          // Check TTL
          if (new Date(pack.audit.expiresAt) < new Date()) {
            pack.status = 'EXPIRED';
            return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Pack expired: ${input.pack_id}`, expiredAt: pack.audit.expiresAt }) }], isError: true };
          }
          // Check role
          if (pack.policy.allowedRoles.length > 0 && !pack.policy.allowedRoles.includes(input.operator_role)) {
            return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Role '${input.operator_role}' not authorized`, allowedRoles: pack.policy.allowedRoles }) }], isError: true };
          }
          // Check context
          if (pack.policy.allowedContexts && pack.policy.allowedContexts.length > 0 && input.context_class) {
            if (!pack.policy.allowedContexts.includes(input.context_class)) {
              return { content: [{ type: 'text' as const, text: JSON.stringify({ error: `Context '${input.context_class}' not allowed`, allowedContexts: pack.policy.allowedContexts }) }], isError: true };
            }
          }
  
          // Update usage
          pack.audit.usageCount++;
          pack.audit.lastUsedBy = input.agent_id;
          pack.status = 'ACTIVE';
          persistPack(pack); // Write-through: usage + status update
  
          const loadEvent = { event: 'GMP_LOADED', memoryPackId: input.pack_id, agentId: input.agent_id, runId: input.run_id, hash: pack.hash, approvedBy: input.operator_role, timestamp: new Date().toISOString() };
          gmpUsageLog.push(loadEvent);
          persistUsageEvent(loadEvent);
  
          const canAutomate = ['SYSTEM', 'ORG'].includes(pack.trustLevel);
  
          // Telemetry: load success
          engine.telemetryService.emitToolCall('load_memory_pack', `load-${Date.now().toString(36)}`, 'ADVISORY', true);
  
          return { content: [{ type: 'text' as const, text: JSON.stringify({
            loaded: true,
            memoryPackId: pack.memoryPackId,
            trustLevel: pack.trustLevel,
            domain: pack.domain,
            scope: pack.scope,
            riskLevel: pack.riskLevel,
            advisoryOnly: !canAutomate,
            gateRequired: pack.policy.requiresGateForUse && pack.riskLevel === 'MANDATORY',
            content: pack.content,
            usageCount: pack.audit.usageCount,
            expiresAt: pack.audit.expiresAt,
          }, null, 2) }] };
        } catch (error) {
          // Telemetry: load failure
          engine.telemetryService.emitToolCall('load_memory_pack', `load-${Date.now().toString(36)}`, 'ADVISORY', false);
  
          return { content: [{ type: 'text' as const, text: JSON.stringify({ error: 'LOAD_FAILED', message: String(error) }) }], isError: true };
        }
      }
    );
  }

• src/mcp/tools/memory-packs.ts:473-479 (schema)

  Zod schema for the 'load_memory_pack' tool input. Defines required parameters: pack_id (string max 100), agent_id (string max 100), run_id (string max 100), operator_role (string max 100), and optional context_class (PROD/STAGING/DEMO/EVAL_ONLY/TRAINING).

  {
    pack_id: z.string().max(100).describe('Memory pack ID to load'),
    agent_id: z.string().max(100).describe('Agent requesting the load'),
    run_id: z.string().max(100).describe('Current run/pipeline ID'),
    operator_role: z.string().max(100).describe('Role of the operator'),
    context_class: z.enum(['PROD', 'STAGING', 'DEMO', 'EVAL_ONLY', 'TRAINING']).optional().describe('Execution context class'),
  },

• src/mcp/tools/memory-packs.ts:1008-1015 (registration)

  The `registerMemoryPackTools` function calls all 6 GMP tool registrations including `registerLoadMemoryPackTool`. This is called from the MCP server registration.

  export function registerMemoryPackTools(server: McpServer, engine: GovernanceEngine): void {
    registerSealMemoryPackTool(server, engine);
    registerLoadMemoryPackTool(server, engine);
    registerTransferMemoryPackTool(server, engine);
    registerComposeMemoryPacksTool(server, engine);
    registerDistillMemoryPackTool(server, engine);
    registerPromoteMemoryPackTool(server, engine);
  }

• src/mcp/server.ts:106-106 (registration)

  The `registerMemoryPackTools` is registered as a 'tenant' tier tool at the MCP server level, which includes load_memory_pack.

  { tier: 'tenant', register: registerMemoryPackTools, description: 'memory_packs (seal, load, transfer, compose, distill, promote)' },

• src/mcp/tools/memory-packs.ts:31-65 (helper)

  The `GMPPack` interface defines the structure of a Governed Memory Pack, including the content fields (principles, sop, heuristics, antiPatterns) that load_memory_pack returns to the agent context.

  interface GMPPack {
    memoryPackId: string;
    version: string;
    type: string;
    trustLevel: string;
    domain: string;
    scope: string[];
    riskLevel: string;
    ttlHours: number;
    createdBy: string;
    signedBy: string;
    hash: string;
    status: string;
    policy: {
      readOnly: boolean;
      writeBackAllowed: boolean;
      exportAllowed: boolean;
      requiresGateForUse: boolean;
      allowedRoles: string[];
      allowedContexts?: string[];
    };
    content: {
      principles: string[];
      sop: string[];
      heuristics: string[];
      antiPatterns: string[];
    };
    audit: {
      createdAt: string;
      lastReviewed: string;
      expiresAt: string;
      usageCount: number;
      lastUsedBy?: string;
    };
  }