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

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

**Before proposing architectural changes:**
- Check `docs/project_notes/decisions.md` for existing decisions
- Verify the proposed approach doesn't conflict with past choices
- If it does conflict, acknowledge the existing decision and explain why a change is warranted

**When encountering errors or bugs:**
- Search `docs/project_notes/bugs.md` for similar issues
- Apply known solutions if found
- Document new bugs and solutions when resolved

**When looking up project configuration:**
- Check `docs/project_notes/key_facts.md` for credentials, ports, URLs, service accounts
- Prefer documented facts over assumptions

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

**When user requests memory updates:**
- Update the appropriate memory file (bugs, decisions, key_facts, or issues)
- Follow the established format and style (bullet lists, dates, concise entries)

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

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

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 protocols
• AGENTS.md includes the same protocols (if file exists or user requested)
• Memory files follow template format and style guidelines
• AI assistant checks memory files before proposing changes
• User can easily request memory updates ("add this to bugs.md")
• Memory files look like standard engineering documentation, not AI artifacts

Project Memory Skill

   

A Claude Code skill that establishes a structured institutional knowledge system for your projects. Track bugs with solutions, architectural decisions (ADRs), key project facts, and work history in a consistent, maintainable format.

Quick Start

# Install via skilz (recommended)
skilz install SpillwaveSolutions_project-memory/project-memory

# Then use in any project
cd your-project
# In Claude Code, type: /project-memory

What This Skill Does

When invoked in a project, this skill:

1. Creates a memory infrastructure in docs/project_notes/ with four files:

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

2. Configures CLAUDE.md and AGENTS.md to make Claude Code (and other AI tools) memory-aware:

• Check memory files before proposing changes
• Search for known solutions to familiar bugs
• Document new decisions, bugs, and completed work
• Maintain consistency across coding sessions

3. Provides templates and examples for maintaining institutional knowledge in a way that looks like standard engineering documentation (not AI artifacts).

Installation

There are four installation options depending on your needs.

Option 1: Skilz Universal Installer (Recommended)

The recommended way to install this skill across different AI coding agents is using the skilz universal installer. This skill supports the Agent Skill Standard, which means it works with 14+ coding agents including Claude Code, OpenAI Codex, Cursor, and Gemini.

Install Skilz

pip install skilz

Git URL Options

You can use either -g or --git with HTTPS or SSH URLs:

# HTTPS URL
skilz install -g https://github.com/SpillwaveSolutions/project-memory

# SSH URL
skilz install --git git@github.com:SpillwaveSolutions/project-memory.git

Claude Code

Install to user home (available in all projects):

skilz install -g https://github.com/SpillwaveSolutions/project-memory

Install to current project only:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --project

OpenCode

Install for OpenCode:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent opencode

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --project --agent opencode

Gemini

Project-level install for Gemini:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent gemini

OpenAI Codex

Install for OpenAI Codex:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent codex

Project-level install:

skilz install -g https://github.com/SpillwaveSolutions/project-memory --project --agent codex

Install from SkillzWave Marketplace

# Claude to user home dir ~/.claude/skills
skilz install SpillwaveSolutions_project-memory/project-memory

# Claude skill in project folder ./claude/skills
skilz install SpillwaveSolutions_project-memory/project-memory --project

# OpenCode install to user home dir ~/.config/opencode/skills
skilz install SpillwaveSolutions_project-memory/project-memory --agent opencode

# OpenCode project level
skilz install SpillwaveSolutions_project-memory/project-memory --agent opencode --project

# OpenAI Codex install to user home dir ~/.codex/skills
skilz install SpillwaveSolutions_project-memory/project-memory --agent codex

# OpenAI Codex project level ./.codex/skills
skilz install SpillwaveSolutions_project-memory/project-memory --agent codex --project

# Gemini CLI (project level) -- only works with project level
skilz install SpillwaveSolutions_project-memory/project-memory --agent gemini

See skill Listing for installation details for 14+ different coding agents.

