Skip to main content

Crate rig_memory

Crate rig_memory 

Source
Expand description

Conversations over time, over rig-core’s Conversation:

use rig_core::message::Message;
use rig_memory::recent::{LastMessages, view};
use rig_memory::{MemoryStore, load, save};

let store = MemoryStore::default();
let mut conversation = load(&store, "user-123")?;
conversation.extend([Message::user("My name is Alice."), Message::assistant("Hi Alice!")]);
save(&store, "user-123", &mut conversation)?;

let resumed = load(&store, "user-123")?;
assert_eq!(resumed, conversation);
assert_eq!(view(resumed.messages(), &LastMessages(1)).len(), 1);

Modules§

recent
Recent messages: which newest messages of a conversation a request sends. A Recent rule says where the messages it keeps start; view moves that start past results whose calls it cut off, so every result it keeps still follows its call.

Structs§

Anchor
The usage a provider reported for an agent’s last reply, and the last entry of the conversation it counts: the reply, or the request’s last message when the reply added none. It anchors the estimate of the next request (next_request_tokens).
ClearPlan
The tool outputs a clearing replaces (ClearToolOutputs::plan), by message id.
ClearToolOutputs
Frees context by clearing the outputs of older tool calls: walking back from the end, the outputs within the first keep_tokens stay, and every older one is replaced by a placeholder. The last message is never touched: it is what the model must answer. Error results stay, being short and telling the model what went wrong, and so do outputs under keep_under tokens, which free little. The calls themselves stay, so the conversation keeps its shape. Each size missing from its serde form is the default’s.
Cleared
What ClearToolOutputs::clear took out.
Compacted
What a compaction replaced, kept with the conversation in an aside of kind COMPACTED by summary_author after its summary: the newest one is what undo_summary puts back.
CompactionPolicy
How a conversation is compacted: what the summarizer is asked, the tool arguments a summary keeps track of, such as the files a coding agent’s file tools read and changed, how much of the newest conversation stays as it is, and how old tool outputs are cleared first. Tokens are estimated by the default HeuristicTokenCounter.
DirFiles
Files kept as plain files under a directory, each name its path there, such as data kept outside any session. Folders are made as files are written, and nothing is written before.
DirStore
A Store in the directory it was opened on, whose folders are made as files are written. Each change locks the directory’s lock file, so stores open on one directory, in this process or another, take turns; reads take no lock. Cloning opens the same directory.
HeuristicTokenCounter
Estimates token cost from UTF-8 lengths, rounded up per text-bearing part. Tool calls count name bytes plus serialized argument bytes. Attachments and message overhead have fixed costs.
LogRewrite
A rewrite of a log in place (rewrite): when, and by whom, such as the plugin that redacted it.
MemoryStore
A session kept in memory, such as for tests or where there is no file system. Cloning shares the contents.
Messages
Only messages; files are left.
PluginFiles
The files of a session’s store under PLUGINS, by their names there: what a plugin keeps for the session.
Prepared
A request as prepared to be sent, as next_request_tokens reads it.
RequestStart
What a sent request started with, to tell whether the usage reported for its reply still describes the next request: a fingerprint of its model, system prompt, tools and messages (each by id, the time it was made and the shared message it holds, so an edit, a splice or a restore changes it), and how many messages it had. It holds in the process that made it only.
Rewritten
What rewrite did.
RewrittenLog
A log rewrite changed.
SavedAgent
An agent as its log left it.
Session
A session as its logs left it.
SessionMeta
What a listing shows of a session, kept in its store: what it is about, the labels plugins give it, and when it last changed. Its logs hold the same facts; this is the cache a listing reads without folding them. Fields a reader does not know are skipped, and missing ones are empty.
Stamp
Where a record is in a session: its place among the session’s records in the order they were made (n, what as_of cuts by), its place in its log (seq, dense from the header’s 0), and when it was written (t, milliseconds since the Unix epoch).
Strings
Every string, keys included, of every value: messages and asides through their serde form, saved values, text and every file. Redaction and path remapping are this. A string that is part of a message’s or an aside’s form, such as a field name or a tag, is left as it is where changing it would make the value unreadable.
Summarizer
Builds the request for a summary of a conversation’s older messages and reads the summary from the model’s answer. The conversation goes as text in one user message, so the model reads it rather than continues it.
SummaryCut
Where a compaction CompactionPolicy::cut_summary chose ends, with no request: for a summary asked at the end of the conversation itself (Summarizer::instruction).
SummaryLimits
The sizes a Summarizer works within. Each size missing from its serde form is the default’s.
SummaryPlan
A summary CompactionPolicy::plan_summary planned.
SummaryPrompts
What a Summarizer asks the model. Each prompt missing from its serde form is the default’s.
SummaryState
A summary of a conversation’s older messages and the values tracked across compactions (such as the files a coding agent read). The default is the state before the first compaction.
TrackArgument
A rule of SummaryState::track: the string argument argument of every call of the tool tool goes into the set set.
TrackedSet
One named set of a SummaryState, sent after the summary inside a <name> tag.
Uncompacted
What undo_summary did.
Unreadable
A log Session::read_lenient could not read.
Writer
A running session’s logs, the harness’s appender. Every method takes &self, so clones share them. Nothing is logged before start, nor once a write failed; a default writer has no store and logs nothing.

