PG-Memory MCP (stdio proxy)

Stdio proxy for PG-Memory - connects stdio-based MCP clients to your PG-Memory HTTP server.

Two Transport Modes

PG-Memory supports two MCP transport modes:

1. HTTP Transport (Direct)

For clients that support HTTP/SSE transport (Codex, Cursor, Claude Code):

{
  "mcpServers": {
    "pg-memory": {
      "type": "http",
      "url": "https://your-server.up.railway.app/mcp",
      "headers": {
        "X-API-Key": "your-clerk-api-key"
      }
    }
  }
}

The X-API-Key header must contain your Clerk User API Key.

2. Stdio Transport (This Package)

For clients that only support stdio (Raycast, local tools):

{
  "name": "pg-memory",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@pragmatic-growth/memory-mcp"],
  "env": {
    "CLERK_API_KEY": "your-api-key"
  }
}

Operating Modes

PG-Memory supports two operating modes:

Read-Only Mode (default, 6 tools)

Semantic search, content retrieval, and smart gap logging. All tools are available by default.

Admin Mode (14 tools)

Full CRUD operations on articles and Q&A records. Enable with:

{
  "env": {
    "CLERK_API_KEY": "your-api-key",
    "PG_MEMORY_ADMIN": "true"
  }
}

Installation

For Claude Code (.mcp.json)

Add to your project's .mcp.json or ~/.claude/.mcp.json:

{
  "mcpServers": {
    "pg-memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@pragmatic-growth/memory-mcp"],
      "env": {
        "CLERK_API_KEY": "your-api-key-here",
        "PG_MEMORY_ADMIN": "true"
      }
    }
  }
}

Remove PG_MEMORY_ADMIN for read-only mode (6 tools).

For Claude Desktop (claude_desktop_config.json)

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pg-memory": {
      "command": "npx",
      "args": ["-y", "@pragmatic-growth/memory-mcp"],
      "env": {
        "CLERK_API_KEY": "your-api-key-here",
        "PG_MEMORY_ADMIN": "true"
      }
    }
  }
}

For Raycast

{
  "name": "pg-memory",
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@pragmatic-growth/memory-mcp"],
  "env": {
    "CLERK_API_KEY": "your-api-key-here"
  }
}

Global Installation

npm install -g @pragmatic-growth/memory-mcp

Then run directly:

CLERK_API_KEY=your-key memory-mcp

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CLERK_API_KEY | Yes | Clerk API key for authentication | | MCP_SERVER_URL | No | Custom server URL (default: production) | | PG_MEMORY_ADMIN | No | Set to true to enable admin tools (default: read-only) |

Available Tools

Read Tools (6, always available)

| Tool | Description | |------|-------------| | search | Unified semantic search across articles + approved Q&A. Returns lightweight results (ID, type, title/question, similarity, date). | | get_article | Retrieve full article content by ID | | get_qa | Retrieve a Q&A record by ID (question, answer, status, metadata) | | log_gap | Smart gap logging with deduplication (>85%), answer detection (>70%), AI quality filtering, and auto-priority | | list_categories | List all knowledge base categories with content counts | | health_check | System health status including article counts, Q&A counts, and connection pool stats |

Admin Tools (8, requires PG_MEMORY_ADMIN=true)

| Tool | Description | |------|-------------| | list_gaps | List unanswered knowledge gaps (Q&A with status='gap') | | create_article | Create a new article with auto-generated embedding | | update_article | Update an existing article with optional re-embedding | | create_qa | Create a Q&A record with full control over status and fields | | draft_qa_answer | Draft an answer for a Q&A record (sets status to 'draft') | | approve_qa | Approve a Q&A record and generate search embedding | | delete_article | Permanently delete an article | | delete_qa | Permanently delete a Q&A record |

Architecture Philosophy

Unified Search: search queries both articles and approved Q&A in parallel with graceful degradation. Returns metadata only for token efficiency — use get_article or get_qa for full content.

Q&A Lifecycle: Questions flow through gap → draft → approved status. Only approved Q&A appears in search results.

AI-Powered Quality: log_gap uses LLM evaluation to filter spam, detect duplicates (>85% similarity), suggest existing answers (>70% match), and auto-assign priority.

How It Works

