@ldavis9000aws/mcp-project-memory/docs/best-practices.md

Enhanced memory system for software development projects with persistent context across sessions

# Best Practices for Project Memory

This guide provides recommendations for effectively using the Project Memory system to maintain persistent context across software development sessions.

## Knowledge Graph Structure

### Entity Naming Conventions

- Use consistent naming patterns for entities:
  - **PascalCase**: `AuthenticationService`, `UserDatabase`, `ReactFrontend`
  - **Underscore_Case**: `Authentication_Service`, `User_Database`, `React_Frontend`
- Choose descriptive names that clearly identify the entity
- Avoid abbreviations unless they're widely understood in your domain
- Use the same name consistently when referring to a component

### Entity Type Selection

Select the most appropriate entity type for the concept you're representing:

- **Project**: Top-level container for a software project
  - Example: `ECommercePlatform`, `DataAnalyticsDashboard`
  
- **Component**: Distinct functional part of a software system
  - Example: `AuthenticationService`, `PaymentProcessor`, `UserInterface`
  
- **Technology**: Frameworks, languages, or tools used in the project
  - Example: `ReactJS`, `PostgreSQL`, `Docker`
  
- **Issue**: Bug, error, or problem encountered
  - Example: `ConnectionTimeout`, `MemoryLeak`, `SecurityVulnerability`
  
- **Decision**: Architectural or implementation choice
  - Example: `MicroserviceArchitecture`, `DatabaseSelection`, `AuthStrategy`

### Relation Type Usage

Use specific relation types to describe the relationships between entities:

- **contains**: Parent-child relationship
  - Example: `Project contains Component`, `Component contains Subcomponent`

- **uses**: Implementation or dependency relationship
  - Example: `Component uses Technology`, `Service uses Library`

- **depends_on**: Functional dependency between components
  - Example: `Frontend depends_on Backend`, `Service depends_on Database`

- **affected_by**: Issue impact relationship
  - Example: `Component affected_by Bug`, `Service affected_by Performance_Issue`

- **resolved_by**: Solution relationship for issues
  - Example: `Bug resolved_by Code_Fix`, `Issue resolved_by Design_Change`

- **led_to**: Causality relationship between decisions
  - Example: `Initial_Decision led_to Follow_Up_Decision`

## Observation Quality

### Writing Effective Observations

- Be specific and concrete rather than vague
- Include relevant technical details
- Keep each observation focused on a single piece of information
- Use clear, consistent language

#### Before (Poor):
```
"Has some issues with the database sometimes"
```

#### After (Good):
```
"Connection pool exhaustion occurs under high load (>500 concurrent users)"
```

### Include Key Information Types

When writing observations, include these types of information:

1. **Context**: Environment, conditions, or situations
2. **Technical details**: Versions, settings, configurations
3. **Rationale**: Reasons behind decisions
4. **Impact**: Effects on other components or users
5. **Status**: Current state (if applicable)

#### Example:

```
"Using PostgreSQL 14 with TimescaleDB extension for time-series data"
"Chosen for performance on large datasets and native time partitioning"
"Connection pooling via PgBouncer with max 50 connections"
"Current data volume: ~500GB with 30-day retention policy"
```

## Memory Management Workflow

### When To Update Memory

Update the knowledge graph at these key moments:

1. **Initial Project Setup**: Define the core structure
2. **Architecture Decisions**: When making significant design choices
3. **Issue Discovery**: When bugs or problems are encountered
4. **Issue Resolution**: When fixes are implemented
5. **Implementation Progress**: After completing major features
6. **Technical Changes**: When modifying the technology stack
7. **Future Planning**: When discussing roadmap items

### Structure for Different Development Activities

#### Architecture Design

1. Create `Decision` entities for major architectural choices
2. Document alternatives considered and rationale
3. Link decisions to affected components
4. Track decision dependencies (`Decision_A led_to Decision_B`)

#### Bug Tracking

1. Create `Issue` entities for bugs
2. Link to affected components
3. Document reproduction steps and impact
4. Update with resolution information when fixed

#### Feature Development

1. Create `Component` entities for new features
2. Document implementation details as observations
3. Link to parent components and dependencies
4. Update with progress and completion status

## Claude Integration Tips

### Setting Context Effectively

When starting a session with Claude:

1. **Project Introduction**: Briefly describe the project at the start
2. **Component Focus**: Specify which component you're working on
3. **Task Context**: Explain what you're trying to accomplish

Example:
```
"I'm working on the AuthService component of our e-commerce platform. Today I need to implement token refresh functionality."
```

### Memory Triggers

To ensure Claude updates memory appropriately, use these triggers:

#### For Design Decisions:

```
"We've decided to use JWT tokens with a 15-minute expiration and separate refresh tokens."
```

#### For Implementation Details:

```
"I've implemented the token refresh using Axios interceptors that automatically refresh on 401 errors."
```

#### For Issues:

```
"We're encountering a race condition where multiple refresh attempts happen simultaneously."
```

### Memory Retrieval

To retrieve information from memory, use consistent phrasing:

- "What do you remember about the authentication service?"
- "Show me all issues related to the payment processor."
- "What was our decision about the database schema?"
- "What components depend on the authentication service?"

## Advanced Usage

### Tracking Decision Evolution

Track how decisions change over time by creating related decisions and linking them:

1. Create the initial decision (`Original_Architecture`)
2. When the decision changes, create a new decision (`Architecture_Update`)
3. Link them with a `supersedes` relation:
   ```
   Architecture_Update supersedes Original_Architecture
   ```
4. Document the reason for the change in observations

### Component Versioning

Track component versions by adding version information in observations:

```
"Version 2.0: Rewritten with TypeScript"
"Version 2.1: Added support for OAuth providers"
"Version 2.2: Performance optimizations for token validation"
```

### Cross-Project References

When components are shared across projects:

1. Create the component entity once
2. Link it to multiple projects using `contains` relations
3. Use observations to note project-specific configurations

Example:
```
"Shared between ECommercePlatform and AdminDashboard"
"In ECommercePlatform: configured with customer roles"
"In AdminDashboard: configured with admin privileges"
```

## Troubleshooting Common Issues

### Entity Duplication

If you find duplicate entities for the same concept:

1. Decide which entity to keep
2. Transfer unique observations from the duplicate to the kept entity
3. Update relations to point to the kept entity
4. Delete the duplicate entity

### Relation Errors

If relations are incorrectly defined:

1. Identify the correct relation type
2. Delete the incorrect relation
3. Create a new relation with the correct type

### Missing Context

If you find Claude is missing context:

1. Check if relevant entities exist in memory
2. Verify relations between entities are correctly defined
3. Add more detailed observations to existing entities
4. Use more specific memory retrieval queries

## Memory Maintenance

Periodically perform these maintenance tasks:

1. **Clean up redundant observations**: Consolidate similar information
2. **Update status information**: Mark resolved issues, completed tasks
3. **Validate relation consistency**: Ensure relations accurately reflect the system
4. **Archive old information**: Add timestamp context to historical information
5. **Consolidate fragmented entities**: Merge related small entities if appropriate