Feedback and outcomes

You tell Agent Memory whether memory was useful with two signals: the task's real outcome (did the build pass, tests, deploy, user rating) and which of the memories returned by search you used. Agent Memory ties these signals only to the memories in the receipt of the relevant search.

FlowCopy Anchor Link

retrieve / search_memory  ──►  receiptId + runId
        │
        ├──► record_retrieval_feedback(runId, receiptId, usedEntryIds, ignoredEntryIds, …)
        └──► report_outcome(runId, receiptId, buildSuccess, testPassRate, …)

Rule: report with the same runId you received the receipt under.

Reporting outcomesCopy Anchor Link

curl -s -X POST $API/v1/outcomes -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"workspaceId\":\"$WS\",\"runId\":\"billing-refactor-12\",\"receiptId\":\"<receiptId>\",
       \"buildSuccess\":true,\"testPassRate\":0.95,\"deploySuccess\":true,\"errorCount\":0,\"userRating\":4}"
# {"runId":"billing-refactor-12","successScore":…}

The success score is a weighted combination of the signals sent (build 0.30, test 0.30, deploy 0.20, error-free 0.10, rating 0.10; normalized over only the signals sent).

Effects:

• The run's episode is re-finalized with the real score; procedures are validated or weakened.
• If the score is low (below 0.4), facts promoted from this run are flagged for review (outcome_review); their confidence is not lowered automatically.
• If learning is enabled (learning.enabled), the utility of the memories in the receipt is updated toward the outcome. Each receipt is credited once.

MCP: report_outcome(runId, receiptId?, buildSuccess?, testPassRate?, deploySuccess?, errorCount, warningCount, userRating?, notes?).

Usage feedbackCopy Anchor Link

curl -s -X POST $API/v1/retrieval-feedback -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d "{\"workspaceId\":\"$WS\",\"runId\":\"billing-refactor-12\",\"receiptId\":\"<receiptId>\",
       \"usedEntryIds\":[\"<id1>\"],\"ignoredEntryIds\":[\"<id2>\"],
       \"appliedProcedureIds\":[],\"skippedProcedureIds\":[]}"
# {"runId":"…","usedCount":1,"ignoredCount":1,"appliedProcedures":0,"skippedProcedures":0}

• Used memories get a higher usage count and stability (freshness in the trust score decays more slowly).
• Applied procedures receive a positive validation.
• Ignored memories are not penalized; they are only recorded.
• If you pass a receiptId and report a memory that is not in the receipt as "used", you get 400 RECEIPT_MISMATCH (the response lists the IDs that were not delivered).

MCP: record_retrieval_feedback(runId, receiptId?, usedEntryIds?, ignoredEntryIds?, appliedProcedureIds?, skippedProcedureIds?).

Feedback from the consoleCopy Anchor Link

On a memory's detail view in the console, you can rate a memory "good" or "bad" and add a note. The rating is written to the memory's history and processed as usage feedback ("good" = used, "bad" = ignored).

How learning affects rankingCopy Anchor Link

By default, utility feeds into the trust score; it does not change search ranking. For utility to affect ranking, "value-aware" selection must be enabled (retrieval.valueAware.enabled, retrieval.utilityWeight). Measuring its effect with evaluation before turning it on is recommended.

PermissionsCopy Anchor Link

Both calls require the feedback permission. These calls do not count toward the monthly operation quota.

Related pagesCopy Anchor Link

• Search and context compilation
• Consolidation, episodes and procedures
• Evaluating recall quality