Other Supported Agents

Skilz supports 14+ coding agents including Windsurf, Qwen Code, Aidr, and more. For the full list of supported platforms, visit:

• SkillzWave Platforms
• skilz-cli GitHub Repository

SkillzWave - Largest Agentic Marketplace for AI Agent Skills | SpillWave - Leaders in AI Agent Development

Option 2: Global Installation (Manual)

Install once in your Claude Code home directory to make the skill available across all projects:

# Create the skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Clone or copy the skill to your skills directory
cp -r project-memory ~/.claude/skills/

# Verify installation
ls ~/.claude/skills/project-memory

When to use: You want this skill available for all your projects without reinstalling.

Option 3: Project-Specific Installation (Manual)

Install in a specific project's .claude/skills/ directory:

# Navigate to your project
cd /path/to/your/project

# Create local skills directory
mkdir -p .claude/skills

# Clone or copy the skill
cp -r /path/to/project-memory .claude/skills/

# Verify installation
ls .claude/skills/project-memory

When to use: You only want this skill available for a specific project.

Option 4: Multi-Project Installation (Workspace)

Install above a workspace directory to share across multiple related projects:

# Navigate to your workspace directory (parent of multiple projects)
cd ~/workspace

# Create shared skills directory
mkdir -p .claude/skills

# Clone or copy the skill
cp -r /path/to/project-memory .claude/skills/

# Verify installation
ls .claude/skills/project-memory

When to use: You have multiple projects in a workspace and want to share the skill without global installation.

Example structure:

~/workspace/
├── .claude/
│   └── skills/
│       └── project-memory/    # Shared across all projects below
├── project-a/
├── project-b/
└── project-c/

How to Use

First-Time Setup in a Project

1. Navigate to your project directory 2. Invoke the skill in Claude Code:

   /project-memory

3. The skill will:

• Create docs/project_notes/ directory
• Initialize the four memory files with templates
• Update (or create) CLAUDE.md with memory protocols
• Optionally update AGENTS.md if it exists

Daily Usage

Once set up, Claude Code will automatically:

• Check memory files before proposing architectural changes
• Search bugs.md when you encounter errors
• Reference key_facts.md for project configuration

You can also explicitly request updates:

Add this CORS fix to our bug log

Document the decision to use FastAPI in decisions.md

Update key_facts.md with the new database connection string

Log this completed ticket in issues.md

File Structure After Setup

your-project/
├── docs/
│   └── project_notes/
│       ├── bugs.md         # Bug log with solutions
│       ├── decisions.md    # Architectural Decision Records
│       ├── key_facts.md    # Project configuration
│       └── issues.md       # Work log
├── CLAUDE.md              # Updated with memory protocols
└── AGENTS.md              # Updated with memory protocols (if exists)

Memory File Formats

bugs.md - Bug Log

### 2025-01-15 - Docker Architecture Mismatch
- **Issue**: Container failing to start with "exec format error"
- **Root Cause**: Built on ARM64 Mac but deploying to AMD64 Cloud Run
- **Solution**: Added `--platform linux/amd64` to docker build
- **Prevention**: Always specify platform in Dockerfile

decisions.md - Architectural Decisions

### ADR-001: Use Workload Identity Federation (2025-01-10)

**Context:**
- Need secure authentication from GitHub Actions to GCP

**Decision:**
- Use Workload Identity Federation instead of service account keys

**Alternatives Considered:**
- Service account JSON keys → Rejected: security risk

**Consequences:**
- ✅ More secure (no long-lived credentials)
- ❌ Slightly more complex initial setup

key_facts.md - Project Configuration

⚠️ SECURITY WARNING: Never store passwords, API keys, or credentials in key_facts.md. Only store non-sensitive reference information like hostnames, ports, client names, project IDs, and account names. Store secrets in .env (excluded via .gitignore), password managers, or secrets management systems.

### Database Configuration

**AlloyDB Cluster:**
- Cluster Name: `prod-cluster`
- Private IP: `10.0.0.5`
- Port: `5432`
- Database Name: `contacts`

