Module observations 

v0.7.0 Gap 3 (#886) — recall-consumption observation tier.

The Batman 6-form audit closeout flagged a missing “what did the caller actually use after we ranked it” feedback channel: recall ranking telemetry stops at the recall response, so the substrate cannot tell which candidates the caller subsequently cited in a memory_store or memory_link payload. This module is the write-side half of the closeout:

• record_recall — at the end of every memory_recall call, the dispatcher writes one ledger row per returned candidate (recall_id + memory_id + retriever + rank + score). The recall_id is a fresh UUID returned in the response so the caller can echo it back on a later store/link.
• mark_consumed — when a memory_store or memory_link request cites a recall_id + memory_ids list, the matching rows flip consumed = TRUE and capture the consumed_by_memory_id FK of the row that did the citing.

Read-side is exposed via the gc submodule (TTL prune) and the memory_recall_observations MCP tool defined in crate::mcp::tools::recall_observations.

Schema

recall_observations (migration 0038_v07_recall_observations.sql, schema v47) is the backing table. Composite primary key (recall_id, memory_id) keeps the substrate idempotent under duplicate writes (an exact replay of the same recall is a no-op, not a UNIQUE-violation refusal).

Modules

gc

v0.7.0 Gap 3 (#886) — recall_observations TTL pruner.

Structs

Candidate

One candidate row passed to record_recall.

Observation

One row of recall_observations as it travels over the read-side MCP memory_recall_observations tool. Mirrors the SQL columns 1:1 plus a derived consumed boolean (the SQL column is an INTEGER 0/1).

Functions

list_observations

Read-side query for the memory_recall_observations MCP tool.

mark_consumed

Flip the consumed flag (and capture consumed_at + consumed_by_memory_id) for every (recall_id, memory_id) pair where memory_id is in cited_memory_ids. Idempotent — replaying the same call is a no-op because the WHERE clause requires consumed = 0.

parse_cite_batch

Convenience helper used by the MCP store/link consume hook: read the recall_id + cited_memory_ids array out of an MCP request params Value. Both must be present for a cite-batch to fire.

record_recall

Write one recall_observations row per candidates entry under a single recall_id. The call is best-effort: a SQL error during insertion logs at warn level and continues, since the substrate MUST NOT block a successful recall response on a failed audit write.

table_exists

Probe whether the recall_observations table exists on this connection. Used by the recall-side instrumentation as a soft gate so a pre-v47 database doesn’t blow up the recall response when the binary briefly precedes the migration apply (the migration runs at open time, so this is only relevant for hand-rolled Connection::open test fixtures that skip crate::storage::open).

try_mark_consumed_from_params

Best-effort wrapper around mark_consumed used by the handle_store / handle_link hot paths: parses the cite batch, invokes the SQL update, and logs (rather than propagates) any substrate error. The recall ledger MUST NOT block the underlying write — it’s an audit trail, not a precondition.