Enums§

CompactReason
Why a conversation is compacted.
LogRecord
One record of a log, as history reads it.
LogWriteError
Why a log write wrote nothing.
NearWindow
What a clearing near the model’s window does with the tool outputs it drops; its serde form is "summarize" or "clear".
Place
Where a value being rewritten is kept.
Repair
What reading a session repaired, or found it must work around.
SessionError
Why a session cannot be read or saved. Reading is strict: a session with any record it cannot read is refused whole, and nothing is written.
SummaryError
Why a summary cannot be used.
UndoError
Why undo_summary put nothing back.

Constants§

ATTACHMENT_TOKENS
About how many tokens an image, or another attachment, costs.
BLOBS
Where a store keeps the blobs its messages name: files under blobs/, each named by a hash of its content.
COMPACTED
The kind of the aside apply_summary puts after each summary.
FORMAT
The saved format a log’s header names: the one format this rig reads.
META
The file of a session’s store that holds its SessionMeta.
MODEL
The key an agent’s model is saved under: a string, vendor/model.
OUTPUT_MARGIN
Tokens a request leaves free below the window, besides the output it asks for: a margin for the estimate’s error.
PLUGINS
Where plugins’ files are in a session’s store.
SESSION
The log of the session’s own saved values, beside the agents’ logs.
TITLE
The key an agent’s title is saved under, such as a subagent’s task: a string.

Traits§

AsyncStore
A session’s storage reached asynchronously: the part of Store that load_async and save_async use, for a store behind a network or a JavaScript promise. Every Store is one, its calls done when made: a local store pays no thread hop and no allocation for it. A type that implements Store gets this from it and cannot have its own (the two impls would overlap): wrap it in a type of your own instead.
Files
A place that keeps files by name, such as a session’s plugin data or effect log. A name is relative and /-separated (check_name). Every method takes &self, so one value is shared, between threads on every target: a host keeps it as Arc<dyn Files> or Arc<dyn Store> in state its systems share, such as a Bevy resource, which is Send and Sync on wasm too; Arc<dyn Store> and Box<dyn Store> are themselves a Store, so an AsyncStore too. A store that is not Send and Sync, such as one over a JavaScript promise, is an AsyncStore.
Rewrite
A change applied to every value a session keeps. Each hook edits its argument in place and returns whether it changed anything. Every hook defaults to no change, except file, which sends JSON files to value, JSON-lines files line by line, and other UTF-8 to text. A hook cannot add, drop or re-kind a record. Shared between owners, so it takes &self.
Store
Where a session is kept: its Files, with the content-addressed blobs its messages name under blobs/, and a log per agent plus the session’s own, appended to and read whole. Log names are one part of a name (check_name without /).
TokenCounter
Counts the tokens of one Message: the provider’s tokenizer (such as tiktoken-rs for OpenAI) or an estimate. It runs once per message a window or a compaction weighs, so it must be cheap.

Functions§

