Project Memory

Project Memory

Table of Contents

• Overview
• When to Use This Skill
• Core Capabilities
  • 1. Initial Setup - Create Memory Infrastructure
  • 2. Configure CLAUDE.md - Memory-Aware Behavior
  • 3. Configure AGENTS.md - Multi-Tool Support
  • 4. Searching Memory Files
  • 5. Updating Memory Files
  • 6. Memory File Maintenance
• Templates and References
• Example Workflows
• Integration with Other Skills
• Success Criteria

Overview

Maintain institutional knowledge for projects by establishing a structured memory system in docs/project_notes/. This skill sets up four key memory files (bugs, decisions, key facts, issues) and configures CLAUDE.md and AGENTS.md to automatically reference and maintain them. The result is a project that remembers past decisions, solutions to problems, and important configuration details across coding sessions and across different AI tools.

When to Use This Skill

Invoke this skill when:

• Starting a new project that will accumulate knowledge over time
• The project already has recurring bugs or decisions that should be documented
• The user asks to "set up project memory" or "track our decisions"
• The user wants to log a bug fix, architectural decision, or completed work
• Encountering a problem that feels familiar ("didn't we solve this before?")
• Before proposing an architectural change (check existing decisions first)
• Working on projects with multiple developers or AI tools (Claude Code, Cursor, etc.)

Core Capabilities

0. MANDATORY: Automatic Memory Protocols

These protocols are NON-NEGOTIABLE. Agents MUST follow them automatically without user prompting.

Automatic Memory LOOKUP (Before Problem Solving)

TRIGGER - Search memory BEFORE acting when:

• Encountering ANY error message or exception
• Build or test failure occurs
• Looking up project configuration
• Making an architectural decision
• Debugging unexpected behavior
• Starting work on an unfamiliar part of the codebase

ACTION (MANDATORY):

# Search all memory files for relevant context
grep -r -i "keyword" docs/project_notes/

REQUIREMENTS:

• Agent MUST search memory BEFORE attempting any fix
• Agent MUST cite memory if relevant entry found: "Found in bugs.md (2026-01-21): [solution]"
• If no relevant entry found, proceed with normal debugging
• NEVER rediscover solutions already documented in memory files

ANTI-PATTERN (BLOCKING):

• Attempting fixes without searching memory first
• Proposing architecture without checking decisions.md
• Guessing configuration instead of checking key_facts.md

Automatic Memory RECORDING (After Verified Solutions)

TRIGGER - Record to memory when ALL conditions are met:

1. Problem was SOLVED (not just attempted)
2. Solution was VERIFIED working (tests pass, build succeeds, functionality confirmed)
3. Knowledge has reuse potential (not a one-off typo fix)

VERIFICATION REQUIREMENTS (must demonstrate before recording):

WHAT TO RECORD (all 5 types):

RECORDING FORMAT (bugs.md):

### YYYY-MM-DD - Brief Description
- **Issue**: What went wrong (exact error message if relevant)
- **Root Cause**: WHY it happened (not just what was changed)
- **Solution**: HOW to fix (include commands/code if helpful)
- **Prevention**: How to avoid in future
- **Verified**: How solution was verified (e.g., "Tests pass", "Build succeeds")

ANTI-PATTERNS (DO NOT RECORD):

SELF-CHECK BEFORE RECORDING:

1. ✅ Can I reproduce the problem?
2. ✅ Does my fix consistently work?
3. ✅ Do I understand WHY it works?
4. ✅ Would another agent benefit from this knowledge?

If ANY answer is NO → DO NOT RECORD.

1. Initial Setup - Create Memory Infrastructure

When invoked for the first time in a project, create the following structure:

docs/
└── project_notes/
    ├── bugs.md         # Bug log with solutions
    ├── decisions.md    # Architectural Decision Records
    ├── key_facts.md    # Project configuration and constants
    └── issues.md       # Work log with ticket references

Directory naming rationale: Using docs/project_notes/ instead of memory/ makes it look like standard engineering organization, not AI-specific tooling. This increases adoption and maintenance by human developers.

Initial file content: Copy templates from the references/ directory in this skill:

