> ## 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.

# Persistent Memory

> Persist agent interaction history to disk via MEMORY.md and resume across process restarts.

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:

```text theme={null}
$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:

```python theme={null}
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:

```python theme={null}
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`:

```python theme={null}
# 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:

```python theme={null}
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:

```python theme={null}
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](/examples/agents/context-compression) so memory stays within the model's context window.

## See also

* [Agent Memory Reference](/agents/agent-memory) — Full memory stack, lifecycle, and disk layout.
* [Context Compression](/examples/agents/context-compression) — Keep persistent memory within the context window.
* [Conversation API](/api/conversation) — Underlying class for export, load, and search.