Skip to main content
A MEMORY.md file gives an agent persistent context that survives across restarts and respawns. While a soul defines who the agent is and tasks define what to do, memory defines what the agent knows.

​
How It Works

MEMORY.md is injected into the agent’s Claude Code system prompt alongside the soul and task list. The agent reads it at the start of every session, so anything written here carries forward even after a respawn. Agents can also write to their own MEMORY.md during a session — for example, recording a debugging insight or noting a project convention they discovered.

​
What to Put in Memory

CategoryExamples
Project contextArchitecture overview, key dependencies, deployment targets
ConventionsNaming patterns, file structure rules, commit message format
LearningsPast debugging insights, workarounds for known issues
Known issuesFlaky tests, deprecated APIs, things to avoid
Credentials/configEnvironment variable names (not values), service URLs, config file locations

​
Example

# Project Context
- Monorepo with three packages: api, web, shared
- API runs on FastAPI 0.104 with PostgreSQL 16
- Web is Next.js 14 with App Router

# Conventions
- All API endpoints return {data, error, meta} envelope
- Database migrations use Alembic with --autogenerate
- Branch naming: type/description (e.g., feat/user-auth)

# Known Issues
- The test suite requires Docker running for integration tests
- WebSocket connections drop after 30s idle — there's a keepalive ping in shared/ws.ts
- Don't upgrade pandas past 2.1 — breaks the reporting pipeline

# Learnings
- The auth middleware caches tokens for 5 minutes — clear cache when debugging auth
- Use `make dev-seed` to populate test data, not the SQL scripts directly

​
Editing

Open the Memory tab in the Detail Panel to view and edit an agent’s MEMORY.md. You can also edit the file directly on disk.

​
Shared Memory

Pods and teams have their own MEMORY.md files. Shared memory provides group-level context:
  • Pod MEMORY.md — context shared with all agents within the pod’s canvas bounds
  • Team MEMORY.md — context shared with all agents assigned to the team
Use shared memory for project-wide knowledge and agent memory for individual context.

​
Soul vs Tasks vs Memory

SoulTasksMemory
PurposeWho you areWhat to doWhat to know
ContentRole, personality, constraintsCheckbox work itemsContext, conventions, learnings
ChangesTake effect on respawnWatched continuouslyInjected on session start
Typical authorYou (human)You and the agentYou and the agent
AnalogyJob descriptionTo-do listNotebook
  • Agents — agent lifecycle and identity files
  • Souls — defining agent identity
  • Tasks — assigning work items
  • Pods & Teams — shared memory files