Memory

Mercury keeps a memory for each project. It is on by default. Facts you ask it to remember live in topic pages, your standing rules stay pinned in your own words, and a session can leave a note for the next one. You can read and correct the records in /memory.

The lineage: a history of the work

The lineage is a ledger of the project's sessions, with one entry per session. Mercury writes the entry from its own records and dates it from its clock. It records the session's number, the models it ran on and when they changed, the rules pinned, the facts retained or corrected, the files touched, how the session ended and the note it left.

The ledger lives in the Mercury config home outside the project tree (see On disk and in settings below), and Mercury never pushes or syncs it with your repository. In /memory, open Lineage to see the sessions, newest first. Each row shows the session, model, start and end, and whether it left a note. Press Enter on a session with a note to read it.

What the next session reads

A new session receives an entry page at its start, in its own section of the system prompt, ahead of your first message. It gives the session its number, how many sessions came before it, the models used before it, the count of pinned rules and whether another session of the same work is live. It includes the last note word for word. A first session reads "First session of this work; no record."

Every memory line the model reads carries a short evidence grade naming who stated it and its authority, distinguishing a rule you asked to pin from an unconfirmed note or a model-authored handoff note (which carries no authority over standby, wait or stop). When a project has no saved facts or pinned rules yet, its # Memory section is a single sentence naming the memory folder.

The entry page sits beside the memory the model already receives:

The library index: Each topic has one line with its fact count. Mercury builds this index; the facts stay on their pages.
The pinned shelf: Standing rules and preferences load in full, word for word. Pinning a rule (pin: true) requires your own asking words in chat (such as "pin that", "make this a rule", "keep that as a preference", "remember this as a rule", or a rule sentence opening with "always" or "never"); a casual remark or a bare "remember: <fact>" stores a regular fact and never pins a rule, and crewmates cannot pin rules. In a headless mercury run, "remember: <fact>" stores a regular fact and an asking form such as "pin this: <rule>" or "make this a rule: <rule>" pins the rule on your words and ends the run completed.
The facts that matter now: Source-linked required records ride in full outside the allowance for other matches. Within an allowance that is the smaller of memory.startLimit (4000 characters by default, adjustable by a thousand in /config under Memory at start, beyond the pins) and 600 × ⌈log2(1 + candidates)⌉ characters, Mercury ranks remaining candidates in tiers without calling a model: matches to your current prompt first, then matches to a source-linked continuation, and when neither channel matches, a fallback using the branch, changed files, files touched in earlier sessions and the last note left. Word and semantic rankings supply reciprocal-rank scores (1 / (60 + rank + 1)), historical matches and stale facts are deprioritized within each tier, and records pack by score / √chars. When a prompt- or continuation-matched fact does not fit in full, a shorter pointer rides asking the model to open it with Recall before the affected decision. One summary line above the # Memory at start block names the pins, facts, pending facts, pointers and earlier notes selected and what they matched, and states that Recall finds the rest.

Memory reaches the model at the start of a session and through Recall; nothing from memory is attached on each turn. Mercury rebuilds the front page when the library or its pinned rules change. Between changes, the same page loads into each chat, preserving the provider's prompt cache.

The note for the next session

When a session ends, Mercury asks the model for one orienting handoff note for the next session. A mercury run ends on the model's final answer and leaves no note; its ledger entry closes without one. When most of the note is already on record, the model is asked once more for what is new, and the reply is stored exactly as written, including its spacing, up to 8000 characters.

On the # Lineage entry page, a previous session that left no note reads "The last session (...) left no note.", while Recall (read: "ledger:<number>") prints "no note left". If the note cannot be stored, Mercury says so. The next session reads the last note at its start, and older notes remain available through Recall and /memory.

Search first, then open a record

