Helm and agent communication

Helm memory

Read, pin, edit, approve and delete the short lessons that Helm keeps across chats, and read the log of changes.

On this page

Purpose

Helm keeps short lessons between chats. Each lesson is one memory: a preference, a rule or a fact that Helm should still know in a later chat. Helm recalls its memories by itself, so you do not repeat them. The Memory panel shows these memories. Use it to check what Helm remembers, to protect a memory, to fix a memory, to confirm a sensitive memory, or to delete a memory.

Where to find it

Open Helm. Click the Memory button in the Helm header. It is an icon button (a small archive box, tooltip "Memory"). It sits between the History button and the dock button. The Memory button shows only while Helm memory is on. To turn memory on or off, see Settings → Helm → Memory in Settings: Helm. For Helm itself, see Helm.

What you see

The panel opens as a small window under the Memory button. It has two views: the memory list and the audit list.

Memory list view

  • Memory header with a number. The number counts all memories, including the ones that need confirmation.
  • Needs confirmation header with a number. It shows only when at least one memory is waiting. The rows of those memories are under it.
  • The memory rows. Each row has three parts, from left to right:
    • Badges and an icon:
      • A kind badge: App lesson, Preference, Convention, Tool lesson, Strategy or Constraint.
      • A scope badge: Global or Project. Hover the Project badge to see "Project: " and the project name.
      • A status badge: Active or Pending.
      • A pin icon (tooltip "Pinned memory"). It shows only on a pinned memory.
    • The memory text. It shows two lines at most. Click the text to open the full text. Click it again to close it. Tooltip: "Expand this record" or "Collapse this record".
    • The row controls. They depend on the status. See the list below.
  • Dream now button (tooltip "Sweep chats for lessons and consolidate").
  • Show audit button (tooltip "Show recent memory changes").
  • A line of text under the buttons after a sweep. See "States and messages".

Row controls

  • An Active memory has three controls:
    • A switch (tooltip "Pin to protect from pruning", or "Unpin this memory" when pinned).
    • An edit icon button (tooltip "Edit this memory").
    • A trash icon button (tooltip "Delete this memory").
  • A Pending memory has two buttons: Approve (tooltip "Approve and keep this memory") and Reject (tooltip "Reject and discard this memory").
  • A memory that you edit shows an edit field in place of its text. See "Edit a memory".

Audit list view

  • Audit header with a number. The number counts the entries.
  • Show memories button (tooltip "Return to memory records").
  • The entries, newest first. Each entry has a badge with the kind of change (for example "create", "update", "delete", "consolidate", "rollback" or "resolve"), a short detail text, and the time on the right. The time reads "just now", "5m ago", "3h ago" or "2d ago". Hover the time to see the full date and time.
  • Roll back button (tooltip "Undo the last consolidation").

How to

Open the Memory panel

Before you start, Helm memory must be on and Helm must be open.

  1. Click the Memory button in the Helm header.

Result: The panel opens under the button with the Memory header. Click the button again to close it.

Read a long memory

  1. Open the Memory panel.
  2. Click the text of a memory row.

Result: The row shows the full text. Click the text again to fold it to two lines.

Pin a memory

Before you start, the memory must be Active. A Pending memory has no pin switch.

  1. Open the Memory panel.
  2. Click the pin switch on the memory row (tooltip "Pin to protect from pruning").

Result: A pin icon shows in the badges of the row. Click the same switch again to unpin.

Edit a memory

Before you start, the memory must be Active. A Pending memory has no edit button.

  1. Open the Memory panel.
  2. Click the edit icon button on the memory row (tooltip "Edit this memory").
  3. Change the text in the Edit memory field.
  4. Click Save.

Result: The row shows the new text. Orkestra trims spaces at the start and the end of the text. Click Cancel (tooltip "Discard this edit") instead of Save to keep the old text. If the new text looks sensitive, Orkestra saves it as Pending. The row then moves to Needs confirmation.

Delete a memory

  1. Open the Memory panel.
  2. Click the trash icon button on the memory row (tooltip "Delete this memory").
  3. Click Delete in the Delete memory dialog.

Result: The memory leaves the list. Helm no longer recalls it. Click Cancel in the dialog to keep the memory.

Approve a memory that needs confirmation

  1. Open the Memory panel.
  2. Find the row under Needs confirmation.
  3. Click Approve on the row.

