Give an agent memory

An agent with memory can hold onto a fact a user tells it — a preference, a name, a standing instruction — and still know it turns, restarts, and days later. maiden ships this as a built-in: one line in agent.toml, no code.

Turn it on

[agent]
model = "openai/gpt-4o-mini"
memory = true

That’s the whole setup. Memory is off by default, so an agent that doesn’t want it pays nothing — no extra tools, no extra prompt bytes.

What you get

Enabling memory does two things every turn:

1. Two tools become available to the model.
   • remember — save a short fact to durable memory. The model calls it on its own whenever the user says something worth keeping.
   • recall — list everything currently saved.
2. Saved notes are injected into the system prompt, at the top of every turn, under a # Remembered heading. This is the important half: a saved preference is applied whether or not the model thinks to call recall. Writing is model-driven (pull); reading is automatic (push).

A short exchange, once memory is on:

» remember I don't care about Dependabot PRs
« Got it — I'll leave those out from now on.

  (a restart, a week later…)

» anything I should look at?
« 2 review requests and a red build on api-gateway.
  (Dependabot PRs omitted — you asked me to.)

Where it lives

A remembered note is not held in the model’s context window — it’s written to the thread’s durable state, under the memory.notes key, and checkpointed with the rest of the thread after every turn:

{
  "history": [ ... ],
  "state": { "memory.notes": ["I don't care about Dependabot PRs"] }
}

That means memory rides the same durability guarantee as everything else: crash the process, redeploy, move machines — the notes come back when the thread resumes. See Execution model and durability.

Memory is scoped per thread. Two chats with the same agent keep separate memories; a note saved in one never leaks into another.

Notes are de-duplicated (the same fact saved twice is stored once) and trimmed of surrounding whitespace, so a model that re-remembers something across turns can’t grow the list.

Guiding the model

Memory works without any instructions, but a line in your instructions.md makes the agent deliberate about it:

## Memory
When the user tells you a lasting preference or fact, call `remember` to save it.
Saved notes appear under "Remembered" on later turns — respect them.

When you need more than notes

Built-in memory is the batteries-included case: a flat list of remembered facts. If you need bespoke per-turn behavior — structured state, memory that changes how the prompt is assembled, picking a model by topic, gating the tool set — reach for a dynamic resolver: a script under dynamic/ that runs at the start of every turn with the live { thread, message, turn, state } and can mutate durable state and reshape the prompt. Built-in memory and resolvers read and write the same durable state map, so they compose. See the agent folder reference.