| name | memory-protocol |
| description | Persistent cross-agent memory system using markdown files in .serena/memories/ouroboros/. Defines read-on-start, write-on-complete protocols for all agents. Per-agent folders prevent overwrite conflicts. Automatically loaded by all agents. |
| user-invokable | false |
Memory Protocol
Every agent in the team MUST follow this protocol to maintain persistent context
across sessions. Memory files are plain markdown in .serena/memories/ouroboros/, git-tracked
and human-editable.
Memory Directory Structure
.serena/memories/ouroboros/
├── INDEX.md # Master list of all memories
├── project/ # OWNER: project-owner (exclusive write)
│ ├── state.md # Current phase (0-7), active features, blockers
│ ├── decisions.md # Business + architectural decisions (append-only)
│ └── onboarding.md # Project structure summary (auto-generated)
├── tasks/ # OWNER: team-lead creates, workers update own rows
│ ├── registry.md # All tasks with status (cross-agent table)
│ └── features/
│ └── <feature-name>/ # Per-feature folder
│ ├── breakdown.md # Task breakdown + dependencies (team-lead)
│ └── notes.md # Implementation notes (assigned worker)
├── agents/ # Per-agent isolation — each agent owns ONLY their folder
│ ├── project-owner/
│ │ ├── handoff.md # Handoff state for resume
│ │ └── sessions/
│ │ └── <YYYY-MM-DD>-summary.md # Session summaries
│ ├── business-analyst/
│ │ ├── handoff.md
│ │ └── sessions/
│ ├── team-lead/
│ │ ├── handoff.md
│ │ └── sessions/
│ ├── backend-dev/
│ │ ├── handoff.md
│ │ └── sessions/
│ ├── web-dev/
│ │ ├── handoff.md
│ │ └── sessions/
│ ├── mobile-dev/
│ │ ├── handoff.md
│ │ └── sessions/
│ ├── test-worker/
│ │ ├── handoff.md
│ │ └── sessions/
│ ├── reviewer/
│ │ ├── handoff.md
│ │ └── sessions/
│ └── ui-designer/
│ ├── handoff.md
│ └── sessions/
└── architecture/ # OWNER: team-lead (primary), workers (append-only)
├── api-contracts.md # API decisions and contract notes
├── data-model.md # Schema evolution notes
└── conventions.md # Project-specific conventions discovered
docs/requirements/ # Deliverables (NOT agent memory)
├── interviews/
│ └── INT-<NNN>-<topic>.md # Phase 1 Interview transcripts
├── seeds/
│ └── SEED-<NNN>.yaml # Phase 2 Seed YAML specifications
└── REQ-<NNN>-<description>.md # Phase 2 Requirement documents
File Ownership Rules
Every file has exactly ONE owner. Only the owner may create or overwrite it.
Other agents may READ any file but must NEVER write to files they don't own.
| Path | Owner | Others |
|---|
project/state.md | project-owner | team-lead may update phase status ONLY when project-owner delegates |
project/decisions.md | project-owner | Any orchestrator (BA, team-lead) may APPEND — never overwrite |
project/onboarding.md | project-owner | Read-only |
tasks/registry.md | team-lead creates rows | Each worker updates ONLY their own row(s) |
tasks/features/<name>/breakdown.md | team-lead | Read-only for workers |
tasks/features/<name>/notes.md | assigned worker | Read-only for others |
agents/<agent-name>/* | that agent ONLY | Read-only for others |
architecture/* | team-lead | Workers may APPEND discoveries — never overwrite |
INDEX.md | project-owner | team-lead may append new entries |
Append-Only Rules
Files marked "append-only" for non-owners follow this pattern:
<!-- Appended by <agent-name> on <YYYY-MM-DD> -->
### <title>
<content>
This makes it easy to trace who wrote what and prevents accidental overwrites.
Protocol: On Agent Start (READ)
Before doing ANY work, every agent MUST:
- Check if
.serena/memories/ouroboros/INDEX.md exists
- If YES → read it, scan memory names, read relevant memories for your role
- If NO → this is a fresh project, proceed with your normal workflow
- Read role-relevant memories:
- project-owner →
project/state.md, tasks/registry.md, agents/project-owner/handoff.md
- team-lead →
project/state.md, tasks/registry.md, agents/team-lead/handoff.md
- business-analyst →
project/state.md, project/decisions.md, agents/business-analyst/handoff.md
- backend-dev →
tasks/registry.md, architecture/api-contracts.md, agents/backend-dev/handoff.md
- web-dev →
tasks/registry.md, architecture/api-contracts.md, agents/web-dev/handoff.md
- mobile-dev →
tasks/registry.md, architecture/api-contracts.md, agents/mobile-dev/handoff.md
- test-worker →
tasks/registry.md, agents/test-worker/handoff.md
- reviewer →
tasks/registry.md, project/decisions.md
- ui-designer →
project/state.md, project/decisions.md, agents/ui-designer/handoff.md
- Announce context: Briefly tell the user what you found in memory
Protocol: On Decision Made (APPEND)
When a significant decision is made (business rule, architecture choice, scope change):
Append to .serena/memories/ouroboros/project/decisions.md:
<!-- Appended by <agent-name> on YYYY-MM-DD -->
### [YYYY-MM-DD] Decision: <title>
- **Context**: <why this came up>
- **Decision**: <what was decided>
- **Rationale**: <why this option was chosen>
- **Alternatives considered**: <other options and why rejected>
- **Impact**: <what this affects>
Protocol: On Task Create/Complete (UPDATE)
When creating or completing tasks, update .serena/memories/ouroboros/tasks/registry.md:
| Task ID | Feature | Agent | Status | Branch | Last Updated | Blockers |
|---------|---------|-------|--------|--------|--------------|----------|
| TASK-001 | [name] | backend-dev | done | backend/task-001-desc | 2026-03-05 | — |
| TASK-002 | [name] | web-dev | in-progress | frontend/task-002-desc | 2026-03-05 | — |
Status values: planned → in-progress → review → done → merged | blocked | deferred | cancelled
Status Ownership
Each status transition is owned by a specific role:
| Transition | Owner | When |
|---|
→ planned | team-lead | Task decomposition in Phase 4 |
→ in-progress | assigned worker | Worker starts the task |
→ review | assigned worker | Worker completes self-check |
→ done | reviewer | Reviewer approves the code |
→ merged | team-lead | Branch is merged |
→ blocked | any agent | Cannot proceed — must set Blockers column |
→ deferred | project-owner or team-lead | Scope change or reprioritization |
→ cancelled | project-owner | Feature dropped or duplicated |
Parallel Write Safety
Multiple agents may update tasks/registry.md concurrently. To avoid conflicts:
- Each agent only updates their own row(s) — never modify another agent's task entry
- Append new rows at the bottom — never reorder existing rows
- team-lead is the only agent that creates new task rows (initial
planned status)
Feature Folders
When team-lead creates tasks for a feature, also create the feature folder:
tasks/features/<feature-name>/
├── breakdown.md # team-lead writes: task list, dependencies, acceptance criteria
└── notes.md # assigned worker writes: implementation notes, gotchas, TODOs
Multiple workers sharing a feature each append to notes.md with their agent name header:
## backend-dev
- Implemented ProductReview model with cascade delete
- Used integer cents for all price fields per convention
## web-dev
- Reused StarRating component from existing catalog page
Protocol: On Phase Transition (UPDATE)
When project-owner transitions between phases, update .serena/memories/ouroboros/project/state.md:
# Project State
**Last Updated**: <YYYY-MM-DD HH:MM>
**Updated By**: <agent-name>
**Phase**: <number 0-7>
**Phase Name**: <RESUME|INTERVIEW|SEED|DESIGN|PLAN|DEVELOPMENT|REVIEW|DELIVERY>
**Status**: <in-progress|completed>
**Active Feature**: <feature being worked on>
**Active Agent**: <which agent is currently working>
## References
- **Seed**: <docs/requirements/seeds/SEED-NNN.yaml or "none">
- **Requirement**: <docs/requirements/REQ-NNN.md or "none">
- **Design**: <docs/designs/DES-NNN/ or "none">
## Design Node ID Mapping
<!-- Filled by project-owner after Phase 3: DESIGN completes -->
| Screen | Pencil Node ID | .pen File |
| ------ | -------------- | --------- |
| [Screen Name] | `[nodeId]` | `[path]` |
## Outputs
- <list of output file paths from completed phases>
## In Progress
- <what's currently happening>
## Completed
- <what's done>
## Blocked
- <blockers if any>
## Next Steps
- <what comes after current work>
Protocol: On Session End (WRITE)
Before ending a session, each agent MUST write to their own folder:
- Update your handoff file at
.serena/memories/ouroboros/agents/<your-name>/handoff.md:
# <Agent Name> Handoff
**Last Session**: <YYYY-MM-DD>
**Phase**: <current phase>
**Active feature**: <feature name>
**Status**: <what you were doing>
**Waiting for**: <agent/user input, or "nothing">
**Next action**: <what to do next session>
## Context
- <key context points for your next session>
## Open Questions
- <unresolved items>
- Write session summary to
.serena/memories/ouroboros/agents/<your-name>/sessions/<YYYY-MM-DD>-summary.md:
# Session Summary: <YYYY-MM-DD>
**Agent**: <your-name>
**Duration**: <approximate>
## What Was Accomplished
- <bullet list>
## Key Decisions Made
- <bullet list with references to decisions.md>
## Current State
- Phase: <phase>
- Feature: <feature>
- Progress: <percentage or description>
## To Resume
- Start by reading: `agents/<your-name>/handoff.md`
- Then: <specific next action>
-
Orchestrators only (project-owner, team-lead): Also update INDEX.md if new memory files were created
-
project-owner only: Call /revise-claude-md to capture session learnings into CLAUDE.md
Protocol: First Run / Onboarding
Owner: project-owner is responsible for first-run initialization during Phase 0.
Other agents that start before memory exists should proceed with their normal workflow
and skip memory reads (per "On Agent Start" step 1).
If .serena/memories/ouroboros/INDEX.md does not exist (fresh project):
- Create the full directory structure:
mkdir -p .serena/memories/ouroboros/project \
.serena/memories/ouroboros/tasks/features \
.serena/memories/ouroboros/agents/project-owner/sessions \
.serena/memories/ouroboros/agents/business-analyst/sessions \
.serena/memories/ouroboros/agents/team-lead/sessions \
.serena/memories/ouroboros/agents/backend-dev/sessions \
.serena/memories/ouroboros/agents/web-dev/sessions \
.serena/memories/ouroboros/agents/mobile-dev/sessions \
.serena/memories/ouroboros/agents/test-worker/sessions \
.serena/memories/ouroboros/agents/reviewer/sessions \
.serena/memories/ouroboros/agents/ui-designer/sessions \
.serena/memories/ouroboros/architecture
- Run codebase exploration:
- Read
prisma/schema.prisma, package.json, src/app/, src/components/
- Document findings in
.serena/memories/ouroboros/project/onboarding.md
- Create
.serena/memories/ouroboros/INDEX.md:
# Memory Index
| File | Owner | Description | Last Updated |
|------|-------|-------------|--------------|
| project/state.md | project-owner | Current phase and project status | YYYY-MM-DD |
| project/decisions.md | project-owner | Business and architectural decisions | YYYY-MM-DD |
| project/onboarding.md | project-owner | Codebase exploration summary | YYYY-MM-DD |
| tasks/registry.md | team-lead | Cross-agent task status registry | YYYY-MM-DD |
| architecture/api-contracts.md | team-lead | API contract decisions | — |
| architecture/data-model.md | team-lead | Schema evolution notes | — |
| architecture/conventions.md | team-lead | Project conventions discovered | — |
- Create
.serena/memories/ouroboros/project/state.md with Phase 1: Discovery
- Create empty
.serena/memories/ouroboros/project/decisions.md with header only
- Create empty
.serena/memories/ouroboros/tasks/registry.md with table header only
Memory Naming Conventions
- Use lowercase, hyphens for filenames:
api-contracts.md, not API_Contracts.md
- Use topic directories for organization:
architecture/, tasks/features/
- Feature folders use the feature's short name:
tasks/features/product-reviews/
- Session files include date:
agents/<name>/sessions/2026-03-11-summary.md
- Keep individual memory files focused — one topic per file
- If a memory grows beyond 200 lines, split into sub-topics
Anti-Patterns
- Do NOT write to another agent's folder under
agents/ — each agent owns ONLY agents/<your-name>/
- Do NOT overwrite shared files — use append-only with
<!-- Appended by --> markers
- Do NOT read all memories on every start — only read what's relevant to your role
- Do NOT create duplicate memories — check INDEX.md first
- Do NOT store temporary/session-specific state — only persistent knowledge
- Do NOT modify another agent's task entry in
registry.md — only your own row(s)
- Do NOT skip the handoff protocol — future sessions depend on it
