@ldavis9000aws/mcp-project-memory/docs/claude-integration.md

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

# Integrating with Claude

This guide explains how to use the Project Memory server with Claude or other LLMs to maintain persistent context for software development projects across multiple chat sessions.

## Prerequisites

- Node.js 14+ installed
- NPX or UVX installed (comes with Node.js/UVX)

## Installation Options

### Option 1: Global Installation

```bash
# Install globally using npm
npm install -g mcp-project-memory

# Or using UVX
uvx install mcp-project-memory
```

### Option 2: NPX Usage (No Installation)

You can run the memory server directly without installation using NPX:

```bash
npx mcp-project-memory start
```

### Option 3: Local Installation

```bash
# Clone and install locally
git clone https://github.com/ldavis9000aws/mcp-project-memory.git
cd mcp-project-memory
npm install
npm run build
```

## Setup Process

### 1. Start the Memory Server

The memory server needs to be running to provide persistent memory to Claude. Start it with:

```bash
# Using NPX (no installation)
npx mcp-project-memory start

# Or if installed globally
mcp-project-memory start

# Start as a background daemon
npx mcp-project-memory daemon

# Specify a custom memory file
npx mcp-project-memory start path/to/memory.json
```

### 2. Configure Claude with the MCP URL

When starting Claude, you need to configure the MCP URL to point to the Project Memory server. The exact method depends on your Claude integration, but it typically involves specifying the server URL in environment variables or configuration settings.

### 3. Apply the Project Memory Prompt Template

Add the project memory prompt template to your system prompt when interacting with Claude. The full template is provided below in the "Prompt Template" section.

## Prompt Template

```
Follow these steps during each software development interaction:

1. Project Identification:
   - You should assume you are working on the last identified project
   - If no project has been identified, ask which software project we're discussing

2. Memory Retrieval:
   - Begin each session with "Remembering project context..." and retrieve relevant information about:
     a) Project architecture and components
     b) Previous design decisions and their rationales
     c) Current implementation status
     d) Known issues and their workarounds
     e) Future development plans

3. Development Memory Collection:
   - While assisting with development, be attentive to information that falls into these categories:
     a) Architecture Decisions (patterns, frameworks, libraries chosen and why)
     b) Implementation Details (key algorithms, data structures, integration points)
     c) Technical Challenges (limitations, performance issues, bugs encountered)
     d) Solutions Applied (how problems were solved, alternatives considered)
     e) Future Considerations (TODOs, planned refactorings, technical debt)

4. Memory Update:
   - When important development information is discussed, update your memory as follows:
     a) Create entities for:
       - Components (frontend modules, backend services, databases)
       - Technologies (languages, frameworks, libraries)
       - Issues (bugs, performance problems, security concerns)
     b) Connect them using relations that describe their interactions
     c) Store specific implementation details as observations
     d) Include timestamps with observations to track when decisions were made
     e) Document the rationale behind significant design decisions

5. Error & Issue Tracking:
   - Create specific entities for recurring errors or issues
   - Link issues to the components where they occur
   - Track resolution status and applied fixes
   - Document workarounds for unresolved issues
   - Note any lessons learned from debugging processes

6. Memory Triggers:
   When you observe these triggers, update the project memory:
   
   a) Code Discussions:
      - When code snippets are shared, record them as observations on the relevant component
      - When bugs are discussed, create Issue entities and link them to components
   
   b) Design Decisions:
      - When architectural choices are made, create Decision entities
      - When tech stack selections are discussed, create Technology entities
   
   c) Implementation Updates:
      - When progress is reported, update Component observations
      - When challenges are mentioned, create Issue entities

7. Memory Access Commands:
   Recognize these user commands to access specific memory functions:
   
   - "What do you remember about [component]?"
   - "Show all issues for [component]"
   - "What was our decision about [topic]?"
   - "List all components of [project]"
   - "What technologies are we using for [component]?"
   - "What were recent changes to [component]?"
```

## Using Claude with Project Memory

Once set up, Claude will maintain persistent memory of your software development context across sessions. Here's how to effectively use this capability:

### Project Structure Documentation

When discussing your project structure, be specific about components and their relationships:

"The backend is built with Node.js and uses Express for the API layer. It connects to a PostgreSQL database."

Claude will record this information as entities and relations.

### Recording Design Decisions

When making important design decisions, explicitly state them and their rationale:

"We've decided to use React Query for data fetching because it provides built-in caching and reduces boilerplate code."

### Tracking Issues

When discussing bugs or challenges, provide specific details:

"We're encountering a memory leak in the image carousel component that causes slowdown after extended use."

### Accessing Memory

To retrieve information from previous sessions, use memory access commands:

"What do you remember about our authentication service?"
"Show all issues for the frontend app."
"What was our decision about the database schema?"

## Troubleshooting

### Memory Not Being Retained

1. Check that the memory server is running (`ps aux | grep node`)
2. Verify the memory file exists and has content
3. Ensure Claude is configured correctly with the MCP URL

### Server Crashes

1. Check the error logs in the logs directory
2. Verify Node.js is version 14 or higher
3. Ensure the memory file is valid JSON

### Claude Not Using Memory

1. Confirm you've included the prompt template in your system prompt
2. Try explicit memory access commands
3. Check if Claude is properly configured with the MCP server