Trait DemotionHook 

pub trait DemotionHook: WasmCompatSend + WasmCompatSync {
    // Required method
    fn on_demote<'a>(
        &'a self,
        conversation_id: &'a str,
        messages: Vec<Message>,
    ) -> WasmBoxedFuture<'a, Result<(), MemoryError>>;
}

A side-channel for messages that a memory policy or adapter removes from active history during ConversationMemory::load.

Truncating policies (sliding window, token budget, …) drop older turns once their limit is exceeded. Without a hook those messages are silently lost. A DemotionHook receives the demoted messages and can persist them into a long-tail store (semantic memory, episodic recall, archival storage, …), turning truncation into demotion.

The trait is defined here in rig-core so that any memory backend (in-memory, vector store, file archive, …) can implement it without taking on a rig-memory dependency. The composing adapter that actually wires a ConversationMemory backend, a policy, and a hook together lives in the rig-memory companion crate.

Hooks should be inexpensive: their future is awaited inline on every load that produces demoted messages, so a slow hook delays the agent’s next turn. Offload heavy I/O (network writes, disk fsyncs, …) to a background task or a buffered channel inside the implementation.

Idempotency contract

Implementations must be idempotent on the (conversation_id, messages) pair. Composing adapters such as the DemotingPolicyMemory in rig-memory track in-process delivery watermarks to avoid replaying the same demotion within a single process lifetime, but those watermarks are not persisted: across process restarts (or when a new adapter is constructed over an existing backend) the hook will receive previously-delivered messages again. Hooks that append to durable storage should deduplicate by content hash, by (conversation_id, message_id), or by an equivalent stable key.

Required Methods

fn on_demote<'a>( &'a self, conversation_id: &'a str, messages: Vec<Message>, ) -> WasmBoxedFuture<'a, Result<(), MemoryError>>

Receive messages that were demoted out of the active window for conversation_id.

messages are in original conversation order. Errors are propagated as MemoryError::Backend by the composing adapter.

Implementations on Foreign Types

impl<H> DemotionHook for Arc<H>

where H: DemotionHook + ?Sized,

Forwarding impl so callers can pass Arc<H> wherever a DemotionHook is expected (e.g. when sharing a single hook between multiple memory adapters).

fn on_demote<'a>( &'a self, conversation_id: &'a str, messages: Vec<Message>, ) -> WasmBoxedFuture<'a, Result<(), MemoryError>>

Implementors

impl DemotionHook for NoopDemotionHook