Eaa Session Memory

Session Memory Skill

Overview

This skill defines how the Architect agent (EAA) handles session memory and context persistence. Session memory ensures that architecture decisions, design patterns, technology choices, and discovered constraints survive across multiple sessions, preventing loss of critical design context and enabling seamless session continuity.

The Architect role involves deep analysis and iterative refinement of designs. Without session memory, each new session would start from zero, forcing re-discovery of decisions already made. This skill provides the mechanisms to persist and retrieve architectural context.

Purpose

Session memory serves four critical functions for the Architect agent:

Prerequisites

• Write access to design output directories (docs_dev/design/, .claude/)
• Understanding of EAA role responsibilities (see plugin docs/ROLE_BOUNDARIES.md)
• Familiarity with session state files and design index formats

Instructions

1. Session Start: Check for existing session state and load context
2. During Work: Persist decisions, patterns, constraints, and questions as they are discovered
3. Session End: Create handoff document if needed
4. Session Resume: Load session state and handoff documents to restore context

When to persist:

• Architecture decision made → Create decision record (ADR)
• Design pattern selected → Update patterns.md
• Technology chosen → Update stack.md
• Constraint discovered → Add to constraints.md
• Question identified → Add to open-questions.md
• Major milestone → Create handoff document

Checklist

Copy this checklist and track your progress:

• Session Start
  • Check for existing session state file at .claude/eaa-session-state.local.md
  • Load design index from docs_dev/design/index.json
  • Report retrieved context summary
• During Session
  • Create decision record for each architecture decision in docs_dev/design/decisions/
  • Update patterns.md when pattern is selected
  • Update stack.md when technology is chosen
  • Add to constraints.md when constraint is discovered
  • Add to open-questions.md when question arises
  • Update session state after each significant activity
• Before Session End
  • Review open questions status
  • Create handoff document if needed
  • Update session state with handoff reference
  • Confirm handoff document is complete

Output

What to Remember

The Architect agent MUST persist the following categories of information:

1. Architecture Decisions Made

Every architecture decision that affects system structure or behavior.

Required fields for each decision:

• Decision identifier (ADR-NNN)
• Decision statement (what was decided)
• Rationale (why this decision was made)
• Alternatives considered (what was rejected and why)
• Impact scope (which components/modules affected)
• Decision state (PROPOSED, ACCEPTED, SUPERSEDED)

Example decision types:

• Component selection ("Use Redis for caching layer")
• Integration approach ("REST API over GraphQL")
• Data flow patterns ("Event-sourcing for order processing")
• Scaling strategy ("Horizontal scaling with stateless services")

2. Design Patterns Chosen

All design patterns selected for the system architecture.

Required fields for each pattern:

• Pattern name
• Where applied (component/module)
• Justification (why this pattern fits)
• Constraints introduced (what limitations this creates)

Pattern categories:

• Structural patterns (Microservices, Monolith, Modular monolith)
• Communication patterns (Request-response, Event-driven, Message queues)
• Data patterns (CQRS, Event sourcing, Repository pattern)
• Resilience patterns (Circuit breaker, Retry with backoff, Bulkhead)

3. Technology Stack Decisions

All technology choices that form the implementation foundation.

Required fields for each technology choice:

• Technology name and version
• Purpose (what role it serves)
• Rationale (why chosen over alternatives)
• Compatibility notes (integration considerations)

4. Constraints and Requirements Discovered

All constraints discovered during design analysis.

Required fields for each constraint:

• Constraint identifier (CON-NNN)
• Constraint statement
• Source (where discovered: user, research, dependency)
• Impact (which design decisions affected)
• Mitigation (how the constraint is addressed)

Constraint types:

• Technical ("Must support offline mode", "Maximum 100ms response time")
• Business ("Cannot use cloud services outside EU")
• Resource ("Team has no Go experience")
• Regulatory ("Must comply with GDPR")

5. Open Design Questions

All unresolved questions requiring future decisions.

Required fields for each open question:

• Question identifier (OQ-NNN)
• Question statement
• Blocking (what is blocked by this question)
• Owner (who should resolve this)
• Status (OPEN, IN_PROGRESS, RESOLVED)

Memory Storage Location

All session memory is persisted to file-based storage in the project directory:

Memory Retrieval Triggers

Memory retrieval is triggered by state changes, not by time intervals:

Memory Update Triggers

Memory updates are triggered by state changes in the design process:

Handoff Document Creation

Handoff documents enable session continuity across context clears or agent transitions.

When to Create Handoff Documents

Create a handoff document when:

• Context window approaching limit
• Session ending intentionally
• Transitioning to implementation (handoff to EOA)
• Major design milestone reached
• Significant time gap expected

Handoff Document Types

Handoff Document Structure

Location: docs_dev/design/handoffs/handoff-{timestamp}.md

Sections:

• Session Summary (project, duration, primary focus)
• Decisions Made This Session
• Patterns Applied
• Constraints Active
• Open Questions
• Current Work State
• Files Modified This Session
• Resume Instructions

Error Handling

Examples

Example 1: Session Start with Existing Context

EAA: Checking for existing session state...
Found: .claude/eaa-session-state.local.md

Session ID: eaa-session-20260203-091500
Last Activity: architecture_decision_made
Decisions: 4
Constraints: 6
Open Questions: 2

Loading design index...
Index loaded: 4 decisions, 2 patterns, 6 constraints, 2 open questions

Context retrieved. Active design: design-payments-xyz789
Current phase: architecture
Next recommended action: Resolve OQ-002 (Payment processor selection)

Ready to continue design work.

Example 2: Architecture Decision Made

EAA: Recording architecture decision...

Creating: docs_dev/design/decisions/ADR-005-session-storage.md

---
id: ADR-005
title: Session Storage Selection
status: ACCEPTED
date: 2026-02-04
---

# ADR-005: Session Storage Selection

## Decision
Use Redis for session storage with 24-hour TTL.

## Rationale
- High read/write performance for session data
- Built-in expiration support
- Cluster mode for horizontal scaling
- Team familiarity with Redis

## Alternatives Considered
- PostgreSQL sessions: Rejected due to higher latency
- In-memory sessions: Rejected due to no horizontal scaling

## Impact
- Affects: auth-module, user-service
- Requires: Redis cluster setup in infrastructure

---

Updating design index... Done.
Updating session state... Done.

Decision ADR-005 recorded. Session state: 5 decisions, 6 constraints, 2 open questions.

Example 3: Handoff Creation for Context Clear

EAA: Creating handoff document for context preservation...

Gathering session context:
- Session ID: eaa-session-20260204-120000
- Decisions made: 3 (ADR-003, ADR-004, ADR-005)
- Constraints discovered: 1 (CON-007)
- Open questions: 1 resolved, 1 remaining

Generating handoff document...
Saved: docs_dev/design/handoffs/handoff-20260204-143022.md

Handoff document created. Type: context_clear
To resume: Read handoff document at docs_dev/design/handoffs/handoff-20260204-143022.md

Session state updated with handoff reference.
Ready for context clear.

References

Detailed reference documentation for session memory operations:

Resources

Related Skills

• eaa-design-lifecycle - Design document states and transitions
• eaa-requirements-analysis - Requirements gathering and management
• eaa-planning-patterns - Architecture planning procedures
• eaa-design-communication-patterns - Inter-agent communication

Converted and distributed by TomeVault — claim your Tome and manage your conversions.