adam-palmer1/pymcp-memory-server

Claude MCP Server

A network-based Python MCP (Model Context Protocol) server that enables multiple Claude instances to communicate and share persistent memory across sessions.

Features

🔄 Multi-Instance Communication

• Real-time WebSocket messaging between Claude instances
• Broadcast messages to all instances in a workspace
• Direct messaging between specific instances
• Server-Sent Events (SSE) for real-time updates

💾 Persistent Memory System

• Store and retrieve structured information across sessions
• Automatic versioning with conflict resolution
• Multiple memory types: decisions, API specs, features, context, code, knowledge
• Fast caching with Redis for quick access

🕸️ Knowledge Graph

• Store relationships between concepts, APIs, and features
• Semantic search across project knowledge
• Visualize dependencies and connections
• Query using natural language

🔐 Security & Authentication

• JWT-based authentication for each Claude instance
• End-to-end encryption for sensitive data
• Rate limiting and quota management
• Workspace isolation for multi-project support

📦 Storage Architecture

• PostgreSQL for structured persistent memory
• Redis for pub/sub messaging and caching
• MinIO/S3 for large artifact storage
• Neo4j for knowledge graph (optional)

Quick Start

Using Docker Compose (Recommended)

1. Clone the repository:

git clone <repository-url>
cd claude-mcp-server

2. Copy environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Start all services:

docker-compose up -d

4. The server will be available at http://localhost:6792

Manual Installation

1. Install dependencies:

pip install poetry
poetry install

2. Start required services:

• PostgreSQL (port 5432)
• Redis (port 6379)
• MinIO (port 9000)
• Neo4j (optional, port 7687)

3. Run migrations:

poetry run alembic upgrade head

4. Start the server:

poetry run python -m src.main

Usage

Note: All demo functionality has been removed. The server now exclusively uses PostgreSQL for persistent storage.

MCP Client for Claude

from src.tools.mcp_client import MCPClient

# Initialize client
client = MCPClient(
    server_url="http://localhost:8000",
    instance_name="claude-backend-dev",
    workspace_id="my-project"
)

# Connect to server
await client.connect()

# Store memory
await client.store_memory(
    key="api.auth.endpoints",
    content="Authentication endpoints: POST /login, POST /logout, GET /me",
    memory_type="api_spec"
)

# Retrieve memory
memory = await client.get_memory("api.auth.endpoints")

# Search memories
results = await client.search_memories(
    query="authentication endpoints",
    memory_type="api_spec"
)

# Send message to other instances
await client.broadcast_message({
    "type": "update",
    "message": "Authentication API updated"
})

# Add knowledge node
await client.add_knowledge_node(
    name="AuthenticationService",
    node_type="service",
    content={"endpoints": [...], "dependencies": [...]}
)

MCP Tools for Claude

The server provides MCP tools that can be used directly by Claude:

• memory_store: Store information persistently
• memory_retrieve: Retrieve stored information
• broadcast_message: Send messages to all instances
• send_direct_message: Send message to specific instance
• list_instances: List active Claude instances
• knowledge_add: Add node to knowledge graph
• knowledge_link: Create relationships between nodes
• knowledge_query: Query the knowledge graph

API Endpoints

Instance Management

• POST /api/v1/instances/register - Register new Claude instance
• GET /api/v1/instances - List active instances

Memory Operations

• POST /api/v1/memories - Store new memory
• GET /api/v1/memories/{key} - Retrieve specific memory
• PATCH /api/v1/memories/{key} - Update memory
• GET /api/v1/memories/search - Search memories

Knowledge Graph

• POST /api/v1/knowledge/nodes - Create knowledge node
• POST /api/v1/knowledge/edges - Create relationship
• GET /api/v1/knowledge/query - Query knowledge graph

WebSocket

• WS /ws?token={jwt_token} - Real-time communication

Server-Sent Events

• GET /api/v1/events/stream - Subscribe to workspace events

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ Claude Instance │     │ Claude Instance │     │ Claude Instance │
│   (Backend)     │     │  (Frontend A)   │     │  (Frontend B)   │
└────────┬────────┘     └────────┬────────┘     └────────┬────────┘
         │                       │                         │
         └───────────────────────┼─────────────────────────┘
                                │
                        ┌───────▼────────┐
                        │                │
                        │   MCP Server   │
                        │   (FastAPI)    │
                        │   Port: 6792   │
                        └───────┬────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        │                       │                       │
┌───────▼────────┐     ┌───────▼────────┐     ┌───────▼────────┐
│                │     │                │     │                │
│   PostgreSQL   │     │     Redis      │     │     MinIO      │
│   (Memories)   │     │   (Pub/Sub)    │     │  (Artifacts)   │
│                │     │                │     │                │
└────────────────┘     └────────────────┘     └────────────────┘

Development

Running Tests

poetry run pytest

Code Formatting

poetry run black src/
poetry run ruff src/

Type Checking

poetry run mypy src/

Configuration

See .env.example for all available configuration options.

Key settings:

• SECRET_KEY: Change this to a random string in production
• MAX_MEMORY_SIZE_MB: Maximum size for individual memory entries
• WS_MAX_CONNECTIONS_PER_INSTANCE: Connection limit per Claude instance
• MEMORY_CACHE_TTL: Cache expiration time in seconds

License

MIT