**Connection:**
- Use AlloyDB Auth Proxy for local development
- Proxy command: `./alloydb-auth-proxy "projects/..."`
- Credentials: Stored in `.env` file (not in git)

issues.md - Work Log

### 2025-01-15 - PROJ-123: Implement Contact API
- **Status**: Completed
- **Description**: Created FastAPI endpoints for contact CRUD
- **URL**: https://jira.company.com/browse/PROJ-123
- **Notes**: Added unit tests, coverage at 85%

Verification

After installation, verify the skill is available:

1. Open Claude Code in any project 2. Type / to see available skills 3. You should see project-memory in the list

Or check manually:

# For global installation
ls ~/.claude/skills/project-memory/SKILL.md

# For project-specific installation
ls .claude/skills/project-memory/SKILL.md

# For workspace installation
ls ../.claude/skills/project-memory/SKILL.md  # From inside a project

Security Best Practices

⚠️ Critical: Never Store Secrets in Version Control

The key_facts.md file is designed to store non-sensitive project reference information only. This file is typically committed to version control and should NEVER contain:

❌ NEVER store in key_facts.md or any git-tracked file:

• Passwords or passphrases
• API keys or authentication tokens
• Service account JSON keys or credentials
• Database passwords
• OAuth client secrets
• Private keys or certificates
• Session tokens
• Any secret values from environment variables

✅ SAFE to store in key_facts.md:

• Database hostnames, ports, and cluster names
• Client names and project identifiers
• JIRA project keys and Confluence space names
• AWS account names and profile names (e.g., "dev", "staging", "prod")
• API endpoint URLs (public URLs only)
• Service account email addresses (not the keys!)
• GCP project IDs and region names
• Docker registry names
• Environment names and deployment targets

✅ WHERE to store sensitive credentials:

• `.env` files - Excluded via .gitignore, used for local development
• Password managers - 1Password, LastPass, Bitwarden, etc.
• Secrets managers - AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Azure Key Vault
• CI/CD environment variables - GitHub Secrets, GitLab CI/CD Variables, etc.
• Platform credential stores - Kubernetes Secrets, Cloud Run Secret Manager integration

✅ VERIFICATION steps before committing: 1. Run git status to see what will be committed 2. Verify .env, credentials.json, and other sensitive files are in .gitignore 3. Never use git add . blindly - review each file being staged 4. Use git diff --cached to review staged changes before committing 5. Consider using tools like git-secrets or gitleaks to prevent credential leaks

Important: Even in private repositories, never commit clear-text passwords or authentication keys. Private repos can become public, be forked, or accessed by unauthorized users.

Features

Memory-Aware Protocols

Once set up, Claude Code will:

• ✅ Check decisions.md before proposing architectural changes
• ✅ Search bugs.md for known solutions to errors
• ✅ Reference key_facts.md for project configuration
• ✅ Log completed work in issues.md
• ✅ Document new bugs, decisions, and facts as they arise

Style Guidelines

All memory files follow these principles:

• Bullet lists over tables (simpler to edit)
• Concise entries (1-3 lines for descriptions)
• Always dated (YYYY-MM-DD format)
• Include URLs (for tickets, docs, monitoring)
• Manual cleanup (periodically remove old entries)

Cross-Tool Compatibility

The memory system works across different AI coding tools:

• Claude Code (via CLAUDE.md)
• Cursor (via .cursor/rules or CLAUDE.md)
• GitHub Copilot (via AGENTS.md or .github/copilot-instructions.md)
• Other tools that read project configuration files

Why Use This Skill?

Without project memory:

• Repeat the same bugs/solutions across sessions
• Propose architectures that conflict with past decisions
• Ask the user repeatedly for database credentials, API keys, ports
• Lose context when switching between projects or AI tools

With project memory:

• Remember and apply known bug solutions instantly
• Maintain architectural consistency across sessions
• Reference documented facts instead of assumptions
• Preserve institutional knowledge across team members and tools