• Use references/bugs_template.md for initial bugs.md
• Use references/decisions_template.md for initial decisions.md
• Use references/key_facts_template.md for initial key_facts.md
• Use references/issues_template.md for initial issues.md

Each template includes format examples and usage tips.

2. Configure CLAUDE.md - Memory-Aware Behavior

Add or update the following section in the project's CLAUDE.md file:

## Project Memory System

This project maintains institutional knowledge in `docs/project_notes/` for consistency across sessions.

### Memory Files

- **bugs.md** - Bug log with dates, solutions, and prevention notes
- **decisions.md** - Architectural Decision Records (ADRs) with context and trade-offs
- **key_facts.md** - Project configuration, credentials, ports, important URLs
- **issues.md** - Work log with ticket IDs, descriptions, and URLs

### Memory-Aware Protocols (MANDATORY)

**⚠️ These are NOT suggestions - they are REQUIREMENTS that agents MUST follow automatically.**

**BEFORE proposing architectural changes (MANDATORY):**
1. Search `docs/project_notes/decisions.md` for existing decisions
2. If conflict found → acknowledge existing decision, explain why change is warranted
3. If no conflict → proceed, then record new decision after implementation verified

**WHEN encountering errors or bugs (MANDATORY):**
1. FIRST: Search `docs/project_notes/bugs.md` for similar issues
2. If found → apply documented solution, cite the entry
3. If not found → debug normally
4. After fix VERIFIED → record new entry in bugs.md with verification evidence

**WHEN looking up project configuration (MANDATORY):**
1. FIRST: Check `docs/project_notes/key_facts.md`
2. Use documented facts, NEVER guess or assume
3. If new config discovered → record in key_facts.md after verification

**WHEN completing work on tickets:**
- Log completed work in `docs/project_notes/issues.md`
- Include ticket ID, date, brief description, and URL

**WHEN solution is VERIFIED working:**
- Automatically record to appropriate memory file (no user prompt needed)
- Include verification evidence in the entry
- Follow format templates exactly

### Style Guidelines for Memory Files

- **Prefer bullet lists over tables** for simplicity and ease of editing
- **Keep entries concise** (1-3 lines for descriptions)
- **Always include dates** for temporal context
- **Include URLs** for tickets, documentation, monitoring dashboards
- **Manual cleanup** of old entries is expected (not automated)

3. Configure AGENTS.md - Multi-Tool Support

If the project has an AGENTS.md file (used for agent workflows or multi-tool projects), add the same memory protocols. This ensures consistency whether using Claude Code, Cursor, GitHub Copilot, or other AI tools.

If AGENTS.md exists: Add the same "Project Memory System" section as above.

If AGENTS.md doesn't exist: Ask the user if they want to create it. Many projects use multiple AI tools and benefit from shared memory protocols.

4. Searching Memory Files

When encountering problems or making decisions, proactively search memory files:

Search bugs.md:

# Look for similar errors
grep -i "connection refused" docs/project_notes/bugs.md

# Find bugs by date range
grep "2025-01" docs/project_notes/bugs.md

Search decisions.md:

# Check for decisions about a technology
grep -i "database" docs/project_notes/decisions.md

# Find all ADRs
grep "^### ADR-" docs/project_notes/decisions.md

Search key_facts.md:

# Find database connection info
grep -A 5 "Database" docs/project_notes/key_facts.md

# Look up service accounts
grep -i "service account" docs/project_notes/key_facts.md

Use Grep tool for more complex searches:

• Search across all memory files: Grep(pattern="oauth", path="docs/project_notes/")
• Context-aware search: Grep(pattern="bug", path="docs/project_notes/bugs.md", -A=3, -B=3)

5. Updating Memory Files

When the user requests updates or when documenting resolved issues, update the appropriate memory file:

Adding a bug entry (MUST include Verified field):

### YYYY-MM-DD - Brief Bug Description
- **Issue**: What went wrong (include exact error message if relevant)
- **Root Cause**: WHY it happened (not just what was changed)
- **Solution**: How it was fixed (include commands/code if helpful)
- **Prevention**: How to avoid it in the future
- **Verified**: How solution was confirmed working (e.g., "Tests pass", "Build succeeds", "Manual test: X works")

