Memory
Long-term facts, session buffer, episodic log, and compaction.
In short: four different things get called "memory," and they solve different problems. What the agent knows about a customer, what was just said, what happened during this run, and where it puts things too big to hold in its head. Keeping them separate is what stops long conversations getting slow and expensive.
"Memory" gets used for four different problems. agentFast keeps them separate, because they have different lifetimes, different costs and different failure modes.
The four tiers
| Tier | Scope | Backed by | Answers | |---|---|---|---| | Long-term facts | Per user | pgvector (or Chroma) | "What do I know about this person?" | | Session buffer | Per session | The run store | "What did we just say?" | | Episodic log | Per run | The run store | "What happened during this run?" | | Scratchpad | Per run | Files on disk | "Where do I put the 40-page document?" |
The scratchpad exists because not everything belongs in a context window. An agent researching twelve sources writes them to files and keeps paths in context, rather than carrying the text and running out of room on source nine.
Recall is visible
When long-term memory injects a fact, it writes a memory:recall step into the trace — so a
surprising answer can be traced back to what the agent remembered, not just what it retrieved:
| memory | recall | 2 facts · cust_alice · prefers email contact | — |
| llm | claude-sonnet-4-5 | context included recalled facts | $0.0031 |
Compaction
Long runs outgrow their context window. Two modes, because two different shapes of work fail differently:
Tiered — for conversations. Older turns are summarised while recent ones stay verbatim. The agent keeps the thread of what was said without carrying every word.
Reset-artifact — for long autonomous runs. Context is reset to a compact artifact of what's been established: findings, decisions, file paths. The agent keeps the conclusions and drops the deliberation that produced them.
memory_enabled: true
compaction:
mode: tiered # tiered | reset_artifact
threshold_tokens: 100000
Compaction runs between iterations, and it writes a memory:compaction step recording tokens before
and after — so a run that suddenly forgot something has an audit trail explaining when.
Both loop-owning adapters compact the message list before the model call. SDK-owned loops (CrewAI, Claude Agent SDK, OpenAI Agents SDK) manage their own context, so agentFast doesn't reach in — the tier that would be lost there is the session buffer, which those SDKs already handle.
Turning it off
memory_enabled: false
The runtime treats memory as an optional collaborator, so this is a genuine no-op rather than a stubbed-out path — useful when your agent is stateless by design and you'd rather not carry a vector store.