> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> Persistent shared and private context for agents

Memory persists context across tasks, loop runs, and chat sessions. Polpo has two scopes:

| Scope  | Visible to                 | Local file                      |
| ------ | -------------------------- | ------------------------------- |
| Shared | Every agent in the project | `.polpo/memory.md`              |
| Agent  | Only the named agent       | `.polpo/memory/{agent-name}.md` |

Polpo Cloud stores the same logical scopes in the project state store. At the start of each run or chat request, the runtime adds non-empty memory to the system context as `<shared-memory>` and `<agent-memory>` blocks.

## Agent tools

Enable `memory_*` when an agent should update its private memory:

| Tool            | Operation                  |
| --------------- | -------------------------- |
| `memory_get`    | Read private memory        |
| `memory_save`   | Replace private memory     |
| `memory_append` | Append a timestamped note  |
| `memory_update` | Find and replace a section |

```json theme={null}
{
  "name": "backend-dev",
  "allowedTools": ["read", "write", "edit", "bash", "memory_*"]
}
```

These tools are scoped to the calling agent. They cannot read or change another agent's private memory.

## API

Project API keys can manage both scopes:

| Method | Path                           | Description                |
| ------ | ------------------------------ | -------------------------- |
| `GET`  | `/v1/memory`                   | Read shared memory         |
| `PUT`  | `/v1/memory`                   | Replace shared memory      |
| `GET`  | `/v1/memory/agent/{agentName}` | Read one agent's memory    |
| `PUT`  | `/v1/memory/agent/{agentName}` | Replace one agent's memory |

Write operations accept `{ "content": "..." }`. Keep memory short and structured because its complete content consumes context on every run.