Adding a decision:

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

**Context:**
- Why the decision was needed
- What problem it solves

**Decision:**
- What was chosen

**Alternatives Considered:**
- Option 1 -> Why rejected
- Option 2 -> Why rejected

**Consequences:**
- Benefits
- Trade-offs

Adding key facts:

• Organize by category (GCP Project, Database, API, Local Development, etc.)
• Use bullet lists for clarity
• Include both production and development details
• Add URLs for easy navigation
• See references/key_facts_template.md for security guidelines on what NOT to store

Adding work log entry:

### YYYY-MM-DD - TICKET-ID: Brief Description
- **Status**: Completed / In Progress / Blocked
- **Description**: 1-2 line summary
- **URL**: https://jira.company.com/browse/TICKET-ID
- **Notes**: Any important context

6. Memory File Maintenance

Periodically clean old entries:

• User is responsible for manual cleanup (no automation)
• Remove very old bug entries (6+ months) that are no longer relevant
• Archive completed work from issues.md (3+ months old)
• Keep all decisions (they're lightweight and provide historical context)
• Update key_facts.md when project configuration changes

Conflict resolution:

• If proposing something that conflicts with decisions.md, explain why revisiting the decision is warranted
• Update the decision entry if the choice changes
• Add date of revision to show evolution

Templates and References

This skill includes template files in references/ that demonstrate proper formatting:

• references/bugs_template.md - Bug entry format with examples
• references/decisions_template.md - ADR format with examples
• references/key_facts_template.md - Key facts organization with examples (includes security guidelines)
• references/issues_template.md - Work log format with examples

When creating initial memory files, copy these templates to docs/project_notes/ and customize them for the project.

Example Workflows

Scenario 1: Encountering a Familiar Bug

User: "I'm getting a 'connection refused' error from the database"
-> Search docs/project_notes/bugs.md for "connection"
-> Find previous solution: "Use AlloyDB Auth Proxy on port 5432"
-> Apply known fix

Scenario 2: Proposing an Architectural Change

Internal: "User might benefit from using SQLAlchemy for migrations"
-> Check docs/project_notes/decisions.md
-> Find ADR-002: Already decided to use Alembic
-> Use Alembic instead, maintaining consistency

Scenario 3: User Requests Memory Update

User: "Add that CORS fix to our bug log"
-> Read docs/project_notes/bugs.md
-> Add new entry with date, issue, solution, prevention
-> Confirm addition to user

Scenario 4: Looking Up Project Configuration

Internal: "Need to connect to database"
-> Check docs/project_notes/key_facts.md
-> Find Database Configuration section
-> Use documented connection string and credentials

Tips for Effective Memory Management

1. Be proactive: Check memory files before proposing solutions
2. Be concise: Keep entries brief (1-3 lines for descriptions)
3. Be dated: Always include dates for temporal context
4. Be linked: Include URLs to tickets, docs, monitoring dashboards
5. Be selective: Focus on recurring or instructive issues, not every bug

Integration with Other Skills

The project-memory skill complements other skills:

• requirements-documenter: Requirements -> Decisions (ADRs reference requirements)
• root-cause-debugger: Bug diagnosis -> Bug log (document solutions after fixes)
• code-quality-reviewer: Quality issues -> Decisions (document quality standards)
• docs-sync-editor: Code changes -> Key facts (update when config changes)

When using these skills together, consider updating memory files as a follow-up action.

Success Criteria

This skill is successfully deployed when:

• docs/project_notes/ directory exists with all four memory files
• CLAUDE.md includes "Project Memory System" section with MANDATORY protocols
• AGENTS.md includes the same protocols (if file exists or user requested)
• Memory files follow template format and style guidelines
• AI assistant ALWAYS searches memory files BEFORE attempting fixes
• AI assistant AUTOMATICALLY records verified solutions without user prompting
• User can easily request memory updates ("add this to bugs.md")
• Memory files look like standard engineering documentation, not AI artifacts
• No solution is "rediscovered" that already exists in bugs.md
• All bug entries include "Verified" field with evidence