Real-World Impact: Pattern Recognition in Action

Example 1: Bug Resolution - Infrastructure State Drift

The Scenario: 1. Oct 20 - Claude Code encounters Pulumi state drift error during deployment 2. Investigation - 45 minutes debugging, trying various solutions 3. Solution Found - pulumi refresh --yes resolves the state inconsistency 4. Documentation - Logged as BUG-017 and BUG-018 in bugs.md, decision documented in ADR-016 5. Oct 22 - Same state drift error occurs during a new deployment

Without Project Memory:

• Claude Code debugs from scratch (again)
• 30-60 minutes of investigation
• Risk of trying wrong solutions first
• Possible production delay
• User frustration: "Didn't we solve this already?"

With Project Memory:

Claude Code: Searching bugs.md for "state drift"...
Found: BUG-018 - Pulumi State Drift Error
Known solution: pulumi refresh --yes
Applying fix... Done in 2 minutes.
Reference: See ADR-016 for why this works.

Result:

• ✅ Instant recognition: "This is BUG-018"
• ✅ Known solution applied immediately
• ✅ 5 minutes instead of 45 minutes
• ✅ References explain why this works (ADR-016)

Knowledge Compound Interest: Every bug solved and documented makes future work exponentially faster.

Example 2: Architectural Consistency - Avoiding Duplicate Dependencies

The Scenario: 1. Week 1 - Team evaluates charting libraries for scatter plots 2. Decision - Selected D3.js for all visualizations (lightweight, flexible, already in dependencies) 3. Documentation - Logged as ADR-012 in decisions.md with rationale 4. Week 4 - New feature requires a bar chart visualization

Without Project Memory:

User: "Add a bar chart to the dashboard"
Claude Code: "I'll add Chart.js for the bar chart visualization."
[Adds Chart.js to package.json - now we have D3.js AND Chart.js]
Result: Bundle size +85KB, inconsistent chart styling, duplicate dependencies

With Project Memory:

User: "Add a bar chart to the dashboard"
Claude Code: Checking decisions.md for visualization decisions...
Found: ADR-012 - Use D3.js for all charts
Claude Code: "I'll implement the bar chart using D3.js to maintain consistency with ADR-012."
[Uses existing D3.js dependency]
Result: No new dependencies, consistent styling, smaller bundle

Result:

• ✅ Maintains architectural consistency
• ✅ Avoids dependency bloat
• ✅ Ensures consistent user experience
• ✅ Faster development (reuse existing patterns)

Key Insight: Remembering past decisions prevents architectural drift and keeps the codebase cohesive.

Example 3: The "Didn't We Fix This?" Problem

The Reality of Long-Running Projects:

Many developers (and AI code assistants) encounter the same bugs months apart and completely forget the solution:

Month 1:

Error: CORS policy blocked request from localhost:3000
[2 hours of debugging]
Solution: Add proxy configuration to package.json

Month 6:

Error: CORS policy blocked request from localhost:3000
Developer: "This looks familiar... how did we fix this?"
[Searches old commits, checks Stack Overflow again]
[1 hour to re-discover the proxy config solution]

With Project Memory:

Error: CORS policy blocked request from localhost:3000
Claude Code: Searching bugs.md for "CORS"...
Found: BUG-003 - CORS Blocked in Local Development
Solution: proxy config in package.json
Applied in 5 minutes.

The Code Agent Memory Problem:

AI code assistants don't remember previous sessions. Without documentation:

• Each new chat session starts from zero knowledge
• Every bug feels like the first time
• Solutions are "rediscovered" repeatedly
• No learning accumulates over time

With project memory, the code agent becomes progressively smarter:

• First encounter: 2 hours to solve → documented in bugs.md
• Second encounter: 5 minutes (reads bugs.md)
• Third encounter: 2 minutes (pattern now familiar)
• Fourth encounter: Preventative advice (suggests avoiding the issue)

This is knowledge compound interest - your project gets easier to maintain over time, not harder.

