Write a consolidation pack

Build a function-mode AgentRuntime whose output is a list of memory actions, and bind it to a MemoryPolicy consolidation axis.

The pack only proposes actions. The Enterprise consolidation worker validates each one and applies the accepted ones. The request, the actions and the rejection reasons are in Memory consolidation function contract.

Prerequisites

• The consolidation worker enabled, as in Configure memory consolidation.
• A MemoryPolicy bound to the workspace’s service group.
• A Provider the pack can use.

Steps

1. Copy the closest example from examples/consolidation/. demo-rescope/ handles crossScopeCandidates and demo-merge-entities/ handles entityDuplicateCandidates. Each directory holds a PromptPack with a ConfigMap, and a function-mode AgentRuntime.

   kubectl create namespace omnia-functions
   kubectl apply -f examples/consolidation/demo-rescope/

2. Set spec.providers[].providerRef.name in the AgentRuntime to a Provider you have. The examples name mock-provider.

3. Write the prompt in the PromptPack’s system_template. Tell the model which axis it handles, which actions to emit, and to return a JSON array and nothing else. State the limits it must respect: rescope cannot target the institutional scope, and an agent-scoped rescope needs gates.minDistinctUserCount.agentScoped distinct users.

4. Keep an object inputSchema and an array outputSchema on the AgentRuntime, as the examples do. Each output item needs an action string.

5. Reference the AgentRuntime from the axis in the policy. namespace is required.

   apiVersion: omnia.altairalabs.ai/v1alpha1
   kind: MemoryPolicy
   metadata:
     name: research
   spec:
     tiers:
       user:          { mode: Composite }
       agent:         { mode: Composite }
       institutional: { mode: Manual }
     consolidation:
       functionRefs:
         crossScopeCandidates:
           name: demo-rescope
           namespace: omnia-functions

6. Start with a narrow consolidation.candidateLimits (maxBucketsPerPass, maxPerBucket) so a wrong prompt touches few rows. Raise the limits once the proposals are correct.

Verify

After the axis’s cron schedule next comes due and the worker ticks, check the actions metric:

omnia_memory_consolidation_actions_total{function="demo-rescope"}

Every action should show outcome="applied". A rejected_<reason> outcome names the gate that refused it; the reasons are listed in Rejection reasons. Adjust the prompt until proposals stop being rejected.

Troubleshooting

The pass fails with function returned 401

The worker calls the pack’s internal management-plane listener on port 18080 with memory-api’s ServiceAccount token. The facade admits it only when a MemoryPolicy names the pack by its exact name and namespace and the calling workspace is bound to that policy. Check both, then check that the pack’s facade container lists memory-api’s ServiceAccount in OMNIA_SCHEDULE_AUTH_ALLOWED_SUBJECTS. Configure memory consolidation lists the other causes.

The pack needs no spec.externalAuth, and setting OMNIA_FACADE_ALLOW_UNAUTHENTICATED does not help: it applies to the external listener, which the worker does not call.

The pass fails with decode action

The function returned something other than a JSON array of known actions. An unknown action value or any text outside the array discards the whole response. Tighten the prompt and the outputSchema.

The pass fails with MemoryFunctionRef.Namespace required

Set namespace on the axis entry in functionRefs.

Related pages

• Memory consolidation function contract: request body, actions and rejection reasons.
• Configure memory consolidation: worker interval, schedules and metrics.
• MemoryPolicy: every consolidation field, including safetyGates.