# Close the loop
> An outcome recorded against a context run changes what future compiles rank first, without editing a single observation.
Section: The memory loop · Source: https://titen.dev/docs/feedback
Derived from: https://github.com/RamaAditya49/titen/blob/main/docs/architecture/memory-lifecycle.md
---
The agent acts outside Titen. What comes back is one small fact about the pack it was given:
did any of it help? That signal is what separates a memory store that accumulates from one
that gets better at choosing.
## Record an outcome
feedback.tstypescript
```ts
await titen.feedback(ctx.context_id, {
outcome: 'useful',
claim_id: ctx.items[0]?.claim_id,
});
```
```sh
curl -X POST http://127.0.0.1:8787/v1/context/ctx_5aa8109e55ed41b49cb75f48868cd289/feedback \
-H "authorization: Bearer $TITEN_API_KEY" \
-H 'content-type: application/json' \
-d '{"outcome":"useful","claim_id":"claim_d5ce4657d6b947aa8ade42271b4176f5"}'
```
```json
{ "data": { "feedback_id": "fb_759a0268e3a84d3b86d07b6590156714",
"context_id": "ctx_5aa8109e55ed41b49cb75f48868cd289",
"claim_id": "claim_d5ce4657d6b947aa8ade42271b4176f5",
"outcome": "useful", "recorded_at": "2026-07-30T10:47:47.575Z" },
"meta": { "request_id": "req_…", "replayed": false } }
```
## Five outcomes
| Outcome | Effect on utility | When to send it |
| --- | --- | --- |
| `used` | positive | The item made it into the prompt and the action succeeded. |
| `useful` | positive | The item changed what the agent did, for the better. |
| `irrelevant` | negative | Eligible and correct, but not about this task. |
| `incorrect` | negative | The claim is wrong. |
| `harmful` | negative | Acting on it caused damage. |
Anything else is refused rather than coerced:
```json
{ "error": { "code": "VALIDATION_ERROR",
"message": "Field \"outcome\" must be one of: used, useful, irrelevant, incorrect, harmful." },
"meta": { "request_id": "req_e5d3a330e24343dfaf34c45d35955bbc" } }
```
An optional `reason_code`, up to 64 characters, rides along for your own evaluation queries.
`incorrect` and `harmful` are signals about a *selection*, not lifecycle commands: retiring a
wrong claim is a separate, authorized decision. See [claim lifecycle](/docs/claim-lifecycle).
## claim_id decides what moves
Run-level feedback moves nothing
Omit `claim_id` and the outcome is recorded against the whole run. Utility is counted per
claim, so only feedback that names a `claim_id` affects ranking. Name the claim to close the
loop; omit it when you are grading the pack as a whole.
A `claim_id` must be one the run actually returned. A claim that was never in the pack is a
non-disclosing `404`, so feedback cannot be used to probe which claims exist:
```json
{ "error": { "code": "NOT_FOUND", "message": "Resource was not found." },
"meta": { "request_id": "req_a4adc0eb7c74469ebe1af88bd8c00b08" } }
```
Retries are idempotent two ways: an `Idempotency-Key` header, or a `client_mutation_id` in
the body. Either one returns the original `feedback_id` with `meta.replayed: true`.
## How utility feeds back into ranking
Positive and negative counts are read at compile time from the feedback rows themselves.
There is no cached utility score to drift out of date. The `utility` component works out to:
Fewer than three signals for the claim: 0.5, the neutral value.
Three or more: (net + 1) / 2, where net is (positive − negative) / total. All-positive gives 1, all-negative gives 0.
The component is weighted 0.10 in the final score, so it reorders neighbours and cannot outvote relevance or trust.
A ranking signal that moved on a single vote is a poisoning surface: anything that can call
this route once could promote its own memory. Requiring three makes that attack cost more,
and slows promotion for everyone equally.
Live, on the same claim, before and after three `useful` outcomes:
Its statement, trust, confidence, evidence links and status are byte-identical; only the
score moved.
## What feedback may never do
Rewrite observation content. Evidence is append-only, and an outcome is not evidence.
Raise trust. Trust comes from a credential's authority over its evidence, never from a popularity count.
Turn repeated opinion into fact. A claim voted useful a hundred times is still a claim, with the same trust and the same sources.
Cross a tenant, subject or visibility boundary, or delete canonical evidence on its own.
Negative feedback is kept for evaluation even after its claim is revoked, so the system can
learn that a selection was bad without losing the record of what it selected.
## Next