# Project Memory MCP Server

A knowledge graph-based memory system specialized for software development projects, designed to maintain persistent context across chat sessions.

## Installation

### Using NPX (No Installation Required)

```bash
# Start the server directly without installation
npx @ldavis9000aws/mcp-project-memory start

# Specify a custom memory file path
npx @ldavis9000aws/mcp-project-memory start custom-memory.json

# Run as a background daemon
npx @ldavis9000aws/mcp-project-memory daemon
```

### Global Installation

```bash
# Install globally
npm install -g @ldavis9000aws/mcp-project-memory

# Then use the command anywhere
mcp-project-memory start
```

### Local Development

```bash
# Clone the repository
git clone https://github.com/ldavis9000aws/mcp-project-memory.git
cd mcp-project-memory

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start
```

## Features

- **Project Context Persistence**: Remembers project architecture, components, and design decisions
- **Technical Decision Tracking**: Records why specific technical choices were made with timestamps
- **Issue Management**: Tracks bugs, errors, and their resolutions over time
- **Component Relationships**: Maps dependencies and interactions between project components
- **Implementation History**: Maintains a historical record of how the codebase evolved

## Core Concepts

### Entity Types

- **Project**: Root node containing project metadata
- **Component**: Represents software components (services, modules, libraries)
- **Technology**: Tracks technologies, frameworks, and libraries used
- **Issue**: Documents errors, bugs, and technical challenges
- **Decision**: Records architectural and implementation decisions with rationale

### Relations

Relations define how entities connect, using meaningful verbs in active voice:

- **contains**: Shows hierarchy of components
- **uses**: Tracks technology implementations
- **depends_on**: Maps dependencies between components
- **affected_by**: Links issues to components
- **resolved_by**: Connects issues to their solutions
- **led_to**: Shows decision chains and consequences

## Using with Claude

This MCP server is designed to work with Claude instances to provide persistent memory of software development contexts.

### Integration with Claude Desktop

To use Project Memory with Claude Desktop:

1. Open Claude Desktop and click on the three dots (⋮) in the top-right corner
2. Select "Preferences"
3. Navigate to the "Advanced" tab
4. Under "MCP Configuration", add the following:

```json
{
  "mcp": {
    "memory": {
      "command": "npx @ldavis9000aws/mcp-project-memory start memory.json"
    }
  }
}
```

For detailed instructions, see [Claude Desktop Integration](docs/claude-desktop.md).

### Integration with LibreChat

For detailed LibreChat integration instructions, see [LibreChat Integration](docs/librechat.md).

### Example Prompt

```
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
```

## API Documentation

### Tools

- **create_entities**: Add new components, technologies, or issues
- **create_relations**: Map interactions between components
- **add_observations**: Record details about entities
- **find_development_history**: Query the development history of components
- **record_issue**: Log errors and issues with structured metadata
- **delete_entities**: Remove entities from the graph
- **read_graph**: Retrieve the full knowledge graph
- **search_nodes**: Find entities by query
- **get_related_entities**: Retrieve entities connected to a specific entity
- **get_project_overview**: Get a summary of a project's structure
- **open_nodes**: Retrieve specific entities by name

## Development

```bash
# Clone the repository
git clone https://github.com/ldavis9000aws/mcp-project-memory.git
cd mcp-project-memory

# Install dependencies
npm install

# Run tests
npm test

# Feature tests
npm run test:features
```

## License

MIT