Feedback

POST /v1/feedback

Attribute an outcome to memory that was exposed by a prior guide.

This is the closed loop that lets Aionis learn which memory helped, which memory hurt, and which exposed memory was ignored.

Request body

/v1/feedback is implemented through the product lifecycle activation path. The Runtime sets operation: "activate" internally.

Field	Type	Required	Description
`reason`	string	Yes	Human-readable outcome reason.
`run_id`	string	Yes	Execution run that produced the outcome.
`outcome`	`positive`, `negative`, `neutral`	Yes	Outcome associated with used memory.
`used_surface`	`use_now`, `inspect_before_use`, `do_not_use`, `explicit_host_assertion`	Yes	Surface the host actually used. Non-neutral feedback requires `use_now` or `explicit_host_assertion`.
`guide_trace_id`	string	Recommended	Guide trace that exposed the memory.
`used_memory_ids`	string[]	Recommended	Memory IDs exposed by the guide and actually used by the Agent.
`memory_ids` / `node_ids`	string[]	No	Alternative memory ID fields.
`actor`	string	No	Agent or host sending the feedback.
`verifier_status`	string	No	`passed`, `failed`, `not_run`, or `unknown`.
`tool_status`	string	No	`succeeded`, `failed`, `not_run`, or `unknown`.

Example


curl -s http://127.0.0.1:3001/v1/feedback \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "target": "memory",
    "guide_trace_id": "guide_trace:abc",
    "run_id": "run-001",
    "outcome": "positive",
    "reason": "The Agent followed the accepted route and validation passed.",
    "used_surface": "use_now",
    "used_memory_ids": ["mem_123"],
    "actor": "worker-1",
    "verifier_status": "passed",
    "tool_status": "succeeded"
  }'

SDK


await aionis.feedback({
  target: "memory",
  guide_trace_id: guide.guide_trace_id,
  run_id: "run-001",
  outcome: "positive",
  reason: "The accepted route was followed and validation passed.",
  used_surface: "use_now",
  used_memory_ids: ["mem_123"],
  actor: "worker-1",
});

Response


{
  "contract_version": "aionis_feedback_result_v1",
  "tenant_id": "default",
  "scope": "checkout-migration",
  "operation": "activate",
  "target": "memory",
  "forget_effect": {
    "action": "activate"
  }
}

Strict attribution

When guide_trace_id is present, feedback is checked against the guide exposure ledger. The host can only attribute outcome to memory IDs that were exposed by that guide.

Common errors

Error	Fix
Missing `run_id`	Send the run that produced the outcome.
Missing `outcome`	Use `positive`, `negative`, or `neutral`.
Missing `used_surface`	State how the memory was actually used.
Memory not exposed by guide	Use memory IDs returned by the same guide trace.