Manage memories

A memory is a durable note your agents can draw on — a convention, a gotcha, a decision worth remembering. Memories are scoped, and the workspace and project ones travel with your synced repository so they are versioned alongside your workflows and scripts.

The Memory page lives under Intelligence → Memory. Its List view holds your memories and one editor both creates and edits them; Governance sets the per-scope review policy, and each memory’s versions and snapshots live in its detail drawer. Proposed memories are decided elsewhere — in the one decision queue at Inbox → Decisions (see Work the inbox).

Write a memory

1. Open Intelligence → Memory.
2. Click New memory. An editor opens with a full Markdown editor — write the note with headings, lists and code as you would any Markdown.
3. Choose the memory’s scope:
   • Workspace — shared across the workspace.
   • Project — attached to one project (pick the project below).
   • Personal — yours alone.
4. Choose the memory’s kind (semantic, episodic, procedural, profile preference or scratchpad).
5. Click Save.

Edit a memory in place

The same editor edits an existing memory — there is no separate edit form.

1. On the List tab, click a memory to open its detail drawer.
2. Click Edit. The editor reopens, seeded with that memory’s text, scope and kind.
3. Change the text or fields and click Save. The change is written back to the same memory in place and a new version is recorded.

Note

Editing the body never changes the memory’s pinned or archived state — Pin and Archive stay separate actions in the detail drawer.

Review proposed memories

Your agents and the workspace’s internal LLM can propose memories — a new note, or an edit to an existing one. Proposals do not change anything on their own; they wait for a person to decide. They are decided in the Inbox, in the one decision queue that also carries agent approvals, skill proposals and governor proposals — not on the memory page itself.

1. Open Inbox → Decisions. Each pending memory item shows its action, source, proposed scope and kind, and the reason for the proposal.
2. When a proposal edits an existing memory, the item shows a side-by-side Current vs Proposed diff so you can see exactly what changes.
3. Click Approve to apply the proposal (it creates or updates the memory) or Reject to discard it.

Note

The Generate outcome candidates button mines your recent task outcomes into fresh review items, so you can curate memories from work that already happened instead of writing them from scratch. The new items land in this same inbox for you to approve or reject.

Review closeout memories

When a task finishes, SupaCloud proposes a short closeout memory — a pointer at the work it just did. These land in Inbox → Decisions as legible cards. Nothing is written to durable memory until you approve.

1. Open Inbox → Decisions.
2. Turn on Show closeouts only to filter the queue to closeout proposals (newest completion first). Each carries a Closeout: Standard badge.
3. A card shows the task’s Completion facts — its pull request, branch and cost — and the proposed memory text.
4. Approve to file the closeout memory (and, when the task is linked to an issue, close or transition that issue in the same step), or Reject to discard it.

Open any closeout memory’s detail drawer to see two extra panels: Completion facts (branch / PR / cost) and Context usage (which tasks saw this memory, linking back to each task).

A comprehensive retro (badge Closeout: Comprehensive) merges several finished tasks into one proposed lesson. Its evidence carries, per merged task, what was measured beside what the agent wrote: the run’s terminal status, which MCP tools it called, which MCP tools it had available, and its PR state. The judge is told that a measurement outranks a claim, that a later run may refute an earlier one, and that an unsuccessful run contributes context but never a rule. A disagreement the measurements cannot settle is left out of the proposed text and listed in the evidence instead; the proposal’s title then ends in (N unresolved disagreements) so you can decide it rather than the judge. The review card lists those disagreements above the proposed text and, below it, what was measured per merged run: its status, the MCP tools it called, and how many it had (recorded at launch, or resolved now against the current profile for older runs). A deterministic guard adds a disagreement of its own when the availability claims the retro declares contradict the measured lists; a text that names tools without declaring a claim gets a muted guard note instead of a banner. The retro request also accepts explicit task ids, so a specific set of runs can be synthesised after newer outcomes exist.

Govern memories per scope

A workspace owner or admin sets, per scope, how new memories are governed in the Governance view of Intelligence → Memory:

• On new memory — Require review (the safe default: proposals queue for a human) or Auto-publish (new memories of that scope go live immediately).
• Retention (days) — how long memories of that scope are kept before they may be archived; 0 keeps them forever.

Set this independently for Workspace, Project and Personal scopes.

When a scope requires review, every new memory of that scope is queued for a decision instead of going live — whether you write it in the editor or an agent proposes it. Editing a live memory of a require-review scope likewise queues the change; the live memory is untouched until a person approves it.

Semantic retrieval and embeddings

