Learning loop

Storing and recalling is half of memory. The other half is learning which memories actually helped. Agent Memory closes that loop with three pieces:

1. Receipts — every recall records exactly what it delivered.
2. Outcomes — the run's measured result (build, tests, deploy, user rating).
3. Retrieval feedback — which delivered memories the agent used or ignored, and which procedures it applied or skipped.

search ──► context + receiptId ──► agent works ──► outcome / feedback (receiptId, same runId)
                                                        │
                       memory utility, usage counts ◄───┤
                       procedure success / failure  ◄───┘

ReceiptsCopy Anchor Link

Each recall returns a receiptId. The receipt records the run, the agent and the IDs of the memories that made it into the context after the token budget was applied — not the ones that were trimmed.

Pass the receipt back with outcomes and feedback, with the same runId you recalled with:

• With a receiptId, an outcome credits exactly what that delivery contained. Without one, it credits everything the run was delivered.
• Each delivery is credited once.
• Feedback that names a receipt from another run or workspace, or claims to have used a memory that receipt did not deliver, is refused with 400 RECEIPT_MISMATCH and nothing is recorded. The error lists the undelivered IDs.

OutcomesCopy Anchor Link

Report an outcome when the real result of a run is known:

curl -s -X POST "$AGENT_MEMORY_BASE_URL/v1/outcomes" \
  -H "Authorization: Bearer $AGENT_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "'"$AGENT_MEMORY_WORKSPACE_ID"'",
    "runId": "run-1",
    "receiptId": "<receiptId>",
    "buildSuccess": true,
    "testPassRate": 0.95,
    "errorCount": 0,
    "notes": "CI green"
  }'
# {"runId":"run-1","successScore":0.9785…}

All signals are optional. The server folds the ones you send into a normalized successScore between 0 and 1, weighting them as follows and re-normalizing over the signals present:

warningCount, notes and measuredAt are recorded with the report. Reporting outcomes needs the feedback capability. Over MCP use report_outcome; in the SDKs, outcome().

What an outcome does:

• Validates the procedures the run applied — successes strengthen them, failures weaken them and can contribute anti-patterns.
• Updates the learned utility of the memories the run was delivered, which value-aware retrieval can use for ranking.

Retrieval feedbackCopy Anchor Link

Feedback is finer-grained: tell memory which delivered entries were actually used.

{
  "workspaceId": "…",
  "runId": "run-1",
  "receiptId": "<receiptId>",
  "usedEntryIds": ["…"],
  "ignoredEntryIds": ["…"],
  "appliedProcedureIds": ["…"],
  "skippedProcedureIds": ["…"]
}

Used entries are reinforced and ignored ones fade; applied procedures gain confidence. Endpoint: POST /v1/retrieval-feedback (MCP: record_retrieval_feedback, SDKs: feedback()).

Validating a procedure directlyCopy Anchor Link

When you know a specific procedure worked (or didn't) outside an outcome report, record it with POST /v1/procedures/validate — see Episodes and procedures.

SettingsCopy Anchor Link

See Workspace settings.