---
name: memory
description: Persistent cross-session memory system for project context. Use at session start to load active context, during work to persist learnings, and after completion to archive knowledge. Follows project-first hierarchy (.opencode/memory/ overrides ~/.config/opencode/memory/).
---

# Memory System

Persistent cross-session context management for maintaining project state across sessions.

## When to Use This Skill

### Session Start (Auto-trigger)

- Load memory.md for active context
- Load development-guidelines.md for code conventions
- Check architecture-decisions.md for design constraints
- Review blockers.md for known issues

### During Work

- Update memory.md when learning new patterns
- Add to architecture-decisions.md when making design choices
- Document blockers.md when hitting obstacles
- Update todo.md for task tracking

### After Completion

- Extract learnings to memory.md
- Archive session ledgers
- Update development-guidelines.md with new conventions

## Memory Layer Structure

**Location Priority (follows OpenCode config pattern):**

1. `.opencode/memory/` - Project-specific memory (takes precedence)
2. `~/.config/opencode/memory/` - Global shared memory (fallback)

**Core Files:**

- `memory.md` - Active session context (project state, current focus)
- `development-guidelines.md` - Code conventions (language patterns, project standards)
- `architecture-decisions.md` - Design constraints (why choices made)
- `blockers.md` - Known issues (what's not working)
- `todo.md` - Task tracking (what's next)

**Subdirectories (Recommended for Organization):**

- `research/` - Research findings (e.g., `research/opencode-sessions.md`)
- `decisions/` - Architectural decision records (e.g., `decisions/database-choice.md`)
- `plans/` - Strategic planning documents (e.g., `plans/q4-roadmap.md`)

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

## Tools Used

This skill orchestrates two MCP tools:

- `memory-read` - Read memory files (project-first, fallback to global)
- `memory-update` - Update memory files (always project-specific)

## Workflow

### Session Start Protocol

```
1. memory-read memory
2. memory-read development-guidelines
3. (Optional) memory-read architecture-decisions
4. (Optional) memory-read blockers
5. (Optional) memory-read todo
6. (Optional) memory-read research/topic-name  # For specific research
```

### During Work

```
When learning new pattern:
  memory-update memory mode=append content="..."

When making design decision:
  memory-update architecture-decisions mode=append content="..."

When hitting blocker:
  memory-update blockers mode=append content="..."

When researching topic:
  memory-update research/topic-name content="..."  # Auto-creates subdirectory
```

### After Completion

```
1. Extract learnings: memory-update memory mode=replace
2. Archive ledgers: Move to plans/archive/
3. Update guidelines: memory-update development-guidelines
```

## Integration with Workflows

### Agentic Workflow System

```
Memory (Persistent) → Backlog (Multi-session) → Ledgers (Session)
.opencode/memory/      backlog/tasks/            plans/ledgers/
```

### Subagent Development

- @plan reads memory for constraints
- @code-auditor reads architecture-decisions for review criteria
- @researcher reads todo for context

### Commands

- `/commit` - Reads memory for commit message style
- `/pr` - Reads memory for PR context
- `/review/codebase` - Updates architecture-decisions

## Best Practices

### Global vs Project Memory

**Global memory (~/.config/opencode/memory/):**

- Universal principles (POSIX compatibility)
- Security constraints (no sudo)
- Cross-project patterns (git workflows)
- Shared learnings across all projects

**Project memory (.opencode/memory/):**

- Tech stack specifics (Spring Boot 2.6, MySQL 8.0)
- Domain knowledge (business rules)
- Active work (current phase, blockers)
- Project-specific conventions

### When to Update

✅ **DO update memory when:**

- Learning new pattern specific to this project
- Making architectural decision
- Hitting blocker that affects future work
- Completing major feature (extract learnings)

❌ **DON'T update memory when:**

- Implementing obvious code changes
- Following existing patterns
- Making trivial fixes

## Anti-Patterns

- ❌ Skip memory read at session start
- ❌ Ignore architecture-decisions.md constraints
- ❌ Forget to archive ledgers after completion
- ❌ Mix project-specific and global knowledge
- ❌ Update memory with every minor change

## Quick Reference

```bash
# Read active context
memory-read memory

# Read research findings
memory-read research/opencode-sessions

# Update with new learning
memory-update memory mode=append content="## New Pattern\n..."

# Create research note (auto-creates subdirectory)
memory-update research/topic-name content="# Research Notes\n..."

# Replace entire file
memory-update memory mode=replace content="# Memory\n..."

# Note: Tool automatically strips .md extension if provided
# memory-update research/topic.md → .opencode/memory/research/topic.md ✅
# memory-update research/topic   → .opencode/memory/research/topic.md ✅
```

## Location Resolution

**Read priority:**

1. `$PWD/.opencode/memory/${file}.md` (project memory)
2. `$HOME/.config/opencode/memory/${file}.md` (global fallback)
3. `$PWD/.config/opencode/memory/${file}.md` (legacy location - backward compat)

**Write destination:**

- Always `$PWD/.opencode/memory/${file}.md` (project-specific)

This ensures project isolation while preserving global knowledge sharing.
