Personal Neo4j Memory Server - Enhanced Cloudflare Access Support

A Model Context Protocol (MCP) server that provides AI assistants with persistent, intelligent memory capabilities using Neo4j's graph database with enhanced Cloudflare Access tunneling support.

🎯 What it does

This server enables AI assistants to:

• Remember - Store memories as interconnected knowledge nodes with observations and metadata
• Search - Find relevant memories using semantic vector search, exact matching, and graph traversal
• Connect - Create meaningful relationships between memories with batch operations and cross-references
• Organize - Separate memories by project using different databases
• Evolve - Track how knowledge develops over time with temporal metadata and relationship networks
• 🚀 NEW: Reliable Remote Access - Connect through Cloudflare Zero Trust Access from anywhere

✨ Key Features

Core Capabilities

• 🧠 Graph Memory - Memories as nodes, relationships as edges, observations as content
• 🔍 Unified Search - Semantic vectors, exact matching, wildcards, and graph traversal in one tool
• 🔗 Smart Relations - Typed connections with strength, source tracking, and temporal metadata
• 📊 Multi-Database - Isolated project contexts with instant switching
• ☁️ Cloudflare Access Ready - Zero Trust tunneling for secure remote connections

Advanced Operations

• ⚡ Batch Operations - Create multiple memories with relationships in single request using localId
• 🎯 Context Control - Response detail levels: minimal (lists), full (complete data), relations-only
• 📅 Time Queries - Filter by relative ("7d", "30d") or absolute dates on any temporal field
• 🌐 Graph Traversal - Navigate networks in any direction with depth control
• 🛡️ Zero Trust Security - mTLS encryption through Cloudflare Access

Architecture

• 🚀 MCP Native - Seamless integration with Claude Desktop and MCP clients
• 💾 Persistent Storage - Neo4j graph database with GDS plugin for vector operations
• ☁️ Cloudflare Optimized - Solved BOLT protocol tunneling issues
• ⚠️ Zero-Fallback - Explicit errors for reliable debugging, no silent failures

🚀 Quick Start - NPM Installation

Option 1: Install from NPM (Recommended)

# Coming soon - after publication
npm install @jeelidev/personal-neo4j-memory-server

Option 2: Install from GitHub (Available Now)

npx -y https://github.com/jeelidev/personal-neo4j-memory-server.git

📝 Claude Code Configuration

Add to Claude Desktop/Claude Code config:

For NPM Package (when published):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@jeelidev/personal-neo4j-memory-server"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

For GitHub Installation (Current):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "https://github.com/jeelidev/personal-neo4j-memory-server.git"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "your-password"
      }
    }
  }
}

☁️ Cloudflare Access Setup (CRITICAL FOR REMOTE SETUP)

🎯 The Problem Solved

