Agent Memory System

Reference for AIOX agent memory, state persistence, and context management

Overview

AIOX agents maintain persistent memory across sessions through dedicated MEMORY.md files and state management systems. This enables agents to learn, adapt, and maintain context between interactions.

Memory Location · string

.aiox-core/development/agents/{agent-id}/MEMORY.md

Mutability · string

Editable - MEMORY.md files are in the L3 (exceptions) layer

Git Status · string

Committed - Team-shared learnings are version controlled

Memory File Structure

Each agent has a dedicated MEMORY.md file:

# {Agent Name} Memory

Last Updated: {timestamp}

## Recent Context

### Current Session
- Active story: {story-id}
- Current branch: {branch-name}
- Last command: {command}
- Timestamp: {iso-8601}

### Recent Work
- {timestamp}: Completed {task} for {story}
- {timestamp}: Fixed {issue} in {file}

## Learned Patterns

### Code Patterns
- Pattern: {name}
  Context: {when-to-use}
  Example: {code-snippet}

### Anti-Patterns Encountered
- Anti-pattern: {name}
  Issue: {problem}
  Solution: {resolution}

## Gotchas

### Build Issues
- Issue: {description}
  Cause: {root-cause}
  Solution: {fix}
  Frequency: {count}

### Integration Issues
- Issue: {description}
  Context: {when-occurs}
  Workaround: {solution}

## Decision Log

### Architecture Decisions
- Decision: {title}
  Rationale: {reasoning}
  Date: {timestamp}
  Story: {story-id}

### Technology Choices
- Technology: {name}
  Why chosen: {rationale}
  Alternatives considered: {options}

## Team Learnings

### Best Practices
- Practice: {description}
  Context: {when-to-apply}
  Source: {story-id or reference}

### Lessons Learned
- Lesson: {what-learned}
  Context: {situation}
  Impact: {result}

Memory Categories

Recent Context

Current Session · object

Active session state

Show properties

active_story · string

Currently active user story

current_branch · string

Active git branch

last_command · string

Most recent command executed

timestamp · string

ISO 8601 timestamp of last update

Recent Work · array

Chronological log of completed work

Each entry includes:

• Timestamp
• Task/action completed
• Associated story
• Key files modified

Learned Patterns

Code Patterns · array

Reusable code patterns discovered during work

Show pattern schema

name · string · required

Pattern identifier

context · string · required

When to apply this pattern

example · string · required

Code snippet demonstrating pattern

source · string

Story or file where pattern was learned

Anti-Patterns Encountered · array

Code anti-patterns to avoid

Each entry documents:

• Anti-pattern name
• Problem caused
• Recommended solution
• Where encountered

Gotchas

Build Issues · array

Build-related problems and solutions

Show gotcha schema

description · string · required

Brief issue description

cause · string · required

Root cause analysis

solution · string · required

Fix or workaround

frequency · number

Number of times encountered

severity · string

Impact level: low, medium, high, critical

Integration Issues · array

Integration and dependency issues

Documents:

• External API issues
• Library incompatibilities
• Environment-specific problems
• Configuration gotchas

Decision Log

Architecture Decisions · array

Informal architecture decisions (not full ADRs)

Show decision schema

title · string · required

Decision summary

rationale · string · required

Why this decision was made

date · string · required

ISO 8601 timestamp

story · string

Associated story ID

alternatives · array

Other options considered

Technology Choices · array

Technology and library selections

Documents:

• Why technology was chosen
• Alternatives evaluated
• Trade-offs accepted
• Integration considerations

Gotchas Memory System

The Gotchas Memory System is an enhanced memory subsystem for capturing and retrieving project-specific issues:

Gotcha Structure

id: gotcha-{timestamp}
title: {short-description}
category: build|test|deploy|integration|config
severity: low|medium|high|critical
frequency: {occurrence-count}
context:
  story: {story-id}
  file: {file-path}
  timestamp: {iso-8601}
