Agent Memory, Planning & Reflection

Why agents need memory and planning#

A bare agent loop works for short tasks. Real tasks — "refactor this module", "research five competitors" — run for dozens of steps, produce lots of tool output, and sometimes span several sessions. Three techniques keep agents on track:

• Memory — what the agent remembers, and for how long.
• Planning — how it breaks a big goal into steps.
• Reflection — how it checks and corrects its own work.

Short-term memory: the context window#

Everything in the messages list is the agent's short-term (working) memory. It's precise but limited: the context window has a maximum size, and every token you resend costs money and time.

Long-running agents fill it quickly with tool results. Common fixes:

A good rule: keep what the model needs to decide the next step, not everything that ever happened.

Long-term memory: remembering across sessions#

Long-term memory survives after the conversation ends. Typical options:

• Files or notes the agent writes and reads back (e.g. progress.md, a to-do list). Simple and surprisingly effective for coding agents.
• A database of user preferences and facts ("prefers Python", "timezone PKT").
• A vector database for semantic recall — store past notes as embeddings and retrieve the most similar ones (the same idea as RAG).

# Minimal file-based memory tools
from pathlib import Path

NOTES = Path("agent_notes.md")

def save_note(text: str) -> str:
    with NOTES.open("a", encoding="utf-8") as f:
        f.write(f"- {text}\n")
    return "Saved."

def read_notes() -> str:
    return NOTES.read_text(encoding="utf-8") if NOTES.exists() else "No notes yet."

Expose these as tools and tell the agent in its system prompt: "Read your notes at the start of a task and save anything you'll need later."

Planning patterns#

ReAct (Reason + Act)#

The model alternates thinking → acting → observing: reason about what's needed, call one tool, read the result, decide again. It's the default behaviour of most tool-calling models and works well for tasks where each step depends on the last.

Plan-and-execute#

First ask the model for an explicit plan, then execute the steps one by one:

Plan:
1. List the files in /src/payments
2. Find where refunds are calculated
3. Write a failing test for the rounding bug
4. Fix the bug and run the tests

Writing the plan down (in a file or the conversation) helps on long tasks: the agent can tick off steps, recover after errors, and you can review the plan before anything runs.

Decomposition into sub-tasks#

For big goals, a lead agent splits work into independent sub-tasks and hands them to helpers — covered in the next lesson on multi-agent systems.

Reflection: checking your own work#

Reflection means the agent evaluates its output before finishing:

• A coding agent runs the tests and fixes failures instead of declaring success.
• A research agent checks each claim against its sources.
• A writing agent re-reads the requirements and confirms each one is met.

The most reliable reflection uses real signals — test results, linters, schema validation, row counts — not just "are you sure?". A model asked to review itself with no new information often just agrees with itself.

System prompt snippet:
Before giving your final answer, verify it:
- run the test suite and confirm it passes
- if anything fails, fix it and run the tests again
Only report success after a passing run.

Putting it together#

A practical long-task agent usually combines:

1. A written plan at the start.
2. File-based notes for progress and decisions.
3. Trimmed tool results to protect the context window.
4. Verification with real checks before finishing.
5. A step or token budget so it ends gracefully.

Common mistakes#

• Stuffing every tool output into context. The agent slows down, costs more, and loses focus on what matters.
• Memory without rules. If you never tell the agent when to read or write notes, it rarely does.
• Planning once and never updating. Plans should change when a step fails or new information appears.
• Self-review without evidence. Reflection works best when it's grounded in tests or data, not opinion.

Key takeaways#

• Short-term memory is the context window — manage it actively.
• Long-term memory lives outside the model: files, databases or vector stores.
• ReAct suits step-by-step tasks; plan-and-execute suits long ones.
• Good reflection is verification with real signals.