My agent kept forgetting what it was doing. A scratchpad fixed it.

This is a submission for the Hermes Agent Challenge.

My Hermes research agent was asking the same questions twice. It would identify a paper, start analyzing it, then two turns later ask if anyone had studied the same topic. The context window had the answer but the agent wasn't tracking its own progress.

The fix isn't more context — it's structured working memory. That's agent-scratchpad.

The idea

A scratchpad is just a keyed dict with helpers for list building and counting. The useful part is to_text() — it renders the current state as plain text you can inject into any system prompt.

from agent_scratchpad import Scratchpad

pad = Scratchpad()
pad.set("topic", "quantum error correction")
pad.append("papers_found", "Shor 1995")
pad.append("papers_found", "Steane 1996")
pad.increment("search_count")
pad.append("hypotheses", "Surface codes may be more practical than Steane codes")

print(pad.to_text(title="Research progress"))
# Research progress:
# hypotheses:
#   - Surface codes may be more practical than Steane codes
# papers_found:
#   - Shor 1995
#   - Steane 1996
# search_count: 1
# topic: quantum error correction

Inject into prompts

context = pad.to_text(title="What I know so far")

response = client.messages.create(
    model="claude-sonnet-4-5",
    system=f"You are a research assistant.\n\n{context}",
    messages=messages,
)

The scratchpad goes in the system prompt. The agent can read what it's already found and not repeat itself.

All the operations

pad.set("key", value)          # set scalar
pad.get("key", default=None)   # deep copy
pad.delete("key")
pad.has("key")

pad.append("papers", "Shor 1995")   # build lists
pad.prepend("queue", "urgent item") # front-of-list
pad.extend_list("papers", [...])    # bulk append

pad.increment("search_count")   # counter (init to 0)
pad.decrement("errors")
pad.increment("cost_cents", 5)

pad.update({"a": 1, "b": 2})  # set multiple
pad.clear()

JSONL log

pad = Scratchpad("logs/scratchpad.jsonl")
pad.set("topic", "ML")
# appends {"ts": ..., "op": "set", "key": "topic", "value": "ML"}

Replay the scratchpad log to see every decision the agent made.

Save and restore

pad.save("state.json")

# Next run
pad = Scratchpad.load("state.json")

Full JSON snapshot for resuming long-running agents.

Zero dependencies

Standard library only: json, copy, time, pathlib. Nothing else.

pip install agent-scratchpad

Repo: https://github.com/MukundaKatta/agent-scratchpad