This package runs locally as a stdio MCP server and proxies requests to the remote PG-Memory HTTP server. This allows clients that only support stdio to use the cloud-hosted knowledge base.

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Raycast/Local  │────▶│  memory-mcp     │────▶│  PG-Memory      │
│  (stdio only)   │     │  (this package) │     │  HTTP Server    │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        stdio                  proxy                   HTTP

Changelog

v3.5.0 (Latest)

• Two operating modes: Read-only (6 tools) and Admin (14 tools) via PG_MEMORY_ADMIN=true
• Unified search: search replaces search_knowledge, queries articles + approved Q&A in parallel
• Q&A lifecycle: Full CRUD with create_qa, draft_qa_answer, approve_qa, delete_qa
• Article management: create_article, update_article, delete_article admin tools
• Smart log_gap: Re-added deduplication, answer detection, and AI quality filtering
• Centralized schemas: Shared Zod schemas between HTTP and stdio servers
• Version alignment: HTTP server and stdio proxy both report v3.5.0

v3.4.0

• Server URL Update: Changed default server to mem-mcp.pragmaticgrowth.com (API subdomain)
• Validation Documentation: Added constraints to tool descriptions (enforced server-side):
  • search_knowledge.query: Minimum 3 characters
  • smart_log_gap.question: 10-2000 characters
  • smart_log_gap.context: Maximum 1000 characters
  • limit: 1-100 range
  • threshold: 0-1 range
• Server-Side Validation: All constraints are enforced by the server with clear error messages

v3.3.1

• Database Fix: Added missing embedding column to rag_query_logs table for vector similarity
• Schema Update: Base schema now includes embedding columns by default
• Build Fix: Excluded test files from production TypeScript compilation
• All 7 tools now fully operational (100% pass rate)

v3.3.0

• Breaking: log_unanswered → smart_log_gap - AI-powered question handling with quality evaluation
• New: __IMPORTANT tool - Workflow instructions embedded as pseudo-tool (claude-mem pattern)
• Smart Behaviors:
  • Real-time duplicate detection (>85% similarity)
  • Existing answer suggestions (>70% match with articles)
  • AI quality filtering (spam/garbage detection with Gemini Flash)
  • Auto-priority assignment (critical/high/medium/low based on urgency signals)
• Returns: {action: 'logged' | 'duplicate' | 'answered' | 'rejected'} with metadata
• Token savings: 5x reduction in typical query workflow (5600 → 1200 tokens)
• Architecture: 3-layer workflow (search → get_content → smart_log_gap)

v3.2.0

• API Documentation Enhancement - Complete REST API documentation with all parameters, examples, and curl commands
• Bearer token authentication examples (Authorization: Bearer ${CLERK_API_KEY})
• Improved API docs UI with expandable endpoint cards and copy-to-clipboard functionality
• Updated Q&A article creation documentation with metadata structure
• Production-ready curl commands for all 17 REST endpoints

v3.1.0

• Breaking: Ultimate Cleanup - Simplified from 15 tools to 6 focused tools
• Removed: Episodic Memory tools (5), Q&A intake (1), Full Mode write tools (3)
• Removed: Token tracking system (~350 lines of SaaS overhead)
• Architecture: Token-efficient pattern (metadata-only search results)
• Philosophy: Personal knowledge base, not a SaaS platform
• Server reduced from 700+ to 260 lines (77% reduction)

v3.0.2

• Clean npm package metadata (bin path, repository URL)
• Limit published files to the essentials

v3.0.1

• Fix HTTP transport example (type: "http"; no command)

v3.0.0

• Breaking: CLERK_API_KEY replaces MCP_API_KEY
• Adds MCP protocol negotiation for 2025-11-25, 2025-06-18, 2025-03-26
• Sends MCP-Protocol-Version on follow-up requests

v2.4.0

• Changed default server URL to custom domain: https://memory.pragmaticgrowth.com/mcp
• Simplified authentication to API key only (removed OAuth infrastructure)
• Updated dependencies to latest versions
• Improved error messages and documentation

v2.3.0

• Added unified get_content and list_content tools (replacing get_article/list_articles)
• Added Knowledge Graph tools: find_related, get_entities, search_entities, get_knowledge_graph
• Added Episodic Memory tools: start_conversation, add_message, get_conversation, list_conversations, get_session_context
• Added Q&A tool: add_question
• Updated to MCP Protocol (supports 2025-11-25, 2025-06-18, 2025-03-26)

v2.1.1

• Initial public release with core knowledge tools

License

MIT