Skip to main content

Module auto_memory

Module auto_memory 

Source
Expand description

Automatic memory (Rust-only; in TypeScript, and with it off, memory is recalled and kept only when the model calls memory.prepare / memory.propose, which it rarely does): the session recalls before each user message and keeps its compaction summaries, and what no summary covered when it closes.

  • Recall: before a root run of a user message (not a continuation, a custom message or a slash command, and of at least MIN_WORDS words), one cheap Hindsight recall (budget: low, no LLM call) over the project and global scopes, with the message as the query, capped at RECALL_TIMEOUT. What it finds and the context has not shown since its last compaction opens the run as an ultron.memory custom message: on the branch, so the request stays a prefix of the next one (the prompt cache holds) and a replay sends the same bytes; never in the system prompt. A failed or slow recall adds nothing and pauses recall for PAUSE. The first such message of a context (at its start and after each compaction) also carries the project’s brief, a Hindsight mental model of the project and global memories (kernel_apis MemoryService::project_digest), and the user’s brief, one written from every project’s memories (MemoryService::user_brief). Each recalled entry names its id, so the model can memory.invalidate a wrong fact or memory.forget a wrong memory. A memory whose evidence quoted a file that no longer holds the quote is marked stale (autolith’s check, with no model call: kernel_apis memory::staleness).
  • Retain: what a session keeps is distilled, not transcribed. A completed compaction’s summary, and the part of a session no compaction summarized (the tail, session_tail: the user’s messages and the agent’s final replies), go to one side request that answers with at most MAX_FACTS durable facts, each quoted verbatim from its source (distill); the facts replace the session’s claim for that summary or tail, marked with the entry it covers. A tail is kept as the session closes (within CLOSE_TIMEOUT), or in the background after IDLE_RETAIN of quiet; a summary in the background. A source its claim already covers costs no model call. The memories the context showed for it are listed to the model, and the ones it relied on are re-confirmed (MemoryService::confirm_recalled). Nothing is stored when no fact survives, and a keep that holds a secret is dropped by the write gate. Every attempt’s outcome goes to memory/auto-retain.log, and while the session is open to the user as one muted line (Outcome).
  • Both are on when the settings say (memory.autoRecall, memory.autoRetain), else when the Hindsight server is set explicitly (ULTRON_HINDSIGHT_URL, or the global hindsightUrl setting): the default URL alone is a guess, and a test’s empty home must not reach a developer’s real memory bank.

Structs§

AutoMemory
Whether automatic recall and retain are on for a session, and when recall may run again.
Distilled
The facts a distill reply holds, each checked against its source.
Keep
One keep: the facts distilled from source replace the claim document_id, which records that it covers the session up to through.
Recalled
One recall: the memories found and, at a context’s first, the briefs with content (the project’s, then the user’s; each {id, content, refreshedAt}).
Shown
What the context shows since its last compaction: the ids of the recalled memories, and whether the briefs.
Tail
The part of a session no compaction summarized, as distilled when the session closes (tail_keep).

Enums§

Outcome
How a keep ended.

Constants§

CLOSE_TIMEOUT
How long closing waits for a keep: the worker waits 10 s to exit, and a keep may not hold it past 8 s.
IDLE_RETAIN
How long a session stays quiet before its tail is distilled without waiting for it to close: a durable session may stay open for days, and most never compact.
MAX_FACTS
The most facts one keep stores.
MIN_WORDS
A message shorter than this many words recalls nothing (“yes”, “go on”).
PAUSE
After PAUSE_AFTER failed or slow recalls in a row, how long recall is skipped (a server that is down costs no turn its timeout): the memory clients’ own outage pause.
PAUSE_AFTER
Failed or slow recalls in a row that pause recall: one slow answer is load, not an outage. A memory server’s outage: after this many calls in a row without an answer (or, for automatic recall, too slow to wait for), calls stop for OUTAGE_PAUSE, so a server that is down costs a session no timeouts. One threshold for the memorantado client and automatic recall alike (session_core::auto_memory).
RECALL_LIMIT
The most memories one message opens with.
RECALL_TIMEOUT
How long a run waits for its recall.
TAIL_MIN_MESSAGES
User messages a tail needs before it is kept: a one-question session is rarely worth remembering.

Functions§

distill
The facts in a distill reply ({"facts": [{text, quote}], "used": [ids]}, fenced or not). A fact is kept only if its quote is at least [MIN_QUOTE_CHARS] and found verbatim in source, and its text is at most [ENTRY_CHARS]; the rest are dropped. None when the reply is not JSON at all.
keep
Distils and stores keep on a thread, waiting at most wait for its outcome; past wait the work is aborted (nothing is written after that) and the outcome is TIMEOUT. Every outcome but Unchanged is logged under agent_dir. None when the session has no memory service (nothing is kept, nothing logged).
outcome_message
The display-only message that tells the user a keep’s outcome (never journaled, so never in the model’s context).
paused_message
The notice that memory is paused (memorantado, the backend, did not answer at start: memorantado::resolve), as the displayed message that opens the session’s first root turn.
recall_message
The custom message that opens a run with what recalled holds; None when it holds nothing.
recalled_since_compaction
The memories the context showed since its last compaction: their ids, and their messages’ text.
session_tail
What the branch entries hold after their last compaction: the user’s messages and the agent’s final replies (an assistant message that ended its run, not one that called a tool), oldest first; never tool output, custom messages (recalled memory among them) or thinking. None with fewer than TAIL_MIN_MESSAGES user messages.
shown
What the context already shows: the ultron.memory messages on the branch entries since its last compaction (a compaction summarizes them away, so they may be shown again).
summary_keep
The keep of the newest compaction’s summary, with the memories the segment it summarized showed.
tail_keep
The keep of a session’s tail as it closes or goes quiet; None when the tail is not worth keeping.
worth_recalling
Whether a user message is worth a recall: not a slash command, and at least MIN_WORDS words.