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
npm install @pragmatic-growth/memory-mcpStdio proxy for PG-Memory - connects stdio-based MCP clients to your PG-Memory HTTP server.
PG-Memory supports two MCP transport modes:
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.$3
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:
$3
Semantic search, content retrieval, and smart gap logging. All tools are available by default.$3
Full CRUD operations on articles and Q&A records. Enable with:
`json
{
"env": {
"CLERK_API_KEY": "your-api-key",
"PG_MEMORY_ADMIN": "true"
}
}
`Installation
$3
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).$3
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"
}
}
}
}
`$3
`json
{
"name": "pg-memory",
"type": "stdio",
"command": "npx",
"args": ["-y", "@pragmatic-growth/memory-mcp"],
"env": {
"CLERK_API_KEY": "your-api-key-here"
}
}
`$3
`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
$3
| 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 |$3
| 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
$3
- 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$3
- 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$3
- 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)$3
- 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)$3
- 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$3
- 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)$3
- Clean npm package metadata (bin path, repository URL)
- Limit published files to the essentials$3
- Fix HTTP transport example (type: "http"; no command)$3
- 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$3
- 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$3
- 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`MIT