Traditional Cloudflare Tunnel with TCP (cloudflared tunnel --url tcp://localhost:7687) fails for Neo4j BOLT protocol, causing HTTP 400 errors.

✅ The Solution: Cloudflare Access

Use cloudflared access tcp instead of cloudflared tunnel for reliable BOLT protocol connections.

1. Cloudflare Dashboard Configuration

Navigate to: Zero Trust → Networks → Tunnels → Public Hostnames

Add Public Hostname:

• Type: TCP
• Hostname: neo4j-bolt.jeelidev.uk (or your domain)
• Service: tcp://localhost:7687

2. Local Cloudflare Access Command

# Start tunnel for Neo4j BOLT
cloudflared access tcp --hostname neo4j-bolt.jeelidev.uk --url localhost:7687

# For multiple services (MySQL, PostgreSQL, SSH, etc.)
cloudflared access tcp --hostname mysql-server.jeelidev.uk --url localhost:3306
cloudflared access tcp --hostname postgres-server.jeelidev.uk --url localhost:5432

3. SSH Configuration (Optional but Recommended)

Add to ~/.ssh/config:

Host *.jeelidev.uk
  ProxyCommand /usr/local/bin/cloudflared access ssh --hostname %h

🛠️ Automated TCP Tunnels Service

📁 Included Scripts

This package includes automated tunnel management for any TCP service:

cloudflare-tcp-tunnels.sh - Main Script

# Start all configured tunnels
./cloudflare-tcp-tunnels.sh start

# Check tunnel status
./cloudflare-tcp-tunnels.sh status

# Add new tunnel
./cloudflare-tcp-tunnels.sh add my-service api.jeelidev.uk 3000

# List configured tunnels
./cloudflare-tcp-tunnels.sh list

# Remove existing tunnel
./cloudflare-tcp-tunnels.sh remove my-service

# Clean all tunnels (resets configuration)
./cloudflare-tcp-tunnels.sh clean

# Stop all tunnels
./cloudflare-tcp-tunnels.sh stop

Pre-configured Services:

• Neo4j BOLT: neo4j-bolt.jeelidev.uk:7687
• Neo4j Routing: neo4j-routing.jeelidev.uk:7688
• MySQL: mysql-server.jeelidev.uk:3306
• PostgreSQL: postgres-server.jeelidev.uk:5432
• SSH: ssh-server.jeelidev.uk:22
• Redis: redis-server.jeelidev.uk:6379
• MongoDB: mongodb-server.jeelidev.uk:27017
• Custom Services: Easily add more with add command

cloudflare-tcp-tunnels.service - Systemd Service

# Install for automatic startup on boot
sudo cp cloudflare-tcp-tunnels.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable cloudflare-tcp-tunnels.service
sudo systemctl start cloudflare-tcp-tunnels.service

🗄️ Neo4j Setup

Working setup: DozerDB with GDS Plugin

For the database, use DozerDB with the Graph Data Science plug-in, GDS is not only recommended but necessary:

For current installation instructions, see: https://dozerdb.org/

Example setup:

# Run DozerDB container with latest version
docker run \
    -p 7474:7474 -p 7687:7687 \
    -v $HOME/neo4j/data:/data \
    -v $HOME/neo4j/logs:/logs \
    -v $HOME/neo4j/plugins:/plugins \
    --env NEO4J_AUTH=neo4j/password \
    --env NEO4J_dbms_security_procedures_unrestricted='gds.*' \
    graphstack/dozerdb:latest

# Install GDS plugin - see dozerdb.org for current instructions

# Verify GDS plugin works
# In Neo4j Browser (http://localhost:7474):
# RETURN gds.similarity.cosine([1,2,3], [2,3,4]) as similarity

Remote Neo4j with Cloudflare Access

For remote Neo4j servers, use Cloudflare Access instead of traditional tunneling:

# On remote server: configure Zero Trust hostname
# On local machine: start access tunnel
cloudflared access tcp --hostname neo4j-remote.jeelidev.uk --url localhost:7687

# Connect Neo4j Browser to: bolt://localhost:7687
# MCP connects through localhost proxy

🛠️ Unified Tools

The server provides 4 unified MCP tools that integrate automatically with Claude:

• memory_store - Create memories with observations and immediate relations in ONE operation
• memory_find - Unified search/retrieval with semantic search, direct ID lookup, date filtering, and graph traversal
• memory_modify - Comprehensive modification operations (update, delete, observations, relations)
• database_switch - Switch database context for isolated environments

📊 Memory Structure

{
  "id": "dZ$abc123",
  "name": "Project Alpha",
  "memoryType": "project",
  "metadata": {"status": "active", "priority": "high"},
  "observations": [
    {"id": "dZ$obs456", "content": "Started development", "createdAt": "2025-06-08T10:00:00Z"}
  ],
  "related": {
    "ancestors": [{"id": "dZ$def789", "name": "Initiative", "relation": "PART_OF", "distance": 1}],
    "descendants": [{"id": "dZ$ghi012", "name": "Task", "relation": "INCLUDES", "distance": 1}]
  }
}

🎯 System Prompt

The simplest use of the memory tool, the following usually is more than enough.

## Memory Tool Usage
- Store all memory for this project in database: 'project-database-name'
- Use MCP memory tools exclusively for storing project-related information
- Begin each session by:
  1. Switching to this project's database
  2. Searching memory for data relevant to the user's prompt

🔧 Troubleshooting

Cloudflare Access Issues

❌ HTTP 400 Error with Traditional Tunneling:

# WRONG - This causes HTTP 400 errors
cloudflared tunnel --url tcp://localhost:7687

# CORRECT - Use Cloudflare Access
cloudflared access tcp --hostname neo4j-bolt.jeelidev.uk --url localhost:7687

✅ Connection Verification:

# Verify tunnel is working
netcat -zv localhost 7687
# Should show: Connection to localhost port 7687 [tcp/*] succeeded!

Vector Search Issues:

• Check logs for [VectorSearch] GDS Plugin detected
• GDS Plugin requires DozerDB setup (see Neo4j Setup section)

Connection Issues:

• Verify Neo4j is running: docker ps
• Test connection: curl http://localhost:7474
• Check credentials in environment variables
• Ensure Cloudflare Access tunnels are running

📚 Cloudflare Access Commands Reference

Supported Protocols:

# TCP Services (Neo4j, MySQL, PostgreSQL, etc.)
cloudflared access tcp --hostname service.domain.com --url localhost:PORT

# SSH Services
cloudflared access ssh --hostname ssh.domain.com

# HTTP/HTTPS Services
cloudflared access https://app.domain.com

# RDP (Windows Remote Desktop)
cloudflared access rdp --hostname rdp.domain.com --local-port 3389

# VNC
cloudflared access vnc --hostname vnc.domain.com --local-port 5900

🚀 Production Deployment

For Production Use:

1. Install systemd service for automatic tunnel startup
2. Configure proper SSL certificates in Cloudflare Zero Trust
3. Set up access policies for additional security
4. Monitor tunnel health with the provided status command
5. Use environment variables for sensitive configuration

📄 License

MIT

🤝 Contributing

This is a personal fork enhanced for Cloudflare Access compatibility. Original project by sylweriusz.

Key Enhancements in This Fork:

• ✅ Cloudflare Access TCP compatibility
• ✅ Enhanced error logging for tunneling issues
• ✅ Automated tunnel management scripts
• ✅ Production-ready systemd service
• ✅ Comprehensive documentation