Skip to main content

3. Review What Agents Remember

A memory is one lesson from a past run, with a note on when it applies. Agents search the approved memories of the project while they work. A memory changes what every agent in the project can find, so a person approves each one first. In this page, you see the pr-review agent search for memories, you make an agent propose a memory, and you approve, use and archive it.

Step 1: Find the memory search in a run​

Open the Transcript of a pr-review run from page 1. Find the search_memory tool call. Its argument is a short query that the agent wrote, for example recommendation service product catalog ListProducts timeout. When the project has no memory for the query, the result is "No relevant memories found for that signal."

Every agent can call search_memory. You do not add it to system_tools. It searches the Active memories of the whole project, from all agents, and returns at most 5 of them.

Step 2: Make an agent that proposes a memory​

Agents propose memories through the project's reflection role: an agent that reviews one finished model step and proposes what it learned. The memory then waits for a person in the review queue. By default the role runs Autoheal's own Reflection, and today nothing starts a review by itself. In this step, you make a small reflection agent of your own, which proposes one lesson from a step, so you can see each part.

In Agent Studio → Editor, click New → New agent, and name it lessons. Replace agent.yaml with this file:

YAML
apiVersion: agents.autoheal.ai/v1
name: Lessons
icon: lightbulb
description: >-
Reviews one model step of a finished run and proposes one lesson for a
person to review.
inputs:
run_id:
type: string
required: true
description: The model step's own run.
with:
prompt: ${{ inputs.run_id }}
instructions: ./instructions.md
model:
name: claude-sonnet-5
limits:
model_requests: 20
timeout: 5m
system_tools: name in ["read_agent_run", "read_agent_messages", "create_memory"]
integration_tools: "false"
returns:
memories_used:
type: array
required: true
description: Always empty. This agent judges no memories.
items: {type: string}
memories_proposed:
type: array
required: true
description: The memory_id that create_memory returned, or empty.
items: {type: string}

Add instructions.md in the same folder:

MARKDOWN
You read one model step of a finished agent run and propose one lesson from it.

1. The prompt is the step's run ID. Read the step with `read_agent_run`, then its messages with `read_agent_messages`.
2. Find one thing that a later review of the same repository must know. For example, how the agent got the code, or a rule that applied.
3. Propose it with `create_memory`, and cite the message IDs that show the lesson. It saves for the step this review was started on.

Propose one memory only. Do not propose a memory if the step shows nothing worth keeping. Answer with `memories_used` empty, and `memories_proposed` holding the `memory_id` that `create_memory` returned, or empty.

Commit both files.

PartWhy
inputs.run_id and returnsThe reflection role starts its agent with a step's run_id, and expects the ids of the memories it used and proposed.
system_tools: name in [...]The agent gets only the three tools that it needs. create_memory is a write tool, so a filter on operation_type == "read" does not include it.
read_agent_run, read_agent_messagesThey read a past run of the project: its outline and its messages.
create_memoryIt saves one pending memory, with the step and the message IDs that support it. It works only in a review that the reflection role started.

Step 3: Choose the agent for reflection​

Go to Settings → System agents. For reflection, choose the main branch and the lessons agent, and click Save selection. When you finish this page, click Use built-in default to go back to Autoheal's Reflection.

Step 4: Review a run​

Copy the run ID of a pr-review run. The run ID is the last part of the run page's URL. The review is of the run's model step, which has its own run ID. Find it, and start the review:

BASH
autoheal runs view <pr-review run ID> -o json | jq -r '.run.metadata.agentStepRuns[0].runId'
autoheal api POST /api/v1/runtime/runs --project <project ID> \
--field systemRole=reflection --field arguments='{"run_id":"<step run ID>"}'

The second command prints the review's run, with its id. Wait for it to end:

BASH
autoheal runs wait <review run ID>

Then check these items:

  • In the Transcript of the lessons run, create_memory returns "status": "created" and a memory_id.
  • In the panel of the pr-review run, reload the page. The Memory card shows Memories proposed with the count 1.

Step 5: Review the memory​

Go to Context Graph → Memories. The Need your Review tab shows the new memory. The tab has a count of the memories that wait for review. The card shows:

  • The title, and the lesson in three parts: Use when, What to do and Avoid when.
  • Why Autoheal proposed this, with the messages of the run that support the lesson.
  • An Agent run link to the run that the lesson came from.

Read the lesson as a reviewer. Is it true? Will it help a later run? Is it too specific to one pull request? Then select one action:

ActionResult
Looks rightThe memory moves to Active. Agents can find it now.
DismissThe Dismiss this lesson dialog opens. Select a Reason (Obvious, Inaccurate, Not actionable, Not generalizable or Duplicate), and click Dismiss. The memory moves to Dismissed. Agents never find it.
The pencil iconChange the title or the lesson before you approve it.

For this exercise, click Looks right.

Step 6: See the agent use the memory​

Run pr-review again with the example pull request URL. In the Transcript, find search_memory. Check that its result now contains your memory, with its summary and its lesson. The review can now refer to the lesson.

Step 7: Archive the memory​

Go to Context Graph → Memories → Active, find the memory, and click Archive. The memory moves to Archived, and agents do not find it anymore. Click Restore to make it active again.

You cannot delete a memory. Archive a memory that is out of date, and dismiss a proposal that is wrong.

What to know​

  • Each agent's page in Agent Studio has a Memories tab. It shows the same four tabs for the memories that come from that agent's runs.
  • On the Memories page, the Agent filter shows the memories of one agent.
  • A memory that an agent proposes always waits for review. A person must select Looks right before any agent can find it.
  • All agents in the project share an approved memory. Approve only lessons that are true for all of them.
  • The Member role can approve, dismiss, edit and archive memories. The Read-only role can only read them.
  • Agent Studio agents do not propose memories by themselves. Only the agent chosen for the reflection role proposes memories, as the lessons agent does on this page, and only in a review that the role started. The Learn page describes the automatic loop for investigations.

From the CLI​

The CLI has no memories command. Use autoheal api:

BASH
autoheal api GET /api/memory-proposals --project <project ID>
autoheal api POST /api/memory-proposals/<proposal ID>/accept --project <project ID>
autoheal api POST /api/memory-proposals/<proposal ID>/dismiss --project <project ID> --field reason="Not generalizable"
autoheal api POST /api/agent-memories/<memory ID>/archive --project <project ID>

The first command lists the proposals that wait for review, each with its id and its proposed_memory_id. A dismiss needs a reason.

See Memories for the memory lifecycle.