apply_summary
Puts the summary of state in place of the messages of conversation before keep_from (every message with None), earlier summaries included: one user entry by summary_author, a splice it makes, followed by an aside of kind COMPACTED that says what it replaced (Compacted), so undo_summary can put that back. None, changing nothing, when keep_from was taken out meanwhile or state has no summary.
as_of
The conversation of the log log of store as the records made before the session’s record n left it (Stamp::n); an empty one when there is no log.
check_name
Refuses name unless it is relative and /-separated, with no empty, . or .. part and no \, so it names a place inside the store wherever the store keeps it.
estimate_tokens
The estimated tokens of messages, by the default HeuristicTokenCounter, as a policy estimates them.
excerpt
One line of entry: who wrote it, then the start of its text, or the tools it called.
history
Every record of the log log of store after its header, in order, with its stamp; images are put back from their blobs. Empty when there is no log.
load
The conversation the log log of store holds; an empty one when there is none. It continues the log (its lineage and its number of changes), so save can tell whether the log moved on or the conversation is another.
load_async
load from an AsyncStore, such as a database or IndexedDB: the log read once, and the blobs its records name.
load_images
Puts the data of each image message names in store back in place. An image whose blob cannot be read has no data any more (Unknown), which a request sends as a placeholder; the first such failure is returned.
main_order
Where an agent sorts among the agents of a session: those nothing spawned first, each group by id. The first is the main agent, the one the user talks to when none is named.
map_strings
Maps every string (keys included) of value through f; whether any changed.
next_request_tokens
About how many tokens request sends. Anchored, it is the usage the provider reported for the reply to the request that started as sent says, plus the estimate of the messages after the anchor’s entry: the anchor holds while that entry is the reply to that request (or its last message) and request starts as that request did, with the same model, system prompt, tools and messages. Otherwise, such as after a compaction, a model change, a prompt or tool change, or a cleared copy, it is Prepared::whole_tokens. The tool definitions are counted once either way: reported input counts them already.
output_room
The most output a request of estimate tokens may ask of a model with a window of tokens and an output limit of most: most, or what the window leaves after the request and OUTPUT_MARGIN when that is less. None when neither is known; Some(0) when the window leaves no room, which calls for compacting first, not for a request with no room to answer.
read_conversation
The conversation of agent (the main agent when None, found from the logs’ headers alone) of the session in store, folded from that agent’s log only, writing nothing. Returns the agent’s id and its conversation, with ids and made-times kept.
rewrite
Rewrites the session in store through with, as done by by, in place: every record stays where it is with its stamp, and every value in it goes through with (see Rewrite). Each log a record of which changed gets a fresh lineage and {t, by} added to its header’s rewrites.
rewrite_file
The file name of files through Rewrite::file, written back whole (Files::write_file, atomic) when it changed: whether it did. A file that is not there is left. How a host or a plugin maps a file it keeps from the session outside the session’s store, such as a history of prompts.
rewrite_value
item mapped through with by its serde form, as a JSON value of a file is (Rewrite::value at at, under key): whether it changed. How a host or a plugin maps what it keeps of a rewritten session, such as a copy of a tool call held in memory.
save
Appends the unsaved changes of conversation to the log log of store, starting it when there is none, and leaves the conversation with nothing unsaved. A torn last line of the log is first set aside, as Writer::open does.
save_async
save to an AsyncStore: the log read once, then the blobs of new images written, then the changes appended with one write, which the store makes only if the log is still as it was read. A save reads only its own log, so one store holds many conversations, a log each. A save cut short, such as by a dropped future, has appended nothing, a cut last line (set aside by the next save), or, for a remote store that already applied it, all of it.
store_images
message as it is saved: the data of each image in it stored in store once per content, and named there instead. Borrowed when it has no image data to store; data that is not valid base64 stays inline.
summarized_prefix
How many of the first entries of conversation are summaries (by summary_author): what a new compaction builds on from its SummaryState instead of reading it again. It is the from the policy’s cut and plan are given.
summary_author
Who writes a compaction’s summary: the author of its entry.
summary_in
The summary a compaction put in, when change is one: the id of the entry by summary_author in a splice that took messages out. Clearing old tool outputs, by the same author, keeps every message and is none.
summary_state
The summary state the next compaction of conversation builds on: the newest compaction’s not undone (Compacted), or the state before any.
title_of
A title or label of text, as a listing shows it: on one line, each run of whitespace one space, cut to 60 characters (the last an ellipsis when cut).
undo_summary
Undoes the newest compaction of conversation, the conversation saved in the log log of store: the entries its summary replaced, read from that log as they were just before it, are put back in the summary’s place with their ids (Conversation::restore by by), and its Compacted aside goes. Entries added after the summary stay after them. Undone one after another, compactions come back newest first, each with the summary it built on.