memory-protocol

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:

1. 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
2. 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
3. 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:

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

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

3. Orchestrators only (project-owner, team-lead): Also update INDEX.md if new memory files were created

4. 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):

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

2. Run codebase exploration:
   • Read prisma/schema.prisma, package.json, src/app/, src/components/
   • Document findings in .serena/memories/ouroboros/project/onboarding.md
3. 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 | — |
   

4. Create .serena/memories/ouroboros/project/state.md with Phase 1: Discovery
5. Create empty .serena/memories/ouroboros/project/decisions.md with header only
6. 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