How To Make An Agent Learn From One Session

The agent finished the task.

It was not graceful the whole way through. It misunderstood one instruction, patched the wrong function once, got corrected, found the right files, broke a test, fixed the test, and eventually produced something useful. The final diff is fine. The session, however, contains a richer question:

How do you make the agent learn from what just happened?

Not in the theatrical sense. The model did not update its weights because you wrote “no, the public API has to preserve the old error envelope” into a chat box. But something can still learn. The workflow can learn. The agent’s memory can learn. The next run can start with a sharper rule, a better test, a narrower skill, or a hook that catches the mistake before it becomes another review comment.

The session is raw material. Learning starts when you consolidate it.

The Espresso Shot

An agent does not learn from a session just because the session happened.

It learns when the completed session is reflected on, compressed into useful lessons, checked against evidence, and written somewhere the next run can actually use. Reflection without a write path is a diary. Memory without admission control becomes compost in the context window.

The useful mental model is a compiler pass over experience:

transcript + tool trace + diff + tests + user corrections + outcome
-> reflection pass
-> candidate lessons
-> admission gate
-> memory, doc, skill, hook, test, eval, or rejection

The lesson is not the transcript. The lesson is a compact, triggered, verified artifact.

That distinction shows up in the research, too. Reflexion showed language agents improving through verbal reflection stored in episodic memory rather than through model weight updates. Experiential Reflective Learning takes a similar direction: reflect on trajectories and outcomes, turn them into heuristics, then retrieve the relevant heuristics later. The important bit for working engineers is wonderfully plain: raw experience is too lumpy. The agent needs distilled guidance it can find at the right moment.

Wait Until The Session Has An Outcome

During the session, corrections are working state. After the session, they become evidence.

That timing matters. If you ask the agent to “remember this forever” while you are irritated halfway through debugging, you are likely to preserve the wrong thing. At that point you may not know whether the mistake came from a missing project rule, a bad assumption, a misleading file name, a failing test, or your own unclear prompt. Very glamorous. Very human. Very dangerous as permanent memory.

Run the learning pass after there is an outcome:

• What changed?
• Which checks passed or failed?
• What did the user correct?
• Which tool calls or files mattered?
• What was the final reason the work succeeded?
• What should be different next time?

This is why traces and diffs matter. A transcript says what everyone said. The diff says what changed. Tests say what survived contact with reality. Review comments say what still violated the team’s expectations. A useful learning pass reads all of them.

A Small Example: The Error Envelope

Imagine an agent adds validation to a signup endpoint. The logic works, but the response is wrong:

{
  "message": "Invalid email"
}

The public API requires:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email",
    "field": "email"
  }
}

During the session, you correct the agent:

The validation logic is fine, but the response shape is wrong.
Public API errors must preserve the typed envelope because mobile clients parse it.
Add a contract test for invalid email.

The agent updates the handler, adds the test, and the task finishes.

Now the learning pass should not save “user dislikes my error object.” It should extract a future behavior:

Candidate lesson:
  Public API handlers must preserve the typed error envelope:
  { error: { code, message, field } }.

Trigger:
  When editing public API handlers or validation responses.

Scope:
  Public HTTP API only; not internal scripts or CLI output.

Evidence:
  User correction plus passing signup invalid-email contract test.

Suggested write:
  Add a scoped API compatibility note and keep the contract test.

That is learning. Small, scoped, boring in exactly the right way.

Use An Admission Gate

The agent should not learn everything it noticed. It should learn what changes future behavior.

Before writing anything durable, require four fields:

Trigger:
  When should this lesson be retrieved?

Scope:
  Where does it apply, and where does it not apply?

Evidence:
  What proves this was a real lesson rather than a momentary guess?

Write surface:
  Memory, doc, skill, hook, test, eval, or reject?

This gate prevents two common failures.

The first is transcript hoarding. Saving the whole session feels thorough, but it makes future retrieval harder. Experiential Reflective Learning’s result is useful here: compact heuristics can be more transferable than raw trajectories, and retrieving the right one matters. Your future agent does not need a 26-turn drama about the signup endpoint. It needs the compatibility rule when it touches public API errors.

The second failure is overlearning. One temporary workaround becomes a permanent commandment. A branch-specific migration note becomes project doctrine. A user preference from a prototype becomes a team-wide rule. Tiny moment, big shadow.

Good memory is not a museum. It is an operating surface.

