# Proj Memory

> Set up and maintain structured project memory systems that track bugs with solutions, architectural decisions, key project facts, and work history. Use when setting up new projects, documenting decisions, tracking bugs and solutions, or maintaining project knowledge across sessions.

- Skill: `karim-bhalwani/proj-memory` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add karim-bhalwani/proj-memory`
- Raw SKILL.md: https://api.skillmd.com/api/skills/karim-bhalwani/proj-memory/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: karim-bhalwani (https://skillmd.com/u/karim-bhalwani)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/karim-bhalwani/proj-memory

---


# Project Memory

Maintain institutional knowledge across your project lifecycle and team members.

## When to Use This Skill

Use when:

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

---

## Core Capabilities

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

---

## Memory System Structure

### Directory Layout

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

**Why `docs/project_notes/`?**

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

### File Purposes

| File | Content | Audience | Refresh Rate |
| :--- | :------- | :-------- | :----------- |
| bugs.md | Bug descriptions, root causes, solutions | Developers | Continuous |
| decisions.md | Architectural decisions with rationale | Architects, leads | Quarterly |
| key_facts.md | Configuration, URLs, ports, facts | All | Monthly |
| tracks.md | Work log, completed tickets | PM, team | Weekly |

---

## Reference Guide

### [Project Memory Setup & Management](references/memory-setup.md)

**Use when:** Creating or maintaining project memory

Covers:

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

---

## Quick Start

### For New Projects

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

### For Existing Projects

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

---

## Memory File Content

### bugs.md Structure

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

Example:

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

### decisions.md Structure (ADR Format)

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

**Context**: Why decision was needed

**Decision**: What was chosen

**Alternatives**: What was rejected and why

**Consequences**: Benefits and trade-offs
```

### key_facts.md Structure

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

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

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

### tracks.md Structure

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

---

## Integration with AGENT.md

Add memory section to `AGENT.md`:

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

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

---

## Best Practices

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

---

## Common Patterns

### Bug Discovery Workflow

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

### Decision Making Workflow

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

### Configuration Reference

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

---

## Quarterly Maintenance

Every quarter:

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

---

## Success Metrics

Good project memory:

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

---

## Dependencies

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