Project Memory

Maintain institutional knowledge across your project lifecycle and team members.

When to Use This Skill

Use when:

• Setting up project memory system for first time
• Documenting architectural decisions and rationale
• Tracking bugs, solutions, and prevention measures
• Maintaining key project facts and configuration
• Logging completed work and milestones
• Configuring AGENT.md with memory protocols
• Quarterly review and refresh of project knowledge

Core Capabilities

1. Memory Infrastructure - Create docs/project_notes/ structure
2. Bugs Management - Document bugs, root causes, solutions, prevention
3. Decision Records - Architectural Decision Records (ADRs) with context
4. Key Facts - Configuration, URLs, ports, credentials pointers
5. Work Tracking - Log completed tickets and milestones
6. Agent Integration - Configure AGENT.md for memory-aware behavior
7. Knowledge Maintenance - Quarterly refresh and pruning

Memory System Structure

Directory Layout

docs/
└── project_notes/
    ├── bugs.md           # 50-100 bug entries, solutions
    ├── decisions.md      # 5-15 architectural decisions
    ├── key_facts.md      # Configuration, URLs, facts
    └── tracks.md         # Work log with ticket references

Why docs/project_notes/?

• Standard engineering organization (not AI-specific)
• Clear purpose for all team members
• Coexists with other documentation

File Purposes

Reference Guide

Project Memory Setup & Management

Use when: Creating or maintaining project memory

Covers:

• Initial memory setup and directory structure
• Template content for each memory file
• Configuring AGENT.md with memory protocols
• Searching and updating memory files
• Quarterly refresh process
• Cross-referencing patterns

Quick Start

For New Projects

1. Create docs/project_notes/ directory
2. Create 4 memory files (bugs.md, decisions.md, key_facts.md, tracks.md)
3. Add templates from reference guide
4. Configure AGENT.md with memory section
5. Start documenting as you work

For Existing Projects

1. Review existing documentation
2. Consolidate into 4 memory files
3. Add AGENT.md configuration
4. Set quarterly refresh reminders
5. Migrate as you encounter issues

Memory File Content

bugs.md Structure

### YYYY-MM-DD - Brief Description
- **Issue**: What went wrong
- **Root Cause**: Why it happened
- **Solution**: How it was fixed
- **Prevention**: How to avoid in future

Example:

### 2025-01-25 - Database Connection Timeout
- **Issue**: API requests timing out after 30s
- **Root Cause**: Connection pool default timeout was 30s, too low
- **Solution**: Increased timeout to 300s, added connection validation
- **Prevention**: Monitor connection pool metrics in staging

decisions.md Structure (ADR Format)

### ADR-XXX: Decision Title (YYYY-MM-DD)

**Context**: Why decision was needed

**Decision**: What was chosen

**Alternatives**: What was rejected and why

**Consequences**: Benefits and trade-offs

key_facts.md Structure

## Category Name
- **Item**: Value
- **URL**: Link
- **Port**: Number
- **Config**: Setting

## Database
- Host: prod-db.aws.region
- Port: 5432
- Failover: automatic

## Local Development
- Database: Docker (PostgreSQL)
- Port: 5432
- URL: localhost:5432

tracks.md Structure

### YYYY-MM-DD - TICKET-ID: Brief Title
- **Status**: Completed / In Progress / Blocked
- **Description**: What was done
- **URL**: Link to ticket/PR
- **Notes**: Key learnings or blockers

Integration with AGENT.md

Add memory section to AGENT.md:

## Project Memory System
This project maintains institutional knowledge in docs/project_notes/.

### Memory-Aware Protocols
- Before proposing architectural changes: Check decisions.md
- When encountering errors: Search bugs.md for solutions
- When looking up configuration: Check key_facts.md
- When completing work: Log in tracks.md

Best Practices

• ✅ Document as you go: Don't wait until end of week
• ✅ Include rationale: Why, not just what
• ✅ Use dates: Temporal context matters
• ✅ Link references: Cross-reference related entries
• ✅ Never store secrets: Use secure vaults, document access
• ✅ Quarterly refresh: Keep information current
• ✅ Human-readable: Write for team members reading later

Common Patterns

Bug Discovery Workflow

1. Encounter bug
2. Search bugs.md for similar issues
3. If found, apply known solution
4. If new, investigate and document
5. Log in bugs.md with solution and prevention

Decision Making Workflow

1. Face architectural decision
2. Check decisions.md for related decisions
3. Consider alternatives
4. Document in ADR format
5. Reference from code/documentation

Configuration Reference

1. Need to look up config
2. Check key_facts.md
3. If not found, document
4. Share with team
5. Link from AGENT.md

Quarterly Maintenance

Every quarter:

1. bugs.md - Archive solved bugs, update documentation
2. decisions.md - Review if decisions still valid, update if needed
3. key_facts.md - Verify URLs, ports, facts still current
4. tracks.md - Archive previous quarter, start fresh

Success Metrics

Good project memory:

• ✅ Team refers to decisions.md before proposing changes
• ✅ Similar bugs don't get re-discovered
• ✅ New team members find onboarding info
• ✅ Configuration is never lost or repeated
• ✅ Work completed is documented for reference

Dependencies

• context-engineer - For context capture and preservation
• state-manager - For state and configuration management