# Memory System README

## Overview

The memory/ directory provides persistent cross-session context for OpenCode agents. This enables continuity and learning over time.

## Structure

```
memory/
├── _templates/                  # Document templates
│   ├── spec.md                 # Template for task specifications
│   ├── research.md             # Template for research documents
│   └── session.md              # Template for session memory
├── memory.md                    # Current project state and session learnings
├── todo.md                      # Task tracking and progress
├── development-guidelines.md    # Code conventions and patterns
├── architecture-decisions.md    # Why we built it this way
├── blockers.md                  # Known issues and workarounds
│
├── research/                    # Research findings and analysis
│   ├── YYYY-MM-DD-topic.md     # Research documents
│   └── cache-topic.md          # Research cache files
│
├── design-guidelines.md        # Design system and UI standards
├── decisions/                   # Architectural decision records
│   └── database-choice.md       # Example: Why PostgreSQL
│
└── plans/                       # Strategic planning documents
    └── q4-roadmap.md            # Example: Quarterly objectives
```

**Subdirectories:** Use to organize knowledge by category and prevent flat directory bloat.

## Usage

### For Agents

**At Session Start:**

1. Read `memory.md` for current project context
2. Check `todo.md` for active tasks
3. Review `blockers.md` for known issues

**During Session:**

- Consult `development-guidelines.md` for coding standards
- Reference `architecture-decisions.md` for design rationale
- Reference `design-guidelines.md` for design standards
- Update progress in `todo.md`
- Save research to `research/YYYY-MM-DD-topic.md` (auto-created by /research command)
- Document decisions in `decisions/choice-name.md`
- Create specs using templates from `_templates/spec.md`

**At Session End:**

- Update `memory.md` with new learnings
- Mark completed tasks in `todo.md`
- Document new blockers or resolve existing ones

### For Humans

**Quick Status Check:**

```bash
# See current state
cat memory/memory.md

# Check active tasks
cat memory/todo.md

# Review blockers
cat memory/blockers.md
```

**Update Memory:**
Edit files directly or use memory-update tool - agents will read on next session.

**Examples:**

```bash
# Read research notes
memory-read research/opencode-sessions

# Create new research note
memory-update research/new-topic content="# Research Notes\n..."

# Add decision record
memory-update decisions/database-choice content="# Why PostgreSQL\n..."

# Tools auto-create subdirectories and strip .md extension
```

## Memory Lifecycle

### Compaction (When memory.md > 5000 words)

1. Distill to critical facts only
2. Archive detailed history to dated file: `memory-archive-YYYY-MM-DD.md`
3. Keep current state lean and focused

### Rotation

- Archive completed tasks monthly
- Move resolved blockers to history section
- Keep active memory under 5000 words

## Integration Points

- **Plan Agent:** Reads memory.md before creating plans
- **Build Agent:** Updates memory.md after major completions
- **All Agents:** Consult development-guidelines.md for standards
- **Design Agent:** Consults design-guidelines.md for design standards

## Best Practices

1. **Be Specific:** "Uses React 18 Server Components" vs "Uses React"
2. **Date Decisions:** Track when and why choices were made
3. **Keep Current:** Update after significant progress, not every trivial change
4. **Prune Regularly:** Remove obsolete information
5. **Link Context:** Reference related files/specs when relevant

## Future Enhancements

- Automatic memory compaction triggers
- Memory-read and memory-update tools
- Integration with task ledgers
- Progress monitoring and re-planning triggers