Result: The memory becomes Active. It moves to the main list.

Reject a memory that needs confirmation

  1. Open the Memory panel.
  2. Find the row under Needs confirmation.
  3. Click Reject on the row.

Result: The memory is deleted at once. No dialog asks you first.

Add a memory through Helm

The Memory panel has no button to add a memory. Helm adds memories itself. You can ask Helm to remember something.

  1. Click the message field in Helm (hint "Ask Helm to do something…").
  2. Type a request, for example "Remember that I prefer short commit messages".
  3. Click Send.
  4. Open the Memory panel.

Result: If Helm saves the lesson, a new row shows in the list with the scope that Helm chose. Helm decides by itself what is worth saving. A request does not force it.

Run a memory sweep

  1. Open the Memory panel.
  2. Click Dream now.

Result: Helm looks through your chats for new lessons and tidies the memory. The button reads Dreaming… while it works. A summary line shows when it ends.

Read the audit list

  1. Open the Memory panel.
  2. Click Show audit.

Result: The panel shows the audit list. Click Show memories to go back.

Roll back the last consolidation

Before you start, open the audit list with Show audit.

  1. Click Roll back.
  2. Click Roll back in the Roll back consolidation dialog.

Result: Orkestra restores the memories to the state before the last consolidation. Click Cancel in the dialog to keep the current memories.

States and messages

  • Empty list: "No memories yet. Helm distills lessons here as you work." The same text shows for a moment while the list loads. There is no separate loading text.
  • Empty audit list: "No audit entries."
  • List error: an error line above the list. Examples: "Memory refresh failed." and "memory service unavailable".
  • Row error: an error under the Save and Cancel buttons. The editor stays open with your text. Examples:
    • "rejected: empty" (the text is empty).
    • "rejected: secret" (the text looks like a key, a token or a secret).
    • "rejected: raw-log" (the text looks like pasted terminal output).
    • "Invalid memory update request" (the text is too long).
    • "Memory action failed." (any other failure).
  • Busy control: a small working dot shows in the button that you pressed. Only that control is disabled.
  • Sweep messages under the buttons:
    • "Dream cycle is running…" while it works.
    • "Dream cycle is already in progress." if a sweep runs already.
    • "Dream cycle did not start because memory is disabled or another sweep is in progress."
    • A count line, for example "2 dreamed · 0 deferred · 0 failed · consolidation 12→10". It can also show "already dreamed" and "skipped" counts. "dreamed" is the number of chats that the sweep read. "deferred" chats wait for a later sweep. "failed" chats had an error. The last part shows the number of memories before and after the tidy-up.
    • An error line "Consolidation failed: " and a reason, if the tidy-up step fails.
  • Audit error: an error line above the audit list. Roll back can show "no-snapshot" when there is no earlier state to restore.
  • Delete dialog text: "Delete this <kind> memory? This cannot be undone." The kind is the kind label, for example "Preference".
  • Roll back dialog text: "Restore memory to the state before the last consolidation pass?"

Limits and tips

  • The panel has no search box, no filter, no sort control and no Add button. The list shows every memory from every scope and every project. Newest created first. The memories that need confirmation show first, in their own section.
  • A row shows no date. Only the audit list shows times.
  • The panel loads the list when it opens and after each action in it. It does not refresh by itself. Close and open it again to see memories that Helm saved in the meantime.
  • You cannot change the kind or the scope of a memory in the panel. You can change only the text and the pin.
  • Memory scope: a Global memory applies in every project. A Project memory applies only in chats of that project. If the project no longer exists, the Project badge tooltip shows the internal id of the project.
  • Orkestra checks every text before it saves it. It rejects keys, tokens and pasted logs. It holds credential-like text as Pending until you approve it.
  • Helm recalls a limited amount of text. Pinned memories are always included first.
  • Click outside the panel or press Escape to close it.
  • Settings → Helm → Memory controls memory itself: Enable Helm memory, Auto-extract lessons after turns, the automatic sweep and its cadence, and a Start now action. See Settings: Helm. When memory is off, the Memory button is hidden. Turning memory off does not delete saved memories.
  • Helm — the assistant that saves and recalls the memories.
  • Settings: Helm — turn memory on or off, and set the automatic sweep.