Skill File Structure

project-memory/
├── SKILL.md                    # Main skill instructions for Claude
├── CLAUDE.md                   # This repository's Claude guidance
├── README.md                   # This file
└── references/                 # Templates for memory files
    ├── bugs_template.md
    ├── decisions_template.md
    ├── key_facts_template.md
    └── issues_template.md

Design Philosophy

1. Looks like standard engineering docs - Using docs/project_notes/ instead of memory/ makes it appear as normal engineering organization, not AI-specific tooling.

2. Prefer simplicity - Bullet lists over tables, concise over exhaustive, manual cleanup over automation.

3. Document what matters - Focus on recurring bugs, important decisions, and frequently-needed facts.

4. Enable collaboration - Works across AI tools, readable by humans, version-controllable with git.

Examples

Setting Up Memory in a New Project

cd ~/projects/my-new-app
claude code

In Claude Code:

/project-memory

Claude will create the memory infrastructure and configure CLAUDE.md.

Documenting a Bug Fix

I just fixed a bug where the database connection pool was exhausted.
Add it to bugs.md with the solution.

Checking for Existing Decisions

I'm thinking about using SQLAlchemy for migrations.
Check if we already have a decision about this.

Claude will search decisions.md and apply existing choices.

Updating Project Facts

Update key_facts.md with the new staging environment URL:
https://staging-api.company.com

Maintenance

Memory files are manually maintained:

