Struct DemotingPolicyMemory 

pub struct DemotingPolicyMemory<M, P, H> { /* private fields */ }

A ConversationMemory adapter that wraps a backend with a MemoryPolicy and a DemotionHook, so messages truncated by the policy flow into the hook before the active window is returned.

DemotingPolicyMemory is the bridge between the recent-turn store (InMemoryConversationMemory or any other ConversationMemory) and a long-tail store (MemvidPersistHook, vector RAG, archival storage, …). Compose it with any MemoryPolicy that overrides MemoryPolicy::apply_with_demoted; policies that rely on the default implementation will still load correctly but will never demote anything.

Concurrency

Concurrent ConversationMemory::load calls on the same conversation_id are serialised at the demotion seam: only one call at a time delivers messages to the hook for a given conversation. Other concurrent loads for that conversation observe the in-flight delivery and return the truncated kept history immediately without firing the hook again. Pending demotions that were skipped this way are picked up by the next load after the in-flight delivery completes.

Failure visibility. A hook error is returned only to the caller whose load actually drove the delivery. Concurrent callers that short-circuited on in_flight see Ok(kept) even if the in-flight delivery ultimately failed; the watermark stays unchanged so the next load retries. Callers that rely on the hook for durability should treat a successful load as best-effort with respect to demotion and surface hook failures through the hook’s own observability (logs, metrics, dead-letter buffer) rather than the load return value.

Persistence

Delivery watermarks are kept in process memory only. Across process restarts, the hook will receive previously-delivered demotions again; see the DemotionHook idempotency contract.

Example

use rig_memory::{
    DemotingPolicyMemory, DemotionHook, InMemoryConversationMemory,
    MemoryError, NoopDemotionHook, SlidingWindowMemory,
};

let memory = DemotingPolicyMemory::new(
    InMemoryConversationMemory::new(),
    SlidingWindowMemory::last_messages(20),
    NoopDemotionHook,
);

Implementations

impl<M, P, H> DemotingPolicyMemory<M, P, H>

pub fn new(inner: M, policy: P, hook: H) -> Self

Wrap inner so every load runs through policy and demoted messages flow into hook.

pub fn inner(&self) -> &M

Return a reference to the wrapped backend.

pub fn policy(&self) -> &P

Return a reference to the wrapped policy.

pub fn hook(&self) -> &H

Return a reference to the demotion hook.

pub fn into_inner(self) -> (M, P, H)

Consume the wrapper and return its three components.

pub fn forget(&self, conversation_id: &str)

Drop the in-process delivery watermark for conversation_id.

Call this when a conversation has ended to bound memory usage. The watermark map is otherwise unbounded — entries persist for the lifetime of the wrapper.

If the internal state lock has been poisoned by a panic in another thread, this is a no-op (the watermark will be dropped naturally when the wrapper itself is dropped).

pub fn tracked_conversations(&self) -> usize

Number of conversations currently tracked in the watermark map. Useful for telemetry and leak detection. Returns 0 if the internal state lock is poisoned.

Trait Implementations

impl<M, P, H> ConversationMemory for DemotingPolicyMemory<M, P, H>

where M: ConversationMemory, P: MemoryPolicy, H: DemotionHook,

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

Load the full conversation history for conversation_id.

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

Append messages to the conversation identified by conversation_id.

fn clear<'a>( &'a self, conversation_id: &'a str, ) -> WasmBoxedFuture<'a, Result<(), MemoryError>>

Remove all stored messages for conversation_id.

impl<M, P, H> Debug for DemotingPolicyMemory<M, P, H>

where M: Debug, P: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.