Memory gives agents persistent context that survives across tasks and sessions.
Scopes
| Scope | Who can read | Purpose |
|---|
| Shared | All agents | Project-wide context: conventions, decisions, domain knowledge |
| Per-agent | Only that agent | Agent-specific notes, preferences, learned patterns |
.polpo/:
.polpo/
├── memory.md # shared memory
└── memory/
├── backend-dev.md # backend-dev's private memory
└── researcher.md # researcher's private memory
How memory is injected
Memory is injected automatically before every response. The agent sees it as context tags:
<shared-memory>
## Project conventions
- Use TypeScript strict mode
- All API responses follow the { data, error } envelope
- Deploy to staging before production
</shared-memory>
<agent-memory>
## Learned patterns
- The payments service uses Stripe webhooks on /api/webhooks/stripe
- Database migrations run via `pnpm db:migrate`
</agent-memory>
memory_* in their allowedTools can read and modify their own memory:
| Tool | Description |
|---|
memory_get | Read the agent’s current memory |
memory_save | Overwrite the agent’s memory |
memory_append | Append to the end |
memory_update | Replace a specific section |
{
"name": "backend-dev",
"allowedTools": ["read", "write", "edit", "bash", "memory_*"]
}
Agents can only access their own private memory. They cannot read or write another agent’s memory.
Best practices
- Keep it concise — memory is injected into every response. Prefer bullet points over paragraphs.
- Use headings — structure with Markdown headings so
memory_update can target specific sections.
- Let agents learn — agents with
memory_* tools will naturally build up useful context over time.
