agent-context

Backend-agnostic LLM conversation context manager built on the kameo actor model.

Three-Zone + Scratch Memory

Messages are split into three storage zones plus a transient scratch layer:

Concatenation order: immutable → compressed → incremental → scratch.

Change Notification

Register a callback via with_on_change to receive ChangeEvent notifications. Every mutation to the incremental zone triggers a notification — there are no silent bypasses.

Usage

use agent_context::{AgentContext, AppendMsg, SendMsg, SendStreamMsg, MessagesMsg, ContextBackend, CommonOpts};
use futures::StreamExt;

// 1. Implement ContextBackend for your LLM backend
// 2. Spawn the actor
let ctx = AgentContext::new(backend, vec![backend.system_message("You are a helpful assistant.")]);
let actor = AgentContext::spawn(ctx);

// 3. Non-streaming conversation
actor.ask(AppendMsg { message: user_msg }).await?;
let response = actor.ask(SendMsg { opts: my_opts }).await?;

// 4. Streaming conversation
let mut stream = actor.ask(SendStreamMsg { opts: my_opts }).await??;
while let Some(chunk) = stream.next().await { /* e.g. render chunk in UI */ }
let chunks = stream.take_chunks();
let msg = backend.merge_chunks(&chunks).expect("chunk merge failed");
let msgs = backend.to_request_messages(vec![msg])?;
for m in msgs {
    actor.ask(AppendMsg { message: m }).await?;
}

ContextBackend

The core trait — implement it to support any LLM provider (DeepSeek, Zhipu, OpenAI, etc.):

• Message factories: user_message, system_message, tool_message
• Format conversion: to_system_message, to_request_messages
• Response parsing: extract_messages, merge_chunks
• Model interaction: send, send_stream, estimate_tokens

Each backend's Opts type must embed CommonOpts (model, context_window, max_tokens, auto_compress, scratch) via AsRef<CommonOpts>.

Compression

Automatic compression is triggered before each SendMsg/SendStreamMsg when CommonOpts::auto_compress is true and the estimated tokens exceed context_window. Use CompressMsg with CompressStrategy::Summarize for manual compression.

License

MIT OR Apache-2.0