Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.swarms.world/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
See also