Skip to content
Back to search

project-memory

This is a claude skill for tracking project state.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spillwavesolutions--project-memory/badge.svg)](/listings/spillwavesolutions--project-memory)

HTML

<a href="/listings/spillwavesolutions--project-memory"><img src="/api/listings/spillwavesolutions--project-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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 was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 298 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: project-memory
  3. description: Set up and maintain a structured project memory system in docs/project_notes/ that tracks bugs with solutions, architectural decisions, key project facts, and work history. Use this skill when asked to "set up project memory", "track our decisions", "log a bug fix", "update project memory", or "initialize memory system". Configures both CLAUDE.md and AGENTS.md to maintain memory awareness across different AI coding tools.
  4. ---
  5. # Project Memory
  6. ## Table of Contents
  7. - [Overview](#overview)
  8. - [When to Use This Skill](#when-to-use-this-skill)
  9. - [Core Capabilities](#core-capabilities)
  10. - [1. Initial Setup - Create Memory Infrastructure](#1-initial-setup---create-memory-infrastructure)
  11. - [2. Configure CLAUDE.md - Memory-Aware Behavior](#2-configure-claudemd---memory-aware-behavior)
  12. - [3. Configure AGENTS.md - Multi-Tool Support](#3-configure-agentsmd---multi-tool-support)
  13. - [4. Searching Memory Files](#4-searching-memory-files)
  14. - [5. Updating Memory Files](#5-updating-memory-files)
  15. - [6. Memory File Maintenance](#6-memory-file-maintenance)
  16. - [Templates and References](#templates-and-references)
  17. - [Example Workflows](#example-workflows)
  18. - [Integration with Other Skills](#integration-with-other-skills)
  19. - [Success Criteria](#success-criteria)
  20. ## Overview
  21. 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.
  22. ## When to Use This Skill
  23. Invoke this skill when:
  24. - Starting a new project that will accumulate knowledge over time
  25. - The project already has recurring bugs or decisions that should be documented
  26. - The user asks to "set up project memory" or "track our decisions"
  27. - The user wants to log a bug fix, architectural decision, or completed work
  28. - Encountering a problem that feels familiar ("didn't we solve this before?")
  29. - Before proposing an architectural change (check existing decisions first)
  30. - Working on projects with multiple developers or AI tools (Claude Code, Cursor, etc.)
  31. ## Core Capabilities
  32. ### 1. Initial Setup - Create Memory Infrastructure
  33. When invoked for the first time in a project, create the following structure:
  34. ```
  35. docs/
  36. └── project_notes/
  37. ├── bugs.md # Bug log with solutions
  38. ├── decisions.md # Architectural Decision Records
  39. ├── key_facts.md # Project configuration and constants
  40. └── issues.md # Work log with ticket references
  41. ```
  42. **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.
  43. **Initial file content:** Copy templates from the `references/` directory in this skill:
  44. - Use `references/bugs_template.md` for initial `bugs.md`
  45. - Use `references/decisions_template.md` for initial `decisions.md`
  46. - Use `references/key_facts_template.md` for initial `key_facts.md`
  47. - Use `references/issues_template.md` for initial `issues.md`
  48. Each template includes format examples and usage tips.
  49. ### 2. Configure CLAUDE.md - Memory-Aware Behavior
  50. Add or update the following section in the project's `CLAUDE.md` file:
  51. ```markdown
  52. ## Project Memory System
  53. This project maintains institutional knowledge in `docs/project_notes/` for consistency across sessions.
  54. ### Memory Files
  55. - **bugs.md** - Bug log with dates, solutions, and prevention notes
  56. - **decisions.md** - Architectural Decision Records (ADRs) with context and trade-offs
  57. - **key_facts.md** - Project configuration, credentials, ports, important URLs
  58. - **issues.md** - Work log with ticket IDs, descriptions, and URLs
  59. ### Memory-Aware Protocols
  60. **Before proposing architectural changes:**
  61. - Check `docs/project_notes/decisions.md` for existing decisions
  62. - Verify the proposed approach doesn't conflict with past choices
  63. - If it does conflict, acknowledge the existing decision and explain why a change is warranted
  64. **When encountering errors or bugs:**
  65. - Search `docs/project_notes/bugs.md` for similar issues
  66. - Apply known solutions if found
  67. - Document new bugs and solutions when resolved
  68. **When looking up project configuration:**
  69. - Check `docs/project_notes/key_facts.md` for credentials, ports, URLs, service accounts
  70. - Prefer documented facts over assumptions
  71. **When completing work on tickets:**
  72. - Log completed work in `docs/project_notes/issues.md`
  73. - Include ticket ID, date, brief description, and URL
  74. **When user requests memory updates:**
  75. - Update the appropriate memory file (bugs, decisions, key_facts, or issues)
  76. - Follow the established format and style (bullet lists, dates, concise entries)
  77. ### Style Guidelines for Memory Files
  78. - **Prefer bullet lists over tables** for simplicity and ease of editing
  79. - **Keep entries concise** (1-3 lines for descriptions)
  80. - **Always include dates** for temporal context
  81. - **Include URLs** for tickets, documentation, monitoring dashboards
  82. - **Manual cleanup** of old entries is expected (not automated)
  83. ```
  84. ### 3. Configure AGENTS.md - Multi-Tool Support
  85. 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.
  86. **If AGENTS.md exists:** Add the same "Project Memory System" section as above.
  87. **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.
  88. ### 4. Searching Memory Files
  89. When encountering problems or making decisions, proactively search memory files:
  90. **Search bugs.md:**
  91. ```bash
  92. # Look for similar errors
  93. grep -i "connection refused" docs/project_notes/bugs.md
  94. # Find bugs by date range
  95. grep "2025-01" docs/project_notes/bugs.md
  96. ```
  97. **Search decisions.md:**
  98. ```bash
  99. # Check for decisions about a technology
  100. grep -i "database" docs/project_notes/decisions.md
  101. # Find all ADRs
  102. grep "^### ADR-" docs/project_notes/decisions.md
  103. ```
  104. **Search key_facts.md:**
  105. ```bash
  106. # Find database connection info
  107. grep -A 5 "Database" docs/project_notes/key_facts.md
  108. # Look up service accounts
  109. grep -i "service account" docs/project_notes/key_facts.md
  110. ```
  111. **Use Grep tool for more complex searches:**
  112. - Search across all memory files: `Grep(pattern="oauth", path="docs/project_notes/")`
  113. - Context-aware search: `Grep(pattern="bug", path="docs/project_notes/bugs.md", -A=3, -B=3)`
  114. ### 5. Updating Memory Files
  115. When the user requests updates or when documenting resolved issues, update the appropriate memory file:
  116. **Adding a bug entry:**
  117. ```markdown
  118. ### YYYY-MM-DD - Brief Bug Description
  119. - **Issue**: What went wrong
  120. - **Root Cause**: Why it happened
  121. - **Solution**: How it was fixed
  122. - **Prevention**: How to avoid it in the future
  123. ```
  124. **Adding a decision:**
  125. ```markdown
  126. ### ADR-XXX: Decision Title (YYYY-MM-DD)
  127. **Context:**
  128. - Why the decision was needed
  129. - What problem it solves
  130. **Decision:**
  131. - What was chosen
  132. **Alternatives Considered:**
  133. - Option 1 -> Why rejected
  134. - Option 2 -> Why rejected
  135. **Consequences:**
  136. - Benefits
  137. - Trade-offs
  138. ```
  139. **Adding key facts:**
  140. - Organize by category (GCP Project, Database, API, Local Development, etc.)
  141. - Use bullet lists for clarity
  142. - Include both production and development details
  143. - Add URLs for easy navigation
  144. - See `references/key_facts_template.md` for security guidelines on what NOT to store
  145. **Adding work log entry:**
  146. ```markdown
  147. ### YYYY-MM-DD - TICKET-ID: Brief Description
  148. - **Status**: Completed / In Progress / Blocked
  149. - **Description**: 1-2 line summary
  150. - **URL**: https://jira.company.com/browse/TICKET-ID
  151. - **Notes**: Any important context
  152. ```
  153. ### 6. Memory File Maintenance
  154. **Periodically clean old entries:**
  155. - User is responsible for manual cleanup (no automation)
  156. - Remove very old bug entries (6+ months) that are no longer relevant
  157. - Archive completed work from issues.md (3+ months old)
  158. - Keep all decisions (they're lightweight and provide historical context)
  159. - Update key_facts.md when project configuration changes
  160. **Conflict resolution:**
  161. - If proposing something that conflicts with decisions.md, explain why revisiting the decision is warranted
  162. - Update the decision entry if the choice changes
  163. - Add date of revision to show evolution
  164. ## Templates and References
  165. This skill includes template files in `references/` that demonstrate proper formatting:
  166. - **references/bugs_template.md** - Bug entry format with examples
  167. - **references/decisions_template.md** - ADR format with examples
  168. - **references/key_facts_template.md** - Key facts organization with examples (includes security guidelines)
  169. - **references/issues_template.md** - Work log format with examples
  170. When creating initial memory files, copy these templates to `docs/project_notes/` and customize them for the project.
  171. ## Example Workflows
  172. ### Scenario 1: Encountering a Familiar Bug
  173. ```
  174. User: "I'm getting a 'connection refused' error from the database"
  175. -> Search docs/project_notes/bugs.md for "connection"
  176. -> Find previous solution: "Use AlloyDB Auth Proxy on port 5432"
  177. -> Apply known fix
  178. ```
  179. ### Scenario 2: Proposing an Architectural Change
  180. ```
  181. Internal: "User might benefit from using SQLAlchemy for migrations"
  182. -> Check docs/project_notes/decisions.md
  183. -> Find ADR-002: Already decided to use Alembic
  184. -> Use Alembic instead, maintaining consistency
  185. ```
  186. ### Scenario 3: User Requests Memory Update
  187. ```
  188. User: "Add that CORS fix to our bug log"
  189. -> Read docs/project_notes/bugs.md
  190. -> Add new entry with date, issue, solution, prevention
  191. -> Confirm addition to user
  192. ```
  193. ### Scenario 4: Looking Up Project Configuration
  194. ```
  195. Internal: "Need to connect to database"
  196. -> Check docs/project_notes/key_facts.md
  197. -> Find Database Configuration section
  198. -> Use documented connection string and credentials
  199. ```
  200. ## Tips for Effective Memory Management
  201. 1. **Be proactive**: Check memory files before proposing solutions
  202. 2. **Be concise**: Keep entries brief (1-3 lines for descriptions)
  203. 3. **Be dated**: Always include dates for temporal context
  204. 4. **Be linked**: Include URLs to tickets, docs, monitoring dashboards
  205. 5. **Be selective**: Focus on recurring or instructive issues, not every bug
  206. ## Integration with Other Skills
  207. The project-memory skill complements other skills:
  208. - **requirements-documenter**: Requirements -> Decisions (ADRs reference requirements)
  209. - **root-cause-debugger**: Bug diagnosis -> Bug log (document solutions after fixes)
  210. - **code-quality-reviewer**: Quality issues -> Decisions (document quality standards)
  211. - **docs-sync-editor**: Code changes -> Key facts (update when config changes)
  212. When using these skills together, consider updating memory files as a follow-up action.
  213. ## Success Criteria
  214. This skill is successfully deployed when:
  215. - `docs/project_notes/` directory exists with all four memory files
  216. - CLAUDE.md includes "Project Memory System" section with protocols
  217. - AGENTS.md includes the same protocols (if file exists or user requested)
  218. - Memory files follow template format and style guidelines
  219. - AI assistant checks memory files before proposing changes
  220. - User can easily request memory updates ("add this to bugs.md")
  221. - Memory files look like standard engineering documentation, not AI artifacts
README.md · README · 687 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Project Memory Skill
  2. [![Agent Skill Standard](https://img.shields.io/badge/Agent%20Skill-Standard-blue)](https://agentskills.io/)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  4. [![Claude Code](https://img.shields.io/badge/Claude-Code-5A67D8)](https://claude.ai/code)
  5. [![SkillzWave Marketplace](https://img.shields.io/badge/SkillzWave-Marketplace-00C7B7)](https://skillzwave.ai/skill/SpillwaveSolutions__project-memory__project-memory__SKILL/)
  6. 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.
  7. ## Quick Start
  8. ```bash
  9. # Install via skilz (recommended)
  10. skilz install SpillwaveSolutions_project-memory/project-memory
  11. # Then use in any project
  12. cd your-project
  13. # In Claude Code, type: /project-memory
  14. ```
  15. ## What This Skill Does
  16. When invoked in a project, this skill:
  17. 1. **Creates a memory infrastructure** in `docs/project_notes/` with four files:
  18. - `bugs.md` - Bug log with solutions and prevention notes
  19. - `decisions.md` - Architectural Decision Records (ADRs)
  20. - `key_facts.md` - Project configuration, credentials, ports, URLs
  21. - `issues.md` - Work log with ticket IDs and descriptions
  22. 2. **Configures CLAUDE.md and AGENTS.md** to make Claude Code (and other AI tools) memory-aware:
  23. - Check memory files before proposing changes
  24. - Search for known solutions to familiar bugs
  25. - Document new decisions, bugs, and completed work
  26. - Maintain consistency across coding sessions
  27. 3. **Provides templates and examples** for maintaining institutional knowledge in a way that looks like standard engineering documentation (not AI artifacts).
  28. ## Installation
  29. There are four installation options depending on your needs.
  30. ### Option 1: Skilz Universal Installer (Recommended)
  31. 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](https://agentskills.io/), which means it works with 14+ coding agents including Claude Code, OpenAI Codex, Cursor, and Gemini.
  32. #### Install Skilz
  33. ```bash
  34. pip install skilz
  35. ```
  36. #### Git URL Options
  37. You can use either `-g` or `--git` with HTTPS or SSH URLs:
  38. ```bash
  39. # HTTPS URL
  40. skilz install -g https://github.com/SpillwaveSolutions/project-memory
  41. # SSH URL
  42. skilz install --git git@github.com:SpillwaveSolutions/project-memory.git
  43. ```
  44. #### Claude Code
  45. Install to user home (available in all projects):
  46. ```bash
  47. skilz install -g https://github.com/SpillwaveSolutions/project-memory
  48. ```
  49. Install to current project only:
  50. ```bash
  51. skilz install -g https://github.com/SpillwaveSolutions/project-memory --project
  52. ```
  53. #### OpenCode
  54. Install for [OpenCode](https://opencode.ai):
  55. ```bash
  56. skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent opencode
  57. ```
  58. Project-level install:
  59. ```bash
  60. skilz install -g https://github.com/SpillwaveSolutions/project-memory --project --agent opencode
  61. ```
  62. #### Gemini
  63. Project-level install for Gemini:
  64. ```bash
  65. skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent gemini
  66. ```
  67. #### OpenAI Codex
  68. Install for OpenAI Codex:
  69. ```bash
  70. skilz install -g https://github.com/SpillwaveSolutions/project-memory --agent codex
  71. ```
  72. Project-level install:
  73. ```bash
  74. skilz install -g https://github.com/SpillwaveSolutions/project-memory --project --agent codex
  75. ```
  76. #### Install from SkillzWave Marketplace
  77. ```bash
  78. # Claude to user home dir ~/.claude/skills
  79. skilz install SpillwaveSolutions_project-memory/project-memory
  80. # Claude skill in project folder ./claude/skills
  81. skilz install SpillwaveSolutions_project-memory/project-memory --project
  82. # OpenCode install to user home dir ~/.config/opencode/skills
  83. skilz install SpillwaveSolutions_project-memory/project-memory --agent opencode
  84. # OpenCode project level
  85. skilz install SpillwaveSolutions_project-memory/project-memory --agent opencode --project
  86. # OpenAI Codex install to user home dir ~/.codex/skills
  87. skilz install SpillwaveSolutions_project-memory/project-memory --agent codex
  88. # OpenAI Codex project level ./.codex/skills
  89. skilz install SpillwaveSolutions_project-memory/project-memory --agent codex --project
  90. # Gemini CLI (project level) -- only works with project level
  91. skilz install SpillwaveSolutions_project-memory/project-memory --agent gemini
  92. ```
  93. See [skill Listing](https://skillzwave.ai/skill/SpillwaveSolutions__project-memory__project-memory__SKILL/) for installation details for 14+ different coding agents.
  94. #### Other Supported Agents
  95. Skilz supports 14+ coding agents including Windsurf, Qwen Code, Aidr, and more. For the full list of supported platforms, visit:
  96. - [SkillzWave Platforms](https://skillzwave.ai/platforms/)
  97. - [skilz-cli GitHub Repository](https://github.com/SpillwaveSolutions/skilz-cli)
  98. [SkillzWave - Largest Agentic Marketplace for AI Agent Skills](https://skillzwave.ai/) | [SpillWave - Leaders in AI Agent Development](https://spillwave.com/)
  99. ### Option 2: Global Installation (Manual)
  100. Install once in your Claude Code home directory to make the skill available across **all projects**:
  101. ```bash
  102. # Create the skills directory if it doesn't exist
  103. mkdir -p ~/.claude/skills
  104. # Clone or copy the skill to your skills directory
  105. cp -r project-memory ~/.claude/skills/
  106. # Verify installation
  107. ls ~/.claude/skills/project-memory
  108. ```
  109. **When to use:** You want this skill available for all your projects without reinstalling.
  110. ### Option 3: Project-Specific Installation (Manual)
  111. Install in a specific project's `.claude/skills/` directory:
  112. ```bash
  113. # Navigate to your project
  114. cd /path/to/your/project
  115. # Create local skills directory
  116. mkdir -p .claude/skills
  117. # Clone or copy the skill
  118. cp -r /path/to/project-memory .claude/skills/
  119. # Verify installation
  120. ls .claude/skills/project-memory
  121. ```
  122. **When to use:** You only want this skill available for a specific project.
  123. ### Option 4: Multi-Project Installation (Workspace)
  124. Install above a workspace directory to share across multiple related projects:
  125. ```bash
  126. # Navigate to your workspace directory (parent of multiple projects)
  127. cd ~/workspace
  128. # Create shared skills directory
  129. mkdir -p .claude/skills
  130. # Clone or copy the skill
  131. cp -r /path/to/project-memory .claude/skills/
  132. # Verify installation
  133. ls .claude/skills/project-memory
  134. ```
  135. **When to use:** You have multiple projects in a workspace and want to share the skill without global installation.
  136. **Example structure:**
  137. ```
  138. ~/workspace/
  139. ├── .claude/
  140. │ └── skills/
  141. │ └── project-memory/ # Shared across all projects below
  142. ├── project-a/
  143. ├── project-b/
  144. └── project-c/
  145. ```
  146. ## How to Use
  147. ### First-Time Setup in a Project
  148. 1. Navigate to your project directory
  149. 2. Invoke the skill in Claude Code:
  150. ```
  151. /project-memory
  152. ```
  153. 3. The skill will:
  154. - Create `docs/project_notes/` directory
  155. - Initialize the four memory files with templates
  156. - Update (or create) `CLAUDE.md` with memory protocols
  157. - Optionally update `AGENTS.md` if it exists
  158. ### Daily Usage
  159. Once set up, Claude Code will automatically:
  160. - **Check memory files** before proposing architectural changes
  161. - **Search bugs.md** when you encounter errors
  162. - **Reference key_facts.md** for project configuration
  163. You can also explicitly request updates:
  164. ```
  165. Add this CORS fix to our bug log
  166. ```
  167. ```
  168. Document the decision to use FastAPI in decisions.md
  169. ```
  170. ```
  171. Update key_facts.md with the new database connection string
  172. ```
  173. ```
  174. Log this completed ticket in issues.md
  175. ```
  176. ## File Structure After Setup
  177. ```
  178. your-project/
  179. ├── docs/
  180. │ └── project_notes/
  181. │ ├── bugs.md # Bug log with solutions
  182. │ ├── decisions.md # Architectural Decision Records
  183. │ ├── key_facts.md # Project configuration
  184. │ └── issues.md # Work log
  185. ├── CLAUDE.md # Updated with memory protocols
  186. └── AGENTS.md # Updated with memory protocols (if exists)
  187. ```
  188. ## Memory File Formats
  189. ### bugs.md - Bug Log
  190. ```markdown
  191. ### 2025-01-15 - Docker Architecture Mismatch
  192. - **Issue**: Container failing to start with "exec format error"
  193. - **Root Cause**: Built on ARM64 Mac but deploying to AMD64 Cloud Run
  194. - **Solution**: Added `--platform linux/amd64` to docker build
  195. - **Prevention**: Always specify platform in Dockerfile
  196. ```
  197. ### decisions.md - Architectural Decisions
  198. ```markdown
  199. ### ADR-001: Use Workload Identity Federation (2025-01-10)
  200. **Context:**
  201. - Need secure authentication from GitHub Actions to GCP
  202. **Decision:**
  203. - Use Workload Identity Federation instead of service account keys
  204. **Alternatives Considered:**
  205. - Service account JSON keys → Rejected: security risk
  206. **Consequences:**
  207. - ✅ More secure (no long-lived credentials)
  208. - ❌ Slightly more complex initial setup
  209. ```
  210. ### key_facts.md - Project Configuration
  211. **⚠️ 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.
  212. ```markdown
  213. ### Database Configuration
  214. **AlloyDB Cluster:**
  215. - Cluster Name: `prod-cluster`
  216. - Private IP: `10.0.0.5`
  217. - Port: `5432`
  218. - Database Name: `contacts`
  219. **Connection:**
  220. - Use AlloyDB Auth Proxy for local development
  221. - Proxy command: `./alloydb-auth-proxy "projects/..."`
  222. - Credentials: Stored in `.env` file (not in git)
  223. ```
  224. ### issues.md - Work Log
  225. ```markdown
  226. ### 2025-01-15 - PROJ-123: Implement Contact API
  227. - **Status**: Completed
  228. - **Description**: Created FastAPI endpoints for contact CRUD
  229. - **URL**: https://jira.company.com/browse/PROJ-123
  230. - **Notes**: Added unit tests, coverage at 85%
  231. ```
  232. ## Verification
  233. After installation, verify the skill is available:
  234. 1. Open Claude Code in any project
  235. 2. Type `/` to see available skills
  236. 3. You should see `project-memory` in the list
  237. Or check manually:
  238. ```bash
  239. # For global installation
  240. ls ~/.claude/skills/project-memory/SKILL.md
  241. # For project-specific installation
  242. ls .claude/skills/project-memory/SKILL.md
  243. # For workspace installation
  244. ls ../.claude/skills/project-memory/SKILL.md # From inside a project
  245. ```
  246. ## Security Best Practices
  247. ### ⚠️ Critical: Never Store Secrets in Version Control
  248. 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:
  249. **❌ NEVER store in key_facts.md or any git-tracked file:**
  250. - Passwords or passphrases
  251. - API keys or authentication tokens
  252. - Service account JSON keys or credentials
  253. - Database passwords
  254. - OAuth client secrets
  255. - Private keys or certificates
  256. - Session tokens
  257. - Any secret values from environment variables
  258. **✅ SAFE to store in key_facts.md:**
  259. - Database hostnames, ports, and cluster names
  260. - Client names and project identifiers
  261. - JIRA project keys and Confluence space names
  262. - AWS account names and profile names (e.g., "dev", "staging", "prod")
  263. - API endpoint URLs (public URLs only)
  264. - Service account email addresses (not the keys!)
  265. - GCP project IDs and region names
  266. - Docker registry names
  267. - Environment names and deployment targets
  268. **✅ WHERE to store sensitive credentials:**
  269. - **`.env` files** - Excluded via `.gitignore`, used for local development
  270. - **Password managers** - 1Password, LastPass, Bitwarden, etc.
  271. - **Secrets managers** - AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Azure Key Vault
  272. - **CI/CD environment variables** - GitHub Secrets, GitLab CI/CD Variables, etc.
  273. - **Platform credential stores** - Kubernetes Secrets, Cloud Run Secret Manager integration
  274. **✅ VERIFICATION steps before committing:**
  275. 1. Run `git status` to see what will be committed
  276. 2. Verify `.env`, `credentials.json`, and other sensitive files are in `.gitignore`
  277. 3. Never use `git add .` blindly - review each file being staged
  278. 4. Use `git diff --cached` to review staged changes before committing
  279. 5. Consider using tools like `git-secrets` or `gitleaks` to prevent credential leaks
  280. **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.
  281. ## Features
  282. ### Memory-Aware Protocols
  283. Once set up, Claude Code will:
  284. - ✅ Check `decisions.md` before proposing architectural changes
  285. - ✅ Search `bugs.md` for known solutions to errors
  286. - ✅ Reference `key_facts.md` for project configuration
  287. - ✅ Log completed work in `issues.md`
  288. - ✅ Document new bugs, decisions, and facts as they arise
  289. ### Style Guidelines
  290. All memory files follow these principles:
  291. - **Bullet lists** over tables (simpler to edit)
  292. - **Concise entries** (1-3 lines for descriptions)
  293. - **Always dated** (YYYY-MM-DD format)
  294. - **Include URLs** (for tickets, docs, monitoring)
  295. - **Manual cleanup** (periodically remove old entries)
  296. ### Cross-Tool Compatibility
  297. The memory system works across different AI coding tools:
  298. - Claude Code (via CLAUDE.md)
  299. - Cursor (via .cursor/rules or CLAUDE.md)
  300. - GitHub Copilot (via AGENTS.md or .github/copilot-instructions.md)
  301. - Other tools that read project configuration files
  302. ## Why Use This Skill?
  303. **Without project memory:**
  304. - Repeat the same bugs/solutions across sessions
  305. - Propose architectures that conflict with past decisions
  306. - Ask the user repeatedly for database credentials, API keys, ports
  307. - Lose context when switching between projects or AI tools
  308. **With project memory:**
  309. - Remember and apply known bug solutions instantly
  310. - Maintain architectural consistency across sessions
  311. - Reference documented facts instead of assumptions
  312. - Preserve institutional knowledge across team members and tools
  313. ## Real-World Impact: Pattern Recognition in Action
  314. ### Example 1: Bug Resolution - Infrastructure State Drift
  315. **The Scenario:**
  316. 1. **Oct 20** - Claude Code encounters Pulumi state drift error during deployment
  317. 2. **Investigation** - 45 minutes debugging, trying various solutions
  318. 3. **Solution Found** - `pulumi refresh --yes` resolves the state inconsistency
  319. 4. **Documentation** - Logged as BUG-017 and BUG-018 in bugs.md, decision documented in ADR-016
  320. 5. **Oct 22** - Same state drift error occurs during a new deployment
  321. **Without Project Memory:**
  322. - Claude Code debugs from scratch (again)
  323. - 30-60 minutes of investigation
  324. - Risk of trying wrong solutions first
  325. - Possible production delay
  326. - User frustration: "Didn't we solve this already?"
  327. **With Project Memory:**
  328. ```
  329. Claude Code: Searching bugs.md for "state drift"...
  330. Found: BUG-018 - Pulumi State Drift Error
  331. Known solution: pulumi refresh --yes
  332. Applying fix... Done in 2 minutes.
  333. Reference: See ADR-016 for why this works.
  334. ```
  335. **Result:**
  336. - ✅ Instant recognition: "This is BUG-018"
  337. - ✅ Known solution applied immediately
  338. - ✅ 5 minutes instead of 45 minutes
  339. - ✅ References explain why this works (ADR-016)
  340. **Knowledge Compound Interest:** Every bug solved and documented makes future work exponentially faster.
  341. ### Example 2: Architectural Consistency - Avoiding Duplicate Dependencies
  342. **The Scenario:**
  343. 1. **Week 1** - Team evaluates charting libraries for scatter plots
  344. 2. **Decision** - Selected D3.js for all visualizations (lightweight, flexible, already in dependencies)
  345. 3. **Documentation** - Logged as ADR-012 in decisions.md with rationale
  346. 4. **Week 4** - New feature requires a bar chart visualization
  347. **Without Project Memory:**
  348. ```
  349. User: "Add a bar chart to the dashboard"
  350. Claude Code: "I'll add Chart.js for the bar chart visualization."
  351. [Adds Chart.js to package.json - now we have D3.js AND Chart.js]
  352. Result: Bundle size +85KB, inconsistent chart styling, duplicate dependencies
  353. ```
  354. **With Project Memory:**
  355. ```
  356. User: "Add a bar chart to the dashboard"
  357. Claude Code: Checking decisions.md for visualization decisions...
  358. Found: ADR-012 - Use D3.js for all charts
  359. Claude Code: "I'll implement the bar chart using D3.js to maintain consistency with ADR-012."
  360. [Uses existing D3.js dependency]
  361. Result: No new dependencies, consistent styling, smaller bundle
  362. ```
  363. **Result:**
  364. - ✅ Maintains architectural consistency
  365. - ✅ Avoids dependency bloat
  366. - ✅ Ensures consistent user experience
  367. - ✅ Faster development (reuse existing patterns)
  368. **Key Insight:** Remembering past decisions prevents architectural drift and keeps the codebase cohesive.
  369. ### Example 3: The "Didn't We Fix This?" Problem
  370. **The Reality of Long-Running Projects:**
  371. Many developers (and AI code assistants) encounter the same bugs months apart and completely forget the solution:
  372. **Month 1:**
  373. ```
  374. Error: CORS policy blocked request from localhost:3000
  375. [2 hours of debugging]
  376. Solution: Add proxy configuration to package.json
  377. ```
  378. **Month 6:**
  379. ```
  380. Error: CORS policy blocked request from localhost:3000
  381. Developer: "This looks familiar... how did we fix this?"
  382. [Searches old commits, checks Stack Overflow again]
  383. [1 hour to re-discover the proxy config solution]
  384. ```
  385. **With Project Memory:**
  386. ```
  387. Error: CORS policy blocked request from localhost:3000
  388. Claude Code: Searching bugs.md for "CORS"...
  389. Found: BUG-003 - CORS Blocked in Local Development
  390. Solution: proxy config in package.json
  391. Applied in 5 minutes.
  392. ```
  393. **The Code Agent Memory Problem:**
  394. AI code assistants don't remember previous sessions. Without documentation:
  395. - Each new chat session starts from zero knowledge
  396. - Every bug feels like the first time
  397. - Solutions are "rediscovered" repeatedly
  398. - No learning accumulates over time
  399. **With project memory, the code agent becomes progressively smarter:**
  400. - First encounter: 2 hours to solve → documented in bugs.md
  401. - Second encounter: 5 minutes (reads bugs.md)
  402. - Third encounter: 2 minutes (pattern now familiar)
  403. - Fourth encounter: Preventative advice (suggests avoiding the issue)
  404. This is **knowledge compound interest** - your project gets easier to maintain over time, not harder.
  405. ## Skill File Structure
  406. ```
  407. project-memory/
  408. ├── SKILL.md # Main skill instructions for Claude
  409. ├── CLAUDE.md # This repository's Claude guidance
  410. ├── README.md # This file
  411. └── references/ # Templates for memory files
  412. ├── bugs_template.md
  413. ├── decisions_template.md
  414. ├── key_facts_template.md
  415. └── issues_template.md
  416. ```
  417. ## Design Philosophy
  418. 1. **Looks like standard engineering docs** - Using `docs/project_notes/` instead of `memory/` makes it appear as normal engineering organization, not AI-specific tooling.
  419. 2. **Prefer simplicity** - Bullet lists over tables, concise over exhaustive, manual cleanup over automation.
  420. 3. **Document what matters** - Focus on recurring bugs, important decisions, and frequently-needed facts.
  421. 4. **Enable collaboration** - Works across AI tools, readable by humans, version-controllable with git.
  422. ## Examples
  423. ### Setting Up Memory in a New Project
  424. ```bash
  425. cd ~/projects/my-new-app
  426. claude code
  427. ```
  428. In Claude Code:
  429. ```
  430. /project-memory
  431. ```
  432. Claude will create the memory infrastructure and configure CLAUDE.md.
  433. ### Documenting a Bug Fix
  434. ```
  435. I just fixed a bug where the database connection pool was exhausted.
  436. Add it to bugs.md with the solution.
  437. ```
  438. ### Checking for Existing Decisions
  439. ```
  440. I'm thinking about using SQLAlchemy for migrations.
  441. Check if we already have a decision about this.
  442. ```
  443. Claude will search `decisions.md` and apply existing choices.
  444. ### Updating Project Facts
  445. ```
  446. Update key_facts.md with the new staging environment URL:
  447. https://staging-api.company.com
  448. ```
  449. ## Maintenance
  450. Memory files are **manually maintained**:
  451. - **bugs.md** - Remove very old entries (6+ months) that are no longer relevant
  452. - **decisions.md** - Keep all decisions (they're lightweight and provide historical context)
  453. - **key_facts.md** - Update when project configuration changes
  454. - **issues.md** - Archive completed work (3+ months old)
  455. ## Integration with Other Skills
  456. This skill complements other Claude Code skills:
  457. - **requirements-documenter** - Requirements inform ADRs in decisions.md
  458. - **root-cause-debugger** - Bug diagnosis results documented in bugs.md
  459. - **code-quality-reviewer** - Quality standards documented in decisions.md
  460. - **docs-sync-editor** - Code changes trigger updates to key_facts.md
  461. ## Troubleshooting
  462. ### Skill not appearing in Claude Code
  463. **Check installation location:**
  464. ```bash
  465. # Global installation
  466. ls ~/.claude/skills/project-memory/SKILL.md
  467. # Project-specific installation
  468. ls .claude/skills/project-memory/SKILL.md
  469. ```
  470. **Ensure SKILL.md exists:**
  471. The skill must have a `SKILL.md` file with proper frontmatter:
  472. ```yaml
  473. ---
  474. name: project-memory
  475. description: Set up and maintain a structured project memory system...
  476. ---
  477. ```
  478. ### Memory files not being created
  479. **Verify you're in a project directory:**
  480. The skill creates files in the current working directory's `docs/project_notes/` folder.
  481. **Check permissions:**
  482. Ensure you have write permissions in the project directory.
  483. ### Claude not checking memory files
  484. **Verify CLAUDE.md was updated:**
  485. ```bash
  486. grep "Project Memory System" CLAUDE.md
  487. ```
  488. The "Project Memory System" section should be present with complete protocols.
  489. ## Contributing
  490. To improve this skill:
  491. 1. Update templates in `references/` directory
  492. 2. Enhance `SKILL.md` with new capabilities
  493. 3. Update `CLAUDE.md` with workflow changes
  494. 4. Test in a sample project
  495. ## License
  496. This skill is part of the Claude Code skills ecosystem and follows standard usage guidelines for Claude Code extensions.
  497. ## Support
  498. For issues or questions:
  499. - Check the troubleshooting section above
  500. - Review `SKILL.md` for detailed skill instructions
  501. - Review `CLAUDE.md` for repository-specific guidance
  502. - Consult Claude Code documentation at https://docs.claude.com/en/docs/claude-code

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.