Persistent Memory

Swarms agents can persist their interaction history to disk through a per-agent MEMORY.md file. The flag is False by default: set persistent_memory=True 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 (PDFs, databases, doc stores), give the agent a retrieval tool instead — MEMORY.md is for the agent’s own history, not a document index. See External knowledge.

How it works

Memory is keyed by agent_name and lives under the workspace directory. When WORKSPACE_DIR is not set, it falls back to ./agent_workspace:

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

On construction, Swarms reads MEMORY.md and adds it to agent.short_memory as a single System message. Every conversation.add(...) then writes through to disk so nothing is lost on exit.

Basic example

Set agent_name and persistent_memory=True. The first construction creates MEMORY.md, and every turn after that is appended to it:

from swarms import Agent

# Off by default; opt in to keep a log that survives restarts.
persistent_agent = Agent(
    agent_name="ResearchAssistant",
    agent_description="Remembers context across sessions",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=True,
)

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 log is loaded into agent.short_memory as one System message, and new turns keep appending to the same file. Changing the name starts a fresh memory folder; id changes between runs and is not used as the key.

agent.run() does not currently send that System message to the model, so a resumed agent does not see its earlier sessions on its own. Until it does, put the log into system_prompt yourself. The system prompt is never written to MEMORY.md, so this does not make the log grow.

import os
from pathlib import Path

from swarms import Agent

memory_file = Path(
    os.getenv("WORKSPACE_DIR", "agent_workspace"),
    "agents",
    "ResearchAssistant",
    "MEMORY.md",
)
earlier = memory_file.read_text() if memory_file.exists() else ""

# Second process, hours later
agent = Agent(
    agent_name="ResearchAssistant",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=True,
    system_prompt=(
        "You are a research assistant.\n\n"
        f"Your notes from earlier sessions:\n{earlier}"
    ),
)

agent.run("Compare BigQuery vs AlloyDB for our latency requirements.")

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 the conversation to JSON and reload it later:

# Writes ./conversations/conversation_<conversation name>.json
agent.short_memory.export()
snapshot = agent.short_memory.save_filepath

# Replace the history with the snapshot
agent.short_memory.load(snapshot)

Snapshots go to ./conversations/ under the current working directory, not to the workspace. The folder is created only when you save.

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

# No MEMORY.md and no archive.
ephemeral_agent = Agent(
    agent_name="EphemeralAgent",
    model_name="gpt-5.4",
    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

Tree of Thoughts

Multi-Agent Examples

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool 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