Choose The Right Write Surface

Once a lesson passes the gate, decide where it belongs.

Scoped memory:
  A concise fact or preference the agent should retrieve later.

Project doc or rule:
  A human-readable source of truth the team also needs.

Skill or runbook:
  A repeatable procedure with steps, checks, and examples.

Hook, validator, schema, or permission:
  A must-not-fail rule that prose should not merely suggest.

Test or eval:
  A behavior that should be checked repeatedly.

Reject:
  A temporary detail, noisy observation, or lesson with weak evidence.

Anthropic’s Claude Code memory docs are refreshingly clear on one point that applies beyond that tool: memory files are context, not enforcement. If a public contract must not change, keep the test. If a tool is risky, use permissions or a hook. If a workflow is subtle and repeated, package it as a skill. If a failure pattern should be measured, turn it into an eval case.

Prose helps the agent choose. Checks make the system harder to break.

The Debrief Prompt

You can make this practical with a short end-of-session command or checklist:

Review the completed session and propose learning artifacts.

Use only evidence from:
- user corrections
- final diff
- test/build results
- tool trace
- review comments
- final outcome

Return:
1. Session outcome
2. User corrections that mattered
3. Candidate lessons
4. For each lesson: trigger, scope, evidence, confidence
5. Proposed write surface: memory, doc, skill, hook, test, eval, or reject
6. Exact text to write, if any
7. Lessons rejected and why

The “rejected” section is not optional. It is the part that keeps your agent from becoming a collector of haunted sticky notes.

For the error-envelope session, the debrief might propose:

• Keep the contract test.
• Add a scoped API compatibility memory.
• Do not create a new global error-handling skill yet.
• Revisit if two more endpoints hit the same issue.

That last line is the bridge to the sequel. One session can teach a precise lesson. Many sessions can tell you whether the lesson is a pattern.

Barista’s Tip: Make The Lesson Executable

After every debrief, ask one more question:

How will the next agent encounter this lesson at the moment it matters?

If the answer is “it will be somewhere in a long memory file,” the lesson may not be learned in practice. Add a trigger. Put it near the relevant code. Link it from the runbook. Create the test. Narrow the skill description. Attach the hook to the lifecycle event where the mistake happens.

MemToolAgent is interesting here because it treats tool-use experience as something that can be extracted into structured memory and retrieved for future tool choices. The same design principle applies to normal development work: the artifact has to be findable at decision time.

Learning is not storage. Learning is storage plus retrieval plus changed behavior.

Do Not Make One Session Carry A Whole Lifetime

A single-session debrief is powerful because it is close to the evidence. It is also limited because it has only one trajectory.

Use it for local lessons:

• a correction the user made clearly,
• a test that captured a real contract,
• a project rule that was missing from context,
• a workflow step that should happen next time,
• a dangerous action that deserves a stronger gate.

Do not use it to declare broad trends. That belongs to many-session learning: clustering repeated mistakes, comparing successful and failed traces, finding contradictions, updating eval datasets, and retiring stale memories. That is a different machine.

Single-session consolidation answers:

What should this one run teach the next run?

Many-session learning answers:

What has experience been trying to teach us for weeks?

Both matter. They just should not be mashed into the same summary file and called wisdom.

The Last Sip

If you want an agent to learn from a session, do not ask the transcript to do magic.

Run a debrief. Extract candidate lessons. Demand trigger, scope, and evidence. Choose the right write surface. Reject the noisy bits. Prefer tests and hooks when correctness matters. Keep memory small enough to be useful.

The agent’s “experience” only becomes experience when it changes the next action.

That is the quiet trick: learning from one session is not a bigger memory dump. It is a disciplined little after-action review that leaves the next agent with fewer excuses and better handles.

Sources On The Counter

• Reflexion grounds the idea of parameter-free learning through verbal reflection and episodic memory.
• Experiential Reflective Learning supports extracting compact heuristics from trajectories instead of replaying raw experience.
• Training Language Agents to Learn from Experience supports separating the worker from a reflector that writes future guidance.
• MemToolAgent supports distilling tool-use experience and corrections into structured memory.
• LangMem and LangGraph memory docs provide practical vocabulary for extraction, consolidation, short-term state, and long-term memory.
• Claude Code memory docs, Codex skills, Codex hooks, OpenAI agent evals, and the OpenAI Cookbook improvement loop ground the write surfaces where lessons can become future behavior.