Skip to Content
Task guidesTechnical: Memory Governance

Memory Governance

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

Orqestra memory is governed state, not silent profiling. The assistant writes memory only from user-visible interaction paths and stores a bounded envelope around each remembered fact, preference, decision, instruction, relationship, task state, or working note.

What Orqestra remembers

Memory can record useful continuity signals such as preferences, facts, decisions, relationships, and task checkpoints. Each row includes:

  • memoryType, such as preference, fact, or task_state.
  • source, including source kind, source reference, evidence refs, and write reason.
  • confirmation, including status, confidence, confirmed-by actor, and confirmed-at timestamp.
  • governance, including sensitivity, retention policy, consent policy, and redaction state.

The portal renders compact labels such as Preference and Model inferred so users can tell what kind of memory they are seeing without exposing low-level policy fields in every row.

Lifecycle and recall

Every memory row has a lifecycle envelope. New memory starts as active/current; older rows that predate lifecycle fields are read the same way. Lifecycle updates can mark rows as stale, superseded, or suppressed.

  • stale memory is retained for inspection but excluded from recall.
  • superseded memory links to a newer replacement and is excluded from recall.
  • suppressed memory is retained for audit and inspection but excluded from recall.

List and inspect surfaces can include non-active rows when needed, but semantic recall always fails closed: stale, suppressed, superseded, non-current, and expired rows are not returned as assistant context.

Context recall policy adds another recall-time gate over typed memory facts. Workspace defaults, workload defaults, and allowed request overrides can narrow which memory types, sources, confirmation states, sensitivity levels, consent postures, retention postures, and ages may enter recall. Recall diagnostics report bounded decision codes and counts; they do not echo memory content, metadata, embeddings, or prompt text.

Lifecycle changes write memory.lifecycle_updated audit events with lifecycle facts only. The audit event does not include memory content, metadata, embeddings, prompts, or source payloads.

Scope posture controls

Workspace administrators can set memory posture at workspace, workload, or memory asset-version scope. The resolver evaluates the chain as a workspace floor, workload override, and asset-version override, then returns the effective state and bounded denial code for the requested access class.

Posture states:

  • enabled: capture and recall are allowed unless another policy denies them.
  • capture_disabled: new writes are denied, while recall may still read allowed memory.
  • fully_disabled: capture and recall are denied for the matching scope.

Each posture row applies to all, user, or shared memory. Effective denial codes are bounded to memory_scope_capture_disabled, memory_scope_recall_disabled, memory_scope_metadata_incomplete, and memory_scope_shared_access_denied.

Operators can use:

  • Portal: open assistant memory management, review the effective posture, set a workspace/workload/asset-version posture, or purge all memory for that posture scope.
  • CLI: orqestractl memory posture get, set, and purge-all.
  • SDK: client.memory.get_governance_posture(...), set_governance_posture(...), and purge_governance_posture_scope(...).

Posture changes and enforcement write bounded receipt actions: memory.scope_posture_set, memory.scope_posture_cleared, memory.scope_capture_denied, memory.scope_recall_denied, memory.scope_purged, and memory.scope_shared_access_denied.

What Orqestra refuses to remember

The write policy refuses:

  • credential-looking content or metadata, including API-key and password-like values;
  • durable high-risk standing instructions such as always approving or bypassing policy/audit;
  • caller self-labels that say the record is a credential or high-risk instruction;
  • forged user_confirmed or operator_confirmed posture;
  • confirmed records with missing or mismatched confirmedBy;
  • non-implicit consent without a matching source write reason;
  • inbound denied, quarantined, or invalid redacted redaction posture;
  • workspace or organization ids that do not match the workload scope.

HIERARCHY_MISMATCH means the supplied workspace or organization does not match the resolved workload scope.

Allowed examples

User-confirmed preference:

{
  "actorRef": "user:ada@example.com",
  "sessionId": "session-1",
  "memoryAssetVersionId": "00000000-0000-0000-0000-000000000001",
  "role": "assistant",
  "content": "Ada prefers release summaries with risk deltas first.",
  "memoryType": "preference",
  "source": {
    "kind": "user_message",
    "sourceRef": "execution:exec-1:turn:3",
    "evidenceRefs": ["evidence:abc"],
    "writeReason": "explicit_user_request"
  },
  "confirmation": {
    "status": "user_confirmed",
    "confidence": 1,
    "confirmedBy": "user:ada@example.com",
    "confirmedAt": "2026-05-28T12:00:00Z"
  },
  "governance": {
    "sensitivity": "normal",
    "retentionPolicy": "release_bound",
    "consentPolicy": "implicit_interaction",
    "redactionState": "none"
  }
}

Model-inferred fact:

{
  "actorRef": "user:ada@example.com",
  "sessionId": "session-1",
  "memoryAssetVersionId": "00000000-0000-0000-0000-000000000001",
  "role": "assistant",
  "content": "Ada works on release readiness.",
  "memoryType": "fact",
  "source": {
    "kind": "assistant_response",
    "sourceRef": "execution:exec-1:turn:4",
    "evidenceRefs": [],
    "writeReason": "user_preference_extracted"
  },
  "confirmation": { "status": "model_inferred", "confidence": 0.72 },
  "governance": {
    "sensitivity": "normal",
    "retentionPolicy": "release_bound",
    "consentPolicy": "implicit_interaction",
    "redactionState": "none"
  }
}

Denied examples

Credential-looking content:

{
  "detail": { "reasonCode": "CREDENTIAL_CONTENT" }
}

Credential-looking metadata returns the same reason code. High-risk standing instructions return:

{
  "detail": { "reasonCode": "HIGH_RISK_INSTRUCTION_CONTENT" }
}

Never paste denied request content, secrets, credentials, prompt text, or raw high-risk instructions into logs, tickets, issue comments, or LLM prompts.

Legacy memory

Older rows appear with safe response defaults:

{
  "memoryType": "working_note",
  "source": null,
  "confirmation": {
    "status": "unknown",
    "confidence": null,
    "confirmedBy": null,
    "confirmedAt": null
  },
  "governance": {
    "sensitivity": "normal",
    "retentionPolicy": "release_bound",
    "consentPolicy": "implicit_interaction",
    "redactionState": "none"
  }
}

Recall response metadata

Recall returns the same typed fields plus score:

{
  "entryId": "me-1",
  "assetVersionId": "mem-version-1",
  "content": "Ada prefers release summaries with risk deltas first.",
  "memoryType": "preference",
  "source": {
    "kind": "assistant_response",
    "sourceRef": "execution:exec-1",
    "evidenceRefs": ["evidence:abc"],
    "writeReason": "user_preference_extracted"
  },
  "confirmation": {
    "status": "model_inferred",
    "confidence": 0.72,
    "confirmedBy": null,
    "confirmedAt": null
  },
  "governance": {
    "sensitivity": "normal",
    "retentionPolicy": "release_bound",
    "consentPolicy": "implicit_interaction",
    "redactionState": "none"
  },
  "score": 0.91
}

Inspect and purge

Users can inspect remembered memory in the Home page and purge memory for the selected workload. Workspace administrators can also manage scope posture and purge all memory for a workspace, workload, or asset-version posture scope. Edit, pin, lifecycle suppression, recall builders, and detailed provenance views are future controls.

Troubleshooting denied writes

Safe to copy:

  • response reasonCode;
  • audit event id;
  • denied subject id in denied:<workload-id>:<uuid> shape;
  • actor ref, workspace id, workload id;
  • memory type, source kind, write reason, confirmation status, confirmed-by actor ref, and sensitivity.

When reasonCode is CONFIRMED_BY_MISMATCH, the audit confirmed_by value is the untrusted caller-supplied value. The authenticated principal is the audit actor field.

Use the repository reference docs/reference/governed-memory-write-policy.md for the bounded denial reason table and operator-level audit examples.

Configure AI resources and the workspace assistantTechnical reference: Pen-Test Runbook