• bugs.md - Remove very old entries (6+ months) that are no longer relevant
• decisions.md - Keep all decisions (they're lightweight and provide historical context)
• key_facts.md - Update when project configuration changes
• issues.md - Archive completed work (3+ months old)

Integration with Other Skills

This skill complements other Claude Code skills:

• requirements-documenter - Requirements inform ADRs in decisions.md
• root-cause-debugger - Bug diagnosis results documented in bugs.md
• code-quality-reviewer - Quality standards documented in decisions.md
• docs-sync-editor - Code changes trigger updates to key_facts.md

Troubleshooting

Skill not appearing in Claude Code

Check installation location:

# Global installation
ls ~/.claude/skills/project-memory/SKILL.md

# Project-specific installation
ls .claude/skills/project-memory/SKILL.md

Ensure SKILL.md exists: The skill must have a SKILL.md file with proper frontmatter:

---
name: project-memory
description: Set up and maintain a structured project memory system...
---

Memory files not being created

Verify you're in a project directory: The skill creates files in the current working directory's docs/project_notes/ folder.

Check permissions: Ensure you have write permissions in the project directory.

Claude not checking memory files

Verify CLAUDE.md was updated:

grep "Project Memory System" CLAUDE.md

The "Project Memory System" section should be present with complete protocols.

Contributing

To improve this skill:

1. Update templates in references/ directory 2. Enhance SKILL.md with new capabilities 3. Update CLAUDE.md with workflow changes 4. Test in a sample project

License

This skill is part of the Claude Code skills ecosystem and follows standard usage guidelines for Claude Code extensions.

Support

For issues or questions:

• Check the troubleshooting section above
• Review SKILL.md for detailed skill instructions
• Review CLAUDE.md for repository-specific guidance
• Consult Claude Code documentation at https://docs.claude.com/en/docs/claude-code

Bug Log Template

This file demonstrates the format for logging bugs and their solutions. Keep entries brief and chronological.

Format

Each bug entry should include:

• Date (YYYY-MM-DD)
• Brief description of the bug/issue
• Solution or fix applied
• Any prevention notes (optional)

Use bullet lists for simplicity. Older entries can be manually removed when they become irrelevant.

Example Entries

2025-01-15 - Docker Architecture Mismatch

• Issue: Container failing to start with "exec format error"
• Root Cause: Built on ARM64 Mac but deploying to AMD64 Cloud Run
• Solution: Added --platform linux/amd64 to docker build command
• Prevention: Always specify platform in Dockerfile and build scripts

2025-01-20 - Cloud Scheduler HTTPS Requirement

• Issue: Cloud Scheduler jobs failing with "URL must use HTTPS"
• Root Cause: Forgot Cloud Run URLs require HTTPS by default
• Solution: Updated all scheduler job URLs from http:// to https://
• Prevention: Remember GCP services enforce HTTPS; check URLs in infrastructure code

2025-01-22 - Database Connection Pool Exhaustion

• Issue: API returning 500 errors under load
• Root Cause: Connection pool size too small (default 5)
• Solution: Increased pool_size to 20 and max_overflow to 10 in SQLAlchemy config
• Prevention: Load test APIs before production deployment

Tips

• Keep descriptions under 2-3 lines
• Focus on what was learned, not exhaustive details
• Include enough context for future reference
• Date entries so you know how recent the issue is
• Periodically clean out very old entries (6+ months)

Architectural Decisions Template

This file demonstrates the format for logging architectural decisions (ADRs). Use bullet lists for clarity.

Format

Each decision should include:

• Date and ADR number
• Context (why the decision was needed)
• Decision (what was chosen)
• Alternatives considered
• Consequences (trade-offs, implications)

Example Entries

ADR-001: Use Workload Identity Federation for GitHub Actions (2025-01-10)

Context:

• Need secure authentication from GitHub Actions to GCP
• Service account keys are deprecated and considered insecure
• Want to avoid managing long-lived credentials

Decision:

• Use Workload Identity Federation (WIF) for GitHub Actions authentication
• Configure via WIF_PROVIDER and WIF_SERVICE_ACCOUNT secrets

Alternatives Considered:

• Service account JSON keys → Rejected: security risk, manual rotation required
• Environment-specific credentials → Rejected: harder to manage across repos

Consequences:

• ✅ More secure (no long-lived credentials)
• ✅ Automatic credential rotation
• ✅ Better audit trail
• ❌ Slightly more complex initial setup
• ❌ Requires GitHub OIDC support

ADR-002: Use Alembic for Database Migrations (2025-01-12)

Context:

• Need version control for database schema changes
• Multiple developers working on database schema
• Want to avoid manual SQL scripts and migration conflicts

Decision:

• Use Alembic as the database migration tool
• Store migrations in alembic/versions/ directory
• Use auto-generate feature for model changes

Alternatives Considered:

• Raw SQL scripts → Rejected: no versioning, error-prone
• Flask-Migrate → Rejected: too tied to Flask framework
• Django migrations → Rejected: using FastAPI, not Django

Consequences:

• ✅ Version-controlled schema changes
• ✅ Automatic migration generation from models
• ✅ Easy rollback capability
• ❌ Learning curve for team
• ❌ Must remember to generate migrations after model changes

ADR-003: Use AlloyDB Instead of Cloud SQL (2025-01-15)

Context:

• Need PostgreSQL-compatible database in GCP
• Require high availability and automatic backups
• Performance-critical application with complex queries

Decision:

• Use AlloyDB for PostgreSQL instead of Cloud SQL
• Configure with automated backups and point-in-time recovery

Alternatives Considered:

• Cloud SQL PostgreSQL → Rejected: slower query performance
• Self-managed PostgreSQL on GCE → Rejected: high operational overhead
• Firestore → Rejected: need relational data model and SQL

Consequences:

• ✅ Better query performance (2-4x faster than Cloud SQL)
• ✅ PostgreSQL compatibility
• ✅ Managed service (automated backups, HA)
• ❌ Higher cost than Cloud SQL
• ❌ Newer service, less community documentation

Tips

• Number decisions sequentially (ADR-001, ADR-002, etc.)
• Always include date for context
• Be honest about trade-offs (use ✅ and ❌)
• Keep alternatives brief but clear
• Update decisions if they're revisited/changed
• Focus on "why" not "how" (implementation details go elsewhere)

Issues/Work Log Template

This file demonstrates the format for logging work completed on tickets. Keep it simple - just enough to remember what was done. Full details live in Jira/GitHub.

Format

Each entry should include:

• Date (YYYY-MM-DD)
• Ticket ID
• Brief description (1-2 lines)
• URL to ticket (if available)
• Status (optional: completed, in-progress, blocked)

Use bullet lists for simplicity. This is NOT a replacement for your ticket system - it's a quick reference log.

Example Entries

2025-01-15 - PROJ-123: Implement Contact API

• Status: Completed
• Description: Created FastAPI endpoints for contact CRUD operations with validation
• URL: https://jira.company.com/browse/PROJ-123
• Notes: Added unit tests, coverage at 85%

2025-01-16 - PROJ-124: Fix Docker Build Issues

• Status: Completed
• Description: Fixed architecture mismatch for Cloud Run deployment
• URL: https://jira.company.com/browse/PROJ-124
• Notes: See bugs.md for details on the fix

2025-01-18 - PROJ-125: Database Migration to AlloyDB

• Status: Completed
• Description: Migrated from Cloud SQL to AlloyDB with Pulumi infrastructure code
• URL: https://jira.company.com/browse/PROJ-125
• Notes: Multi-phase migration completed over 3 days

2025-01-20 - GH-45: Add OAuth2 Authentication

• Status: In Progress
• Description: Implementing OAuth2 flow with Google provider
• URL: https://github.com/company/repo/issues/45
• Notes: Backend complete, frontend integration pending

2025-01-22 - PROJ-130: Performance Optimization

• Status: Blocked
• Description: Optimize slow queries in contact search endpoint
• URL: https://jira.company.com/browse/PROJ-130
• Notes: Waiting for DBA review of proposed indexes

Alternative Format (Grouped by Week)

Week of 2025-01-15

Completed:

• PROJ-123: Contact API implementation → https://jira.company.com/browse/PROJ-123
• PROJ-124: Docker build fix → https://jira.company.com/browse/PROJ-124

In Progress:

• PROJ-125: AlloyDB migration (phase 2 of 3)

Week of 2025-01-22

Completed:

• PROJ-125: AlloyDB migration completed → https://jira.company.com/browse/PROJ-125
• GH-45: OAuth2 backend done → https://github.com/company/repo/issues/45

Blocked:

• PROJ-130: Query optimization (waiting on DBA) → https://jira.company.com/browse/PROJ-130

Tips

• Keep descriptions brief (1-2 lines max)
• Always include ticket URL for easy reference
• Update status if work gets blocked or resumed
• Optional: Group by week or sprint for better organization
• Don't duplicate ticket details - link to source of truth
• Clean out very old entries periodically (3+ months)
• Include both Jira and GitHub tickets as appropriate

Key Facts Template

This file demonstrates the format for storing project constants, configuration, and frequently-needed non-sensitive information. Organize by category using bullet lists.

⚠️ SECURITY WARNING: What NOT to Store Here

NEVER store passwords, API keys, or sensitive credentials in this file. This file is typically committed to version control and should only contain non-sensitive reference information.

❌ NEVER store:

• Passwords or passphrases
• API keys or authentication tokens
• Service account JSON keys or credentials
• Database passwords
• OAuth client secrets
• Private keys or certificates
• Session tokens
• Any secret values from environment variables

✅ SAFE to store:

• Database hostnames, ports, and cluster names
• Client names and project identifiers
• JIRA project keys and Confluence space names
• AWS/GCP account names and profile names
• API endpoint URLs (public URLs only)
• Service account email addresses (not the keys!)
• GCP project IDs and region names
• Docker registry names
• Environment names and deployment targets

Where to store secrets:

• .env files (excluded via .gitignore)
• Password managers (1Password, LastPass, Bitwarden)
• Secrets managers (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
• CI/CD environment variables (GitHub Secrets, GitLab Variables)
• Platform credential stores (Kubernetes Secrets, Cloud Run)

Format

Organize information into logical categories:

• GCP/Cloud configuration
• Database connection details (hostnames, ports, cluster names)
• API endpoints (URLs only, not credentials)
• Local development setup (ports, service names)
• Important URLs
• Service accounts and permissions (emails and roles, not keys)

Use bullet lists for simplicity and easy scanning.

Example Structure

GCP Project Information

Current Project:

• Project ID: my-company-prod
• Project Number: 123456789012
• Region: us-central1
• Zone: us-central1-a

Old Project (Deprecated):

• Project ID: my-company-dev-old
• Migration Date: 2025-01-10
• Status: Archived, do not use

Database Configuration

AlloyDB Cluster:

• Cluster Name: prod-cluster
• Instance Name: prod-primary
• Region: us-central1
• Private IP: 10.0.0.5
• Port: 5432
• Database Name: contacts

Connection:

• Use AlloyDB Auth Proxy for local development
• Proxy command: ./alloydb-auth-proxy "projects/my-company-prod/locations/us-central1/clusters/prod-cluster/instances/prod-primary"
• Local port: 5432

Authentication:

• Service Account (email only): alloydb-client@my-company-prod.iam.gserviceaccount.com
• Service Account Key: Stored in .env as GOOGLE_APPLICATION_CREDENTIALS (not in git!)
• Connection String Template: postgresql://user:${DB_PASSWORD}@localhost:5432/contacts
• Password Location: Stored in .env file (excluded via .gitignore)

API Configuration

Backend API:

• Production URL: https://api.mycompany.com
• Staging URL: https://api-staging.mycompany.com
• Local Development: http://localhost:8000

Authentication:

• OAuth Client ID (public): 123456789-abcdefg.apps.googleusercontent.com
• OAuth Client Secret: Stored in GCP Secret Manager as oauth-client-secret (not in git!)
• Local Development Secret: Stored in .env as OAUTH_CLIENT_SECRET (not in git!)
• Scopes: openid email profile

Local Development Ports

Services:

• Backend API: 8000
• Frontend: 3000
• AlloyDB Proxy: 5432
• Redis: 6379
• Prometheus: 9090

Service Accounts

GitHub Actions:

• Service Account: github-actions@my-company-prod.iam.gserviceaccount.com
• Roles: roles/run.admin, roles/secretmanager.secretAccessor
• WIF Pool: projects/123456789012/locations/global/workloadIdentityPools/github-pool

Cloud Run Service:

• Service Account: cloud-run-sa@my-company-prod.iam.gserviceaccount.com
• Roles: roles/alloydb.client, roles/secretmanager.secretAccessor

Important URLs

Documentation:

• API Docs: https://docs.mycompany.com/api
• Internal Wiki: https://wiki.mycompany.com
• Runbook: https://wiki.mycompany.com/runbook

Monitoring:

• Cloud Console: https://console.cloud.google.com/home/dashboard?project=my-company-prod
• Logs: https://console.cloud.google.com/logs?project=my-company-prod
• Monitoring: https://console.cloud.google.com/monitoring?project=my-company-prod

Deployment:

• Cloud Run Service: https://console.cloud.google.com/run?project=my-company-prod
• Cloud Build: https://console.cloud.google.com/cloud-build?project=my-company-prod
• Artifact Registry: https://console.cloud.google.com/artifacts?project=my-company-prod

Infrastructure as Code

Pulumi:

• Stack: prod
• Backend: gs://my-company-pulumi-state
• Config Passphrase: Stored in team password manager (1Password vault: "Infrastructure")
• State: Stored in GCS bucket with versioning enabled
• Note: Never commit Pulumi.prod.yaml with unencrypted secrets

Configuration:

• Cloud Run Image: us-central1-docker.pkg.dev/my-company-prod/app/backend:latest
• VPC Connector: prod-vpc-connector
• Max Instances: 10
• Min Instances: 1

Tips

• Keep entries current (update when things change)
• Remove deprecated information after migration is complete
• Include both production and development details
• Add URLs to make navigation easier
• Use consistent formatting (same structure for similar items)
• Group related information together
• Mark deprecated items clearly with dates