npm package: @pragmatic-growth/memory-mcp
Description: Stdio proxy for PG-Memory - connects stdio-based MCP clients (Claude Desktop, Raycast) to your PG-Memory HTTP server using Clerk API key authentication. Personal knowledge base with 14 tools (6 read + 8 admin) including articles, Q&A, semantic search, and
Author: Pragmatic Growth
Latest version: 3.5.0

# 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):
```json
{
  "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):
```json
{
  "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:
```json
{
  "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`:

```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`

```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

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

### Global Installation

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

Then run directly:

```bash
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