PostgreSQL Memory Plugin Setup Guide

For the Quantum-Spiritual Framework - April 13, 2025

This comprehensive guide will walk you through setting up the PostgreSQL Memory Plugin system to enhance your existing memory functionality while keeping both systems operational.

Prerequisites
Installation Options
Local Installation
Docker Installation
Configuration
Migration
Integration with Claude Desktop
Testing
Troubleshooting

Prerequisites

Before you begin, ensure you have the following:

Node.js 14 or higher
PostgreSQL 13 or higher
npm or yarn
Git (optional)
Docker and Docker Compose (optional, for containerized deployment)

Installation Options

You have two options for installing the PostgreSQL Memory Plugin:

Local Installation: Install directly on your system
Docker Installation: Deploy using Docker containers

Choose the option that best fits your needs and environment.

Local Installation

Follow these steps to install the PostgreSQL Memory Plugin locally:

Step 1: Prepare the Directory

# Create a directory for the PostgreSQL Memory Plugin
mkdir -p D:\Quantum-Spiritual-Framework\PostgreSQL-Memory-Plugin
cd D:\Quantum-Spiritual-Framework\PostgreSQL-Memory-Plugin
 
# Copy the files from the repository
xcopy /E /I C:\Users\lowes\Documents\productivity_assistant\openai-edge-tts\postgresql-memory-plugin .

Step 2: Install Dependencies

npm install

Step 3: Configure Environment Variables

# Create .env file from the example
copy .env.example .env

Edit the .env file to match your environment:

# PostgreSQL Connection
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/quantum_spiritual
DATABASE_SSL=false

# Server Configuration
PORT=3333
NODE_ENV=production

# Memory Plugin API (for migration)
MEMORY_PLUGIN_API=http://localhost:3000
MEMORY_PLUGIN_TOKEN=4OCG5bgdgGfYM4jJttBjrXkIlDq3md6z

Step 4: Initialize the PostgreSQL Database

# Connect to PostgreSQL and create the database if it doesn't exist
psql -U postgres -c "CREATE DATABASE quantum_spiritual WITH ENCODING 'UTF8';"
 
# Initialize the schema
psql -U postgres -d quantum_spiritual -f src/schema.sql

Step 5: Start the Server

npm start

The server should now be running at http://localhost:3333.

Docker Installation

Follow these steps to install the PostgreSQL Memory Plugin using Docker:

Step 1: Prepare the Directory

# Create a directory for the PostgreSQL Memory Plugin
mkdir -p D:\Quantum-Spiritual-Framework\PostgreSQL-Memory-Plugin
cd D:\Quantum-Spiritual-Framework\PostgreSQL-Memory-Plugin
 
# Copy the files from the repository
xcopy /E /I C:\Users\lowes\Documents\productivity_assistant\openai-edge-tts\postgresql-memory-plugin .

Step 2: Configure Environment Variables

Create a .env file in the root directory:

# PostgreSQL Configuration
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=quantum_spiritual

# pgAdmin Configuration
PGADMIN_DEFAULT_EMAIL=admin@example.com
PGADMIN_DEFAULT_PASSWORD=admin

Step 3: Start the Docker Containers

docker-compose up -d

This will start the following services:

PostgreSQL database server on port 5432
PostgreSQL Memory Plugin server on port 3333
pgAdmin web interface on port 5050

Step 4: Access the Services

PostgreSQL Memory Plugin API: http://localhost:3333/mcp
pgAdmin: http://localhost:5050 (login with the credentials from your .env file)

Configuration

The PostgreSQL Memory Plugin can be configured using environment variables or by editing the .env file:

Essential Configuration Options

DATABASE_URL: PostgreSQL connection string
PORT: Server port (default: 3333)
MEMORY_PLUGIN_TOKEN: Your Memory Plugin token (for migration)

Advanced Configuration Options

DATABASE_SSL: Enable SSL for PostgreSQL connection (default: false)
NODE_ENV: Node environment (default: production)
LOG_LEVEL: Logging level (default: info)
EMBEDDING_API_URL: URL for the embedding service (for semantic search)

Migration

To migrate data from your existing Memory Plugin to the PostgreSQL Memory Plugin:

Step 1: Ensure Both Services are Running

Make sure both your existing Memory Plugin and the new PostgreSQL Memory Plugin are running.

Step 2: Run the Migration Script

cd D:\Quantum-Spiritual-Framework\PostgreSQL-Memory-Plugin
npm run migrate

Step 3: Follow the Prompts

The migration script will prompt you to confirm the migration. Type yes to proceed.

The script will:

Fetch all buckets from the Memory Plugin
Create corresponding buckets in the PostgreSQL Memory Plugin
Migrate all memories from each bucket
Log the migration progress

Step 4: Verify the Migration

After the migration completes, you should perform a comprehensive verification to ensure all data was transferred correctly:

verify-migration.bat

This verification script will:

