# Eaa Session Memory

> Architecture decision and design pattern persistence. Use when preserving architectural context across sessions or creating design handoffs. Trigger with session start. Use when this capability is needed.

- Skill: `tomevault-io/eaa-session-memory` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/eaa-session-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/eaa-session-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/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:

| Function | Description |
|----------|-------------|
| **Decision Preservation** | Architecture decisions and their rationale persist across sessions |
| **Context Continuity** | Design patterns, technology choices, and constraints are not lost |
| **Handoff Enablement** | Complete context can be transferred to other agents or sessions |
| **Progress Tracking** | Open questions and pending decisions are tracked explicitly |

## 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

| Output Type | Location | Purpose |
|-------------|----------|---------|
| **Architecture Decisions** | `docs_dev/design/decisions/ADR-NNN-*.md` | Document each decision with rationale and alternatives |
| **Design Patterns** | `docs_dev/design/patterns.md` | Track patterns applied to system |
| **Technology Stack** | `docs_dev/design/stack.md` | Record technology choices |
| **Constraints Registry** | `docs_dev/design/constraints.md` | Track discovered constraints |
| **Open Questions** | `docs_dev/design/open-questions.md` | Track unresolved questions |
| **Session State** | `.claude/eaa-session-state.local.md` | Current session context |
| **Design Index** | `docs_dev/design/index.json` | Quick lookup of all artifacts |
| **Handoff Documents** | `docs_dev/design/handoffs/handoff-{timestamp}.md` | Context transfer documents |

## 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:

| Content Type | Location | Format |
|--------------|----------|--------|
| Architecture decisions | `docs_dev/design/decisions/` | Markdown files |
| Design patterns | `docs_dev/design/patterns.md` | Markdown |
| Technology stack | `docs_dev/design/stack.md` | Markdown |
| Constraints registry | `docs_dev/design/constraints.md` | Markdown |
| Open questions | `docs_dev/design/open-questions.md` | Markdown |
| Session state | `.claude/eaa-session-state.local.md` | YAML frontmatter + Markdown |
| Handoff documents | `docs_dev/design/handoffs/` | Markdown files |

## Memory Retrieval Triggers

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

| Trigger | Condition | Action |
|---------|-----------|--------|
| **Session Start** | New Claude Code session begins | Load session state and design index |
| **Design Work Request** | Receiving a design request | Retrieve relevant decisions, constraints, and questions |
| **Architecture Decision Needed** | Design choice requires explicit decision | Retrieve existing decisions and constraints |
| **Design Review Request** | Design document submitted for review | Verify consistency with decisions and constraints |
| **Handoff Creation Request** | Session handoff needed | Package complete session context |

## Memory Update Triggers

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

| Trigger | Condition | Action |
|---------|-----------|--------|
| **Architecture Decision Made** | New architecture decision finalized | Create decision record, update index |
| **Design Pattern Selected** | Pattern chosen for component/module | Add pattern entry, update index |
| **Technology Stack Choice Made** | Technology selected for stack | Add entry to stack.md |
| **Constraint Discovered** | New constraint identified | Add to constraints.md, update index |
| **Open Question Identified** | Question arises that cannot be resolved | Add to open-questions.md |
| **Open Question Resolved** | Previously open question resolved | Update status to RESOLVED |
| **Session State Change** | Any significant session activity | Update session state file |

## 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

| Type | Purpose | Target |
|------|---------|--------|
| `session_continuity` | Continue work in new session | Future EAA session |
| `orchestrator_handoff` | Design approved, ready for implementation | EOA (via EAMA) |
| `context_clear` | Save state before context window reset | Future EAA session |

### 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

| Error | Cause | Solution |
|-------|-------|----------|
| Session state file not found | First session or file deleted | Initialize new session state file |
| Design index corrupted | Manual edit or system error | Regenerate index from decision files |
| Handoff document incomplete | Interrupted creation | Re-run handoff creation procedure |
| Decision file missing | Referenced but not found | Check file path, restore from backup if available |
| Constraint ID conflict | Duplicate ID generated | Use higher sequence number, update index |

## 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:

| Reference | Description |
|-----------|-------------|
| [record-keeping-formats.md](references/record-keeping-formats.md) | Session record-keeping formats and file structure specifications |

## Resources

| Resource | Location |
|----------|----------|
| Session state file | `.claude/eaa-session-state.local.md` |
| Design index | `docs_dev/design/index.json` |
| Decisions directory | `docs_dev/design/decisions/` |
| Patterns registry | `docs_dev/design/patterns.md` |
| Technology stack | `docs_dev/design/stack.md` |
| Constraints registry | `docs_dev/design/constraints.md` |
| Open questions | `docs_dev/design/open-questions.md` |
| Handoff documents | `docs_dev/design/handoffs/` |

## 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](https://tomevault.io/claim/emasoft) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-14 -->