slowave_feedback: record memory and procedure assessments

Submit append-only assessments of retrieved memories and procedures — required for every exposed retrieval target before slowave_commit will succeed.

slowave_feedback records what actually happened after retrieval. Every memory and procedure exposed by slowave_activate or slowave_recall must be assessed before the session can be committed. Feedback is append-only — assessments are evidence that persists in Slowave’s retrieval quality ledger and influences future activations; they cannot be retracted. Task outcome does not belong here; slowave_commit owns that.

Scalar vs batch calling

slowave_feedback supports two calling patterns:

• Scalar: pass retrieval_id and the feedback lists directly to assess one retrieval event.
• Batch: pass an items list where each entry is a scalar-shaped feedback object, to assess multiple retrieval events in one round trip.

The two forms are mutually exclusive. If items is provided, all scalar feedback fields (retrieval_id, memory_feedback, procedure_feedback, retrieval_quality, missing) must be omitted and coverage must remain at its default of partial.

Parameters

retrieval_id · string

The opaque retrieval identifier returned by slowave_activate or slowave_recall. Required when using the scalar form. Must correspond to a known retrieval event for the current session.

memory_feedback · array

A list of per-memory assessments. Each entry must contain memory_id and assessment, plus additional fields required by certain assessment values.

Show memory feedback entry fields

memory_id · string · required

The sch_N identifier of the memory being assessed, as returned in the memories array of the activate or recall response.

assessment · string · required

One of three values:

• used — the memory was directly consulted and contributed to the task.
• irrelevant — the memory was returned but had no bearing on this task.
• stale — the memory is no longer accurate or applicable. Requires stale_reason and reason.

stale_reason · string

Required when assessment is stale. Classifies why the memory is stale:

• contradicted — the claim contradicts verified current state.
• superseded — a newer, more accurate claim replaces this one. Requires replacement_memory_id.
• outdated — the claim was true at some point but is no longer current.
• unsupported — the claim lacks supporting evidence.
• withdrawn — the claim was explicitly retracted.

replacement_memory_id · string

Required when stale_reason is superseded. The sch_N identifier of the memory that replaces this one.

reason · string

Required when assessment is stale. A concise explanation of why the memory is stale, in your own words.

procedure_feedback · array

A list of per-procedure assessments. Procedure feedback keeps usage and effect as separate signals.

Show procedure feedback entry fields

procedure_id · string · required

The identifier of the procedure being assessed, as returned in the procedures array of the activate or recall response.

use · string · required

Whether the procedure was used:

• used — the procedure was followed or referenced during the task.
• not_used — the procedure was retrieved but not applied.

effect · string · required

The observed outcome of applying the procedure:

• helped — the procedure contributed positively to the task outcome.
• no_effect — the procedure was followed but had no measurable impact.
• harmed — following the procedure made things worse.
• unknown — the effect cannot be determined.

contribution · string

A brief description of how the procedure contributed. Required when use is used.

reason · string

Optional free-text explanation of the assessment, especially useful when effect is harmed or no_effect.

retrieval_quality · string

Optional whole-result quality assessment for the retrieval event as a whole, independent of individual memory assessments.

missing · array

Optional list of strings describing knowledge that was expected but absent from the retrieval results. Use this to record what Slowave should have surfaced but did not — this signal helps improve future retrievals.

coverage · string

Controls how silence is interpreted for this feedback call. Accepted values:

• partial (default) — you are only assessing a subset of exposed targets. Targets not mentioned are left as unknown rather than treated as negative evidence.
• complete — you have assessed every target exposed by this retrieval. Targets not mentioned in memory_feedback or procedure_feedback are implicitly treated as assessed.

Use complete only when you have genuinely reviewed every memory and procedure returned by the retrieval event.

items · array

A batch list of scalar-shaped feedback objects. Each entry has the same shape as the scalar parameters (retrieval_id, memory_feedback, procedure_feedback, retrieval_quality, missing, coverage). Mutually exclusive with all scalar feedback fields.

Response

Scalar response

Returns the feedback record as stored by the engine, confirming what was recorded.

Batch response

When items is used, the response is {"ok": true, "data": {"results": [...]}} where each entry contains:

ok · boolean

true if this individual feedback item was recorded successfully.

data · object

Present when ok is true. The stored feedback record for this item.

error · object

Present when ok is false. Contains code, message, and retryable.

Append-only semantics

Feedback cannot be retracted or modified after it is written. Each call appends new evidence to the retrieval quality ledger. If you call slowave_feedback twice for the same retrieval_id, both records are preserved. This is by design: the accumulation of honest, granular feedback over time is what allows Slowave to improve retrieval quality across sessions.

Coverage and the feedback authorization model

Slowave tracks exactly which memories and procedures were exposed by each retrieval event. Before slowave_commit can succeed, every exposed target must have received at least one feedback assessment. This is the feedback authorization model: feedback is authorized only for targets that were actually returned, and closure is gated on coverage of all of them.

The coverage parameter determines how partial silence is interpreted:

• With coverage: partial, you can submit feedback for a subset of targets in one call and cover the rest in subsequent calls before committing.
• With coverage: complete, you are declaring that your current feedback submission covers all exposed targets.

If slowave_commit returns {"ok": false, "error": {"code": "incomplete_feedback", "retryable": true}}, the outstanding array in the error lists every retrieval ID and target that still needs feedback. Submit slowave_feedback for each outstanding item, then retry the commit.

Examples

Used memory, irrelevant memory

{
  "retrieval_id": "ctx_a1b2c3d4e5f6",
  "memory_feedback": [
    {
      "memory_id": "sch_42",
      "assessment": "used"
    },
    {
      "memory_id": "sch_17",
      "assessment": "irrelevant"
    }
  ],
  "coverage": "complete"
}

slowave_feedback is not the place to record the task outcome. Whether the task succeeded or failed belongs in slowave_commit. Feedback is strictly about the quality and accuracy of what was retrieved, not about what you accomplished.