Retrieval ranks memories by meaning as well as by words. The embedder that turns memories and prompts into vectors is resolved from what your workspace brings — an API key for OpenAI, Google, Qwen or OpenRouter — and configured under Settings → Models → Memory embeddings: pick a provider (or leave it on Automatic, which takes the first provider with a key); with a provider pinned you can also override the model id (a model without a provider is refused, not silently ignored). The card shows what is in force; a workspace without a usable key keeps a built-in word-bucket fallback, so retrieval never stops working — it just gains no semantics.

Existing memories are re-indexed in the background after you set or change the model (a fresh memory is on the fallback until the next sweep, a few minutes at most). The memory block an agent receives is picked for breadth: near-duplicate memories no longer crowd out the other useful ones.

The card also says what the inventory holds — how many live memories carry a vector under the model in force — and shows the background re-index’s error when it keeps failing (a wrong model id, a revoked key), so “in force” is never a claim the store does not back.

Automatic resolution uses only what the workspace brings: a key stored under Credentials for the workspace or its organisation. A key configured on the server itself counts only when you pin that provider explicitly, so one server key can never silently buy embeddings for every workspace of the instance. Embedding calls are metered like every other model call: they appear on the workspace’s monthly spend (under system:embedding), and a workspace whose hard-stop budget is exhausted stays on the built-in fallback until the month turns or the cap is raised.

Note

An Anthropic key cannot serve embeddings (there is no embeddings API), and a subscription sign-in is not an API key — that includes the Gemini sign-in your agents use, which Google’s API refuses for server-side calls. Add an API key for one of the four providers under Credentials to enable real embeddings. An OpenRouter key defaults to qwen/qwen3-embedding-8b and can pin any of OpenRouter’s embedding models by id, including its free-tier ones (which carry rate limits and OpenRouter’s free-route data terms).

Retired memories

Approving a replacement (supersede) or a merge in the review inbox retires the old memory instead of deleting it: it is stamped no longer valid, linked to its successor, and stays readable on the List tab and in its detail drawer — but agents stop receiving it. Nothing about the history is lost, and the decision is auditable.

An archived memory can come back: open it (turn on Show archived on the List tab) and press Unarchive in the detail drawer. The memory is re-embedded on the way back, so it returns into the live vector space and is found and compared like any other memory; the version history records the step.

Let agents correct the record

An agent can propose to revise or retract an existing memory through two tools, memory.update and memory.supersede. Both write into the review inbox, never into the store, and both are off by default: enable allow_self_correction in the agent profile’s memory policy (Settings → Profiles, Raw view) for the profiles that may argue with the inventory. A read-only pinned session (an auditor, a concept planner) can never use them.

The end-of-task memory proposal also reads the nearest existing memories first and decides whether a run adds a new fact, revises one, replaces one, or is already covered — a revision lands in the inbox against exactly that memory, and the Health view’s measurement panel counts the covered runs.

Keep the inventory tidy

Two things maintain the inventory for you, both through the same inbox:

• A daily consolidation run turns duplicate and contradiction findings into merge / resolve conflict proposals — at most ten per day, each pair asked only once (a rejected proposal is a “keep both” that is never repeated), and only for pairs measured with real embeddings. The panel hints at a duplicate from 70 % similarity; a merge is proposed automatically only from 90 %. A contradiction is checked first, so two memories that disagree are never proposed for a merge.
• Check now — a workspace admin can run the whole hygiene pass on the spot from the Health view: re-index stale vectors, apply the retention policy, and file the proposals. The result line says what each step did. The same pass also runs automatically right after a re-index that upgraded vectors.
• The reflection task — armed in the Governance view — is a scheduled task under its own agent profile (memory-reflector, created when you first arm it) that reads the recent memories and proposes merges, retractions and higher-level lessons. Choose the agent on the first arm and a daily, weekly or monthly cadence; pausing keeps the profile so you can tune it like any other.

Memories an agent cited in a run that succeeded gain standing (and their retention window restarts); ones cited in a run that failed lose some; memories that were merely injected are left alone.

Inspect versions and snapshots

Open a memory’s detail drawer (click it on the List tab) to see everything about a single memory in one place:

• Its scope, kind, source, importance, salience and when it was last used and updated.
• Its links to related memories, entities and runs.
• Its version history — every saved revision of the memory, newest first.
• A snapshots inspector (expandable) showing the context snapshots a past task or council run selected — useful to understand why a memory was used.

Pin, archive and edit the memory from the drawer’s footer.

How memories travel with repo-sync

Workspace and project memories are part of repo-sync: they serialise into the synced repository (under memories/), alongside your workflows, scripts, resources and apps, and sync in both directions like any other repo-managed item. A memory edited in the repository flows back into SupaCloud on pull, and one written in the UI is written out on push.

Note

Personal memories are never serialised to the repository — they stay private to you. Only workspace- and project-scoped memories are shared and synced.

See also

• Runs and tasks
• Approve or reject agent actions