Context Budget Planner

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

Context recall policy and context budgeting decide which governed memory can enter recall and how much context budget each segment may use. Workspace defaults set the operator floor, workload defaults may narrow that floor, and a request policyOverride may only touch axes the workspace policy marks as relaxable.

The detailed cross-surface contract is in docs/reference/context-recall-policy-and-budget.md.

Policy Layers

Layer	Purpose
Workspace default	Operator floor for memory eligibility and context budget
Workload default	Workload-specific narrowing within the workspace floor
Request override	Per-call override on workspace-approved relaxable axes

Overrides that touch a non-relaxable axis return USER_OVERRIDE_NOT_PERMITTED. Workload defaults that relax the workspace floor return WORKLOAD_RELAXES_OPERATOR_FLOOR.

Recall Policy Axes

Recall policy filters memory before vector ranking. Common axes include:

Axis	Governs
`memoryTypeAllowed`	Fact, preference, decision, instruction, and related memory categories
`sourceKindAllowed`	User, assistant, tool, retrieval, operator, system, or import source
`confirmationStatusAllowed`	User confirmed, operator confirmed, observed, inferred, imported, or unknown
`confidenceMin`	Minimum confidence for inferred or observed memory
`sensitivityCeiling`	Highest allowed sensitivity label
`consentPolicyAllowed`	Consent posture required for recall
`maxAgeSeconds`	Recency bound for eligible memory

Lifecycle and quality filters still fail closed: inactive, stale, suppressed, disabled, expired, or non-current rows do not enter recall.

Budget Shape

Budgets allocate the available context across segment kinds. Reservations are floors, ceilings are caps, and dropOrder controls what is reduced first when the total budget is exceeded.


{
  "totalTokenBudget": 3200,
  "perSegmentReservation": {
    "system_policy": 500,
    "memory": 800,
    "retrieval": 900,
    "tool_result": 300
  },
  "perSegmentCeiling": {
    "memory": 1200,
    "retrieval": 1200
  },
  "dropOrder": ["tool_result", "retrieval", "memory"],
  "forbiddenSegmentKinds": [],
  "pinned": ["system_policy"],
  "diagnosticsVerbosity": "summary"
}

Pinned segment kinds are not dropped during budget pressure. Forbidden segment kinds receive zero allocation even if a reservation exists.

Recall Request


curl -X POST "http://localhost:8000/v1/memory/actors/user:ada/recall" \
  -H "Content-Type: application/json" \
  -d '{
    "workloadId": "00000000-0000-0000-0000-000000000001",
    "environment": "prod",
    "query": "release summary preferences",
    "topK": 5,
    "policyOverride": {
      "memoryTypeAllowed": ["preference", "decision"],
      "diagnosticsVerbosity": "summary"
    }
  }'

Recall returns an envelope with entries and diagnostics. Diagnostics include bounded decisions such as passes_policy, confidence_below_min, budget_floor_hit, budget_drop_order, and segment_kind_forbidden. Planner-truncated memory refs count toward afterBudgetAllocation and the digest, but are not returned as full entries[] content.

Audit

Policy changes emit context.workspace_policy_set or context.workload_policy_set. Governed context envelopes emit context.assembled with the effective policy hash, effective budget hash, prefix fingerprint, digest, token counts, and reuse flag.