Recall searches the topic pages, archived facts, pending facts and the lineage. A search returns at most twenty pointers (counting records and leaving a page's own heading or summary lines out of the count, and when cut at the maximum of twenty stating that the limit is at its ceiling instead of suggesting raising it), and the model opens a pointer to read the record. Each pointer has an id, a kind (fact, ruling, handoff or session), a short title and footnotes showing where it came from. Matching facts and rulings rank ahead of session handoff notes unless the query asks about a session or handoff.

Recall scores facts using hybrid retrieval: inflected word forms match (deploying finds deployed), a recent fact outranks an older one when the words tie, and a fact the model opened and then cited rises next time, with no model call and the pointers unchanged.

Alongside word matching, Recall ranks by meaning using a 118 MB BGE base embedding model (MIT licence, bundled in every release archive, built for its platform; on Linux and Windows a vectorised kernel answers a Recall by meaning in about a tenth of a second, and macOS Accelerate answers in a few hundredths) that runs in-process on your machine, so a query like "the laptop's clock" finds "the notebook's time zone" even when they share no words. Nothing leaves your machine and no account or paid model call is involved. The model loads when memory needs it (a build, a Retain or a query) and unloads after five idle minutes. Vectors are stored in memory/library/.index/embeddings.json (one row per fact, no fact text, stamped with the model that made it) and rebuilt from the markdown pages whenever missing or stale, so the markdown pages stay the single source of truth. Retain embeds new facts in the background off the UI thread. The meaning ranking joins the exact-text hits, word ranking and usage signal through reciprocal rank fusion (k = 60), and on a library without trained citation history Recall also refines the first five pointers by their cached semantic scores. In /config, the Memory recall ranking row (memory.embeddingModel) selects which embedding model is active (the shipped default or the path of a .gguf file); a model name or path that resolves nowhere, or an install without the embedding pack, leaves memory on word match only and says so on the front page.

For example, the model can search for a decision about tests, then open the matching record by its id. Reading a specific fact id (read: "seq:<number>") returns that single entry with its footnotes and breadcrumb; reading doc:<slug> opens the whole topic page. A session's note can be found by its words; a session can also be found by the files, outcome or ids in its ledger entry. Recall with read: "ledger:<number>" opens that session's entry and its note verbatim, or says "no note left". Reads include the footnotes too: the source session, the ruling a fact fell under and any record it replaced or was replaced by.

The model writes or changes memory only when you ask it to: a preference about how to work, a constraint you state, or a fact you name, in your words. Retain and Correct check your latest typed message for asking words (taking inflected endings such as "remembered" and "memorized": "remember", "memorise", "don't forget", "never forget", "from now on", "standing rule", "make this a rule", "pin this", "keep this", "keep this in mind", "bear in mind", "keep track of", "keep a note of", "note:", "note to self", "note this down", "make a note", "take a note", "write this down", "jot down", "log this", "save"/"add"/"store"/"put"/"record" something "to memory", "store this fact", "use the Retain tool", "remind me", "next time", "for future sessions", "for future reference", and equivalents in German, French, Spanish, Italian and Portuguese; while "don't remember", "do you remember" and asks withdrawn in the same message such as "no wait", "never mind", "scratch that" or "forget it" never pass) and refuse otherwise, quoting the message they read. A crewmate's Retain or Correct is refused always; a crewmate's finding goes in its report, and a decision or outcome belongs in the project's records. The memory tools are:

Retain: Saves one or more facts for future sessions. Each fact is searchable while waiting to be filed on its topic page, and a batch of distinct facts stores whole. Memory refuses a fact that contradicts a rule, fact or pending draft already on record about the same subject (such as a changed count, source or location for the same thing, a single-digit count included) and names the conflicting record, while a plain fact with a differing number about a different subject or a restatement of an existing fact is not refused. A pinned rule requires your asking words in chat and triggers maintenance immediately.
Recall: Searches for pointers or opens a single record (seq:<n>, pending:<ts>, ledger:<n>) or topic page (doc:<slug>) by its id. The model must open a pointer before relying on its contents.
Reflect: Answers a question from recalled records and cites them. An answer without citations is refused.
Correct: Replaces a wrong fact (op: "supersede"), amends its wording after a full read (op: "amend"), or retracts it (op: "retract"). A consolidated fact remains as history on the page. A superseded or amended pending draft (pending:<ts>) is replaced by a new draft that keeps the old words as its history until consolidation files the fact, while retracting a pending draft strikes it from the buffer before it reaches a page. Rules you asked to pin remain yours to change in /memory or on your confirmation card in chat.

The journal

The journal is off by default. When you turn on memory.journal, the model has a Journal tool for one brief entry per session, no longer than a sentence: where the project stands, what is queued and the constraints you set. A later call replaces that session's earlier entry. Mercury adds it to the journal when the session ends, dated from its own clock. A session that leaves no entry adds nothing.

This is separate from the note for the next session and from the project's facts. Project conventions belong in the instruction file; reusable facts belong in memory.

The journal lives beside the project's memory in the Mercury config home (see On disk and in settings below), never in the project tree, and Mercury does not push, sync or share the file. The next session does not read it unless you also turn on memory.journalOnEntryPage. If you do, its last entry becomes part of the request sent to that session's model provider. The same is true of any memory or note the model reads: keeping the file locally does not keep those words out of its requests.

Open Journal in /memory to see entries newest first, then press Enter to read one.

The model and the constitution

If you ask Mercury which model is running, it reads the live session record (mercury://seat). That record names the model serving the current turn, its effort level and permission mode, and any earlier model switches in this session with the time of each switch. An earlier answer or an instruction naming a model is not used in place of that record.

By default, switching models leaves a /model row in your transcript without sending a switch notice to the model. Turn on memory.tellEngineSwitch to send it one line naming the new model and the time. Resuming a session does not resend those display-only rows.

Every session starts with the same core operating rules (checked by /health under Mercury constitution), including headless runs, crewmates and the coordinator: the underlying model is an engine that can be swapped and Mercury was not built by its maker; follow your scope and preferences, use plain words, state material assumptions, ground project claims in inspected files and observed behaviour, consult current authoritative sources for external facts, and check material claims from memory, documentation and crewmate reports. The agent asks before unauthorised destructive, hard-to-reverse or externally visible actions and stops when you tell it to stop.

How the library stays small

A long topic page splits into smaller pages under one index line. Maintenance merges duplicates and files corrections, checking that every fact remains either live or in history before writing: a fact that restates one already on record becomes the current one with the older wording kept as its history, both verbatim, while a flipped rule or a changed name never merges. A fact's cited project paths are checked whole so only a path the project actually lost demotes it, and deep project paths have their memory folder key capped the same way as the transcript key while existing stores written under the longer key continue to be read in place. A fact not confirmed, cited or opened for about two months reads stale: not confirmed since <date> in Recall, at the start of a session and in the memory centre, comes back when cited or confirmed, and is never deleted; pinned rules never age. A fact unused for ninety days moves to an archive; Recall still finds it, and using it brings it back.

The pinned shelf limits how much text loads into each session, counted in characters, so any number of rules fits inside it. memory.pinnedLimit sets the limit (8000 characters by default, at least 1000), and the Pinned memory limit row in /config changes it. Above the limit, every rule still loads and Mercury tells you how much is pinned and where to trim it. Crewmates receive the index and the pinned rules whose scope applies to them.

A rule you asked to pin changes only on your word. Consolidation leaves it as said. When the model is asked to correct, replace or drop it in chat, it shows a confirmation card with the rule's stored words verbatim and Yes or No; under the sovereign permission mode the change runs without the card and /memory records that it was made under sovereign. You can also change or unpin it in /memory.

Open the memory centre

Enter /memory to open a popup over the chat. The project and its memory folder sit under the title, with a search line at the top. The overview lists facts and decisions, pinned rules, topics, lineage, journal, maintenance and instruction files. Each row shows a count, the newest date and its state. Old notes waiting to be taken in have a row while any remain.

Select a section and press Enter. The overview collapses to a breadcrumb while the list or page opens. Type on the overview to search topic pages, pinned rules, recent facts and project instruction files (MERCURY.md, AGENTS.md, MERCURY.local.md, where Enter opens the file at the matching line and e opens it in your editor), or type inside a section to filter that list. Topic pages, session notes and journal entries wrap to the popup; ↑ and ↓ scroll longer pages.

Open a fact to see why it matched, how often it was offered, opened and cited, and its place on the topic page. c corrects it and keeps the old fact as history, x retires it (pressing x asks for confirmation first and pressing x again retires it), p pins it word for word and u unpins it. Esc goes back one level and closes the popup from the overview; clicking outside closes it too.

/memory files opens the instruction files picker in the same popup. /memory stats prints the numbers, /memory enqueue runs maintenance now, and /health shows the index size and pinned shelf's fill. /chronicle is an alias of /memory.

/memory page draws the library as a page in your browser: every fact is a node with its first words, pinned rules and stale facts are marked, each node shows how often it was offered, opened and cited, and the links are edges showing what a fact supersedes, the ruling it was made under and the session that made it. Clicking a node opens its record word for word. The page reads the library and writes nothing back; it is kept as a versioned sample each time you open it (requires Samples to be enabled).

On disk and in settings

All three records live under the Mercury config home, outside your project:

The library: <config-home>/projects/<project>/memory/library/, with topic pages, archives, pending facts and the index.
The lineage: <config-home>/projects/<project>/lineage/.
The journal: <config-home>/projects/<project>/journal/journal.md.

In addition to memory.startLimit, memory.pinnedLimit and memory.embeddingModel above, the settings are:

memory.enabled: On by default. Set it to false to stop memory loading, saving and lookup. The memory tools and Journal leave the tool list.
memory.directory: Chooses a custom memory directory. Checked-in project settings cannot choose it.
memory.journal: Off by default. true adds the Journal tool and writes its one-line entry when the session ends.
memory.journalOnEntryPage: Off by default. true gives the next session the last journal entry, which then travels to its model provider with the request.
memory.tellEngineSwitch: Off by default. true tells the model once when its model changes.
records.retentionDays: 0 stops new transcript and lineage writing and the request for a note. Existing records stay on disk, and the entry page says that no record of this work is kept.

Memory surfaces

/memory and /console: The memory & goals commands in /help (/console opens a side panel where you can ask a quick question about the current conversation without adding turns to the main chat; /orient is listed under config & setup).
/submodels: Picks the model and effort level for /console and /advise. Tab moves between the CONSOLE and ADVISOR containers, Enter pins a row, and e sets the container's own effort.

The Console's model

The Console (/console) selects its model in this order: environment pin, saved pick, then unset.

Environment pin: MERCURY_CONSOLE_MODEL takes precedence over a saved pick.
Saved pick: /submodels saves the pick across sessions and lists the full catalogue from the main /model picker across every connected provider or gateway, with no tier, serve check or family policy applied.
Unset: No default is derived. A question to an unpinned Console spends no model call, and the reply is the line use /submodels to pin one of the available model catalogues.
Row states: A row is selectable, signed out, or refused with the catalogue's own reason. Activating a signed-out row routes to the family's sign-in, and the pick lands on return.
Effort: e on a model row opens the effort strip with the levels that model supports under the Console's own call context. Enter saves the level for the Console, and Esc keeps the prior one. The row reads the chosen level, or the model default when none is chosen.

The Console's identity and role go in the question's framing and the system prompt stays unchanged, so a pick identical to the main model keeps the cache-hit prefix.

The advisor

The advisor is a second model of any family, local models included, that reads the working model's conversation and writes it one short note as a muted [advisor] row. It advises only the main chat. It has its own memory and compaction clock, and the working model can ask it a question through AskAdvisor while it is enabled.

Each new chat starts with its advisor off. Both that chat's switch and the master setting must be on before it can receive notes.

Model: /submodels → ADVISOR picks it. With no model pinned, the advisor stays silent. MERCURY_ADVISOR_MODEL pins it from the environment and locks the picker.
This chat: /advise on enables it and /advise off disables it. /advise alone reports its state, model and interval (and notes when /config → Advisor must be enabled). A model switch keeps the setting, and a resumed chat remembers it.
Every chat: /config → Advisor is the master switch. Turning it off stops advice everywhere without changing the individual chats' choices. Turning it back on restores eligibility only for chats whose own switch is on.
Cadence: /config → Advisor interval sets minutes: 2, 5, 10, 20, 30, 45 or 60, with 10 the default. Once an interval has passed, a note waits for the next turn or tool-round boundary with new conversation to read. An idle chat triggers no call.
Headless: mercury run --advise "<prompt>" enables the advisor for that run; its config home's master setting still applies.
Spend: The advisor's calls have their own line on /usage.

An advisor call uses the selected model's own output ceiling and has no separate timeout. Tool input keys are kept while long string values are shortened individually, tool results reach the advisor whole within the 60,000-character digest budget, and any shortened text or omitted earlier rows carry an explicit marker (… [N more characters not shown] or [N earlier rows; M characters not shown]); the advisor never raises a correction based on what might lie past a marker or outside the shown conversation window, and treats its own earlier notes as hypotheses to recheck against visible results. An empty answer is requested once more. If the advisor still returns no text, the chat shows a muted [advisor] row saying so.

Sessions · Workshop · Models and effort · Workspace trust and permissions