mcp-agentmemory 0.1.2

Add your description here

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:

{
  "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:

{
  "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:

{
  "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)

{
  "mcpServers": {
    "memory-graph": {
      "command": "uv",
      "args": [
        "run",
        "--script",
        "/path/to/your/init.py"
      ],
      "env": {
        "MEMORY_FILE_PATH": "~/.mcp/"
      }
    }
  }
}

Python Direct

{
  "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

# 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:

# Make the script executable
chmod +x init.py

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

Manual Installation

# 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.