Agent Memory System

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 workEach 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 avoidEach 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 issuesDocuments:

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

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 contextAutomatically suggests relevant gotchas based on:

Current file/directory
Active story
Recent error messages

Auto-Capture

Gotchas are automatically captured when:

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

State Persistence

Session State

Session Files

string

.aiox/session-{timestamp}.yamlContains:

Active agent
Current story
Command history
Permission mode
Context snapshots

Build State

Build State Files

string

.aiox/build-state/{story-id}.jsonTracks:

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:

After command completion - Update Recent Work
On pattern discovery - Add to Learned Patterns
On issue resolution - Add to Gotchas
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

Team Memory

Committed Memory

string

MEMORY.md files are committed to repositoryShared 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 patternsTriggers:

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.mdValidates:

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

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

Configuration

Agent System

Templates & Tasks

Overview

Memory File Structure

Memory Categories

Recent Context

Learned Patterns

Gotchas

Decision Log

Gotchas Memory System

Gotcha Structure

Gotcha Commands

Auto-Capture

State Persistence

Session State

Build State

Recovery State

Memory Operations

Reading Memory

Writing Memory

Memory Cleanup

Team Memory

Personal Memory

Memory Intelligence Features

Pattern Learning

Context Awareness

Memory Validation

Best Practices

Configuration

Agent System

Templates & Tasks

Documentation Index

​Overview

​Memory File Structure

​Memory Categories

​Recent Context

​Learned Patterns

​Gotchas

​Decision Log

​Gotchas Memory System

​Gotcha Structure

​Gotcha Commands

​Auto-Capture

​State Persistence

​Session State

​Build State

​Recovery State

​Memory Operations

​Reading Memory

​Writing Memory

​Memory Cleanup

​Memory Sharing

​Team Memory

​Personal Memory

​Memory Intelligence Features

​Pattern Learning

​Context Awareness

​Memory Validation

​Best Practices

​Related Documentation

Overview

Memory File Structure

Memory Categories

Recent Context

Learned Patterns

Gotchas

Decision Log

Gotchas Memory System

Gotcha Structure

Gotcha Commands

Auto-Capture

State Persistence

Session State

Build State

Recovery State

Memory Operations

Reading Memory

Writing Memory

Memory Cleanup

Memory Sharing

Team Memory

Personal Memory

Memory Intelligence Features

Pattern Learning

Context Awareness

Memory Validation

Best Practices

Related Documentation