> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

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

<ParamField path="Memory Location" type="string">
  `.aiox-core/development/agents/{agent-id}/MEMORY.md`
</ParamField>

<ParamField path="Mutability" type="string">
  **Editable** - MEMORY.md files are in the L3 (exceptions) layer
</ParamField>

<ParamField path="Git Status" type="string">
  **Committed** - Team-shared learnings are version controlled
</ParamField>

## Memory File Structure

Each agent has a dedicated MEMORY.md file:

```markdown theme={null}
# {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

<ParamField path="Current Session" type="object">
  Active session state

  <Expandable title="properties">
    <ResponseField name="active_story" type="string">
      Currently active user story
    </ResponseField>

    <ResponseField name="current_branch" type="string">
      Active git branch
    </ResponseField>

    <ResponseField name="last_command" type="string">
      Most recent command executed
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO 8601 timestamp of last update
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="Recent Work" type="array">
  Chronological log of completed work

  Each entry includes:

  * Timestamp
  * Task/action completed
  * Associated story
  * Key files modified
</ParamField>

### Learned Patterns

<ParamField path="Code Patterns" type="array">
  Reusable code patterns discovered during work

  <Expandable title="pattern schema">
    <ResponseField name="name" type="string" required>
      Pattern identifier
    </ResponseField>

    <ResponseField name="context" type="string" required>
      When to apply this pattern
    </ResponseField>

    <ResponseField name="example" type="string" required>
      Code snippet demonstrating pattern
    </ResponseField>

    <ResponseField name="source" type="string">
      Story or file where pattern was learned
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="Anti-Patterns Encountered" type="array">
  Code anti-patterns to avoid

  Each entry documents:

  * Anti-pattern name
  * Problem caused
  * Recommended solution
  * Where encountered
</ParamField>

### Gotchas

<ParamField path="Build Issues" type="array">
  Build-related problems and solutions

  <Expandable title="gotcha schema">
    <ResponseField name="description" type="string" required>
      Brief issue description
    </ResponseField>

    <ResponseField name="cause" type="string" required>
      Root cause analysis
    </ResponseField>

    <ResponseField name="solution" type="string" required>
      Fix or workaround
    </ResponseField>

    <ResponseField name="frequency" type="number">
      Number of times encountered
    </ResponseField>

    <ResponseField name="severity" type="string">
      Impact level: `low`, `medium`, `high`, `critical`
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="Integration Issues" type="array">
  Integration and dependency issues

  Documents:

  * External API issues
  * Library incompatibilities
  * Environment-specific problems
  * Configuration gotchas
</ParamField>

### Decision Log

<ParamField path="Architecture Decisions" type="array">
  Informal architecture decisions (not full ADRs)

  <Expandable title="decision schema">
    <ResponseField name="title" type="string" required>
      Decision summary
    </ResponseField>

    <ResponseField name="rationale" type="string" required>
      Why this decision was made
    </ResponseField>

    <ResponseField name="date" type="string" required>
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="story" type="string">
      Associated story ID
    </ResponseField>

    <ResponseField name="alternatives" type="array">
      Other options considered
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField path="Technology Choices" type="array">
  Technology and library selections

  Documents:

  * Why technology was chosen
  * Alternatives evaluated
  * Trade-offs accepted
  * Integration considerations
</ParamField>

## Gotchas Memory System

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

### Gotcha Structure

```yaml theme={null}
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

<ResponseField name="*gotcha" type="command">
  Manually add a gotcha

  ```bash theme={null}
  *gotcha Build fails with TypeScript errors - Missing type definitions
  ```
</ResponseField>

<ResponseField name="*gotchas" type="command">
  Search and list gotchas

  ```bash theme={null}
  *gotchas                          # List all
  *gotchas --category=build         # Filter by category
  *gotchas --severity=high          # Filter by severity
  *gotchas --search="typescript"    # Text search
  ```
</ResponseField>

<ResponseField name="*gotcha-context" type="command">
  Get relevant gotchas for current context

  Automatically suggests relevant gotchas based on:

  * Current file/directory
  * Active story
  * Recent error messages
</ResponseField>

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

<ParamField path="Session Files" type="string">
  `.aiox/session-{timestamp}.yaml`

  Contains:

  * Active agent
  * Current story
  * Command history
  * Permission mode
  * Context snapshots
</ParamField>

### Build State

<ParamField path="Build State Files" type="string">
  `.aiox/build-state/{story-id}.json`

  Tracks:

  * Implementation plan
  * Completed subtasks
  * Current checkpoint
  * Attempt history
  * Test results
</ParamField>

### Recovery State

<ParamField path="Recovery Files" type="string">
  `.aiox/recovery/{story-id}/`

  Contains:

  * `attempts.json` - Implementation attempt history
  * `approach.md` - Current approach documentation
  * `checkpoints/` - Git checkpoints for rollback
</ParamField>

## Memory Operations

### Reading Memory

Agents automatically load MEMORY.md on activation:

```yaml theme={null}
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

<ResponseField name="Automatic Cleanup" type="string">
  Old entries are archived after:

  * Recent Work: 30 days
  * Session State: 7 days (stale TTL)
  * Build State: After merge
</ResponseField>

## Memory Sharing

### Team Memory

<ParamField path="Committed Memory" type="string">
  MEMORY.md files are committed to repository

  **Shared across team:**

  * Learned patterns
  * Gotchas
  * Decision log
  * Best practices
</ParamField>

### Personal Memory

<ParamField path="Local Memory" type="string">
  Session-specific state in `.aiox/` (gitignored)

  **Personal only:**

  * Session history
  * Command history
  * Personal preferences
</ParamField>

## Memory Intelligence Features

### Pattern Learning

<ResponseField name="Automatic Pattern Extraction" type="feature">
  Agent analyzes code changes to identify reusable patterns

  **Triggers:**

  * Similar code written 3+ times
  * Successful problem resolution
  * Team member code review feedback
</ResponseField>

### Context Awareness

<ResponseField name="Smart Context Loading" type="feature">
  Agent loads relevant memory based on:

  * Current story
  * Current file/directory
  * Command being executed
  * Recent failures
</ResponseField>

### Memory Validation

<ResponseField name="Memory Audit Checklist" type="checklist">
  Location: `.aiox-core/development/checklists/memory-audit-checklist.md`

  Validates:

  * Memory file structure
  * Entry completeness
  * Pattern validity
  * Gotcha accuracy
</ResponseField>

## Best Practices

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Agent Definition Files](/api/agent-definition)
* [Agent Commands](/api/agent-commands)
* [Gotchas System](/guides/gotchas)
* [State Management](/guides/state-management)

***

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