Expand description
Conversations over time, over rig-core’s Conversation:
recent: which newest messages a request sends.prepare_compaction,apply_summary: compacting a long conversation.load,save,Session,Writer: saving and resuming, in the one formatFORMAT. Reading is strict: a session of another format, or that does not read whole, is refused and nothing is written.load_asyncandsave_asynckeep a conversation in anyAsyncStore, such as a database or IndexedDB.history,as_of: how a conversation got where it is.rewrite(what it promises is on it): rewriting a saved session.SessionMeta,read_conversation: what a session list shows, read without folding every log.Store,MemoryStore,DirStore(featurefs): where a session is kept;Files,DirFilesandPluginFilesfor named files on their own. EveryStoreis anAsyncStore, its calls done when made. A log write appends only if the log is as long as the writer read it, the store checking and writing in one step, so of two saves that read one log the second is refused (SessionError::Changed) and writes nothing to it.rig-sqliteandrig-postgreskeep sessions in a database with theirmemoryfeature, andconformance(featuretest-utils) checks a store against the contract.
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§
- conformance
- The contract every
AsyncStorekeeps, checked against a store: what a missing log or file reads as, the length check of the two log writes, names refused, and racing writers, of which exactly one wins. A store’s own tests runcheck_storeon two handles to one empty storage, such as two connections to one database, so it also checks that what one handle writes the other reads. - recent
- Recent messages: which newest messages of a conversation a request
sends. A
Recentrule says where the messages it keeps start;viewmoves 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: the reported tokens plus an estimate of the messages after it.
- Compaction
Preparation - A compaction ready to summarize (
prepare_compaction). - Compaction
Settings - When compaction runs and how much it keeps:
[compaction]in settings. - DirFiles
Fileskept 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
Storein 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. - File
Lists - The files a compaction lists after its summary.
- Heuristic
Token Counter - 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. - Memory
Store - 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.
- Plugin
Files - The files of a session’s store under
PLUGINS, by their names there: what a plugin keeps for the session. - Rewritten
- What
rewritedid. - Rewritten
Log - A log
rewritechanged. - Saved
Agent - An agent as its log left it.
- Session
- A session as its logs left it.
- Session
Meta - 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, whatas_ofcuts 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, their tool calls’ facts 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.
- Summary
State - A compaction’s summary and the files listed after it, which the next compaction carries on.
The default is the state before the first compaction. The summary’s entry in the
conversation is its only record:
apply_summarywrites it andreadreads it back. - Unreadable
- A log
Session::read_lenientcould not read. - Writer
- A running session’s logs, appended to as it runs. Every method takes
&self, so clones share them. Nothing is logged beforestart, nor once a write failed; a default writer has no store and logs nothing.
Enums§
- LogRecord
- One record of a log, as
historyreads it. - LogWrite
Error - Why a log write wrote nothing.
- Place
- Where a value being rewritten is kept.
- Repair
- What reading a session repaired, or found it must work around.
- Session
Error - 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.
- Summary
Failure - Why a summary reply cannot be used.
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. - CURRENT
- The key the session’s current agent is saved under, the agent the user talks to when none is named: a string, the agent’s id. One of the session’s own values.
- FORMAT
- The saved format a log’s header names: the one format this rig reads.
- MAX_
NEW_ LOG_ NAME - The longest name, in bytes,
check_new_log_nameallows: with its file’s extension it fits the 255 bytes every disk allows a file name. - 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. - PLUGINS
- Where plugins’ files are in a session’s store.
- SESSION
- The log of the session’s own saved values, beside the agents’ logs.
- SUMMARIZATION_
SYSTEM_ PROMPT - The system prompt of every summary request.
- TITLE
- The key an agent’s title is saved under, such as a subagent’s task: a string.
Traits§
- Async
Store - A session’s storage reached asynchronously: the part of
Storethatload_asyncandsave_asyncuse, for a store behind a network or a JavaScript promise. EveryStoreis one, its calls done when made: a local store pays no thread hop and no allocation for it. A type that implementsStoregets 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 asArc<dyn Files>orArc<dyn Store>in state its systems share, such as a Bevy resource, which isSendandSyncon wasm too;Arc<dyn Store>andBox<dyn Store>are themselves aStore, so anAsyncStoretoo. A store that is notSendandSync, such as one over a JavaScript promise, is anAsyncStore. - 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 tovalue, JSON-lines files line by line, and other UTF-8 totext. 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 underblobs/, and a log per agent plus the session’s own, appended to and read whole. Log names are one part of a name (check_namewithout/).
Functions§
- already_
compacted - Whether
conversationends in its last compaction, as pi’s session does when nothing was added after it: a summary is in, and every other message is older than it. - apply_
summary - Puts the summary of
statein place ofreplaces, the first messages ofconversationas a compaction read them (CompactionPreparation::replaces), earlier summaries included: one user entry bysummary_author, in one splice, which is the compaction’s whole record. Messages added after them stay.None, changing nothing, whenreplacesis empty, when the conversation no longer starts with those very messages, such as after an edit of one, so a summary never replaces what it did not read, or when what stays would start with a tool result whose call the summary replaced. - as_of
- The conversation of the log
logofstoreas the records made before the session’s recordnleft it (Stamp::n); an empty one when there is no log. - check_
log_ name - Refuses
nameas a log name:check_name, in one part. - check_
name - Refuses
nameunless 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. - check_
new_ log_ name - Refuses
namefor a new log:check_log_name, a name longer thanMAX_NEW_LOG_NAMEbytes, orSESSIONin any letter case (same_log_name), which names the session’s own log on a disk that ignores case. A log that exists keeps its name: stores read and write it undercheck_log_name. - clamp_
max_ tokens max_tokensfitted intospec’s context window after an input ofinput_tokens, leaving a margin for an input counted higher than estimated: unchanged when the window is not known, and never below 1.- estimate_
message_ tokens - The estimated tokens of
message, at four characters a token, rounded up: on the high side, as pi’s compaction counts. Each tool result counts as a message of its own, rounded apart, beside the rest of a user message. - estimate_
tokens - The estimated tokens of
messages(estimate_message_tokens). - excerpt
- One line of
entry: who wrote it, then the start of its text, or the tools it called. - find_
cut_ point - The index of the first message kept by the cut of
messages[start..end]that keeps aboutkeep_recent_tokens: walking back from the newest message until that many are counted, it cuts at the nearest message at or after that point that is no tool result and lies outside every tool exchange. Cut at a reply, its results stay after it, and the turn it is part of is split. With nothing to cut at, it keeps fromstart. After an overflow (overflowed), a last message over the budget alone is summarized too, as the turn’s earlier part, since sending it again would overflow again. - fit_
to_ model - The end of
text, a conversation another plugin summarizes for a modelspecin at mostsummary_tokens, cut to fit that model as rig’s summaries were fitted before compaction followed pi; the cut start says how many characters were left out. Returns the text and the output limit to ask for,Nonewhen the model’s limits are unknown. The room below a reserve of 16384 tokens, or half the input limit when that is more, is split: the answer gets at most half, and the text the rest at three characters a token, but never less than 16384 tokens or an eighth of the input limit, whichever is smaller; with no limit known, 400000 characters. - history
- Every record of the log
logofstoreafter 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
logofstoreholds; an empty one when there is none. It continues the log (its lineage and its number of changes), sosavecan tell whether the log moved on or the conversation is another. - load_
async loadfrom anAsyncStore, such as a database or IndexedDB: the log read once, and the blobs its records name.- map_
strings - Maps every string (keys included) of
valuethroughf; whether any changed. - merge_
split_ turn - One summary of a split turn: the
historysummary, without file lists a model wrote at its end, then its earlier part’sprefix. - no_
history - The history summary when a split turn’s earlier part has no messages of its own to summarize: the previous summary without its file lists, or a note that there is none.
- prepare_
compaction - What a compaction of
conversation, keeping aboutkeep_recent_tokens, summarizes, orNonewhen nothing would be, as when nothing was added since the last one (already_compacted);overflowedafter the provider refused a request as too long (find_cut_point), which is compacted for even then, as the summary before it may have gone in after its prompt. The earlier summaries (summarized_prefix) are never cut again: the new summary updates the newest one. - prepare_
compaction_ at - What a compaction of
conversationthat keeps from messagefirst_keptsummarizes: the messages after the earlier summaries and before it (or before the start of the turn it splits), and a split turn’s earlier part.Nonewhenfirst_keptreplaces no message after the earlier summaries, lies past the end, or would keep a tool result without its call. - read_
conversation - The conversation of
agent(the main agent whenNone, found from the session’s own log and the agent logs’ headers) of the session instore, folded from that agent’s log only, writing nothing. Returns the agent’s id and its conversation, with ids and made-times kept. - request_
estimate - The estimate of a request sent as it is: its messages and tools, by the
default
HeuristicTokenCounter. Its documents are not counted. - request_
tokens - The tokens of a request as pi-ai’s provider layer estimates them before it fits the output
limit: the
systemprompt and thetools(their definitions as JSON) and each message at 3.5 characters a token, or, with ananchor(the tokens reported for the reply at that index), that count plus an estimate of the messages after it. - rewrite
- Rewrites the session in
storethroughwith, as done byby, in place: every record stays where it is with its stamp, and every value in it goes throughwith(seeRewrite). Each log a record of which changed gets a fresh lineage and{t, by}added to its header’srewrites. - rewrite_
file - The file
nameoffilesthroughRewrite::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. - same_
log_ name - Whether the logs
aandbmay be one file on a disk that ignores case: their names differ only in letter case, as Unicode’s lower- or uppercase mapping sees it, so the final and medial sigma (ς,σ) match too. A file system’s own folding can still differ. - save
- Appends the unsaved changes of
conversationto the loglogofstore, starting it when there is none, and leaves the conversation with nothing unsaved. A torn last line of the log is first set aside, asWriter::opendoes. - save_
async saveto anAsyncStore: 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.- serialize_
conversation messagesas labeled text, so the model reads them rather than continues them. Thinking is left out, and tool results are cut to 2000 characters.- summarization_
request - A one-off summary request to
spec:system, thenpromptas the user’s message, with thereasoningeffort when the model takes it and no prompt-cache writes. Its output limit ismax_outputexactly when given, as a caller that fitted its own sets it, else the model’s output limit fitted by pi’s clamp to the room the input leaves (clamp_max_tokens). - summarized_
in_ log - The entries each compaction in the log
logofstorereplaced (summary_in), by the summary’s id, as they were just before it, read in one pass over the log. A summary named again keeps what it first replaced. A reset, the log’s value replaced by a whole other one, drops them all: nothing says the new value is the same conversation, so its summaries show nothing of the old one’s messages. - summarized_
prefix - How many of the first entries of
conversationare summaries (bysummary_author): what a new compaction builds on from itsSummaryStateinstead of reading it again, soprepare_compactionnever cuts them again. - summary_
author - Who writes a compaction’s summary: the author of its entry.
- summary_
in - The summary a compaction put in, when
changeis one: the id of the entry bysummary_authorin a splice that took messages out. A splice by the same author that keeps every message, as an earlier version’s clearing of old tool outputs did, is none. - summary_
request - The request for the history summary of
messagestospecwith thereasoningeffort, updatingprevious(the newest summary, sent with its file lists) when it holds anything, focused oninstructions. - summary_
state - The summary state the next compaction of
conversationbuilds on: the one its newest leading summary entry holds (summarized_prefix,SummaryState::read), or the state before any. - summary_
text - The summary in
response, a reply to the requestlabelnames, its text parts joined by newlines, or why it cannot become a session’s checkpoint: an errored reply, one cut at the output limit, one that calls a tool, or one with no text. - 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). - turn_
prefix_ request - The request for the summary of a split turn’s earlier part,
messages, tospecwith thereasoningeffort, focused oninstructions.