Memory & Decisions

How an agent remembers chat, prior runs, and past decisions — and how to control what carries over.

Overview

An agent remembers things in three independent ways. They can be used together or separately.

Mechanism	What it carries	Cost per run
Active Memory	Full conversation transcript (chat + prior runs)	Grows over time
Review Previous Decisions	Structured summary of the last ~5 decision cards	Low — one tool call
Re-examination	A new full run that updates conviction on a specific prior decision	One full run

Active Memory

Active Memory is a per-agent toggle (off by default) that makes chat and scheduled runs share the same Claude session via --resume.

When off (default)

Every run is a clean slate. The agent only sees:

• System prompt / SKILL.md
• Default prompt for this run
• Team roster (for leads)
• MCP tools it can call

No chat history and no prior run outputs carry into context. The agent has no recollection of previous work beyond what you pass in the prompt.

When on

Everything above plus the shared Claude session, which accumulates:

• Every chat message with this agent
• Every scheduled run’s transcript (prompts, tool calls, replies)
• Accumulates until you click Reset

How the shared session flows

[chat]      user sends a message
              ↓ Claude runs with --resume <sessionId>
              ↓ writes new sessionId back to ChatSession

[heartbeat] scheduled or manual run fires
              ↓ reads ChatSession.claudeSessionId
              ↓ spawns with --resume <sessionId> + defaultPrompt
              ↓ Claude sees: skill + full history + new prompt
              ↓ writes new sessionId back to ChatSession

[chat]      next message picks up where the run left off

Under the hood, there’s one ChatSession row per agent. Both chat and heartbeat read claudeSessionId from it, and both write the latest session id back after their run completes. Disabling the toggle leaves the data in place but stops using it.

Enabling memory on an agent is treated as a fresh start — same semantics as clicking Reset. Re-enabling after a disable also starts fresh, so stale context doesn’t resurface unexpectedly.

What memory can’t do

Memory preserves context, not control. If you tell the agent in chat “next run just say hi”, the agent remembers — but when the heartbeat fires, it receives its normal scheduled prompt (e.g. “analyze BTC”) and follows that. Most recent explicit instructions win. If you need to steer the next run specifically, change the default prompt or invoke manually with an override.

Review Previous Decisions

Independent of Active Memory. When the Review Previous Decisions toggle is on, the agent calls mcp__orchestrator__get_my_decisions at the start of each run. This fetches the last ~5 structured result cards — the agent’s own prior outputs — without carrying full transcripts.

Use this when:

• You want the agent to be aware of what it decided recently, but
• You don’t want the context cost of full transcripts to grow over time, and
• The signal you care about is the decision, not the reasoning that got there.

The agent sees clean entries like 2d ago · WAIT · range unresolved rather than re-reading its own conversations.

Re-examination

A re-examination is a fresh full run of the same agent, anchored to a specific prior decision. The agent re-runs whatever analysis it normally does (full council for a lead agent), then produces a re-examination card with three required fields:

Field	Meaning
conviction_score	0–100. 0 = original conclusion fully invalidated, 100 = fully confirmed.
notes	One sentence on what changed since the original decision.
suggested_action	Domain-specific advisory string (e.g. HOLD / CLOSE / SCALE for trade decisions). Advisory only — the user decides whether to act on it.

When to use it

• A trade is open and you want a fresh read on whether the thesis is still valid
• A research thesis was published days ago and you want to confirm or revise it
• Any decision with a lifetime that benefits from periodic re-evaluation

How it works

Triggered by clicking Re-examine on a parent run — either on the run detail page or, for trade decisions, directly on the trade card in /results/trade-decisions. The platform builds a self-contained prompt server-side from the parent’s structured slot values (entry, TP, SL, watch_for items, etc.) and invokes the same agent with parentRunId set on the new run. The prompt is authoritative — it overrides the agent’s normal output format without requiring any SKILL.md cooperation, so re-examination works on any agent including custom ones.

The new run renders as a re-examination card. The parent run gains a chronological Conviction history list of all its re-examinations underneath, and trade-decision rows on the results page surface the latest conviction score inline.

Which card types support it

A card type opts in via two optional fields on its CardDefinition:

• reExaminable: true | "until_resolved" — controls whether the Re-examine button shows. "until_resolved" (used by trade-decision) hides the button once the run’s resolutionStatus becomes resolved or expired, so closed trades aren’t re-examined.
• reExamineActions: string[] — the action vocabulary inlined into the prompt for suggested_action. Trade-decision declares ["HOLD", "CLOSE", "SCALE"]. Without this, the model is allowed any short uppercase string.

The re-examination machinery itself is generic — adding a new re-examinable card type is a config change, not a code change.

What stays the same

• The original decision’s resultJson is never modified. The re-examination is an annotation that lives on its own run, linked via parentRunId.
• Auto-resolve behavior is unaffected. A re-examination’s suggested_action: "CLOSE" is advisory — the original trade keeps tracking until SL/TP hits or you manually mark it exited. The user remains the source of truth on whether to actually close a position.
• Council agents are not told about the open position. Specialists analyze the asset blind so their fresh read isn’t anchored to the existing exposure; the lead reconciles the view with the prior decision.

Quick reference

	Memory off	Memory on	Review Decisions
Chat history	–	✓ full	–
Prior run transcripts	–	✓ full	–
Prior decision cards	–	✓ (inside transcript)	✓ last ~5, structured
Context cost per run	low	grows over time	low (one tool call)

The two can be combined. Memory on + Review Decisions on gives the agent both the full reasoning history and a clean decision summary on demand.

The Active Memory panel

On the agent detail page, when Memory is enabled you see:

• Status — “Fresh” before the first run writes a session id, “Carrying context” after
• Runs since reset — how many scheduled runs have fired since the last Reset (or since enabling)
• Session age — how long ago the session was last updated (e.g. 2h 15m)

When Runs since reset passes 20, the pill turns amber on /agents cards and a warning appears on the detail panel suggesting a reset to keep runs fast.

Managing memory

1. Enable for an agent

   On New Agent or Edit Agent, toggle Active Memory on. The toggle is off by default with an amber warning explaining the tradeoff (context grows over time).

2. Let it accumulate

   Chat with the agent or let scheduled runs fire. Each one extends the shared session.

3. Reset when drift starts

   Click Reset memory from either the agent detail page or the card on /agents. This clears the stored claudeSessionId and bumps the counter anchor — the next run starts fresh while chat messages remain visible.

Enabling memory and resetting memory have the same effect: fresh session, counter back to zero. Disabling memory leaves the stored session untouched but ignores it; re-enabling starts fresh.

Where the data lives

Table / column	Role
ChatSession.claudeSessionId	The latest Claude CLI session id. Shared between chat and heartbeat when memory is on.
ChatSession.lastResetAt	Anchor for the runs-since-reset counter. Bumped on enable and on explicit reset.
HeartbeatRun.sessionIdBefore	Session id the run was spawned with (for audit).
HeartbeatRun.sessionIdAfter	Session id Claude emitted on completion. Used to count “successful runs since reset”.
Agent.adapterConfig.memoryEnabled	Per-agent toggle. Off by default.
Agent.adapterConfig.reviewDecisions	Independent per-agent toggle for structured decision fetch.
HeartbeatRun.parentRunId	Set on re-examination runs. Points at the original decision being re-evaluated. Children are queried via GET /api/runs/:id/re-examinations.