Skip to main content

Crate rig_memory

Crate rig_memory 

Source
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 format FORMAT. Reading is strict: a session of another format, or that does not read whole, is refused and nothing is written. load_async and save_async keep a conversation in any AsyncStore, 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 (feature fs): where a session is kept; Files, DirFiles and PluginFiles for named files on their own. Every Store is an AsyncStore, 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-sqlite and rig-postgres keep sessions in a database with their memory feature, and conformance (feature test-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 AsyncStore keeps, 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 run check_store on 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 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: the reported tokens plus an estimate of the messages after it.
CompactionPreparation
A compaction ready to summarize (prepare_compaction).
CompactionSettings
When compaction runs and how much it keeps: [compaction] in settings.
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.
FileLists
The files a compaction lists after its summary.
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.
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, 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.
SummaryState
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_summary writes it and read reads it back.
Unreadable
A log Session::read_lenient could not read.
Writer
A running session’s logs, appended to as it runs. 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§

LogRecord
One record of a log, as history reads it.
LogWriteError
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.
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.
SummaryFailure
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_name allows: 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§

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 /).

Functions§

already_compacted
Whether conversation ends 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 state in place of replaces, the first messages of conversation as a compaction read them (CompactionPreparation::replaces), earlier summaries included: one user entry by summary_author, in one splice, which is the compaction’s whole record. Messages added after them stay. None, changing nothing, when replaces is 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 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_log_name
Refuses name as a log name: check_name, in one part.
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.
check_new_log_name
Refuses name for a new log: check_log_name, a name longer than MAX_NEW_LOG_NAME bytes, or SESSION in 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 under check_log_name.
clamp_max_tokens
max_tokens fitted into spec’s context window after an input of input_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 about keep_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 from start. 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 model spec in at most summary_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, None when 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 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.
map_strings
Maps every string (keys included) of value through f; whether any changed.
merge_split_turn
One summary of a split turn: the history summary, without file lists a model wrote at its end, then its earlier part’s prefix.
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 about keep_recent_tokens, summarizes, or None when nothing would be, as when nothing was added since the last one (already_compacted); overflowed after 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 conversation that keeps from message first_kept summarizes: 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. None when first_kept replaces 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 when None, found from the session’s own log and the agent logs’ headers) 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.
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 system prompt and the tools (their definitions as JSON) and each message at 3.5 characters a token, or, with an anchor (the tokens reported for the reply at that index), that count plus an estimate of the messages after it.
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.
same_log_name
Whether the logs a and b may 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 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.
serialize_conversation
messages as 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, then prompt as the user’s message, with the reasoning effort when the model takes it and no prompt-cache writes. Its output limit is max_output exactly 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 log of store replaced (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 conversation are summaries (by summary_author): what a new compaction builds on from its SummaryState instead of reading it again, so prepare_compaction never 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 change is one: the id of the entry by summary_author in 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 messages to spec with the reasoning effort, updating previous (the newest summary, sent with its file lists) when it holds anything, focused on instructions.
summary_state
The summary state the next compaction of conversation builds 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 request label names, 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, to spec with the reasoning effort, focused on instructions.