issue: |
  {detailed-description}
cause: |
  {root-cause-analysis}
solution: |
  {fix-or-workaround}
autoCaptured: true|false
tags:
  - {tag1}
  - {tag2}

Gotcha Commands

*gotcha · command

Manually add a gotcha

*gotcha Build fails with TypeScript errors - Missing type definitions

*gotchas · command

Search and list gotchas

*gotchas                          # List all
*gotchas --category=build         # Filter by category
*gotchas --severity=high          # Filter by severity
*gotchas --search="typescript"    # Text search

*gotcha-context · command

Get relevant gotchas for current context

Automatically suggests relevant gotchas based on:

• Current file/directory
• Active story
• Recent error messages

Auto-Capture

Gotchas are automatically captured when:

1. Build fails multiple times (≥2 failures)
2. Tests fail with same error pattern
3. Agent encounters same issue multiple times
4. Error patterns match known signatures

State Persistence

Session State

Session Files · string

.aiox/session-{timestamp}.yaml

Contains:

• Active agent
• Current story
• Command history
• Permission mode
• Context snapshots

Build State

Build State Files · string

.aiox/build-state/{story-id}.json

Tracks:

• Implementation plan
• Completed subtasks
• Current checkpoint
• Attempt history
• Test results

Recovery State

Recovery Files · string

.aiox/recovery/{story-id}/

Contains:

• attempts.json - Implementation attempt history
• approach.md - Current approach documentation
• checkpoints/ - Git checkpoints for rollback

Memory Operations

Reading Memory

Agents automatically load MEMORY.md on activation:

activation-instructions:
  - STEP 1: Read THIS ENTIRE FILE
  - STEP 1.5: Load MEMORY.md if exists
  - STEP 2: Adopt persona
  - STEP 3: Display greeting

Writing Memory

Memory is updated:

1. After command completion - Update Recent Work
2. On pattern discovery - Add to Learned Patterns
3. On issue resolution - Add to Gotchas
4. On decision made - Add to Decision Log

Memory Cleanup

Automatic Cleanup · string

Old entries are archived after:

• Recent Work: 30 days
• Session State: 7 days (stale TTL)
• Build State: After merge

Memory Sharing

Team Memory

Committed Memory · string

MEMORY.md files are committed to repository

Shared across team:

• Learned patterns
• Gotchas
• Decision log
• Best practices

Personal Memory

Local Memory · string

Session-specific state in .aiox/ (gitignored)

Personal only:

• Session history
• Command history
• Personal preferences

Memory Intelligence Features

Pattern Learning

Automatic Pattern Extraction · feature

Agent analyzes code changes to identify reusable patterns

Triggers:

• Similar code written 3+ times
• Successful problem resolution
• Team member code review feedback

Context Awareness

Smart Context Loading · feature

Agent loads relevant memory based on:

• Current story
• Current file/directory
• Command being executed
• Recent failures

Memory Validation

Memory Audit Checklist · checklist

Location: .aiox-core/development/checklists/memory-audit-checklist.md

Validates:

• Memory file structure
• Entry completeness
• Pattern validity
• Gotcha accuracy

Best Practices

Memory Maintenance

• Update MEMORY.md after significant learnings
• Review and clean up old entries monthly
• Ensure gotchas include clear solutions
• Document why decisions were made, not just what
• Use consistent terminology and categories

Gotcha Management

• Capture gotchas immediately when discovered
• Include reproduction steps
• Document root cause, not just symptoms
• Update frequency counter when recurring
• Link to related stories/PRs

Pattern Documentation

• Include complete, runnable examples
• Explain when to use vs. when not to use
• Reference source story or documentation
• Update patterns as conventions evolve
• Remove deprecated patterns

Related Documentation

• Agent Definition Files
• Agent Commands
• Gotchas System
• State Management

---

Reference: .aiox-core/development/agents/*/MEMORY.md