Outcome Memory - Evidence-Based Agent Learning

Record decisions before acting, report delayed outcomes, and learn from evidence without treating silence as failure.

Explicit causal loop. Outcome Memory does not claim to infer success from ordinary traffic. Your agent records the candidate set and selected action, then reports a delayed result. Hebbrix keeps propensity, uncertainty, correction, and idempotency evidence tenant-scoped.

01. How Outcome Memory Learns

A reliable learning loop separates the decision-time record from the later observation. Missing outcomes remain censored; they are not silently converted into failures or synthetic rewards.

Decision Receipt. Before acting, record the policy key, authorized candidates, context, collection, and idempotency key.
Propensity Evidence. Store the selected action and its probability so later evaluation can distinguish policy evidence from cherry-picked successful examples.
Delayed Outcome. Report success, reward, or typed business metrics after the real-world result is known.
Correction Semantics. A corrected outcome revises the evidence for the original decision instead of creating another decision.
Posterior Uncertainty. Policy insights expose sample counts, posterior probability, and uncertainty rather than one opaque score.
Conservative Evaluation. Promotion evaluation can refuse weak or non-randomized evidence instead of declaring a winner.

02. Agent Autonomy Features

Confidence, corrections, and Outcome Memory help agents decide when to act, when to abstain, and how to learn from results:

Confidence Scoring. Agents fetch confidence scores from GET /v1/confidence before acting to check "do I know enough to act without asking the user?" Returns a score and recommendation, including a hard do_not_act result when operational constraints conflict with the proposed action.
Correction Memory. When a user corrects an agent, it calls POST /v1/corrections. The correction is stored as versioned evidence. Agents still need to retrieve and apply relevant corrections; no system can guarantee that a mistake never repeats. You can also submit explicit user feedback via POST /v1/feedback/relevance (see the API Reference below for the full feedback, decisions, and confidence schemas).
Decision Receipts & Delayed Outcomes. Use POST /v1/learning/decisions before acting, then report the observed result to /v1/learning/decisions/{id}/outcomes. The older /v1/decisions route remains a decision log, not an automatic policy-training guarantee.

03. What Happens Behind the Scenes

Your application supplies the actions it is actually allowed to take
Hebbrix records the candidates, mode, choice, and action probability
The agent performs the external action under your authorization rules
Your application reports the delayed outcome or business metric
Hebbrix updates policy evidence idempotently, including corrections
You inspect insights and evaluate evidence before changing behavior

04. Safety & Quality Controls

Caller Authorization. Outcome Memory ranks only the candidate actions your application supplies. It does not grant tool, data, or side-effect permissions.
Bounded Exploration. Explore mode accepts an explicit exploration rate capped at 0.2; observe, recommend, and shadow modes support safer rollout and measurement.
Censored Missing Feedback. A missing or late outcome is not interpreted as failure. Final observations and corrections remain attached to the original decision.
Isolation & Idempotency. Collection and user scope prevent cross-tenant evidence leakage, while idempotency keys make decision and outcome retries safe.

05. Outcome Memory API

The causal learning surface is explicit and inspectable:

POST /v1/learning/decisions: choose or record an action receipt
GET /v1/learning/decisions/{id}: inspect the immutable decision context
POST /v1/learning/decisions/{id}/outcomes: report delayed or corrected outcomes
GET/POST /v1/learning/metrics: define and inspect typed business metrics
GET /v1/learning/policies/{key}/insights: inspect posterior evidence
POST /v1/learning/policies/{key}/evaluate: evaluate whether evidence is sufficient

The Bottom Line. Outcome learning is powerful only when your integration closes the loop. Record the decision before acting, report the real result afterward, and use the returned uncertainty when deciding whether evidence is strong enough to change policy.

06. API Reference

These established confidence, correction, decision-log, and relevance endpoints complement the Outcome Memory API above. They do not by themselves train or promote a policy. All require authentication (Authorization: Bearer <api_key>).

07. Schemas & Scoping

Two rules trip agents up most often: the strict enums on the create schemas, and the difference between the create body and the read endpoint's query parameter.

decisions.outcome normalizes to an enum. POST /v1/decisions stores one of success, failure, partial, or unknown (default unknown), but accepts common synonyms and maps them, e.g. positive/good/ok/pass → success, negative/bad/fail/error → failure, mixed → partial, neutral/na → unknown. Only a genuinely-unrecognized value, for example safe_block, returns HTTP 422. decision_type is a free string up to 50 chars; description is required.
corrections.correction_type is an optional enum. POST /v1/corrections requires only corrected_content; correction_type is optional and defaults to preference. When supplied it must be one of preference, factual, or procedural — any other value returns HTTP 422.

query is a read parameter, not a create field. query belongs to the GET read endpoints, /v1/corrections/relevant and /v1/decisions/similar, where it describes the agent's current task. The create schemas reject unknown fields, so sending query in a POST body to /v1/corrections or /v1/decisions returns HTTP 422.

Tenant isolation via collection_id. Both corrections and decisions are tenant-isolatable. Pass collection_id when creating to scope a record to one collection. On the read endpoints, collection_id enforces strict isolation (only that collection's records), and include_global additionally folds in account-wide records. Omitting collection_id keeps everything account-wide, fully backward compatible.

curl

# Create a correction scoped to one tenant/collection
curl -X POST https://api.hebbrix.com/v1/corrections \
  -H "Authorization: Bearer $HEBBRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "corrected_content": "Refund approvals above \$500 require human review",
    "correction_type": "procedural",
    "original_content": "above \$250 require human review",
    "collection_id": "col_tenant_acme"
  }'

# Read corrections for that tenant only (strict isolation)
curl "https://api.hebbrix.com/v1/corrections/relevant?query=approve+a+refund&collection_id=col_tenant_acme" \
  -H "Authorization: Bearer $HEBBRIX_API_KEY"

# ...or include account-wide corrections alongside the tenant's
curl "https://api.hebbrix.com/v1/corrections/relevant?query=approve+a+refund&collection_id=col_tenant_acme&include_global=true" \
  -H "Authorization: Bearer $HEBBRIX_API_KEY"

# Log a decision (outcome normalizes to success|failure|partial|unknown, synonyms accepted; query is NOT a body field)
curl -X POST https://api.hebbrix.com/v1/decisions \
  -H "Authorization: Bearer $HEBBRIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decision_type": "refund_approval",
    "description": "Auto-approved a \$120 refund",
    "outcome": "success",
    "agent_confidence": 0.82,
    "collection_id": "col_tenant_acme"
  }'