Metadata-Version: 2.3
Name: mcp-agentmemory
Version: 0.1.2
Summary: Add your description here
Author: Jens Rehpöhler
Author-email: Jens Rehpöhler <jens.rehpoehler@bertelsmann.de>
Requires-Dist: asyncio>=4.0.0
Requires-Dist: click>=8.2.1
Requires-Dist: fastmcp>=2.11.3
Requires-Dist: pydantic>=2.11.7
Requires-Python: >=3.12
Project-URL: Issues, https://github.com/jenreh/MCP-AgentMemory/issues
Project-URL: Repository, https://github.com/jenreh/MCP-AgentMemory
Description-Content-Type: text/markdown

# Memory Graph MCP Server for Python Development

A specialized MCP server that tracks your Python development sessions, errors, fixes, and coding patterns using a persistent knowledge graph. This helps you build a searchable database of your development learnings, solutions, and insights.

## Core Concepts

### Entities
Entities represent the building blocks of your development knowledge:
- **Features**: Projects or tasks you're working on
- **Sessions**: Individual development work periods
- **Errors**: Persistent error tracking with fingerprinting
- **Patterns**: Reusable solutions and coding patterns
- **Modules/Classes/Functions**: Code structure elements

Example:
```json
{
  "name": "user-authentication",
  "entityType": "Feature",
  "tags": ["backend", "security"],
  "description": "JWT-based user authentication system"
}
```

### Relations
Relations connect your development knowledge to show how different pieces relate:
- `implements`: A session implements a feature
- `encounters`: A feature encounters an error
- `fixed_by`: An error is fixed by a pattern
- `depends_on`: Dependencies between modules/features

Example:
```json
{
  "from": "session:abc123",
  "to": "user-authentication",
  "relationType": "implements"
}
```

### Observations
Observations store your actual development insights and knowledge:
- **note**: General observations and learnings
- **snippet**: Code examples and implementations
- **error**: Exception details and stack traces
- **command**: CLI commands and scripts
- **qa**: Questions, answers, and troubleshooting

Example:
```json
{
  "kind": "snippet",
  "text": "JWT token validation middleware",
  "code": "def validate_jwt(token: str) -> dict:
    return jwt.decode(token, SECRET_KEY)",
  "language": "python",
  "tags": ["jwt", "middleware", "auth"]
}
```

## API Tools

### Core Knowledge Management
- **upsert_entity**: Create or update entities (features, patterns, concepts)
- **create_relations**: Establish connections between entities
- **add_insights**: Store observations and code snippets
- **read_graph**: Retrieve the complete knowledge graph
- **search_insights**: Search through insights by text, tags, kind, or language

### Development Session Tracking
- **start_session**: Begin a tracked development session for a feature
- **log_event**: Record development activities, decisions, and code during a session
- **end_session**: Complete a session with a summary of outcomes

### Error and Solution Management
- **record_error**: Create persistent error entities with automatic fingerprinting
- **record_fix**: Attach solutions to errors and create reusable patterns

### Export and Maintenance
- **export_markdown**: Generate comprehensive documentation from your knowledge graph
- **compact_store**: Optimize storage by creating snapshots and clearing logs

## Usage with Claude Desktop

### Setup

Add this to your `claude_desktop_config.json`:

#### UV Script (Recommended)
```json
{
  "mcpServers": {
    "memory-graph": {
      "command": "uv",
      "args": [
        "run",
        "--script",
        "/path/to/your/init.py"
      ],
      "env": {
        "MEMORY_FILE_PATH": "~/.mcp/"
      }
    }
  }
}
```

#### Python Direct
```json
{
  "mcpServers": {
    "memory-graph": {
      "command": "python",
      "args": ["/path/to/your/init.py"],
      "env": {
        "MEMORY_FILE_PATH": "~/.mcp/"
      }
    }
  }
}
```

### Configuration

The server supports the following environment variable:
- `MEMORY_FILE_PATH`: Directory for storing memory files (default: `~/.mcp/`)

The server creates two files in the specified directory:
- `agentmemory.json`: Snapshot of the current knowledge graph
- `agentmemory.log.jsonl`: Append-only event log for durability

## Development Workflow Example

```python
# Start a development session
start_session(
    feature="payment-processing",
    description="Implementing Stripe payment integration",
    tags=["backend", "payments", "stripe"]
)

# Log your development activities
log_event(
    session_id="session-uuid",
    kind="snippet",
    text="Payment intent creation",
    code="stripe.PaymentIntent.create(amount=1000, currency='usd')",
    tags=["stripe", "payment-intent"]
)

# Record errors you encounter
record_error(
    feature="payment-processing",
    exception_type="StripeError",
    message="Invalid API key",
    traceback="...",
    tags=["stripe", "api-key"]
)

# Document the solution
record_fix(
    error_entity="error:abc123",
    description="API key must be set in environment variables",
    code="os.environ['STRIPE_SECRET_KEY'] = 'sk_test_...'",
    tags=["configuration", "environment"]
)

# End the session
end_session(
    session_id="session-uuid",
    success=True,
    summary="Successfully integrated Stripe payments with error handling"
)
```

## System Prompt for Development

Use this prompt to optimize the memory server for development work:

```
You are a development assistant with persistent memory. Follow these steps:

1. Session Management:
   - Start sessions when beginning focused development work
   - Log significant code changes, decisions, and learnings
   - Record errors and their solutions for future reference

2. Knowledge Capture:
   - Store useful code snippets with proper tagging
   - Document architectural decisions and trade-offs
   - Record debugging approaches and troubleshooting steps
   - Capture CLI commands and development workflows

3. Pattern Recognition:
   - Identify recurring solutions and create reusable patterns
   - Link related errors to their fixes
   - Build connections between similar technical concepts

4. Search and Retrieval:
   - Search previous solutions when encountering similar problems
   - Reference past sessions for context on ongoing features
   - Use tags and entity relationships to find relevant knowledge
```

## Building and Installation

### Requirements
- Python 3.12+
- Dependencies: `fastmcp`, `pydantic`, `click`

### UV Script Setup
The project includes a UV script configuration in `init.py` for easy dependency management:

```bash
# Make the script executable
chmod +x init.py

# Run with UV (handles dependencies automatically)
uv run --script init.py
```

### Manual Installation
```bash
# Install dependencies
pip install fastmcp pydantic click

# Run the server
python init.py --memory-file-path ~/.mcp/
```

## Storage and Persistence

The server uses a dual storage approach:
- **Snapshot file**: Complete knowledge graph state for fast loading
- **Event log**: Append-only log of all changes for durability and replay

Use `compact_store` periodically to optimize storage by creating fresh snapshots and clearing the event log.

## License

This MCP server is licensed under the MIT License. You are free to use, modify, and distribute the software under the terms of the MIT License.
