Persistent Memory

Swarms agents persist their interaction history to disk through a per-agent MEMORY.md file. Set persistent_memory=True (the default) and reuse the same agent_name across process starts to resume the same memory.

When to use it

The agent runs in separate processes (CLI, cron, restarts) and needs to resume prior context.
You want a human-readable transcript of what the agent has seen and produced.
You need to inspect, search, or export the agent’s interaction log.

For external knowledge retrieval (PDFs, databases, doc stores), use long_term_memory (RAG) instead — MEMORY.md is for the agent’s own history, not a document index.

How it works

Memory is keyed by agent_name and lives under the workspace directory:

$WORKSPACE_DIR/agents/{agent_name}/
|-- MEMORY.md
`-- archive/
    `-- history_<timestamp>.md

On construction, Swarms reads MEMORY.md and injects it into conversation_history as a single System message. Every conversation.add(...) then write-throughs to disk so nothing is lost on exit.

Basic example

Set agent_name and persistent_memory=True (the default). On the first run Swarms creates MEMORY.md. On subsequent runs the prior conversation is preloaded as a system preamble and the agent picks up where it left off:

from swarms import Agent

# Persistent agent (default behavior).
# On first run it creates MEMORY.md. On subsequent runs it picks up
# where it left off — the model sees the prior conversation as a
# system preamble.
persistent_agent = Agent(
    agent_name="ResearchAssistant",
    agent_description="Remembers context across sessions",
    model_name="gpt-4.1",
    max_loops=1,
    persistent_memory=True,  # default — state survives restarts
)

persistent_agent.run("Research low-latency cloud data warehouses for analytics.")
persistent_agent.run("Narrow the recommendation to GCP.")

# Active on-disk memory
print(persistent_agent.short_memory.memory_md_path)
# -> $WORKSPACE_DIR/agents/ResearchAssistant/MEMORY.md

Resume across restarts

Re-instantiate an agent with the same agent_name and persistent_memory=True. The prior transcript is preloaded as a system message before the new task runs:

from swarms import Agent

# Second process, hours later
agent = Agent(
    agent_name="ResearchAssistant",  # same name -> same memory
    model_name="gpt-4.1",
    max_loops=1,
    persistent_memory=True,
)

# The agent already "remembers" the GCP shortlist from before
agent.run("Compare BigQuery vs AlloyDB for our latency requirements.")

Changing the name starts a fresh memory folder; id changes between runs and is not used as the key.

Inspect memory in code

The Conversation object is exposed as agent.short_memory:

# Full prompt-ready history
print(agent.short_memory.return_history_as_string())

# Structured message list
messages = agent.short_memory.to_dict()

# Last response only
print(agent.short_memory.get_final_message_content())

# Search past turns
hits = agent.short_memory.search("GCP")
matches = agent.short_memory.search_keyword_in_conversation("latency")

Export and reload

Snapshot memory to JSON or YAML and reload it later:

agent.short_memory.export(force=True)
agent.short_memory.save_as_json(force=True)
agent.short_memory.save_as_yaml(force=True)

# Restore from a prior snapshot
agent.short_memory.load("conversation_agent-123.json")

Disable disk-backed memory

For privacy-sensitive or one-off agents, set persistent_memory=False. In-process conversation_history still works for the duration of the run, but nothing is written to disk and nothing is preloaded next time:

from swarms import Agent

# Ephemeral agent — no MEMORY.md, no archive, fresh state every run.
ephemeral_agent = Agent(
    agent_name="EphemeralAgent",
    model_name="gpt-4.1",
    max_loops=1,
    persistent_memory=False,
)

ephemeral_agent.run("This task is not written to MEMORY.md.")

Tips

Use stable, descriptive agent_name values for any agent that should remember prior work.
Don’t reuse the same agent_name across unrelated tasks — memory will leak between runs.
For long-running agents, also enable context compression so memory stays within the model’s context window.

Index

Basic Examples

Model Providers

Single Agent

Multi-Agent Examples

Auto Agent Builder

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

Deployment

CLI

Persistent Memory

When to use it

How it works

Basic example

Resume across restarts

Inspect memory in code

Export and reload

Disable disk-backed memory

Tips

See also

​When to use it

​How it works

​Basic example

​Resume across restarts

​Inspect memory in code

​Export and reload

​Disable disk-backed memory

​Tips

​See also

When to use it

How it works

Basic example

Resume across restarts

Inspect memory in code

Export and reload

Disable disk-backed memory

Tips

See also