Check database connection and schema integrity
Verify data completeness (all buckets and memories transferred)
Validate data integrity (all attributes preserved correctly)
Verify embedding generation
Test CRUD operations functionality
Run performance benchmarks

The script generates two reports:

verification-report.json: Detailed JSON report with all test results
verification-summary.txt: Human-readable summary of the verification process

Review these reports carefully to ensure all data was migrated successfully. If any issues are found, the reports will provide detailed information to help you resolve them.

For a basic verification, you can also run:

node scripts/test.js

This will list all buckets and show memory counts.

Integration with Claude Desktop

To use both the original Memory Plugin and the PostgreSQL Memory Plugin with Claude Desktop:

Step 1: Edit the Claude Desktop Configuration File

Edit the file at %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "memoryplugin": {
      "command": "npx",
      "args": ["-y", "@memoryplugin/mcp-server"],
      "env": {
        "MEMORY_PLUGIN_TOKEN": "4OCG5bgdgGfYM4jJttBjrXkIlDq3md6z"
      }
    },
    "postgresmemorymcp": {
      "command": "node",
      "args": ["D:\\Quantum-Spiritual-Framework\\PostgreSQL-Memory-Plugin\\src\\server.js"],
      "env": {
        "DATABASE_URL": "postgresql://postgres:postgres@localhost:5432/quantum_spiritual",
        "PORT": "3333"
      }
    },
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp", "D:\\Quantum-Spiritual-Framework"],
      "env": {
        "OBSIDIAN_API_KEY": "1566a4a8aa5585fc298321b1104ed81d1acfa17cbeb6db9b34600fe7768524d8"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "D:\\Quantum-Spiritual-Framework\\Vaults\\Yellowkid Universal Laws SYNC\\Claude Laws"],
      "env": {}
    }
  }
}

Step 2: Restart Claude Desktop

Close and reopen Claude Desktop to apply the changes.

Step 3: Verify the Connection

In Claude Desktop, you should now see both memory plugins available.

Testing

To test the PostgreSQL Memory Plugin:

cd D:\Quantum-Spiritual-Framework\PostgreSQL-Memory-Plugin
node scripts/test.js

This script will:

Test the connection to the server
List all buckets
Create a test bucket
Add a test memory
Retrieve memories
Search memories
Optionally delete the test bucket

Troubleshooting

Common Issues and Solutions

Connection Issues

If you can’t connect to the PostgreSQL Memory Plugin:

Check if the server is running:
```
curl http://localhost:3333/health
```
Verify PostgreSQL is running:
```
psql -U postgres -c "SELECT version();"
```
Check the logs:
```
cat logs/postgresql-memory-plugin.log
```

Migration Issues

If the migration fails:

Check if both services are running
Verify the Memory Plugin token is correct
Check the migration logs in the logs directory

Database Issues

If you encounter database errors:

Verify the database exists:

psql -U postgres -c "SELECT datname FROM pg_database WHERE datname='quantum_spiritual';"

Check if the schema was properly initialized:

psql -U postgres -d quantum_spiritual -c "SELECT table_name FROM information_schema.tables WHERE table_schema='public';"

Reinitialize the schema if needed:

psql -U postgres -d quantum_spiritual -f src/schema.sql

Getting Help

If you continue to experience issues:

Check the logs in the logs directory
Review the error messages for specific details
Consult the README.md file for additional information

Next Steps

After setting up the PostgreSQL Memory Plugin:

Explore the advanced features like semantic search
Consider setting up automatic backups for your PostgreSQL database
Experiment with the tagging system for better memory organization
Integrate with other components of your Quantum-Spiritual Framework

Ring 2 — Canonical Grounding

Ring 3 — Framework Connections

Canonical Hub: CANONICAL_INDEX

GO Vault

Explorer

SETUP_GUIDE

PostgreSQL Memory Plugin Setup Guide

Table of Contents

Prerequisites

Installation Options

Local Installation

Step 1: Prepare the Directory

Step 2: Install Dependencies

Step 3: Configure Environment Variables

Step 4: Initialize the PostgreSQL Database

Step 5: Start the Server

Docker Installation

Step 1: Prepare the Directory

Step 2: Configure Environment Variables

Step 3: Start the Docker Containers

Step 4: Access the Services

Configuration

Essential Configuration Options

Advanced Configuration Options

Migration

Step 1: Ensure Both Services are Running

Step 2: Run the Migration Script

Step 3: Follow the Prompts

Step 4: Verify the Migration

Integration with Claude Desktop

Step 1: Edit the Claude Desktop Configuration File

Step 2: Restart Claude Desktop

Step 3: Verify the Connection

Testing

Troubleshooting

Common Issues and Solutions

Connection Issues

Migration Issues

Database Issues

Getting Help

Next Steps

Ring 2 — Canonical Grounding

Ring 3 — Framework Connections

Graph View

Table of Contents