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_WORDSwords), one cheap Hindsight recall (budget: low, no LLM call) over theprojectandglobalscopes, with the message as the query, capped atRECALL_TIMEOUT. What it finds and the context has not shown since its last compaction opens the run as anultron.memorycustom 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 forPAUSE. 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_apisMemoryService::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 canmemory.invalidatea wrong fact ormemory.forgeta 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_apismemory::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 mostMAX_FACTSdurable 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 (withinCLOSE_TIMEOUT), or in the background afterIDLE_RETAINof 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 tomemory/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 globalhindsightUrlsetting): the default URL alone is a guess, and a test’s empty home must not reach a developer’s real memory bank.
Structs§
- Auto
Memory - 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
sourcereplace the claimdocument_id, which records that it covers the session up tothrough. - 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_AFTERfailed 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 insource, and its text is at most [ENTRY_CHARS]; the rest are dropped.Nonewhen the reply is not JSON at all. - keep
- Distils and stores
keepon a thread, waiting at mostwaitfor its outcome; pastwaitthe work is aborted (nothing is written after that) and the outcome isTIMEOUT. Every outcome butUnchangedis logged underagent_dir.Nonewhen 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
recalledholds;Nonewhen 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
entrieshold 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.Nonewith fewer thanTAIL_MIN_MESSAGESuser messages. - shown
- What the context already shows: the
ultron.memorymessages on the branchentriessince 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;
Nonewhen the tail is not worth keeping. - worth_
recalling - Whether a user message is worth a recall: not a slash command, and at least
MIN_WORDSwords.