Struct BufferMemory 

pub struct BufferMemory { /* private fields */ }

Bounded conversation buffer.

Each call to append pushes one message and (if the buffer exceeds max_turns) drops the oldest. messages() returns the full retained list.

An optional ConsolidationPolicy can be attached via Self::with_consolidation_policy. When attached, Self::should_consolidate surfaces the policy’s decision so the caller (typically an agent recipe) can run an LLM-driven summarisation pass and write the result into a sibling crate::SummaryMemory before clearing the buffer. The buffer tracks last_consolidated_at itself — recipes call Self::mark_consolidated after a successful summarisation pass and the time-aware policies see the updated timestamp on the next check, so the consolidation loop reduces to:

if buffer.should_consolidate(&ctx).await? {
    run_summariser(&ctx, &buffer, &summary).await?;
    buffer.clear(&ctx).await?;
    buffer.mark_consolidated_now();
}

Implementations

impl BufferMemory

pub fn new( store: Arc<dyn Store<Vec<Message>>>, namespace: Namespace, max_turns: usize, ) -> Self

Build a buffer over store scoped to namespace, retaining at most max_turns messages.

pub fn with_consolidation_policy( self, policy: Arc<dyn ConsolidationPolicy>, ) -> Self

Attach a ConsolidationPolicy. The buffer itself never performs the summarisation — the policy only decides when the caller should — but having the policy bound here means agent recipes can ask the buffer directly via Self::should_consolidate without threading the policy through every call site.

pub const fn max_turns(&self) -> usize

Effective retention cap.

pub const fn namespace(&self) -> &Namespace

Borrow the bound namespace.

pub fn last_consolidated_at(&self) -> Option<DateTime<Utc>>

Wall-clock time of the most recent successful consolidation, as recorded via Self::mark_consolidated. Returns None before the first consolidation has been marked.

pub fn mark_consolidated(&self, at: DateTime<Utc>)

Record that a consolidation pass completed at at. Recipes call this after a successful summarise-and-clear cycle so time-aware policies (throttling, “at most once per hour”) observe the new floor on the next check.

pub fn mark_consolidated_now(&self)

Convenience over Self::mark_consolidated using chrono::Utc::now. Use when the caller doesn’t already have a timestamp in hand.

pub async fn append( &self, ctx: &ExecutionContext, message: Message, ) -> Result<()>

Append message, dropping the oldest entries when over capacity.

pub async fn messages(&self, ctx: &ExecutionContext) -> Result<Vec<Message>>

Read the retained messages oldest-first.

pub async fn clear(&self, ctx: &ExecutionContext) -> Result<()>

Clear the buffer.

pub async fn should_consolidate(&self, ctx: &ExecutionContext) -> Result<bool>

Consult the bound ConsolidationPolicy (if any) against the current buffer and the buffer’s tracked last_consolidated_at. Returns Ok(false) when no policy is bound — that path is the explicit “consolidation disabled” answer.

For token-budget policies that need the active model’s usage, use Self::should_consolidate_with and supply the values in PolicyExtras.

pub async fn should_consolidate_with( &self, ctx: &ExecutionContext, extras: PolicyExtras, ) -> Result<bool>

As Self::should_consolidate, but lets the caller layer on model-specific token usage signals or override the buffer’s internally-tracked last_consolidated_at (rare — useful when a downstream system has more authoritative state).